@relayflows/sdk 2.0.8 → 2.0.10

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.8",
+  "version": "2.0.10",
   "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.8",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@relayfile/adapter-core": "0.5.24",
+    "@relayfile/relay-helpers": "0.4.11",
+    "@relayflows/surface": "2.0.10",
     "@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-transport.ts

@@ -0,0 +1,187 @@
+/**
+ * Agent-relay HTTP transport for f.agent step dispatch (flows#385).
+ *
+ * The SDK's default agent path is a direct `child_process.spawn(cli, ...)`
+ * in worker-cli.ts. That is unobservable — you cannot DM the spawned agent
+ * mid-flight, and every ecosystem tool that wants to steer or watch it
+ * ends up shelling out to the `agent-relay` CLI, which is fragile.
+ *
+ * This module speaks to agent-relay via structured HTTP: the same call
+ * shape the `mcp__agent-relay__spawn` MCP tool posts. The SDK becomes a
+ * first-class agent-relay participant, registered under a derived agent
+ * name a caller can DM against.
+ *
+ * Scope: spawn + close. Streaming inbox and observation are follow-ups.
+ */
+
+export type AgentTransport = 'direct' | 'relay';
+
+export interface AgentRelaySpawnRequest {
+  /** Registered agent name in the workspace. */
+  name: string;
+  /** CLI to launch. */
+  cli: 'claude' | 'codex' | 'gemini' | 'aider' | 'goose' | 'grok' | 'opencode';
+  /** Initial task instructions. */
+  task: string;
+  /** Optional model powering the worker. */
+  model?: string;
+  /** Optional working directory for the spawned worker process. */
+  worker_cwd?: string;
+  /** Optional target fleet node name. */
+  target_node?: string;
+  /** Declared objective for workforce reporting. */
+  objective?: string;
+  /** Declared role for workforce reporting. */
+  role?: string;
+  /** Declared project for workforce reporting. */
+  project?: string;
+  /** Declared workstream for workforce reporting. */
+  workstream?: string;
+}
+
+export interface AgentRelayEnv {
+  /** `RELAY_BASE_URL` env; defaults to https://cast.agentrelay.com. */
+  baseUrl?: string;
+  /** `RELAY_API_KEY` env (rk_live_...). Required. */
+  apiKey?: string;
+  /** `RELAY_DEFAULT_WORKSPACE` env; workspace scoping for the spawn. */
+  workspaceId?: string;
+  /** Optional bearer token for the individual agent identity, if pre-registered. */
+  agentToken?: string;
+}
+
+export interface AgentSpawnHandle {
+  /** Registered agent name in the workspace — DM this to steer. */
+  readonly registeredName: string;
+  /** Invocation id returned by relay; use for status polling. */
+  readonly invocationId: string;
+  /** Best-effort deregistration/notification. */
+  close(): Promise<void>;
+}
+
+export class AgentRelayTransportError extends Error {
+  constructor(message: string, public readonly cause?: unknown) {
+    super(message);
+    this.name = 'AgentRelayTransportError';
+  }
+}
+
+/**
+ * Read the same env the relay MCP already consumes. Explicit override wins.
+ * Missing RELAY_API_KEY refuses immediately — the transport cannot proceed
+ * unauthenticated and the direct-spawn fallback is a separate decision.
+ */
+export function readAgentRelayEnv(env: NodeJS.ProcessEnv = process.env): Required<Pick<AgentRelayEnv, 'baseUrl' | 'apiKey'>> & AgentRelayEnv {
+  const baseUrl = env['RELAY_BASE_URL']?.trim() || 'https://cast.agentrelay.com';
+  const apiKey = env['RELAY_API_KEY']?.trim();
+  if (!apiKey) {
+    throw new AgentRelayTransportError(
+      'agent-relay transport requires RELAY_API_KEY in the environment; falling back to direct transport is the caller\'s responsibility.',
+    );
+  }
+  return {
+    baseUrl,
+    apiKey,
+    workspaceId: env['RELAY_DEFAULT_WORKSPACE']?.trim() || undefined,
+    agentToken: env['RELAY_AGENT_TOKEN']?.trim() || undefined,
+  };
+}
+
+/**
+ * Spawn a worker via agent-relay HTTP. The endpoint mirrors what the
+ * `mcp__agent-relay__spawn` MCP tool wraps — a POST that requests a fleet
+ * node dispatch. Returns a handle keyed on the registered agent name.
+ *
+ * The `fetch` argument is injected so tests can mock the transport without
+ * hitting the network.
+ */
+export async function agentRelaySpawn(
+  request: AgentRelaySpawnRequest,
+  env: AgentRelayEnv & { fetch?: typeof fetch } = {},
+): Promise<AgentSpawnHandle> {
+  // Only fall back to process.env if the caller didn't supply the required
+  // fields directly. Tests pass { apiKey, fetch } inline; they shouldn't need
+  // to also set RELAY_API_KEY in the runner env.
+  const fromEnv: Partial<AgentRelayEnv> = env.apiKey
+    ? { baseUrl: env.baseUrl || 'https://cast.agentrelay.com' }
+    : readAgentRelayEnv();
+  const resolved = { ...fromEnv, ...env };
+  const url = new URL('/api/v1/agents/spawn', resolved.baseUrl).toString();
+  const doFetch: typeof fetch = env.fetch ?? (globalThis as typeof globalThis & { fetch: typeof fetch }).fetch;
+  if (typeof doFetch !== 'function') {
+    throw new AgentRelayTransportError('global fetch is unavailable; provide { fetch } explicitly.');
+  }
+  const headers: Record<string, string> = {
+    'content-type': 'application/json',
+    'authorization': `Bearer ${resolved.apiKey}`,
+  };
+  if (resolved.workspaceId !== undefined) headers['x-relay-workspace'] = resolved.workspaceId;
+  if (resolved.agentToken !== undefined) headers['x-relay-agent-token'] = resolved.agentToken;
+
+  let response: Response;
+  try {
+    response = await doFetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(request),
+    });
+  } catch (cause) {
+    throw new AgentRelayTransportError(
+      `agent-relay spawn network error at ${url}: ${(cause as Error).message ?? String(cause)}`,
+      cause,
+    );
+  }
+
+  if (response.status < 200 || response.status >= 300) {
+    let body: string;
+    try { body = (await response.text()).slice(0, 512); } catch { body = '<no body>'; }
+    throw new AgentRelayTransportError(
+      `agent-relay spawn refused with status ${response.status}: ${body}`,
+    );
+  }
+
+  let json: { invocation?: { invocationId?: string; input?: { name?: string } } };
+  try { json = await response.json() as typeof json; } catch (cause) {
+    throw new AgentRelayTransportError(
+      'agent-relay spawn response was not JSON',
+      cause,
+    );
+  }
+  const invocationId = json.invocation?.invocationId;
+  const registeredName = json.invocation?.input?.name ?? request.name;
+  if (typeof invocationId !== 'string' || invocationId.length === 0) {
+    throw new AgentRelayTransportError(
+      'agent-relay spawn response missing invocation.invocationId',
+    );
+  }
+
+  return {
+    registeredName,
+    invocationId,
+    async close(): Promise<void> {
+      // Best-effort: post to /api/v1/invocations/<id>/close if defined server-side;
+      // no throw on error because the invocation may already be terminal.
+      const closeUrl = new URL(`/api/v1/invocations/${encodeURIComponent(invocationId)}/close`, resolved.baseUrl).toString();
+      try {
+        await doFetch(closeUrl, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify({ reason: 'sdk_transport_close' }),
+        });
+      } catch {
+        // Deliberate: close is advisory in this minimum-viable slice.
+      }
+    },
+  };
+}
+
+/**
+ * Derive a workspace-unique agent name from a run identity + step id. The
+ * result is stable across replays of the same step so DMs can be addressed
+ * even during retries.
+ */
+export function deriveAgentName(runId: string, stepId: string): string {
+  // Keep readable + collision-safe: prefix with 'flow-' and use lower-kebab.
+  const clean = (s: string): string => s.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+  return `flow-${clean(runId)}-${clean(stepId)}`.slice(0, 96);
+}