Defining tools

import { defineSchema, defineTool } from "@pactmark/agent";
import { z } from "zod";

const input = defineSchema({
  id: "billing.invoice.lookup.input",
  semanticRevision: "1",
  schema: z.object({ invoiceId: z.string().regex(/^INV-\d{6}$/) }).strict(),
});

const output = defineSchema({
  id: "billing.invoice.lookup.output",
  semanticRevision: "1",
  schema: z
    .object({
      invoiceId: z.string(),
      status: z.enum(["draft", "issued", "paid", "void"]),
      totalMinor: z.number().int().nonnegative(),
      currency: z.string().regex(/^[A-Z]{3}$/),
    })
    .strict(),
});

export const lookupInvoice = defineTool({
  id: "billing.invoice-lookup@1",
  implementationVersion: "1.2.0",
  description: "Read one invoice by identifier from the billing service.",
  input,
  output,
  security: {
    riskClass: "R1",
    dataClasses: ["confidential"],
    reversibility: "not_applicable",
    requiredScopes: ["billing:invoice:read"],
    egress: {
      mode: "allowlist",
      destinations: ["https://billing.internal.example.com"],
      methods: ["GET"],
      credentialSlots: ["billing.api"],
    },
    networkEnforcement: "required",
    maxCallsPerRun: 8,
    timeoutMs: 4_000,
    costCeiling: 0,
  },
  operation: {
    kind: "read",
    async execute({ invoiceId }, context) {
      const response = await context.egress.fetch(
        `https://billing.internal.example.com/v1/invoices/${invoiceId}`,
        { method: "GET" },
      );
      if (!response.ok) throw new Error(`billing_lookup_failed_${response.status}`);
      return response.json();
    },
  },
});

// Wrong: letting the target decide what happens next.
const { nextAction } = await response.json();
await doWhatever(nextAction);

// Right: return typed data and let policy decide.
return { invoiceId, status, totalMinor, currency };

import { FakeToolExecutor, ScenarioBuilder } from "@pactmark/testing";

// Cover, at minimum:
// - the happy path
// - malformed input (KAF_SCHEMA_INVALID)
// - policy denial without a grant (KAF_POLICY_DENIED)
// - exceeding maxCallsPerRun
// - a timeout, and what the run does next
// - registration drift: same version, changed schema