@relayflows/sdk 2.0.9 → 2.0.11

package/dist/yaml-helper-effect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-helper-effect.js","sourceRoot":"","sources":["../src/yaml-helper-effect.ts"],"names":[],"mappings":"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"}

package/dist/yaml-helpers.d.ts

@@ -0,0 +1,18 @@
+import { type RelayTransport } from '@relayfile/relay-helpers';
+import type { AgentStepSpec, KernelAgentStep, YamlHelperParams } from './spec.js';
+export type HelperCall = {
+    [P in keyof YamlHelperParams]: {
+        [V in keyof YamlHelperParams[P]]: {
+            type: 'effect';
+            provider: P;
+            verb: V;
+            params: YamlHelperParams[P][V];
+        };
+    }[keyof YamlHelperParams[P]];
+}[keyof YamlHelperParams];
+/** Runs on the inert JSON snapshot, before ordinary step validation. */
+export declare function expandYamlHelpers(spec: unknown): unknown;
+/** The versioned instruction envelope survives canonical specs and journal resume. */
+export declare function helperCall(step: Partial<AgentStepSpec | KernelAgentStep>): HelperCall | undefined;
+export declare function invokeHelper(call: HelperCall, transport: RelayTransport): Promise<unknown>;
+//# sourceMappingURL=yaml-helpers.d.ts.map

package/dist/yaml-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-helpers.d.ts","sourceRoot":"","sources":["../src/yaml-helpers.ts"],"names":[],"mappings":"AACA,OAAO,EAA2C,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACxG,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAyDlF,MAAM,MAAM,UAAU,GAAG;KAAG,CAAC,IAAI,MAAM,gBAAgB,GAAG;SAAG,CAAC,IAAI,MAAM,gBAAgB,CAAC,CAAC,CAAC,GACzF;YAAE,IAAI,EAAE,QAAQ,CAAC;YAAC,QAAQ,EAAE,CAAC,CAAC;YAAC,IAAI,EAAE,CAAC,CAAC;YAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;SAAE;KACzE,CAAC,MAAM,gBAAgB,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC,MAAM,gBAAgB,CAAC,CAAC;AA2BvD,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CA4BxD;AAED,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,aAAa,GAAG,eAAe,CAAC,GAAG,UAAU,GAAG,SAAS,CAKjG;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAGhG"}

package/dist/yaml-helpers.js

@@ -0,0 +1,116 @@
+import Ajv from 'ajv';
+import { githubClient, linearClient, slackClient } from '@relayfile/relay-helpers';
+import { canonicalize } from './canonical.js';
+import { unknownKeyErrors } from './unknown-keys.js';
+const string = { type: 'string', minLength: 1 };
+const text = { type: 'string' };
+const strings = { type: 'array', items: string };
+const object = (properties, required = Object.keys(properties)) => ({ type: 'object', properties, required, additionalProperties: false });
+const target = object({ owner: string, repo: string, number: { type: 'integer', minimum: 1 } });
+const issueChanges = { title: string, description: text, assigneeId: string, stateId: string,
+    projectId: string, labelIds: strings, addedLabelIds: strings, removedLabelIds: strings };
+const ajv = new Ajv({ allErrors: true });
+function verb(schema, invoke) {
+    const validate = ajv.compile(schema);
+    return { validate, invoke: (params, transport) => invoke(params, transport) };
+}
+/** Closed catalog: only write verbs with a declared argument schema can execute. */
+const helpers = {
+    slack: {
+        post: verb(object({ channel: string, text,
+            opts: object({ replyTo: string }, []) }, ['channel', 'text']), (p, transport) => slackClient({ transport }).post(p.channel, p.text, p.opts)),
+        dm: verb(object({ user: string, text }), (p, transport) => slackClient({ transport }).dm(p.user, p.text)),
+        reply: verb(object({ channel: string, threadTs: string, text }), (p, transport) => slackClient({ transport }).reply(p.channel, p.threadTs, p.text)),
+        react: verb(object({ channel: string, messageTs: string, emoji: string }), (p, transport) => slackClient({ transport }).react(p.channel, p.messageTs, p.emoji)),
+    },
+    github: {
+        comment: verb(object({ target, body: text }), (p, transport) => githubClient({ transport }).comment(p.target, p.body)),
+        createIssue: verb(object({ owner: string, repo: string,
+            title: string, body: text, labels: strings }, ['owner', 'repo', 'title', 'body']), (p, transport) => githubClient({ transport }).createIssue(p)),
+        createPullRequest: verb(object({ owner: string,
+            repo: string, title: string, head: string, base: string, body: text, draft: { type: 'boolean' },
+            author: { enum: ['app', 'user'] } }, ['owner', 'repo', 'title', 'head', 'base']), (p, transport) => githubClient({ transport }).createPullRequest(p)),
+        closePullRequest: verb(target, (p, transport) => githubClient({ transport }).closePullRequest(p)),
+    },
+    linear: {
+        comment: verb(object({ issueId: string, body: text }), (p, transport) => linearClient({ transport }).comment(p.issueId, p.body)),
+        createIssue: verb(object({ teamId: string, title: string,
+            description: text, assigneeId: string, labelIds: strings, projectId: string, stateId: string }, ['teamId', 'title']), (p, transport) => linearClient({ transport }).createIssue(p)),
+        updateIssue: verb(object({ issueId: string,
+            args: object(issueChanges, []) }), (p, transport) => linearClient({ transport }).updateIssue(p.issueId, p.args)),
+    },
+};
+const prefix = 'relayflows:helper:v1\n';
+const commonFields = ['id', 'dependsOn', 'maxIterations', 'verification', 'output'];
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+function descriptor(provider, name) {
+    if (!Object.hasOwn(helpers, provider))
+        throw new Error(`unknown helper provider "${provider}"`);
+    const verbs = helpers[provider];
+    if (!Object.hasOwn(verbs, name))
+        throw new Error(`unknown ${provider} helper verb "${name}"`);
+    return verbs[name];
+}
+function validateCall(value) {
+    if (!isObject(value) || value.type !== 'effect' || typeof value.provider !== 'string' || typeof value.verb !== 'string') {
+        throw new Error('expected a helper effect call');
+    }
+    const extra = unknownKeyErrors(value, ['type', 'provider', 'verb', 'params'], 'helper');
+    if (extra.length)
+        throw new Error(extra.join('; '));
+    const entry = descriptor(value.provider, value.verb);
+    if (!entry.validate(value.params)) {
+        throw new Error(`${value.provider}.${value.verb}: ${ajv.errorsText(entry.validate.errors)}`);
+    }
+    return value;
+}
+/** Runs on the inert JSON snapshot, before ordinary step validation. */
+export function expandYamlHelpers(spec) {
+    if (!isObject(spec) || !Array.isArray(spec.steps))
+        return spec;
+    return { ...spec, steps: spec.steps.map((step, index) => {
+            if (!isObject(step))
+                return step;
+            const providers = Object.keys(helpers).filter(provider => Object.hasOwn(step, provider));
+            if (!providers.length) {
+                // Recompiling a canonical envelope must fail with the same compile error
+                // contract as authoring it, before preflight or workers see it.
+                helperCall(step);
+                return step;
+            }
+            const at = `spec.steps[${index}]`;
+            try {
+                if (providers.length !== 1)
+                    throw new Error('expected exactly one helper provider per step');
+                const provider = providers[0];
+                const errors = unknownKeyErrors(step, [...commonFields, provider], at);
+                if (errors.length)
+                    throw new Error(errors.join('; '));
+                const verbs = step[provider];
+                if (!isObject(verbs) || Object.keys(verbs).length !== 1)
+                    throw new Error(`${provider}: expected exactly one helper verb`);
+                const name = Object.keys(verbs)[0];
+                const call = validateCall({ type: 'effect', provider, verb: name, params: verbs[name] });
+                const { [provider]: _, ...base } = step;
+                return { ...base, type: 'agent', instruction: prefix + canonicalize(call),
+                    recoveryMode: 'reset', surfaces: { external: [`/${provider}`] } };
+            }
+            catch (error) {
+                throw new Error(`${at}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }) };
+}
+/** The versioned instruction envelope survives canonical specs and journal resume. */
+export function helperCall(step) {
+    if (step.type !== 'agent' || typeof step.instruction !== 'string' || !step.instruction.startsWith(prefix))
+        return undefined;
+    const call = validateCall(JSON.parse(step.instruction.slice(prefix.length)));
+    if (!step.surfaces?.external?.includes(`/${call.provider}`))
+        throw new Error('helper effect is missing its declared external surface');
+    return call;
+}
+export async function invokeHelper(call, transport) {
+    const validated = validateCall(call);
+    return (await descriptor(validated.provider, validated.verb).invoke(validated.params, transport)) ?? null;
+}
+//# sourceMappingURL=yaml-helpers.js.map

package/dist/yaml-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-helpers.js","sourceRoot":"","sources":["../src/yaml-helpers.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayflows/sdk",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "description": "TypeScript-first authoring SDK for Relayflows. Compiles specs; speaks the journal protocol.",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,6 +12,18 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./create-flow": {
+      "types": "./dist/create-flow.d.ts",
+      "import": "./dist/create-flow.js"
+    },
+    "./progress": {
+      "types": "./dist/progress.d.ts",
+      "import": "./dist/progress.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
     }
   },
   "files": [
@@ -30,11 +42,16 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@relayflows/surface": "2.0.9",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@relayfile/adapter-core": "0.5.24",
+    "@relayfile/relay-helpers": "0.4.11",
+    "@relayflows/surface": "2.0.11",
     "@types/js-yaml": "^4.0.9",
+    "ai-hist": "0.4.1",
     "ajv": "^8.17.1",
     "ajv-draft-04": "^1.0.0",
     "js-yaml": "^5.4.1",
+    "re2js": "^2.8.6",
     "yaml": "^2.5.1"
   },
   "devDependencies": {

package/src/adapters/base.ts

@@ -0,0 +1,53 @@
+/**
+ * First-class headless adapter contract (flows#141).
+ *
+ * Every supported agent CLI ships one implementation. `worker-cli.ts` and
+ * `cli/check.ts` dispatch through the registry in `./index.ts` — never string
+ * formatting against per-CLI knowledge inline. Adding a new CLI is one new
+ * file that implements this interface.
+ *
+ * Behavior-preserving migration: the exported functions in `cli-adapter.ts`
+ * (`agentExecution`, `llmExecution`, `authenticationProbe`,
+ * `modelReadinessProbe`, `adapterIdentification`) now delegate to the
+ * registered adapter for the resolved kind, so callers don't change.
+ */
+
+export interface CliInvocation {
+  args: string[];
+  timeoutMs: number;
+  /** Set only for wrapper readiness probes; raw providers receive a model flag. */
+  modelEnv?: string;
+}
+
+export interface CliAdapterIdentification {
+  invocation: CliInvocation;
+  expectedStdout?: string;
+}
+
+/**
+ * The declared, per-CLI headless contract. Members intentionally mirror the
+ * function-scoped predecessors in `cli-adapter.ts` so migration is mechanical.
+ */
+export interface HeadlessAdapter {
+  /** Identity of this adapter — matches CliAdapterKind for registry keys. */
+  readonly kind: string;
+
+  /** Shape-check invocation before classifying an auth failure. */
+  buildIdentification(): CliAdapterIdentification;
+
+  /** Non-interactive auth-status probe. */
+  buildAuthProbe(): CliInvocation;
+
+  /**
+   * Real, noninteractive model round-trip. Providers hand the model via a
+   * native flag; wrappers hand it via the explicitly identified environment
+   * contract on `modelEnv`.
+   */
+  buildModelReadinessProbe(model: string): CliInvocation;
+
+  /** Agent-step worker argv for an instruction under an optional model. */
+  buildAgentInvocation(instruction: string, model?: string): CliInvocation;
+
+  /** LLM-step worker argv for a prompt under an optional model. */
+  buildLlmInvocation(prompt: string, model?: string): CliInvocation;
+}

package/src/adapters/claude.ts

@@ -0,0 +1,55 @@
+import type {
+  CliAdapterIdentification,
+  CliInvocation,
+  HeadlessAdapter,
+} from './base.js';
+
+const MODEL_PROBE_PROMPT = 'Reply with exactly RELAYFLOWS_MODEL_READY and nothing else.';
+
+/** Claude Code CLI headless contract. Wire and behavior identical to the
+ *  pre-#141 inline shape in `cli-adapter.ts` — only the packaging changed. */
+export const claudeAdapter: HeadlessAdapter = {
+  kind: 'claude',
+
+  buildIdentification(): CliAdapterIdentification {
+    return { invocation: { args: ['auth', 'status', '--help'], timeoutMs: 10_000 } };
+  },
+
+  buildAuthProbe(): CliInvocation {
+    return { args: ['auth', 'status'], timeoutMs: 10_000 };
+  },
+
+  buildModelReadinessProbe(model: string): CliInvocation {
+    return {
+      args: [
+        '-p', '--model', model, '--tools', '', '--no-session-persistence',
+        MODEL_PROBE_PROMPT,
+      ],
+      timeoutMs: 60_000,
+    };
+  },
+
+  buildAgentInvocation(instruction: string, model?: string): CliInvocation {
+    return {
+      args: [
+        '-p',
+        // Symmetric to codex's --dangerously-bypass-approvals-and-sandbox: in
+        // agent mode the flow explicitly delegates writes. Without this
+        // claude's headless mode prompts for tool approval, gets no TTY,
+        // and completes "successfully" without touching files.
+        '--dangerously-skip-permissions',
+        ...(model === undefined ? [] : ['--model', model]),
+        instruction,
+      ],
+      timeoutMs: 0,
+    };
+  },
+
+  buildLlmInvocation(prompt: string, model?: string): CliInvocation {
+    return {
+      args: ['-p', '--tools', '', '--no-session-persistence',
+        ...(model === undefined ? [] : ['--model', model]), prompt],
+      timeoutMs: 0,
+    };
+  },
+};

package/src/adapters/codex.ts

@@ -0,0 +1,56 @@
+import type {
+  CliAdapterIdentification,
+  CliInvocation,
+  HeadlessAdapter,
+} from './base.js';
+
+const MODEL_PROBE_PROMPT = 'Reply with exactly RELAYFLOWS_MODEL_READY and nothing else.';
+
+/** OpenAI Codex CLI headless contract. Behavior identical to the pre-#141
+ *  inline shape in `cli-adapter.ts` — only the packaging changed. */
+export const codexAdapter: HeadlessAdapter = {
+  kind: 'codex',
+
+  buildIdentification(): CliAdapterIdentification {
+    return { invocation: { args: ['login', 'status', '--help'], timeoutMs: 10_000 } };
+  },
+
+  buildAuthProbe(): CliInvocation {
+    return { args: ['login', 'status'], timeoutMs: 10_000 };
+  },
+
+  buildModelReadinessProbe(model: string): CliInvocation {
+    return {
+      args: [
+        'exec', '--ephemeral', '--sandbox', 'read-only', '--skip-git-repo-check',
+        '--model', model, MODEL_PROBE_PROMPT,
+      ],
+      timeoutMs: 60_000,
+    };
+  },
+
+  buildAgentInvocation(instruction: string, model?: string): CliInvocation {
+    return {
+      args: [
+        'exec', '--ephemeral', '--skip-git-repo-check',
+        // Agent-mode is where the flow explicitly delegates code changes to
+        // the CLI. Without this flag codex prompts for approval on every
+        // write, gets nothing (no TTY), and completes "successfully" without
+        // touching files — the dogfood no-op failure mode. LLM-mode stays
+        // read-only and does NOT get the bypass.
+        '--dangerously-bypass-approvals-and-sandbox',
+        ...(model === undefined ? [] : ['--model', model]),
+        instruction,
+      ],
+      timeoutMs: 0,
+    };
+  },
+
+  buildLlmInvocation(prompt: string, model?: string): CliInvocation {
+    return {
+      args: ['exec', '--ephemeral', '--sandbox', 'read-only', '--skip-git-repo-check',
+        ...(model === undefined ? [] : ['--model', model]), prompt],
+      timeoutMs: 0,
+    };
+  },
+};

package/src/adapters/index.ts

@@ -0,0 +1,36 @@
+import { basename } from 'node:path';
+
+import { claudeAdapter } from './claude.js';
+import { codexAdapter } from './codex.js';
+import { wrapperAdapter } from './wrapper.js';
+import type { HeadlessAdapter } from './base.js';
+
+export type CliAdapterKind = 'claude' | 'codex' | 'relayflows-wrapper-v1';
+
+/** The registered adapter set. Adding a CLI is adding one file + one entry. */
+const ADAPTERS: Record<CliAdapterKind, HeadlessAdapter> = {
+  claude: claudeAdapter,
+  codex: codexAdapter,
+  'relayflows-wrapper-v1': wrapperAdapter,
+};
+
+/** Select the adapter for the resolved executable basename. */
+export function resolveAdapter(executable: string): HeadlessAdapter {
+  const name = basename(executable).replace(/\.exe$/i, '');
+  if (name === 'claude') return ADAPTERS.claude;
+  if (name === 'codex') return ADAPTERS.codex;
+  return ADAPTERS['relayflows-wrapper-v1'];
+}
+
+/** Backward-compatible kind lookup for callers still speaking string-tag lang. */
+export function resolveAdapterKind(executable: string): CliAdapterKind {
+  return resolveAdapter(executable).kind as CliAdapterKind;
+}
+
+/** Registered adapters by kind (read-only view for tests and diagnostics). */
+export function registeredAdapters(): Readonly<Record<CliAdapterKind, HeadlessAdapter>> {
+  return ADAPTERS;
+}
+
+export { claudeAdapter, codexAdapter, wrapperAdapter };
+export type { HeadlessAdapter, CliInvocation, CliAdapterIdentification } from './base.js';

package/src/adapters/wrapper.ts

@@ -0,0 +1,42 @@
+import type {
+  CliAdapterIdentification,
+  CliInvocation,
+  HeadlessAdapter,
+} from './base.js';
+
+/**
+ * `relayflows-adapter-v1` identifies a per-flow wrapper script — the pre-#141
+ * per-flow shim shape. The wrapper answers a probe with a known token; agent
+ * and llm execution flow through `runWrapperSession`, so this adapter refuses
+ * to construct a direct-argv invocation for them.
+ */
+export const WRAPPER_IDENTIFY_ARG = '--relayflows-adapter-v1';
+export const WRAPPER_IDENTIFY_TOKEN = 'relayflows-agent-cli-v1';
+export const WRAPPER_EXECUTE_TOKEN = 'relayflows-agent-cli-v1-execute';
+
+export const wrapperAdapter: HeadlessAdapter = {
+  kind: 'relayflows-wrapper-v1',
+
+  buildIdentification(): CliAdapterIdentification {
+    return {
+      invocation: { args: [WRAPPER_IDENTIFY_ARG], timeoutMs: 10_000 },
+      expectedStdout: WRAPPER_IDENTIFY_TOKEN,
+    };
+  },
+
+  buildAuthProbe(): CliInvocation {
+    return { args: ['auth', 'status'], timeoutMs: 10_000 };
+  },
+
+  buildModelReadinessProbe(model: string): CliInvocation {
+    return { args: ['auth', 'status'], timeoutMs: 60_000, modelEnv: model };
+  },
+
+  buildAgentInvocation(): CliInvocation {
+    throw new Error('custom wrapper execution requires the runAgentCli same-process session');
+  },
+
+  buildLlmInvocation(): CliInvocation {
+    throw new Error('custom wrapper execution requires the same-process session');
+  },
+};

package/src/agent-relay-receipt.ts

@@ -0,0 +1,120 @@
+import { canonicalize } from "./canonical.js";
+
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+export const nonempty = (value: unknown): value is string =>
+  typeof value === "string" && value.length > 0;
+
+export interface RelayTaskExecution {
+  execution_id: string;
+  run_id: string;
+  step_id: string;
+  dispatch_id: string;
+  deadline: string;
+  worker_generation?: string;
+  accepted_at?: string;
+  accounting?: Record<string, number>;
+}
+export interface RelayTaskReceipt {
+  invocation_id: string;
+  action_name: "task.run";
+  status: "pending" | "dispatched" | "running" | "completed" | "failed";
+  task_execution: RelayTaskExecution;
+  output: unknown;
+  error: string | null;
+  completed_at: string | null;
+}
+
+/** GET is authoritative. A spawn/POST acknowledgment is never a task result. */
+export function readTaskReceipt(
+  value: unknown,
+  invocationId: string,
+  input: Record<string, unknown>,
+  previous?: RelayTaskReceipt,
+): RelayTaskReceipt {
+  const context = input.task_context as Record<string, unknown>;
+  if (
+    !isRecord(value) ||
+    value.invocation_id !== invocationId ||
+    value.action_name !== "task.run" ||
+    canonicalize(value.input) !== canonicalize(input) ||
+    !isRecord(value.task_execution)
+  ) {
+    throw new Error("Relay task receipt has mismatched invocation or input");
+  }
+  const execution = value.task_execution;
+  const validDate = (date: unknown): date is string =>
+    nonempty(date) && Number.isFinite(Date.parse(date));
+  if (
+    !nonempty(execution.execution_id) ||
+    !validDate(execution.deadline) ||
+    ["run_id", "step_id", "dispatch_id"].some(
+      (key) => execution[key] !== context[key],
+    ) ||
+    !["pending", "dispatched", "running", "completed", "failed"].includes(
+      String(value.status),
+    )
+  ) {
+    throw new Error("Relay task receipt has invalid execution correlation");
+  }
+  const accepted =
+    nonempty(execution.worker_generation) && validDate(execution.accepted_at);
+  if (
+    (value.status === "running" || value.status === "completed") &&
+    !accepted
+  ) {
+    throw new Error("Relay task receipt is missing durable acceptance");
+  }
+  if (
+    (execution.worker_generation !== undefined ||
+      execution.accepted_at !== undefined) &&
+    !accepted
+  ) {
+    throw new Error("Relay task receipt has incomplete durable acceptance");
+  }
+  if (
+    previous !== undefined &&
+    (previous.task_execution.execution_id !== execution.execution_id ||
+      previous.task_execution.deadline !== execution.deadline ||
+      (previous.task_execution.worker_generation !== undefined &&
+        (previous.task_execution.worker_generation !==
+          execution.worker_generation ||
+          previous.task_execution.accepted_at !== execution.accepted_at)))
+  ) {
+    throw new Error(
+      "Relay task receipt changed its execution, accepted generation/time, or deadline",
+    );
+  }
+  if (
+    execution.accounting !== undefined &&
+    (!isRecord(execution.accounting) ||
+      Object.values(execution.accounting).some(
+        (n) => typeof n !== "number" || !Number.isFinite(n) || n < 0,
+      ))
+  ) {
+    throw new Error("Relay task receipt has invalid accounting");
+  }
+  if (
+    value.status === "completed" &&
+    (!Object.hasOwn(value, "output") ||
+      value.error !== null ||
+      !validDate(value.completed_at))
+  ) {
+    throw new Error("Relay task receipt has no authoritative final output");
+  }
+  if (
+    value.status === "failed" &&
+    (!nonempty(value.error) || !validDate(value.completed_at))
+  ) {
+    throw new Error("Relay task failure receipt has no reason");
+  }
+  return {
+    invocation_id: invocationId,
+    action_name: "task.run",
+    status: value.status as RelayTaskReceipt["status"],
+    task_execution: execution as unknown as RelayTaskExecution,
+    output: value.output,
+    error: value.error as string | null,
+    completed_at: value.completed_at as string | null,
+  };
+}

package/src/agent-relay-state.ts

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+import { mkdir, open, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { canonicalize } from "./canonical.js";
+
+export interface RelayTaskClaim {
+  version: 1;
+  baseUrl: string;
+  callerId: string;
+  workspaceId: string;
+  invocationId: string;
+  runId: string;
+  stepId: string;
+  idempotencyKey: string;
+  input: Record<string, unknown>;
+  startedAt: number;
+}
+
+/** Exclusive creation pins the request before POST; no last-writer overwrite. */
+export async function claimRelayTask(
+  dataDir: string,
+  claim: RelayTaskClaim,
+): Promise<{ claim: RelayTaskClaim; created: boolean }> {
+  const directory = join(dataDir, "relay-tasks");
+  await mkdir(directory, { recursive: true });
+  const parent = await open(dataDir, "r");
+  try {
+    await parent.sync();
+  } finally {
+    await parent.close();
+  }
+  const digest = createHash("sha256")
+    .update(canonicalize([claim.runId, claim.stepId, claim.idempotencyKey]))
+    .digest("hex");
+  const path = join(directory, `${digest}.json`);
+  let file;
+  try {
+    file = await open(path, "wx", 0o600);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    const prior: unknown = JSON.parse(await readFile(path, "utf8"));
+    if (
+      typeof prior !== "object" ||
+      prior === null ||
+      !("startedAt" in prior) ||
+      typeof prior.startedAt !== "number" ||
+      !Number.isSafeInteger(prior.startedAt) ||
+      prior.startedAt < 0 ||
+      canonicalize(prior) !==
+        canonicalize({ ...claim, startedAt: prior.startedAt })
+    ) {
+      throw new Error(
+        "Relay task dispatch conflicts with its durable caller, endpoint, or input",
+      );
+    }
+    return { claim: prior as RelayTaskClaim, created: false };
+  }
+  // A crash during creation leaves a partial claim that fails closed on read.
+  // Never remove an uncertain claim and retry under a different identity.
+  try {
+    await file.writeFile(canonicalize(claim));
+    await file.sync();
+  } finally {
+    await file.close();
+  }
+  const dir = await open(directory, "r");
+  try {
+    await dir.sync();
+  } finally {
+    await dir.close();
+  }
+  return { claim, created: true };
+}