Agent API - Pactmark

Compatibility: Pactmark 0.1.x. Exact public signatures are generated from committed API Extractor reports in the repository. This page documents the surface you will actually use.

Authoring

`defineAgent(input)`

function defineAgent<I extends z.ZodType, O extends z.ZodType>(
  input: DefineAgentInput<I, O>,
): DefinedAgent<I, O>;

string

required

Stable agent identifier.

string

required

Contract version.

string

required

DefinedSchema<I>

required

DefinedSchema<O>

required

InstructionBundle

required

CompiledModelDefinition

required

DefinedPolicy

required

readonly string[]

required

Verifier ids that must pass.

Record<string, DefinedTool>

Optional.

readonly string[]

Capabilities the runtime must provide, or the run fails with KAF_RUNTIME_CAPABILITY_MISSING.

Type helpers: InferAgentInput<A> and InferAgentOutput<A>.

`defineTool(input)`

function defineTool<I extends z.ZodType, O extends z.ZodType>(
  input: DefineToolInput<I, O>,
): DefinedTool<I, O>;

string

required

Matches namespace.name@version.

string

required

string

required

DefinedSchema

required

Omit<ToolSecurity, 'schemaVersion'>

required

{ kind: 'read'; execute(input, context) }

required

Returns a DefinedTool carrying registration: ToolRegistrationContract — including toolRegistrationDigest.

`definePolicy(input)`

function definePolicy(input: DefinePolicyInput): DefinedPolicy;

"deny"

required

The literal "deny". No other value is accepted.

{ riskClass, decision }[]

required

decision is "deny", "allow_with_grant" or "require_approval".

`defineSchema` · `defineInstructions` · model profiles

defineSchema({ id, semanticRevision, schema });
defineInstructions({ text, sourceName? });
defineModelSecurityProfile({ /* provider, region, retention, … */ });
defineModelResourceProfile({ /* per-call and per-run caps */ });

Runtime

`createLocalRuntime(input)`

function createLocalRuntime(input: {
  agents: readonly DefinedAgent[];
  authorityIssuer: AuthorityIssuer;
}): LocalRuntimeFacade;

Deterministic memory-backed defaults for development and tests. LocalRuntimeFacade adds wait(authority, runId) to the standard facade.

`createRuntime(input)`

function createRuntime(input: CreateRuntimeInput): RuntimeFacade;

Extends RuntimeKernelConfig and additionally requires contextStore, inputSubmissionStore and egressBroker, with optional evidenceReader and requiredRuntimeCapabilities. Every port is explicit — there are no ambient defaults.

`RuntimeFacade`

Every method takes authority first. There is no ambient current user.

Method	Purpose
`start(authority, agent, request, command, options?)`	Accept work; returns `{ runId, workOrderId }`
`resume(authority, runId, command, options?)`	Resume; returns `{ runId, status }`
`cancel(authority, runId, reasonOrCommand, command?)`	Cancel; returns the projection
`getRun(authority, runId)`	Current `RunProjection`
`events(authority, runId, { afterSequence?, signal? })`	`AsyncIterable<RunEvent>` with replay
`getArtifacts(authority, runId)`	`{ artifact, content }[]`
`getEvidence(authority, runId)`	`EvidenceRecord \| undefined`
`submitInput(authority, runId, requestId, value, command)`	Answer an `InputRequested`
`issueDecisionChallenge(authority, runId, decisionId, command)`	`{ challengeProof, expiresAt }`
`approve(authority, runId, decision, command)`	`{ approvalId, runId, automaticResume }`
`reject(authority, runId, decision, command)`	`{ decisionId, runId, automaticResume }`
`reconcileEffect(authority, runId, effectId, resolution, command)`	`{ status: "recovered" \| "abandoned" }`
`requestCompensation(authority, runId, effectId, request, command)`	`{ compensationRunId }`
`getCapabilities()`	`RuntimeCapabilities`
`evaluateReadiness({ profile })`	`RuntimeReadinessReport`

Authority

`createLocalAuthorityIssuer(options?)`

const local = createLocalAuthorityIssuer({ issuerId?, now?, validityMs? });

const authority = local.issue({
  principal: { type: "user", id: "u-1" },
  tenant: { id: "acme" },
  authenticationStrength: "strong",
  decisionRoles: ["refund_approver"],
  requestCorrelationId: "req-…",
});

createLocalAuthorityIssuer is for development, tests and clearly-marked preview profiles. In production, authority comes from your authenticated host mapping — never from a locally minted issuer reachable by request input.

Commands

const command = createCommandContext({
  commandId: createCommandId(),
  operation: "run.start",
  payload: request,
});

Replaying a command with the same id and the same content returns the same semantic result. Different content raises KAF_HTTP_IDEMPOTENCY_CONFLICT; an elapsed horizon raises KAF_COMMAND_IDEMPOTENCY_EXPIRED.

Readiness

const report = evaluateRuntimeReadiness({
  capabilities: runtime.getCapabilities(),
  profile: "production",
  evaluatedAt: new Date().toISOString(),
  requiredCapabilities: ["durableStorage", "backgroundWakeup"],
  admissionConfigured: true,
  activeExecutionConfigured: true,
});

Profiles are local, preview and production. Production readiness rejects missing durability, atomicity, registered effect strategies, bounded model resources, credential enforcement or host capability.

Run events

Every event type and its payload.

Configuration

The ports createRuntime expects.

​Authoring

​defineAgent(input)

​defineTool(input)

​definePolicy(input)

​defineSchema · defineInstructions · model profiles

​Runtime

​createLocalRuntime(input)

​createRuntime(input)

​RuntimeFacade

​Authority

​createLocalAuthorityIssuer(options?)

​Commands

​Readiness

Run events

Configuration

Authoring

`defineAgent(input)`

`defineTool(input)`

`definePolicy(input)`

`defineSchema` · `defineInstructions` · model profiles

Runtime

`createLocalRuntime(input)`

`createRuntime(input)`

`RuntimeFacade`

Authority

`createLocalAuthorityIssuer(options?)`

Commands

Readiness