Minimal tool agent

Compatibility: Pactmark 0.1.x. No network, no external account. The memory-backed runtime is an ephemeral development profile and deliberately fails production readiness.

Run it

pnpm --filter pactmark-example-minimal-tool test
pnpm --filter pactmark-example-minimal-tool dev

Expected output:

{
  "runId": "run_01J…",
  "status": "completed",
  "eventTypes": ["RunAccepted", "ToolCallCompleted", "RunCompleted"],
  "evidenceDigest": "sha256:…",
  "productionReady": false
}

What it demonstrates

A complete run

Accepted, planned, one tool call, completed — with a real artifact and evidence record at the end.

A deterministic model driver

An async generator that yields a tool_call then a final. Fully reproducible.

Default-deny policy in the smallest possible form

One rule for R1; everything else denied.

Honest readiness

productionReady: false, because a memory store is not durability.

The tool

examples/minimal-tool-agent/src/example.ts

const fixture = Object.freeze({
  sku: "P-100",
  name: "Portable notebook",
  available: true,
});

export const lookupCatalog = defineTool({
  id: "catalog.lookup@1",
  implementationVersion: "1.0.0",
  description: "Read one item from the immutable example catalog.",
  input: toolInput,
  output: toolOutput,
  security: {
    riskClass: "R1",
    dataClasses: ["public"],
    reversibility: "not_applicable",
    requiredScopes: ["catalog:read"],
    egress: { mode: "none" },
    networkEnforcement: "declared_ok",
    maxCallsPerRun: 1,
    timeoutMs: 1_000,
  },
  operation: {
    kind: "read",
    execute: ({ sku }) =>
      Promise.resolve({ ...fixture, available: fixture.sku === sku }),
  },
});

egress: { mode: "none" } and a frozen fixture together mean this tool is incapable of reaching anything. That is what makes it a good first example — nothing about it can surprise you.

The model driver

function model(): CompiledModelDefinition {
  let turn = 0;
  return {
    modelSecurityProfileDigest: security.modelSecurityProfileDigest,
    modelResourceProfileDigest: resources.modelResourceProfileDigest,
    modelAdapterRegistrationDigest: digestCanonicalJson({
      adapter: "example.catalog@1",
    }),
    modelConfig: { kind: "deterministic" },
    credentialMode: "ambient_preview",
    driver: {
      capabilities,
      async *invoke() {
        turn += 1;
        yield turn === 1
          ? {
              type: "tool_call",
              value: {
                toolRegistrationDigest:
                  lookupCatalog.registration.toolRegistrationDigest,
                input: { sku: "P-100" },
                targetDigest: digestCanonicalJson({
                  source: "embedded-catalog",
                  sku: "P-100",
                }),
              },
            }
          : {
              type: "final",
              value: {
                summary: "Portable notebook is available.",
                source: "embedded-catalog",
              },
            };
      },
    },
  };
}

The driver names the tool by registration digest. That is not incidental — it is how the example demonstrates that a tool whose schema or security metadata changed cannot be reached by an old reference.

The capabilities declaration

const capabilities: RuntimeCapabilities = {
  schemaVersion: "1",
  executionProfile: "ephemeral",
  durableStorage: false,
  protectedContext: false,
  protectedWorkOrders: false,
  protectedInputSubmissions: false,
  streaming: true,
  cancellation: true,
  sandbox: "unsafe_local",
  networkPolicy: "declared",
  backgroundWakeup: false,
  atomicCommandAndWakeup: false,
  humanDecisions: false,
  typedInput: false,
  effectReconciliation: false,
  compensation: false,
  modelCredentials: false,
  toolCredentials: false,
  telemetry: "none",
  transactionDomains: [],
};

Read this as a list of things this runtime cannot do. It is honest about every one of them, which is why readiness for a production profile fails rather than degrading.

The run

const local = createLocalAuthorityIssuer();
const authority = local.issue({
  principal: { type: "user", id: "example-user" },
  tenant: { id: "local" },
});
const runtime = createLocalRuntime({
  agents: [catalogAgent],
  authorityIssuer: local.issuer,
});

const { runId } = await runtime.start(authority, catalogAgent, request, command);

const events = [];
for await (const event of runtime.events(authority, runId)) events.push(event);

return {
  runId,
  projection: await runtime.wait(authority, runId),
  events,
  artifacts: await runtime.getArtifacts(authority, runId),
  evidence: await runtime.getEvidence(authority, runId),
  productionReadiness: runtime.evaluateReadiness({ profile: "production" }),
};

What comes out

Figure 1. Even this minimal run produces the full structure: ordered events, a derived projection, a content-addressed artifact and a bounded evidence record.

What it does not support

The result supports only what the embedded fixture contained during this run. Its memory-backed runtime is an ephemeral development profile and deliberately fails production readiness. No network or external account is used, so nothing here is evidence about a real catalogue service.

Modify it to learn something

Change maxToolCalls to 0

Watch the run terminate on budget rather than on completion.

Remove the R1 rule from the policy

The tool call is denied with KAF_POLICY_DENIED — and the tool executor records zero calls.

Change the tool's input schema without bumping the version

The registration digest changes and the driver’s reference no longer resolves.

Ask for a sku the fixture does not have

available: false — the tool returns a truthful negative rather than an error.

Build it yourself

The same agent, written from scratch with every object explained.

Workspace agent

The next step up: bounded filesystem access with real denial paths.

​Run it

​What it demonstrates

A complete run

A deterministic model driver

Default-deny policy in the smallest possible form

Honest readiness

​The tool

​The model driver

​The capabilities declaration

​The run

​What comes out

​What it does not support

​Modify it to learn something

Build it yourself

Workspace agent

Run it

What it demonstrates

The tool

The model driver

The capabilities declaration

The run

What comes out

What it does not support

Modify it to learn something