@relayflows/sdk 2.0.44 → 2.0.46

package/src/cli/direct-run.ts

@@ -1,3 +1,4 @@
+import { resumeCommand } from '../authored-human.js';
 import { completedResultUnreadableReport, daemonUnresponsiveReport, isReadInterruption } from './journal-timeout.js';
 import { FLOW_READ_BUDGET_MS } from '../journal-read-policy.js';
 import { onWorkerFailure } from '../worker-lease.js';
@@ -179,6 +180,12 @@ export async function runDirectFlow(
         },
       };
     }
+    if (error instanceof AuthoredFlowExecutionError && error.code === 'helper_writeback_pending') {
+      return { exitCode: 3, report: { ...base, ok: false,
+        runId: error.rootRunId ?? error.runId, rootRunId: error.rootRunId, socketPath, status: 'parked',
+        diagnostics: [...base.diagnostics, { severity: 'parked', kind: error.code,
+          message: error.message + ` Continue with: ${resumeCommand(error.rootRunId ?? error.runId!, dataDir, options.localAgent === true)}.` }] } };
+    }
     if (error instanceof AuthoredFlowExecutionError && (error.code === 'agent_parked' || error.code === 'llm_parked')) {
       return {
         exitCode: 3,

package/src/cli/run.ts

@@ -12,6 +12,7 @@ import { attachReuseSummary } from './reuse.js';
 import { resumeHelperEffect } from '../authored-helper-effect.js';
 import { AuthoredFlowExecutionError, AuthoredHumanParked, type AuthoredHumanWait } from '../authored-flow-error.js';
 import { answerCommand, resumeCommand } from '../authored-human.js';
+import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import type { ProgressEvent } from '../progress.js';
 import type { JournalEvent } from '../journal-reader.js';
@@ -255,7 +256,14 @@ async function executeCheckedFlow(
         diagnostics: [...base.diagnostics, { severity: failed ? 'failure' : 'refusal',
           kind: error.code, message: error.message }] } };
     }
-    return protocolFailure('run', base, socketPath, communicationWorkers?.failure ?? localAgent?.failure ?? error);
+    const cause = communicationWorkers?.failure ?? localAgent?.failure ?? error;
+    if (cause instanceof AuthoredFlowExecutionError && cause.code === 'helper_writeback_pending') {
+      return { exitCode: 3, report: { ...base, ok: false, runId: cause.rootRunId ?? cause.runId ?? base.runId,
+        rootRunId: cause.rootRunId, socketPath, status: 'parked',
+        diagnostics: [...base.diagnostics, { severity: 'parked', kind: cause.code,
+          message: cause.message + ` Continue with: ${resumeCommand(cause.rootRunId ?? cause.runId ?? base.runId ?? '', dataDir, options.localAgent === true)}.` }] } };
+    }
+    return protocolFailure('run', base, socketPath, cause);
   } finally {
     if (options.onJournalEntry !== undefined) client.off('entry', options.onJournalEntry);
     try { await communicationWorkers?.close(); } finally { try { await localAgent?.close(); } finally { client.close(); } }
@@ -364,7 +372,11 @@ export async function resumeFlow(
     // slack effect resume plus every other provider from N's codegen. The
     // second call the earlier rebase left is a stale reference from before
     // the helper fanout renamed the API.
-    if (options.localAgent) {
+    // A helper child brings its own worker in resumeHelperEffect. A local agent
+    // pinned to that stream first receives the park's redispatch and does not
+    // understand the authored helper instruction.
+    const helperChild = existsSync(join(dataDir, 'helper-runs', `${runId}.json`));
+    if (options.localAgent && !helperChild) {
       const entries = (await client.journalRead(runId, 1)).entries as Array<{ entry_type: string; payload?: { spec?: import('../spec.js').KernelRunSpec } }>;
       const spec = entries.find(entry => entry.entry_type === 'run.spawned')?.payload?.spec;
       if (!spec) throw new Error('Cannot attach a local worker: the journaled run spec is missing');
@@ -384,6 +396,12 @@ export async function resumeFlow(
       // the run unprojected, and the resume below reports the run's own fate.
       await client.runWatch(runId).catch(() => client.off('entry', onEntry));
     }
+    // A helper child answers its own park after its worker attaches.
+    // Emitting here, with no worker, journals the next attempt as a crash.
+    if (options.localAgent && !helperChild) {
+      const { releaseHelperReceiptWaits } = await import('../helper-park.js');
+      await releaseHelperReceiptWaits(client, runId);
+    }
     let outcome = await client.runResume(runId, options.allowHumanInfluenced);
     options.onRunReceipt?.({ runId, flow: 'flow' });
     if (await resumeHelperEffect(client, runId, dataDir)) {
@@ -432,6 +450,16 @@ export async function resumeFlow(
     // only honest instruction is a new run carrying the same `--input`.
     // `runId` here is the CHILD run holding the evidence; the root this resume
     // named stays separate, so `flows` can still collect it.
+    const pending = error instanceof AuthoredFlowExecutionError && error.code === 'helper_writeback_pending'
+      ? error
+      : authoredAgent?.failure instanceof AuthoredFlowExecutionError && authoredAgent.failure.code === 'helper_writeback_pending'
+        ? authoredAgent.failure : undefined;
+    if (pending !== undefined) {
+      return { exitCode: 3, report: { ...base, ok: false,
+        runId: pending.rootRunId ?? pending.runId, rootRunId: pending.rootRunId, socketPath, status: 'parked',
+        diagnostics: [...base.diagnostics, { severity: 'parked', kind: 'helper_writeback_pending',
+          message: pending.message + ` Continue with: ${resumeCommand(pending.rootRunId ?? pending.runId ?? runId, dataDir, options.localAgent === true)}.` }] } };
+    }
     if (error instanceof AuthoredFlowExecutionError && (error.code === 'agent_parked' || error.code === 'llm_parked')) {
       return {
         exitCode: 3,

package/src/cloud-mirror-step.ts

@@ -416,7 +416,12 @@ function finalStep(
   const summary = text(verification?.detail, env, OUTPUT_SUMMARY_MAX_CHARS)
     ?? `step ${succeeded ? 'completed' : 'ended'}: ${identifier(completionReason, env) ?? 'unknown'}`;
   const model = identifier(transcript?.model, env);
-  const error = succeeded ? undefined : text(failure?.excerpt, env, ERROR_MAX_CHARS);
+  // Agent attempts carry a transcript failure excerpt; deterministic timeouts
+  // do not. Their execution failure is journaled in verification.detail, so
+  // fall back to that same record for a timeout instead of publishing a failed
+  // dashboard row with an empty error column.
+  const error = succeeded ? undefined : text(failure?.excerpt, env, ERROR_MAX_CHARS)
+    ?? (completionReason === 'timeout' ? text(verification?.detail, env, ERROR_MAX_CHARS) : undefined);
   return {
     stepName,
     stepType,

package/src/compile.ts

@@ -75,6 +75,7 @@ export class CompileError extends Error {
  * being rejected by `isSafeInteger`.
  */
 export const AGENT_STEP_TIMEOUT_MAX_MS = 60 * 60_000;
+export const RUN_STEP_TIMEOUT_MAX_MS = 15 * 60_000;
 export function parseAgentStepTimeout(timeout: unknown): number {
   return parseStepTimeout(timeout, true);
 }
@@ -103,7 +104,7 @@ export function parseStepTimeout(timeout: unknown, agent = false): number {
   if (!Number.isSafeInteger(milliseconds) || milliseconds <= 0) {
     throw new CompileError([`${agent ? 'f.agent' : 'f.run'} timeout must be a positive whole number of milliseconds or a duration such as "10s" or "5m".`], 'timeout_invalid');
   }
-  if (milliseconds > (agent ? AGENT_STEP_TIMEOUT_MAX_MS : 15 * 60_000)) {
+  if (milliseconds > (agent ? AGENT_STEP_TIMEOUT_MAX_MS : RUN_STEP_TIMEOUT_MAX_MS)) {
     throw new CompileError([`${agent ? 'f.agent' : 'f.run'} timeout exceeds the maximum of ${agent ? 60 : 15} minutes declared in SURFACE.md.`], 'lease_exceeded');
   }
   return milliseconds;

package/src/failure-kinds.ts

@@ -161,6 +161,7 @@ export const RUN_FAILURE_KINDS = [
    */
   'daemon_unresponsive',
   'root_lease_lost',
+  'helper_writeback_pending',
 ] as const;
 
 /**

package/src/flow-tool-adapters.ts

@@ -0,0 +1,43 @@
+import { canonicalize } from './canonical.js';
+import { FlowToolClient, type FlowToolInvocationOptions } from './flow-tool-client.js';
+import { flowToolFunctionDefinition } from './flow-tool-definitions.js';
+import { FLOW_TOOL_RUN_SCHEMA, type FlowToolCatalogEntryV1 } from './flow-tool-contract.js';
+import { parseFlowToolEntry } from './flow-tool-wire.js';
+
+/**
+ * One selected, authorized revision; no alternate execution path. Host/session
+ * code supplies stable operation metadata separately from model tool arguments.
+ * Register only after discovery with this same authenticated client. The server
+ * MUST reauthorize; possession of this object is not an authorization token.
+ */
+export function createFlowToolAdapters(client: FlowToolClient, selected: FlowToolCatalogEntryV1) {
+  const entry = parseFlowToolEntry(selected);
+  const invoke = (input: unknown, operation: FlowToolInvocationOptions) => client.invoke(entry, input, operation);
+  return Object.freeze({
+    native: Object.freeze({ definition: flowToolFunctionDefinition(entry.manifest), call: invoke }),
+    mcp: Object.freeze({
+      // Do not reuse the legacy business-result-only metadata descriptor here:
+      // tools/call returns an async run envelope, not the eventual result object.
+      definition: Object.freeze({
+        name: entry.manifest.name, description: entry.manifest.description,
+        inputSchema: entry.manifest.inputSchema, outputSchema: FLOW_TOOL_RUN_SCHEMA,
+      }),
+      async call(input: unknown, operation: FlowToolInvocationOptions) {
+        const run = await invoke(input, operation);
+        return {
+          structuredContent: Object.freeze({ ...run }),
+          content: [{ type: 'text' as const, text: canonicalize(run) }],
+        };
+      },
+    }),
+    // Relay action registration can use this schema/handler. An action dispatch
+    // acknowledgment is not this return value and must never become completion.
+    action: Object.freeze({
+      definition: Object.freeze({
+        name: entry.manifest.name, description: entry.manifest.description,
+        inputSchema: entry.manifest.inputSchema, outputSchema: FLOW_TOOL_RUN_SCHEMA,
+      }),
+      invoke,
+    }),
+  });
+}

package/src/flow-tool-client.ts

@@ -0,0 +1,115 @@
+import { canonicalize } from './canonical.js';
+import { snapshotJsonValue } from './json-value.js';
+import { FLOW_TOOL_LIMITS } from './flow-tool-schema.js';
+import { validateFlowToolInput } from './flow-tool-manifest.js';
+import { FlowToolError, type FlowToolCatalogEntryV1, type FlowToolRunV1, type FlowToolEventV1 } from './flow-tool-contract.js';
+import { parseFlowToolCatalog, parseFlowToolEntry, parseFlowToolRun, parseFlowToolEvent, parseFlowToolEvidence, flowToolInputDigest, toolId } from './flow-tool-wire.js';
+
+export interface FlowToolRequest {
+  readonly method: 'GET' | 'POST';
+  readonly path: string;
+  readonly body?: unknown;
+  readonly idempotencyKey?: string;
+}
+/**
+ * Authenticated control-plane boundary. Implementations must authorize every
+ * operation and durably admit/deduplicate runs; the client owns no run ledger.
+ * A test transport is not a hosted implementation. No source-submission fallback.
+ */
+export interface FlowToolTransport {
+  request(request: FlowToolRequest): Promise<unknown>;
+  events(path: string, after: number): AsyncIterable<unknown>;
+}
+export interface FlowToolInvocationOptions {
+  /** Host-owned operation identity; preserve across reconnect/retry, never generate per retry. */
+  readonly idempotencyKey: string;
+  readonly mode?: 'async' | 'sync';
+  /** Server-side observation bound only, not an execution timeout or cancellation. */
+  readonly waitMs?: number;
+}
+export function flowToolOperationKey(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');
+}
+
+export class FlowToolClient {
+  constructor(private readonly transport: FlowToolTransport) {}
+
+  async discover() {
+    return parseFlowToolCatalog(await this.transport.request({ method: 'GET', path: '/api/v1/flow-tools' }));
+  }
+
+  async invoke(selected: FlowToolCatalogEntryV1, input: unknown, options: FlowToolInvocationOptions): Promise<FlowToolRunV1> {
+    const entry = parseFlowToolEntry(selected);
+    // Schema validation precedes ALL transport calls, including credential access.
+    let validated: ReturnType<typeof validateFlowToolInput>;
+    try { validated = validateFlowToolInput(entry.manifest, input); }
+    catch { throw new FlowToolError('invalid_contract'); }
+    flowToolOperationKey(options.idempotencyKey);
+    const mode = options.mode ?? 'async';
+    const waitMs = options.waitMs ?? 0;
+    if (!['async', 'sync'].includes(mode) || !Number.isSafeInteger(waitMs) || waitMs < 0 || waitMs > 25_000
+      || (mode === 'async' && waitMs !== 0)) throw new FlowToolError('invalid_contract');
+    const inputDigest = flowToolInputDigest(validated);
+    const body = {
+      api_version: 1, flow: `${entry.manifest.flow.name}@${entry.manifest.flow.digest}`,
+      deployment_id: entry.deployment_id, manifest_digest: entry.manifest.digest,
+      input: validated, input_digest: inputDigest, mode, wait_ms: waitMs,
+    };
+    const run = parseFlowToolRun(await this.transport.request({
+      method: 'POST', path: `/api/v1/flow-tools/${entry.manifest.name}/invoke`, body, idempotencyKey: options.idempotencyKey,
+    }), entry);
+    if (run.input_digest !== inputDigest) throw new FlowToolError('invalid_contract');
+    return run;
+  }
+
+  async status(selected: FlowToolCatalogEntryV1, receipt: FlowToolRunV1): Promise<FlowToolRunV1> {
+    const entry = parseFlowToolEntry(selected), run = parseFlowToolRun(receipt, entry);
+    return parseFlowToolRun(await this.transport.request({ method: 'GET', path: run.status_url }), entry, run);
+  }
+
+  async *events(selected: FlowToolCatalogEntryV1, receipt: FlowToolRunV1, after = 0): AsyncIterable<FlowToolEventV1> {
+    const run = parseFlowToolRun(receipt, parseFlowToolEntry(selected));
+    if (!Number.isSafeInteger(after) || after < 0) throw new FlowToolError('invalid_contract');
+    let cursor = after;
+    for await (const raw of this.transport.events(run.events_url, after)) {
+      const event = parseFlowToolEvent(raw, run, cursor);
+      cursor = event.sequence;
+      yield event;
+      if (event.type === 'run.terminal') return;
+    }
+  }
+
+  async evidence(selected: FlowToolCatalogEntryV1, receipt: FlowToolRunV1) {
+    const run = parseFlowToolRun(receipt, parseFlowToolEntry(selected));
+    const response = await this.transport.request({ method: 'GET', path: run.evidence_url });
+    let raw: ReturnType<typeof snapshotJsonValue>;
+    try { raw = snapshotJsonValue(response, 'flow tool evidence', FLOW_TOOL_LIMITS); }
+    catch { throw new FlowToolError('invalid_contract'); }
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)
+      || Object.keys(raw).sort().join(',') !== 'api_version,evidence,run_id'
+      || raw.api_version !== 1 || raw.run_id !== run.run_id) throw new FlowToolError('invalid_contract');
+    const evidence = parseFlowToolEvidence(raw.evidence, run.flow_digest);
+    if (run.terminal !== null && canonicalize(evidence) !== canonicalize(run.terminal.evidence)) throw new FlowToolError('invalid_contract');
+    return evidence;
+  }
+
+  cancel(selected: FlowToolCatalogEntryV1, receipt: FlowToolRunV1, key: string) {
+    return this.command(selected, receipt, '/cancel', key, { api_version: 1 });
+  }
+  resume(selected: FlowToolCatalogEntryV1, receipt: FlowToolRunV1, key: string) {
+    return this.command(selected, receipt, '/resume', key, { api_version: 1 });
+  }
+  answer(selected: FlowToolCatalogEntryV1, receipt: FlowToolRunV1, waitId: string, approved: boolean, key: string) {
+    toolId(waitId);
+    if (typeof approved !== 'boolean') throw new FlowToolError('invalid_contract');
+    // No answered_by claim: the server derives/audits the authenticated human actor.
+    return this.command(selected, receipt, `/human/${waitId}/answer`, key, { api_version: 1, input: { approved } });
+  }
+  private async command(selected: FlowToolCatalogEntryV1, receipt: FlowToolRunV1, suffix: string, key: string, body: unknown) {
+    const entry = parseFlowToolEntry(selected), run = parseFlowToolRun(receipt, entry);
+    flowToolOperationKey(key);
+    return parseFlowToolRun(await this.transport.request({
+      method: 'POST', path: `${run.status_url}${suffix}`, idempotencyKey: key, body,
+    }), entry, run);
+  }
+}

package/src/flow-tool-contract.ts

@@ -0,0 +1,153 @@
+import type { FlowToolDigest, FlowToolManifestV1 } from './flow-tool-manifest.js';
+import type { FlowToolJson, FlowToolObjectSchema } from './flow-tool-schema.js';
+import type { Spend } from './run-state.js';
+import { snapshotJsonValue } from './json-value.js';
+import { FLOW_TOOL_LIMITS } from './flow-tool-schema.js';
+
+export const FLOW_TOOL_API_VERSION = 1 as const;
+export const FLOW_TOOL_TERMINAL_REASONS = [
+  'success', 'gate_failed', 'model_failed', 'agent_failed', 'budget_exceeded',
+  'human_rejected', 'human_timeout', 'canceled', 'execution_failed',
+] as const;
+export type FlowToolTerminalReason = typeof FLOW_TOOL_TERMINAL_REASONS[number];
+export type FlowToolRunState = 'accepted' | 'running' | 'parked' | 'cancelling' | 'completed' | 'failed' | 'cancelled';
+
+/** Operator-owned, server-authorized read-only revision; never generated from run input. */
+export interface FlowToolCatalogEntryV1 {
+  readonly manifest: FlowToolManifestV1;
+  readonly deployment_id: string;
+  readonly read_only: true;
+  readonly effects: readonly string[];
+  readonly requires_human: readonly string[];
+  readonly business_verdicts: readonly string[];
+  readonly budget: Readonly<{ max_tokens: number; max_dollars: string | null; max_wallclock_ms: number }>;
+}
+export interface FlowToolCatalogV1 {
+  readonly api_version: 1;
+  readonly tools: readonly FlowToolCatalogEntryV1[];
+}
+export interface FlowToolEvidenceV1 {
+  readonly journal_digest: FlowToolDigest;
+  readonly flow_digest: FlowToolDigest;
+  readonly artifacts: readonly Readonly<{ name: string; ref: string; media_type: string }>[];
+  readonly redacted_transcript_refs: readonly string[];
+}
+export interface FlowToolTerminalV1 {
+  readonly terminal_reason: FlowToolTerminalReason;
+  readonly business_verdict: string | null;
+  readonly result: Readonly<Record<string, FlowToolJson>> | null;
+  readonly gates: readonly Readonly<{ name: string; status: 'pass' | 'fail' | 'skipped'; evidence_ref: string }>[];
+  readonly evidence: FlowToolEvidenceV1;
+  readonly spend: Readonly<Spend>;
+}
+/** Accepted is durable admission, never successful execution; terminal is null until finished. */
+export interface FlowToolRunV1 {
+  readonly api_version: 1;
+  readonly accepted: true;
+  readonly run_id: string;
+  readonly tool_name: string;
+  readonly deployment_id: string;
+  readonly manifest_digest: FlowToolDigest;
+  readonly flow_digest: FlowToolDigest;
+  readonly input_digest: FlowToolDigest;
+  readonly state: FlowToolRunState;
+  readonly sequence: number;
+  readonly status_url: string;
+  readonly events_url: string;
+  readonly evidence_url: string;
+  readonly cancel_url: string;
+  readonly resume_url: string;
+  readonly terminal: FlowToolTerminalV1 | null;
+}
+export interface FlowToolEventV1 {
+  readonly api_version: 1;
+  readonly run_id: string;
+  readonly flow_digest: FlowToolDigest;
+  readonly sequence: number;
+  readonly type: 'run.accepted' | 'run.state_changed' | 'step.completed' | 'human.required' | 'run.terminal';
+  readonly state: FlowToolRunState;
+  readonly step_id?: string;
+  readonly wait_id?: string;
+  readonly terminal_reason?: FlowToolTerminalReason;
+}
+export interface FlowToolInvokeRequestV1 {
+  readonly api_version: 1;
+  readonly flow: string;
+  readonly deployment_id: string;
+  readonly manifest_digest: FlowToolDigest;
+  readonly input: Readonly<Record<string, FlowToolJson>>;
+  /** Assertion only: admission MUST recompute this from schema-validated canonical input. */
+  readonly input_digest: FlowToolDigest;
+  readonly mode: 'async' | 'sync';
+  readonly wait_ms: number;
+}
+export type FlowToolFailureCode = 'invalid_contract' | 'not_authorized' | 'not_found'
+  | 'idempotency_conflict' | 'unsupported' | 'unavailable' | 'transport_error';
+export class FlowToolError extends Error {
+  constructor(readonly code: FlowToolFailureCode) {
+    // Never interpolate remote bodies, model input, bearer tokens or transport errors.
+    super(`Flow Tool ${code}${code === 'transport_error' ? ': admission or command outcome may be unknown; observation failure does not cancel a run' : ''}`);
+    this.name = 'FlowToolError';
+  }
+}
+
+const text = { type: 'string', minLength: 1, maxLength: 128 };
+const digest = { type: 'string', minLength: 71, maxLength: 71 };
+const integer = { type: 'integer', minimum: 0, maximum: Number.MAX_SAFE_INTEGER };
+const positive = { ...integer, minimum: 1 };
+const strings = { type: 'array', items: text, maxItems: 64, uniqueItems: true };
+const state = { enum: ['accepted', 'running', 'parked', 'cancelling', 'completed', 'failed', 'cancelled'] };
+function object(properties: Record<string, unknown>, required = Object.keys(properties)) {
+  return snapshotJsonValue({ type: 'object', properties, required, additionalProperties: false },
+    'flow tool protocol schema', FLOW_TOOL_LIMITS) as FlowToolObjectSchema;
+}
+export const FLOW_TOOL_EVIDENCE_SCHEMA = object({
+  journal_digest: digest, flow_digest: digest,
+  artifacts: { type: 'array', maxItems: 128, items: object({ name: text, ref: text, media_type: text }) },
+  redacted_transcript_refs: strings,
+}) as FlowToolObjectSchema;
+const terminal = object({
+  terminal_reason: { enum: FLOW_TOOL_TERMINAL_REASONS },
+  business_verdict: { type: ['string', 'null'], minLength: 1, maxLength: 128 },
+  result: { type: ['object', 'null'] },
+  gates: { type: 'array', maxItems: 128, items: object({ name: text, status: { enum: ['pass', 'fail', 'skipped'] }, evidence_ref: text }) },
+  evidence: FLOW_TOOL_EVIDENCE_SCHEMA,
+  spend: object({ tokens_in: integer, tokens_out: integer, dollars: text, dollars_unmetered: { type: 'boolean' } }),
+});
+/** Async adapters return this envelope, NOT the flow's eventual business-result schema. */
+export const FLOW_TOOL_RUN_SCHEMA = object({
+  api_version: { const: 1 }, accepted: { const: true }, run_id: text, tool_name: text,
+  deployment_id: text, manifest_digest: digest, flow_digest: digest, input_digest: digest,
+  state, sequence: integer,
+  status_url: { type: 'string' }, events_url: { type: 'string' }, evidence_url: { type: 'string' },
+  cancel_url: { type: 'string' }, resume_url: { type: 'string' },
+  terminal: { anyOf: [{ type: 'null' }, terminal] },
+}) as FlowToolObjectSchema;
+export const FLOW_TOOL_CATALOG_SCHEMA = object({
+  api_version: { const: 1 },
+  tools: { type: 'array', maxItems: 64, items: object({
+    manifest: { type: 'object' }, deployment_id: text, read_only: { const: true },
+    effects: strings, requires_human: strings,
+    business_verdicts: { ...strings, minItems: 1 },
+    budget: object({ max_tokens: positive, max_dollars: { type: ['string', 'null'] }, max_wallclock_ms: positive }),
+  }) },
+}) as FlowToolObjectSchema;
+export const FLOW_TOOL_EVENT_SCHEMA = object({
+  api_version: { const: 1 }, run_id: text, flow_digest: digest, sequence: positive,
+  type: { enum: ['run.accepted', 'run.state_changed', 'step.completed', 'human.required', 'run.terminal'] },
+  state, step_id: text, wait_id: text, terminal_reason: { enum: FLOW_TOOL_TERMINAL_REASONS },
+}, ['api_version', 'run_id', 'flow_digest', 'sequence', 'type', 'state']) as FlowToolObjectSchema;
+
+export const FLOW_TOOL_INVOKE_SCHEMA = object({
+  api_version: { const: 1 }, flow: { type: 'string', minLength: 73, maxLength: 200 },
+  deployment_id: text, manifest_digest: digest, input_digest: digest,
+  input: { type: 'object' }, mode: { enum: ['async', 'sync'] },
+  wait_ms: { type: 'integer', minimum: 0, maximum: 25000 },
+}) as FlowToolObjectSchema;
+export const FLOW_TOOL_COMMAND_SCHEMA = object({ api_version: { const: 1 } }) as FlowToolObjectSchema;
+export const FLOW_TOOL_ANSWER_SCHEMA = object({
+  api_version: { const: 1 }, input: object({ approved: { type: 'boolean' } }),
+}) as FlowToolObjectSchema;
+export const FLOW_TOOL_ERROR_SCHEMA = object({
+  api_version: { const: 1 }, code: { enum: ['invalid_contract', 'not_authorized', 'not_found', 'idempotency_conflict', 'unsupported', 'unavailable'] },
+}) as FlowToolObjectSchema;

package/src/flow-tool-definitions.ts

@@ -0,0 +1,27 @@
+import { parseFlowToolManifest, type FlowToolManifestV1 } from './flow-tool-manifest.js';
+import type { FlowToolObjectSchema } from './flow-tool-schema.js';
+
+export interface FlowToolFunctionDefinition {
+  readonly type: 'function';
+  readonly name: string;
+  readonly description: string;
+  readonly parameters: FlowToolObjectSchema;
+}
+export interface FlowToolMcpDefinition {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: FlowToolObjectSchema;
+  readonly outputSchema: FlowToolObjectSchema;
+}
+
+/** Plain function-call descriptor. Provider-specific strict-mode translation is not implied. */
+export function flowToolFunctionDefinition(value: FlowToolManifestV1): FlowToolFunctionDefinition {
+  const manifest = parseFlowToolManifest(value);
+  return Object.freeze({ type: 'function', name: manifest.name, description: manifest.description, parameters: manifest.inputSchema });
+}
+
+/** MCP tools/list metadata only: no server, call handler, authority, or idempotency claim. */
+export function flowToolMcpDefinition(value: FlowToolManifestV1): FlowToolMcpDefinition {
+  const manifest = parseFlowToolManifest(value);
+  return Object.freeze({ name: manifest.name, description: manifest.description, inputSchema: manifest.inputSchema, outputSchema: manifest.resultSchema });
+}

package/src/flow-tool-http.ts

@@ -0,0 +1,134 @@
+import { canonicalize } from './canonical.js';
+import { cloudConnection } from './cloud-http.js';
+import { FlowToolError } from './flow-tool-contract.js';
+import { flowToolOperationKey, type FlowToolRequest, type FlowToolTransport } from './flow-tool-client.js';
+import { FLOW_TOOL_ENVELOPE_LIMITS } from './flow-tool-wire.js';
+
+export interface FlowToolHttpOptions {
+  /** Explicit trusted HTTPS API origin/base path. No implicit production endpoint. */
+  readonly apiUrl: string;
+  /** Dedicated scoped bearer; never included in definitions, bodies, errors or persisted state. */
+  readonly token: string;
+  readonly requestTimeoutMs?: number;
+  readonly signal?: AbortSignal;
+  /** Test/integration seam; the default is the standard fetch implementation. */
+  readonly fetch?: typeof fetch;
+}
+
+function pathIsSafe(path: string): boolean {
+  return /^\/api\/v1\/flow-tools(?:\/[A-Za-z_][A-Za-z0-9_-]{0,63}\/invoke)?$/.test(path)
+    || /^\/api\/v1\/flow-runs\/[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}(?:\/(?:events|evidence|cancel|resume)|\/human\/[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}\/answer)?$/.test(path);
+}
+async function* chunks(response: Response, maximumBytes: number): AsyncIterable<string> {
+  if (!response.body) throw new FlowToolError('invalid_contract');
+  const reader = response.body.getReader(), decoder = new TextDecoder('utf-8', { fatal: true });
+  let size = 0;
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      size += chunk.value.byteLength;
+      if (size > maximumBytes) throw new FlowToolError('invalid_contract');
+      yield decoder.decode(chunk.value, { stream: true });
+    }
+    yield decoder.decode();
+  } finally { await reader.cancel().catch(() => {}); reader.releaseLock(); }
+}
+function refuse(status: number): never {
+  const code = status === 400 || status === 422 ? 'invalid_contract' : status === 401 || status === 403 ? 'not_authorized' : status === 404 ? 'not_found'
+    : status === 409 ? 'idempotency_conflict' : status === 501 ? 'unsupported' : 'unavailable';
+  throw new FlowToolError(code);
+}
+function safeError(error: unknown): never {
+  if (error instanceof FlowToolError) throw error;
+  throw new FlowToolError('transport_error');
+}
+
+/** No automatic retry; the owner can repeat the same operation key after an ambiguous failure. */
+export function createFlowToolHttpTransport(options: FlowToolHttpOptions): FlowToolTransport {
+  // Reuse existing HTTPS/token validation, but never fall back to its ambient login store.
+  if (typeof options.apiUrl !== 'string' || typeof options.token !== 'string') throw new FlowToolError('invalid_contract');
+  let connection: { baseUrl: string; token: string };
+  try { connection = cloudConnection({ apiUrl: options.apiUrl, token: options.token }); }
+  catch { throw new FlowToolError('not_authorized'); }
+  const timeout = options.requestTimeoutMs ?? 30_000;
+  if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 120_000) throw new FlowToolError('invalid_contract');
+  const fetcher = options.fetch ?? globalThis.fetch;
+  async function response(path: string, init: RequestInit, accept: string): Promise<Response> {
+    if (!pathIsSafe(path)) throw new FlowToolError('invalid_contract');
+    const signal = AbortSignal.any([AbortSignal.timeout(timeout), ...(options.signal ? [options.signal] : [])]);
+    const result = await fetcher(`${connection.baseUrl}${path}`, {
+      ...init, redirect: 'error', signal,
+      headers: { ...init.headers, Authorization: `Bearer ${connection.token}`, Accept: accept },
+    });
+    if (!result.ok) { await result.body?.cancel(); refuse(result.status); }
+    if (result.headers.get('content-type')?.toLowerCase().split(';')[0]?.trim() !== accept) {
+      await result.body?.cancel(); throw new FlowToolError('invalid_contract');
+    }
+    return result;
+  }
+  return {
+    async request(request: FlowToolRequest): Promise<unknown> {
+      try {
+        if (request.idempotencyKey !== undefined) flowToolOperationKey(request.idempotencyKey);
+        if (request.method === 'POST' && request.idempotencyKey === undefined) throw new FlowToolError('invalid_contract');
+        const result = await response(request.path, {
+          method: request.method,
+          headers: { ...(request.idempotencyKey === undefined ? {} : { 'Idempotency-Key': request.idempotencyKey }), 'Content-Type': 'application/json' },
+          ...(request.body === undefined ? {} : { body: canonicalize(request.body) }),
+        }, 'application/json');
+        let body = '';
+        for await (const chunk of chunks(result, FLOW_TOOL_ENVELOPE_LIMITS.maxBytes)) body += chunk;
+        try { return JSON.parse(body); } catch { throw new FlowToolError('invalid_contract'); }
+      } catch (error) { return safeError(error); }
+    },
+    async *events(path: string, after: number): AsyncIterable<unknown> {
+      try {
+        if (!path.endsWith('/events') || !Number.isSafeInteger(after) || after < 0) throw new FlowToolError('invalid_contract');
+        const result = await response(path, { method: 'GET', headers: { 'Last-Event-ID': String(after) } }, 'text/event-stream');
+        let buffer = '', frame: string[] = [], frameSize = 0;
+        // Each bounded subscription may reconnect with its last validated cursor.
+        for await (const chunk of chunks(result, 4 * 1024 * 1024)) {
+          buffer += chunk;
+          let newline: number;
+          while ((newline = buffer.indexOf('\n')) >= 0) {
+            const line = buffer.slice(0, newline).replace(/\r$/, '');
+            buffer = buffer.slice(newline + 1);
+            frameSize += line.length;
+            if (frameSize > 65536) throw new FlowToolError('invalid_contract');
+            if (line === '') {
+              const event = parseFrame(frame);
+              frame = []; frameSize = 0;
+              if (event !== undefined) yield event;
+            } else frame.push(line);
+          }
+          if (buffer.length > 65536) throw new FlowToolError('invalid_contract');
+        }
+        if (buffer.length || frame.some(line => !line.startsWith(':'))) throw new FlowToolError('invalid_contract');
+      } catch (error) { safeError(error); }
+    },
+  };
+}
+
+function parseFrame(lines: string[]): unknown {
+  const data: string[] = [];
+  let id: string | undefined, name: string | undefined;
+  for (const line of lines) {
+    if (line.startsWith(':')) continue;
+    const separator = line.indexOf(':');
+    const field = separator < 0 ? line : line.slice(0, separator);
+    const value = separator < 0 ? '' : line.slice(separator + 1).replace(/^ /, '');
+    if (field === 'data') data.push(value);
+    else if (field === 'id' && id === undefined) id = value;
+    else if (field === 'event' && name === undefined) name = value;
+    else throw new FlowToolError('invalid_contract');
+  }
+  if (data.length === 0 && id === undefined && name === undefined) return undefined;
+  if (id === undefined || !/^[1-9][0-9]*$/.test(id) || !Number.isSafeInteger(Number(id))) throw new FlowToolError('invalid_contract');
+  let parsed: unknown;
+  try { parsed = JSON.parse(data.join('\n')); } catch { throw new FlowToolError('invalid_contract'); }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)
+    || (parsed as Record<string, unknown>).sequence !== Number(id)
+    || (parsed as Record<string, unknown>).type !== name) throw new FlowToolError('invalid_contract');
+  return parsed;
+}