@relayflows/sdk 2.0.45 → 2.0.46

package/src/flow-tool-kernel.ts

@@ -0,0 +1,319 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { canonicalize } from './canonical.js';
+import { sha256, verifyBundle } from './bundle.js';
+import { FlowToolError, type FlowToolCatalogEntryV1, type FlowToolEventV1,
+  type FlowToolRunState, type FlowToolRunV1, type FlowToolTerminalReason } from './flow-tool-contract.js';
+import type { FlowToolRequest, FlowToolTransport } from './flow-tool-client.js';
+import { flowToolOperationKey } from './flow-tool-client.js';
+import { JournalClient, JournalProtocolError } from './journal-client.js';
+import { parseFlowToolEntry, parseFlowToolInvocation, flowToolRunLinks, toolId } from './flow-tool-wire.js';
+import { validateFlowToolResult } from './flow-tool-manifest.js';
+import type { FlowToolJson } from './flow-tool-schema.js';
+import type { KernelDeterministicStep, KernelRunSpec } from './spec.js';
+
+/** The only executable accepted by the v1 embedded runtime. It receives JSON as argv data. */
+export const FLOW_TOOL_INPUT_PLACEHOLDER = '__RELAYFLOWS_FLOW_TOOL_INPUT_V1__';
+const RESULT_STEP = 'flow-tool-result';
+const MAX_RESULT_BYTES = 60 * 1024; // below relayflowd's 64 KiB stdout tail
+
+export interface KernelFlowToolDeployment {
+  readonly entry: FlowToolCatalogEntryV1;
+  /** A bundle whose content digest is entry.manifest.flow.digest. */
+  readonly bundlePath: string;
+  /** Operator-owned outcome label, never selected by invocation input. */
+  readonly businessVerdict: string;
+}
+
+export interface KernelFlowToolControlPlaneOptions {
+  readonly journal: JournalClient;
+  /** Authenticated server-side identity. This value is hashed before journaling. */
+  readonly principal: string;
+  readonly deployments: readonly KernelFlowToolDeployment[];
+  /** Server-side grants for this principal. Omission grants nothing. */
+  readonly authorizedDeploymentIds?: readonly string[];
+}
+
+interface LoadedDeployment {
+  entry: FlowToolCatalogEntryV1;
+  template: KernelRunSpec;
+  businessVerdict: string;
+}
+
+// relayflowd's Rust boundary accepts an untagged shell-string | argv command.
+// The public authoring compiler deliberately remains shell-string-only; this
+// closed runtime constructs the narrower argv variant internally.
+type KernelArgvStep = Omit<KernelDeterministicStep, 'command'> & { command: string[] };
+
+interface RunBinding {
+  kind: 'relayflows.flow-tool-run.v1';
+  deployment_id: string;
+  manifest_digest: string;
+  flow_digest: string;
+  input_digest: string;
+  principal_digest: string;
+}
+
+interface JournalEntry {
+  seq: number;
+  entry_type: string;
+  step_id?: string | null;
+  payload: Record<string, unknown>;
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function runtimeFailure(code: 'unsupported' | 'invalid_contract' = 'unsupported'): never {
+  throw new FlowToolError(code);
+}
+
+function exactKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+  return Object.keys(value).every(key => allowed.includes(key));
+}
+
+function preflightTemplate(value: unknown, entry: FlowToolCatalogEntryV1): KernelRunSpec {
+  if (!record(value) || !exactKeys(value, ['version', 'name', 'description', 'steps'])
+    || typeof value['version'] !== 'string' || value['name'] !== entry.manifest.flow.name
+    || !Array.isArray(value['steps']) || value['steps'].length !== 1) runtimeFailure();
+  const step = value['steps'][0];
+  if (!record(step) || !exactKeys(step, [
+    'id', 'type', 'command', 'depends_on', 'max_iterations', 'retry', 'verification', 'timeout_ms',
+  ]) || step['id'] !== RESULT_STEP || step['type'] !== 'deterministic'
+    || !Array.isArray(step['command']) || step['command'].length !== 3
+    || !['/usr/bin/printf', '/bin/printf'].includes(step['command'][0] as string)
+    || step['command'][1] !== '%s' || step['command'][2] !== FLOW_TOOL_INPUT_PLACEHOLDER
+    || !Array.isArray(step['depends_on']) || step['depends_on'].length !== 0
+    || step['max_iterations'] !== 1 || !record(step['retry']) || !record(step['verification'])
+    || Object.keys(step['verification']).length !== 0
+    || !Number.isSafeInteger(step['timeout_ms']) || (step['timeout_ms'] as number) < 1
+    || (step['timeout_ms'] as number) > entry.budget.max_wallclock_ms) runtimeFailure();
+  const retry = step['retry'];
+  if (!exactKeys(retry, ['initial_backoff_ms', 'max_backoff_ms', 'multiplier', 'jitter_percent'])
+    || retry['initial_backoff_ms'] !== 0 || retry['max_backoff_ms'] !== 0
+    || retry['multiplier'] !== 1 || retry['jitter_percent'] !== 0) runtimeFailure();
+  return value as unknown as KernelRunSpec;
+}
+
+async function loadDeployment(deployment: KernelFlowToolDeployment): Promise<LoadedDeployment> {
+  let entry: FlowToolCatalogEntryV1;
+  try { entry = parseFlowToolEntry(deployment.entry); } catch { runtimeFailure('invalid_contract'); }
+  if (entry.effects.length !== 0 || entry.requires_human.length !== 0
+    || !entry.business_verdicts.includes(deployment.businessVerdict)) runtimeFailure();
+  // This runtime prints the invocation input and nothing else. A result schema
+  // that is not that same document would journal success and then have to
+  // invent a different public reason. Refuse the deployment instead.
+  if (canonicalize(entry.manifest.inputSchema) !== canonicalize(entry.manifest.resultSchema)) {
+    runtimeFailure('unsupported');
+  }
+  const expected = entry.manifest.flow.digest.slice('sha256:'.length);
+  try {
+    const before = await readFile(join(deployment.bundlePath, 'spec.canonical.json'));
+    const preflightBefore = await readFile(join(deployment.bundlePath, 'preflight.json'));
+    await verifyBundle(deployment.bundlePath, expected);
+    const after = await readFile(join(deployment.bundlePath, 'spec.canonical.json'));
+    const preflightAfter = await readFile(join(deployment.bundlePath, 'preflight.json'));
+    if (!before.equals(after) || !preflightBefore.equals(preflightAfter)) runtimeFailure();
+    const report: unknown = JSON.parse(preflightAfter.toString('utf8'));
+    if (!record(report) || report['ok'] !== true) runtimeFailure();
+    return { entry, template: preflightTemplate(JSON.parse(after.toString('utf8')), entry),
+      businessVerdict: deployment.businessVerdict };
+  } catch (error) {
+    if (error instanceof FlowToolError) throw error;
+    runtimeFailure();
+  }
+}
+
+function bindingDescription(binding: RunBinding): string { return canonicalize(binding); }
+
+function parseBinding(entries: readonly JournalEntry[]): RunBinding {
+  const spawned = entries.find(entry => entry.entry_type === 'run.spawned');
+  const spec = spawned?.payload['spec'];
+  const description = record(spec) ? spec['description'] : undefined;
+  try {
+    const value: unknown = JSON.parse(typeof description === 'string' ? description : 'null');
+    if (!record(value) || value['kind'] !== 'relayflows.flow-tool-run.v1'
+      || typeof value['deployment_id'] !== 'string' || typeof value['manifest_digest'] !== 'string'
+      || typeof value['flow_digest'] !== 'string' || typeof value['input_digest'] !== 'string'
+      || typeof value['principal_digest'] !== 'string'
+      || !/^sha256:[a-f0-9]{64}$/.test(value['manifest_digest'])
+      || !/^sha256:[a-f0-9]{64}$/.test(value['flow_digest'])
+      || !/^sha256:[a-f0-9]{64}$/.test(value['input_digest'])
+      || !/^[a-f0-9]{64}$/.test(value['principal_digest'])) runtimeFailure('invalid_contract');
+    return value as unknown as RunBinding;
+  } catch (error) {
+    if (error instanceof FlowToolError) throw error;
+    runtimeFailure('invalid_contract');
+  }
+}
+
+function journalEntries(value: unknown[]): JournalEntry[] {
+  if (!value.every(item => record(item) && Number.isSafeInteger(item['seq'])
+    && typeof item['entry_type'] === 'string' && record(item['payload']))) runtimeFailure('invalid_contract');
+  return value as unknown as JournalEntry[];
+}
+
+function terminalReason(reason: unknown): FlowToolTerminalReason {
+  if (reason === 'success') return 'success';
+  if (reason === 'canceled') return 'canceled';
+  if (reason === 'budget_exceeded') return 'budget_exceeded';
+  return 'execution_failed';
+}
+
+function runState(status: string, reason: FlowToolTerminalReason | null): FlowToolRunState {
+  if (reason === 'success') return 'completed';
+  if (reason === 'canceled') return 'cancelled';
+  if (reason !== null) return 'failed';
+  if (status === 'parked') return 'parked';
+  return 'running';
+}
+
+function mapProtocolError(error: unknown, admission = false): never {
+  if (error instanceof JournalProtocolError) {
+    if (error.code === 'run_admission_conflict') throw new FlowToolError('idempotency_conflict');
+    if (error.code === 'run_not_found') throw new FlowToolError('not_authorized');
+    throw new FlowToolError('unavailable');
+  }
+  throw new FlowToolError(admission ? 'transport_error' : 'unavailable');
+}
+
+/**
+ * Build an authenticated embedded control plane over relayflowd's durable journal.
+ * This intentionally supports only the effect-free JSON echo/conformance program;
+ * arbitrary declarative, authored, LLM, and agent flows remain unsupported.
+ */
+export async function createKernelFlowToolControlPlane(
+  options: KernelFlowToolControlPlaneOptions,
+): Promise<FlowToolTransport> {
+  if (typeof options.principal !== 'string' || options.principal.length < 1 || options.principal.length > 1024) {
+    runtimeFailure('invalid_contract');
+  }
+  const principalDigest = sha256(options.principal);
+  const grants = new Set(options.authorizedDeploymentIds ?? []);
+  const deployments = new Map<string, LoadedDeployment>();
+  const names = new Map<string, LoadedDeployment>();
+  for (const candidate of options.deployments) {
+    const loaded = await loadDeployment(candidate);
+    if (deployments.has(loaded.entry.deployment_id) || names.has(loaded.entry.manifest.name)) runtimeFailure('invalid_contract');
+    deployments.set(loaded.entry.deployment_id, loaded);
+    names.set(loaded.entry.manifest.name, loaded);
+  }
+
+  const authorized = (deployment: LoadedDeployment): boolean => grants.has(deployment.entry.deployment_id);
+
+  async function readAuthorizedRun(runId: string) {
+    toolId(runId);
+    let entries: JournalEntry[];
+    try { entries = journalEntries((await options.journal.journalRead(runId, 1, 1000)).entries); }
+    catch (error) { mapProtocolError(error); }
+    const binding = parseBinding(entries!);
+    const deployment = deployments.get(binding.deployment_id);
+    if (deployment === undefined || !authorized(deployment) || binding.principal_digest !== principalDigest
+      || binding.manifest_digest !== deployment.entry.manifest.digest
+      || binding.flow_digest !== deployment.entry.manifest.flow.digest) throw new FlowToolError('not_authorized');
+    return { deployment, binding, entries: entries! };
+  }
+
+  async function projectRun(runId: string): Promise<FlowToolRunV1> {
+    const { deployment, binding, entries } = await readAuthorizedRun(runId);
+    let snapshot: Awaited<ReturnType<JournalClient['runGet']>>;
+    try { snapshot = await options.journal.runGet(runId); } catch (error) { mapProtocolError(error); }
+    const completed = entries.find(entry => entry.entry_type === 'step.completed' && entry.step_id === RESULT_STEP);
+    const ended = entries.find(entry => entry.entry_type === 'run.completed');
+    let reason = ended === undefined ? null : terminalReason(ended.payload['completionReason']);
+    if (reason === null && ['failed', 'interrupted'].includes(snapshot!.status)) reason = 'execution_failed';
+    let result: Readonly<Record<string, FlowToolJson>> | null = null;
+    if (reason === 'success') {
+      // The journal already recorded success. Do not publish a different
+      // terminal reason from a projection-time check the journal never stored.
+      const output = completed?.payload['output'];
+      if (!record(output) || typeof output['stdout_tail'] !== 'string') throw new FlowToolError('unavailable');
+      try { result = validateFlowToolResult(deployment.entry.manifest, JSON.parse(output['stdout_tail'])); }
+      catch { throw new FlowToolError('unavailable'); }
+    }
+    const state = runState(snapshot!.status, reason);
+    const sequence = Math.max(0, ...entries.map(entry => entry.seq));
+    const evidence = { journal_digest: `sha256:${sha256(canonicalize(entries))}` as const,
+      flow_digest: deployment.entry.manifest.flow.digest, artifacts: [], redacted_transcript_refs: [] };
+    const terminal = reason === null ? null : {
+      terminal_reason: reason,
+      business_verdict: reason === 'success' ? deployment.businessVerdict : null,
+      result: reason === 'success' ? result : null,
+      gates: [], evidence,
+      spend: { tokens_in: snapshot!.budget.tokens_in, tokens_out: snapshot!.budget.tokens_out,
+        dollars: snapshot!.budget.dollars, dollars_unmetered: snapshot!.budget.dollars_unmetered === true },
+    };
+    return { api_version: 1, accepted: true, run_id: runId, tool_name: deployment.entry.manifest.name,
+      deployment_id: deployment.entry.deployment_id, manifest_digest: deployment.entry.manifest.digest,
+      flow_digest: deployment.entry.manifest.flow.digest, input_digest: binding.input_digest as `sha256:${string}`,
+      state, sequence, ...flowToolRunLinks(runId), terminal };
+  }
+
+  function eventsFor(run: FlowToolRunV1, entries: readonly JournalEntry[], after: number): FlowToolEventV1[] {
+    const projected: FlowToolEventV1[] = [];
+    for (const entry of entries) {
+      if (entry.seq <= after) continue;
+      if (entry.entry_type === 'run.spawned') projected.push({ api_version: 1, run_id: run.run_id,
+        flow_digest: run.flow_digest, sequence: entry.seq, type: 'run.accepted', state: 'accepted' });
+      else if (entry.entry_type === 'step.completed') projected.push({ api_version: 1, run_id: run.run_id,
+        flow_digest: run.flow_digest, sequence: entry.seq, type: 'step.completed', state: 'running',
+        ...(entry.step_id === null || entry.step_id === undefined ? {} : { step_id: entry.step_id }) });
+      else if (entry.entry_type === 'run.completed') projected.push({ api_version: 1, run_id: run.run_id,
+        flow_digest: run.flow_digest, sequence: entry.seq, type: 'run.terminal', state: run.state,
+        terminal_reason: run.terminal!.terminal_reason });
+    }
+    return projected;
+  }
+
+  return {
+    async request(request: FlowToolRequest): Promise<unknown> {
+      if (request.method === 'GET' && request.path === '/api/v1/flow-tools') {
+        return { api_version: 1, tools: [...deployments.values()].filter(authorized).map(value => value.entry) };
+      }
+      const invoke = request.path.match(/^\/api\/v1\/flow-tools\/([^/]+)\/invoke$/);
+      if (request.method === 'POST' && invoke !== null) {
+        const deployment = names.get(invoke[1]!);
+        if (deployment === undefined || !authorized(deployment)) throw new FlowToolError('not_authorized');
+        flowToolOperationKey(request.idempotencyKey);
+        const body = parseFlowToolInvocation(request.body, deployment.entry);
+        const encoded = canonicalize(body.input);
+        if (Buffer.byteLength(encoded) > MAX_RESULT_BYTES) throw new FlowToolError('unsupported');
+        // Catalog bytes and the operator verdict label are not part of the
+        // admitted program. Putting them in the spec description changes the
+        // kernel spec hash, so a budget or verdict reload conflicts with the
+        // same operation key and the original run can no longer be read.
+        const binding: RunBinding = { kind: 'relayflows.flow-tool-run.v1', deployment_id: deployment.entry.deployment_id,
+          manifest_digest: deployment.entry.manifest.digest, flow_digest: deployment.entry.manifest.flow.digest,
+          input_digest: body.input_digest, principal_digest: principalDigest };
+        const step = deployment.template.steps[0]! as unknown as KernelArgvStep;
+        const spec: KernelRunSpec = { ...deployment.template, description: bindingDescription(binding), steps: [{
+          ...step, command: [step.command[0]!, '%s', encoded],
+        } as unknown as KernelDeterministicStep] };
+        const admissionKey = `flow-tool:${sha256(canonicalize([principalDigest, deployment.entry.deployment_id,
+          deployment.entry.manifest.flow.digest, deployment.entry.manifest.digest, request.idempotencyKey]))}`;
+        let started: Awaited<ReturnType<JournalClient['runStart']>>;
+        try { started = await options.journal.runStart(spec, undefined, admissionKey); }
+        catch (error) { mapProtocolError(error, true); }
+        return projectRun(started!.run_id);
+      }
+      const runPath = request.path.match(/^\/api\/v1\/flow-runs\/([^/]+)(.*)$/);
+      if (runPath === null) throw new FlowToolError('not_found');
+      const run = await projectRun(runPath[1]!);
+      if (request.method === 'GET' && runPath[2] === '') return run;
+      if (request.method === 'GET' && runPath[2] === '/evidence') {
+        if (run.terminal === null) throw new FlowToolError('unavailable');
+        return { api_version: 1, run_id: run.run_id, evidence: run.terminal.evidence };
+      }
+      // The conformance program cannot park, so commands are deliberately absent.
+      throw new FlowToolError('unsupported');
+    },
+    async *events(path: string, after: number): AsyncIterable<unknown> {
+      const match = path.match(/^\/api\/v1\/flow-runs\/([^/]+)\/events$/);
+      if (match === null || !Number.isSafeInteger(after) || after < 0) throw new FlowToolError('invalid_contract');
+      const { entries } = await readAuthorizedRun(match[1]!);
+      const run = await projectRun(match[1]!);
+      for (const event of eventsFor(run, entries, after)) yield event;
+    },
+  };
+}

package/src/flow-tool-manifest.ts

@@ -0,0 +1,104 @@
+import { canonicalize } from './canonical.js';
+import { sha256 } from './bundle.js';
+import { snapshotJsonValue, type JsonValue } from './json-value.js';
+import { FLOW_TOOL_LIMITS, FLOW_TOOL_SCHEMA_DIALECT, flowToolSchema, compileFlowToolSchema } from './flow-tool-schema.js';
+import type { FlowToolJson, FlowToolObjectSchema } from './flow-tool-schema.js';
+
+export type FlowToolDigest = `sha256:${string}`;
+export interface FlowToolDeclarationV1 {
+  readonly name: string;
+  readonly description: string;
+  /** Author-supplied immutable bundle reference; not proof of bundle verification. */
+  readonly flow: Readonly<{ name: string; version: string; digest: FlowToolDigest }>;
+  readonly inputSchema: FlowToolObjectSchema;
+  readonly resultSchema: FlowToolObjectSchema;
+}
+export interface FlowToolManifestV1 extends FlowToolDeclarationV1 {
+  readonly manifestVersion: 1;
+  readonly schemaDialect: typeof FLOW_TOOL_SCHEMA_DIALECT;
+  /** SHA-256 of canonical manifest content excluding this field. Not a signature. */
+  readonly digest: FlowToolDigest;
+}
+
+const FIELDS = ['name', 'description', 'flow', 'inputSchema', 'resultSchema'];
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+function record(value: JsonValue, fields: readonly string[], at: string): Record<string, JsonValue> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${at}: expected an object`);
+  if (Object.keys(value).some(key => !fields.includes(key)) || fields.some(key => !Object.hasOwn(value, key))) {
+    // Unknown field names may themselves be sensitive caller data; do not echo them.
+    throw new TypeError(`${at}: missing or unknown fields`);
+  }
+  return value;
+}
+
+function declaration(value: unknown): FlowToolDeclarationV1 {
+  const data = record(snapshotJsonValue(value, 'flow tool', FLOW_TOOL_LIMITS), FIELDS, 'flow tool');
+  if (typeof data.name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_-]{0,63}$/.test(data.name)) {
+    throw new TypeError('flow tool.name: expected a portable tool name (1–64 ASCII characters)');
+  }
+  if (typeof data.description !== 'string' || !data.description.trim() || data.description.length > 4096) {
+    throw new TypeError('flow tool.description: expected 1–4096 characters of operator-authored description');
+  }
+  const flow = record(data.flow!, ['name', 'version', 'digest'], 'flow tool.flow');
+  if (typeof flow.name !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(flow.name)) {
+    throw new TypeError('flow tool.flow.name: expected a safe flow name');
+  }
+  if (typeof flow.version !== 'string' || flow.version.length > 128 || !VERSION.test(flow.version)
+    || flow.version.split('+')[0]!.split('-').slice(1).join('-').split('.').some(id => /^0\d+$/.test(id))) {
+    throw new TypeError('flow tool.flow.version: expected a semantic version');
+  }
+  if (typeof flow.digest !== 'string' || !DIGEST.test(flow.digest)) throw new TypeError('flow tool.flow.digest: expected sha256 and 64 lowercase hex digits');
+  return Object.freeze({
+    name: data.name, description: data.description,
+    flow: Object.freeze({ name: flow.name, version: flow.version, digest: flow.digest as FlowToolDigest }),
+    inputSchema: flowToolSchema(data.inputSchema, 'flow tool.inputSchema'),
+    resultSchema: flowToolSchema(data.resultSchema, 'flow tool.resultSchema'),
+  });
+}
+
+/** Explicit runtime contract; TypeScript generics are never treated as schemas. */
+export function createFlowToolManifest(value: FlowToolDeclarationV1): FlowToolManifestV1 {
+  const content = Object.freeze({ manifestVersion: 1 as const, schemaDialect: FLOW_TOOL_SCHEMA_DIALECT, ...declaration(value) });
+  return snapshotJsonValue({ ...content, digest: `sha256:${sha256(canonicalize(content))}` },
+    'flow tool manifest', FLOW_TOOL_LIMITS) as unknown as FlowToolManifestV1;
+}
+
+/** Verify untrusted JSON and optionally bind it to a caller-trusted catalog digest. */
+export function parseFlowToolManifest(value: unknown, expectedDigest?: FlowToolDigest): FlowToolManifestV1 {
+  const data = record(snapshotJsonValue(value, 'flow tool manifest', FLOW_TOOL_LIMITS),
+    [...FIELDS, 'manifestVersion', 'schemaDialect', 'digest'], 'flow tool manifest');
+  if (data.manifestVersion !== 1 || data.schemaDialect !== FLOW_TOOL_SCHEMA_DIALECT) {
+    throw new TypeError('flow tool manifest: unsupported manifest version or schema dialect');
+  }
+  // Identity verification must never trim, case-fold or otherwise normalize metadata.
+  const parsed = createFlowToolManifest(Object.fromEntries(FIELDS.map(key => [key, data[key]])) as unknown as FlowToolDeclarationV1);
+  if (data.digest !== parsed.digest || (expectedDigest !== undefined && parsed.digest !== expectedDigest)) {
+    throw new TypeError('flow tool manifest: digest mismatch');
+  }
+  return parsed;
+}
+
+export function canonicalFlowToolManifest(value: FlowToolManifestV1): string {
+  return canonicalize(parseFlowToolManifest(value));
+}
+
+function validate(value: unknown, schema: FlowToolObjectSchema, at: string): Readonly<Record<string, FlowToolJson>> {
+  const snapshot = snapshotJsonValue(value, at, FLOW_TOOL_LIMITS);
+  const validator = compileFlowToolSchema(schema);
+  if (!validator(snapshot)) {
+    // Report only the keyword: instance paths can contain sensitive caller keys.
+    throw new TypeError(`${at}: schema validation failed (${validator.errors?.[0]?.keyword ?? 'invalid'})`);
+  }
+  return snapshot as Readonly<Record<string, FlowToolJson>>;
+}
+
+export function validateFlowToolInput(manifest: FlowToolManifestV1, input: unknown): Readonly<Record<string, FlowToolJson>> {
+  return validate(input, parseFlowToolManifest(manifest).inputSchema, 'flow tool input');
+}
+
+/** Validates structure only, not business truth or successful execution. */
+export function validateFlowToolResult(manifest: FlowToolManifestV1, result: unknown): Readonly<Record<string, FlowToolJson>> {
+  return validate(result, parseFlowToolManifest(manifest).resultSchema, 'flow tool result');
+}

package/src/flow-tool-schema.ts

@@ -0,0 +1,66 @@
+import Ajv2020 from 'ajv/dist/2020.js';
+import { jsonSchemaBoundError } from './json-schema-bound.js';
+import { snapshotJsonValue, type JsonValue } from './json-value.js';
+
+export const FLOW_TOOL_SCHEMA_DIALECT = 'https://json-schema.org/draft/2020-12/schema' as const;
+export type FlowToolJson = null | boolean | number | string | readonly FlowToolJson[]
+  | { readonly [key: string]: FlowToolJson };
+export type FlowToolObjectSchema = Readonly<Record<string, FlowToolJson>> & { readonly type: 'object' };
+export const FLOW_TOOL_LIMITS = Object.freeze({ maxDepth: 64, maxNodes: 4096, maxBytes: 262144 });
+
+// A deliberately explicit portable v1 profile, not silently ignored JSON Schema.
+const KEYWORDS = new Set([
+  '$schema', '$defs', '$ref', 'title', 'description', 'type', 'enum', 'const',
+  'properties', 'required', 'additionalProperties', 'items', 'minItems', 'maxItems',
+  'uniqueItems', 'minLength', 'maxLength', 'minimum', 'maximum', 'exclusiveMinimum',
+  'exclusiveMaximum', 'multipleOf', 'minProperties', 'maxProperties', 'anyOf', 'oneOf', 'allOf', 'not',
+]);
+
+function inspect(schema: JsonValue, at: string): void {
+  if (typeof schema === 'boolean') return;
+  if (schema === null || typeof schema !== 'object' || Array.isArray(schema)) {
+    throw new TypeError(`${at}: expected a JSON Schema object or boolean`);
+  }
+  for (const [key, value] of Object.entries(schema)) {
+    if (!KEYWORDS.has(key)) throw new TypeError(`${at}: unsupported v1 schema keyword ${key}`);
+    if (key === '$schema' && value !== FLOW_TOOL_SCHEMA_DIALECT) {
+      throw new TypeError(`${at}: expected JSON Schema 2020-12`);
+    }
+    if (key === '$ref' && (typeof value !== 'string' || !value.startsWith('#/'))) {
+      throw new TypeError(`${at}: only document-local JSON Pointer references are supported`);
+    }
+    if (key === 'properties' || key === '$defs') {
+      if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError(`${at}.${key}: expected an object`);
+      }
+      for (const [name, child] of Object.entries(value)) inspect(child, `${at}.${key}.${name}`);
+    } else if (key === 'items' || key === 'additionalProperties' || key === 'not') {
+      inspect(value, `${at}.${key}`);
+    } else if (key === 'anyOf' || key === 'oneOf' || key === 'allOf') {
+      if (!Array.isArray(value)) throw new TypeError(`${at}.${key}: expected an array`);
+      value.forEach((child, i) => inspect(child, `${at}.${key}[${i}]`));
+    }
+  }
+}
+
+export function compileFlowToolSchema(schema: FlowToolObjectSchema) {
+  // No coercion, defaults, removal of extras, network retrieval, or ignored formats.
+  // Deliberately revalidate each supplied manifest; no unbounded global schema cache.
+  // A future admitted catalog may own a bounded compiled-validator lifecycle.
+  return new Ajv2020({ strict: true, strictRequired: true, allowUnionTypes: true, allErrors: false })
+    .compile(schema);
+}
+
+export function flowToolSchema(value: unknown, at: string): FlowToolObjectSchema {
+  const snapshot = snapshotJsonValue(value, at, FLOW_TOOL_LIMITS);
+  inspect(snapshot, at);
+  if (snapshot === null || typeof snapshot !== 'object' || Array.isArray(snapshot) || snapshot.type !== 'object') {
+    throw new TypeError(`${at}: tool schemas must explicitly have type "object"`);
+  }
+  const bounded = jsonSchemaBoundError(snapshot);
+  if (bounded !== undefined) throw new TypeError(`${at}: ${bounded}`);
+  const schema = snapshot as FlowToolObjectSchema;
+  try { compileFlowToolSchema(schema); }
+  catch { throw new TypeError(`${at}: invalid or unsupported JSON Schema`); }
+  return schema;
+}

package/src/flow-tool-wire.ts

@@ -0,0 +1,152 @@
+import { canonicalize } from './canonical.js';
+import { sha256 } from './bundle.js';
+import { snapshotJsonValue } from './json-value.js';
+import { compileFlowToolSchema, FLOW_TOOL_LIMITS, type FlowToolObjectSchema } from './flow-tool-schema.js';
+import { parseFlowToolManifest, validateFlowToolInput, validateFlowToolResult, type FlowToolDigest } from './flow-tool-manifest.js';
+import {
+  FlowToolError, FLOW_TOOL_CATALOG_SCHEMA, FLOW_TOOL_RUN_SCHEMA, FLOW_TOOL_EVIDENCE_SCHEMA, FLOW_TOOL_EVENT_SCHEMA, FLOW_TOOL_INVOKE_SCHEMA,
+  type FlowToolCatalogV1, type FlowToolCatalogEntryV1, type FlowToolRunV1, type FlowToolEventV1, type FlowToolEvidenceV1, type FlowToolInvokeRequestV1,
+} from './flow-tool-contract.js';
+
+// Compile only our fixed protocol schemas; never cache caller-controlled schemas globally.
+const validators = new Map([FLOW_TOOL_CATALOG_SCHEMA, FLOW_TOOL_RUN_SCHEMA, FLOW_TOOL_EVIDENCE_SCHEMA, FLOW_TOOL_EVENT_SCHEMA, FLOW_TOOL_INVOKE_SCHEMA]
+  .map(schema => [schema, compileFlowToolSchema(schema)]));
+// FLOW_TOOL_LIMITS bounds one manifest, input, or result. A catalog holds up
+// to 64 of those documents, and a run or invoke envelope wraps one of them.
+// Snapshotting the envelope with the single-document budget rejects a valid
+// catalog or a near-limit result before that document is checked on its own.
+const CATALOG_TOOL_CAP = 64;
+export const FLOW_TOOL_ENVELOPE_LIMITS = Object.freeze({
+  maxDepth: FLOW_TOOL_LIMITS.maxDepth,
+  maxNodes: FLOW_TOOL_LIMITS.maxNodes * CATALOG_TOOL_CAP + FLOW_TOOL_LIMITS.maxNodes,
+  maxBytes: FLOW_TOOL_LIMITS.maxBytes * CATALOG_TOOL_CAP + FLOW_TOOL_LIMITS.maxBytes,
+});
+const ENVELOPE_SCHEMAS = new Set<FlowToolObjectSchema>([FLOW_TOOL_CATALOG_SCHEMA, FLOW_TOOL_RUN_SCHEMA, FLOW_TOOL_INVOKE_SCHEMA]);
+function wire<T>(value: unknown, schema: FlowToolObjectSchema): T {
+  try {
+    const snapshot = snapshotJsonValue(value, 'flow tool protocol', ENVELOPE_SCHEMAS.has(schema) ? FLOW_TOOL_ENVELOPE_LIMITS : FLOW_TOOL_LIMITS);
+    if (!validators.get(schema)!(snapshot)) throw new FlowToolError('invalid_contract');
+    return snapshot as T;
+  } catch { throw new FlowToolError('invalid_contract'); }
+}
+export function toolId(value: unknown): asserts value is string {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/.test(value)) throw new FlowToolError('invalid_contract');
+}
+function digest(value: unknown): asserts value is FlowToolDigest {
+  if (typeof value !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(value)) throw new FlowToolError('invalid_contract');
+}
+function decimal(value: string): void {
+  if (!/^(0|[1-9][0-9]*)(\.[0-9]+)?$/.test(value)) throw new FlowToolError('invalid_contract');
+}
+export function flowToolInputDigest(value: unknown): FlowToolDigest {
+  return `sha256:${sha256(canonicalize(snapshotJsonValue(value, 'flow tool input', FLOW_TOOL_LIMITS)))}`;
+}
+export function parseFlowToolCatalog(value: unknown): FlowToolCatalogV1 {
+  const catalog = wire<FlowToolCatalogV1>(value, FLOW_TOOL_CATALOG_SCHEMA);
+  const names = new Set<string>();
+  for (const entry of catalog.tools) {
+    try { parseFlowToolManifest(entry.manifest); } catch { throw new FlowToolError('invalid_contract'); }
+    toolId(entry.deployment_id);
+    if (names.has(entry.manifest.name)) throw new FlowToolError('invalid_contract');
+    names.add(entry.manifest.name);
+    for (const name of [...entry.business_verdicts, ...entry.requires_human]) toolId(name);
+    // Policy labels are not enforcement. The server must also bind read_only to
+    // effective capabilities; this v1 client will not accept a write-enabled entry.
+    if (entry.effects.some(effect => !/^[a-z][a-z0-9_-]*:read$/.test(effect))) throw new FlowToolError('invalid_contract');
+    if (entry.budget.max_dollars !== null) {
+      if (entry.budget.max_dollars.length > 128) throw new FlowToolError('invalid_contract');
+      decimal(entry.budget.max_dollars);
+    }
+  }
+  return catalog;
+}
+export function parseFlowToolEntry(value: unknown): FlowToolCatalogEntryV1 {
+  return parseFlowToolCatalog({ api_version: 1, tools: [value] }).tools[0]!;
+}
+/** Stable discovery serialization independent of input key or catalog ordering. */
+export function canonicalFlowToolCatalog(value: unknown): string {
+  const catalog = parseFlowToolCatalog(value);
+  return canonicalize({ api_version: 1, tools: [...catalog.tools].sort((a, b) =>
+    a.manifest.name < b.manifest.name ? -1 : a.manifest.name > b.manifest.name ? 1 : 0) });
+}
+/** Shared admission validation; this proves a contract binding, not authorization. */
+export function parseFlowToolInvocation(value: unknown, selected: FlowToolCatalogEntryV1): FlowToolInvokeRequestV1 {
+  const entry = parseFlowToolEntry(selected);
+  const request = wire<FlowToolInvokeRequestV1>(value, FLOW_TOOL_INVOKE_SCHEMA);
+  if (request.flow !== `${entry.manifest.flow.name}@${entry.manifest.flow.digest}`
+    || request.deployment_id !== entry.deployment_id || request.manifest_digest !== entry.manifest.digest
+    || (request.mode === 'async' && request.wait_ms !== 0)) throw new FlowToolError('invalid_contract');
+  let input: unknown;
+  try { input = validateFlowToolInput(entry.manifest, request.input); } catch { throw new FlowToolError('invalid_contract'); }
+  if (flowToolInputDigest(input) !== request.input_digest) throw new FlowToolError('invalid_contract');
+  return request;
+}
+export function parseFlowToolEvidence(value: unknown, flowDigest: FlowToolDigest): FlowToolEvidenceV1 {
+  const evidence = wire<FlowToolEvidenceV1>(value, FLOW_TOOL_EVIDENCE_SCHEMA);
+  digest(evidence.journal_digest);
+  if (evidence.flow_digest !== flowDigest) throw new FlowToolError('invalid_contract');
+  const refs = new Set<string>();
+  for (const artifact of evidence.artifacts) {
+    toolId(artifact.name); toolId(artifact.ref);
+    if (refs.has(artifact.ref) || !/^[a-z0-9.+-]+\/[a-z0-9.+-]+$/.test(artifact.media_type)) throw new FlowToolError('invalid_contract');
+    refs.add(artifact.ref);
+  }
+  evidence.redacted_transcript_refs.forEach(toolId);
+  return evidence;
+}
+export function flowToolRunLinks(runId: string) {
+  toolId(runId);
+  const path = `/api/v1/flow-runs/${runId}`;
+  return { status_url: path, events_url: `${path}/events`, evidence_url: `${path}/evidence`, cancel_url: `${path}/cancel`, resume_url: `${path}/resume` };
+}
+export function parseFlowToolRun(value: unknown, selected: FlowToolCatalogEntryV1, previous?: FlowToolRunV1): FlowToolRunV1 {
+  const run = wire<FlowToolRunV1>(value, FLOW_TOOL_RUN_SCHEMA);
+  toolId(run.run_id); digest(run.input_digest);
+  if (run.tool_name !== selected.manifest.name || run.deployment_id !== selected.deployment_id
+    || run.manifest_digest !== selected.manifest.digest || run.flow_digest !== selected.manifest.flow.digest) throw new FlowToolError('invalid_contract');
+  for (const [key, url] of Object.entries(flowToolRunLinks(run.run_id))) {
+    if (run[key as keyof FlowToolRunV1] !== url) throw new FlowToolError('invalid_contract');
+  }
+  const terminal = ['completed', 'failed', 'cancelled'].includes(run.state);
+  if (terminal !== (run.terminal !== null)) throw new FlowToolError('invalid_contract');
+  if (run.terminal !== null) {
+    const result = run.terminal;
+    const success = result.terminal_reason === 'success';
+    if (success !== (run.state === 'completed') || (run.state === 'cancelled') !== (result.terminal_reason === 'canceled')) throw new FlowToolError('invalid_contract');
+    if (success) {
+      if (result.business_verdict === null || !selected.business_verdicts.includes(result.business_verdict) || result.result === null) throw new FlowToolError('invalid_contract');
+      try { validateFlowToolResult(selected.manifest, result.result); } catch { throw new FlowToolError('invalid_contract'); }
+    } else if (result.business_verdict !== null || result.result !== null) throw new FlowToolError('invalid_contract');
+    const evidence = parseFlowToolEvidence(result.evidence, run.flow_digest);
+    const refs = new Set(evidence.artifacts.map(artifact => artifact.ref));
+    const gateNames = new Set<string>();
+    for (const gate of result.gates) {
+      toolId(gate.name); toolId(gate.evidence_ref);
+      if (!refs.has(gate.evidence_ref) || gateNames.has(gate.name)) throw new FlowToolError('invalid_contract');
+      gateNames.add(gate.name);
+    }
+    decimal(result.spend.dollars);
+    if (selected.budget.max_dollars !== null && result.spend.dollars_unmetered) throw new FlowToolError('invalid_contract');
+  }
+  if (previous !== undefined) {
+    if (run.run_id !== previous.run_id || run.input_digest !== previous.input_digest || run.sequence < previous.sequence
+      || (run.sequence === previous.sequence && canonicalize(run) !== canonicalize(previous))
+      || (previous.terminal !== null && canonicalize(run) !== canonicalize(previous))) throw new FlowToolError('invalid_contract');
+  }
+  return run;
+}
+export function parseFlowToolEvent(value: unknown, run: FlowToolRunV1, cursor: number): FlowToolEventV1 {
+  const event = wire<FlowToolEventV1>(value, FLOW_TOOL_EVENT_SCHEMA);
+  if (event.run_id !== run.run_id || event.flow_digest !== run.flow_digest || event.sequence <= cursor) throw new FlowToolError('invalid_contract');
+  if (event.step_id !== undefined) toolId(event.step_id);
+  if (event.wait_id !== undefined) toolId(event.wait_id);
+  const terminal = ['completed', 'failed', 'cancelled'].includes(event.state);
+  if ((event.type === 'run.terminal') !== terminal || terminal !== (event.terminal_reason !== undefined)
+    || (event.type === 'run.accepted' && event.state !== 'accepted')
+    || (event.type !== 'human.required' && event.wait_id !== undefined)
+    || (event.type === 'human.required' && (event.wait_id === undefined || event.state !== 'parked'))
+    || (event.type === 'step.completed' && event.step_id === undefined)
+    || (terminal && ((event.state === 'completed') !== (event.terminal_reason === 'success')
+      || (event.state === 'cancelled') !== (event.terminal_reason === 'canceled')))) throw new FlowToolError('invalid_contract');
+  return event;
+}