@relayflows/sdk 2.0.10 → 2.0.11

package/dist/agent-relay-receipt.d.ts

@@ -0,0 +1,24 @@
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+export declare const nonempty: (value: unknown) => value is string;
+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 declare function readTaskReceipt(value: unknown, invocationId: string, input: Record<string, unknown>, previous?: RelayTaskReceipt): RelayTaskReceipt;
+//# sourceMappingURL=agent-relay-receipt.d.ts.map

package/dist/agent-relay-receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-relay-receipt.d.ts","sourceRoot":"","sources":["../src/agent-relay-receipt.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CACH,CAAC;AACvE,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MACJ,CAAC;AAEhD,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AACD,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,UAAU,CAAC;IACxB,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IACtE,cAAc,EAAE,kBAAkB,CAAC;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,gFAAgF;AAChF,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,gBAAgB,CAsFlB"}

package/dist/agent-relay-receipt.js

@@ -0,0 +1,66 @@
+import { canonicalize } from "./canonical.js";
+export const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const nonempty = (value) => typeof value === "string" && value.length > 0;
+/** GET is authoritative. A spawn/POST acknowledgment is never a task result. */
+export function readTaskReceipt(value, invocationId, input, previous) {
+    const context = input.task_context;
+    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) => 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,
+        task_execution: execution,
+        output: value.output,
+        error: value.error,
+        completed_at: value.completed_at,
+    };
+}
+//# sourceMappingURL=agent-relay-receipt.js.map

package/dist/agent-relay-receipt.js.map

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

package/dist/agent-relay-state.d.ts

@@ -0,0 +1,18 @@
+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 declare function claimRelayTask(dataDir: string, claim: RelayTaskClaim): Promise<{
+    claim: RelayTaskClaim;
+    created: boolean;
+}>;
+//# sourceMappingURL=agent-relay-state.d.ts.map

package/dist/agent-relay-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-relay-state.d.ts","sourceRoot":"","sources":["../src/agent-relay-state.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,iFAAiF;AACjF,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC;IAAE,KAAK,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAkDtD"}

package/dist/agent-relay-state.js

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { mkdir, open, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { canonicalize } from "./canonical.js";
+/** Exclusive creation pins the request before POST; no last-writer overwrite. */
+export async function claimRelayTask(dataDir, claim) {
+    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.code !== "EEXIST")
+            throw error;
+        const prior = 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, 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 };
+}
+//# sourceMappingURL=agent-relay-state.js.map

package/dist/agent-relay-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-relay-state.js","sourceRoot":"","sources":["../src/agent-relay-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAe9C,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAe,EACf,KAAqB;IAErB,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IAC/C,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;IACtB,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IACD,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC;SAChC,MAAM,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;SACvE,MAAM,CAAC,KAAK,CAAC,CAAC;IACjB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,GAAG,MAAM,OAAO,CAAC,CAAC;IAC/C,IAAI,IAAI,CAAC;IACT,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,KAAK,CAAC;QACpE,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QAChE,IACE,OAAO,KAAK,KAAK,QAAQ;YACzB,KAAK,KAAK,IAAI;YACd,CAAC,CAAC,WAAW,IAAI,KAAK,CAAC;YACvB,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ;YACnC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC;YACtC,KAAK,CAAC,SAAS,GAAG,CAAC;YACnB,YAAY,CAAC,KAAK,CAAC;gBACjB,YAAY,CAAC,EAAE,GAAG,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,EACxD,CAAC;YACD,MAAM,IAAI,KAAK,CACb,2EAA2E,CAC5E,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,KAAuB,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5D,CAAC;IACD,4EAA4E;IAC5E,wEAAwE;IACxE,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1C,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IACnB,CAAC;YAAS,CAAC;QACT,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAClC,CAAC"}

package/dist/agent-relay-transport.d.ts

@@ -1,84 +1,31 @@
-/**
- * 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. */
+import { type RelayTaskReceipt } from "./agent-relay-receipt.js";
+export type AgentTransport = "direct" | "relay";
+export interface AgentRelayTaskRequest {
+    cli: string;
     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;
+    result_schema?: unknown;
+    runId: string;
+    stepId: string;
+    idempotencyKey: string;
+    dataDir: string;
+    /** Engine task contract ceiling; bounded independently of the renewing lease. */
+    timeoutMs?: number;
 }
 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 declare class AgentRelayTransportError extends Error {
     readonly cause?: unknown | undefined;
     constructor(message: string, cause?: unknown | undefined);
 }
-/**
- * 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 declare function readAgentRelayEnv(env?: NodeJS.ProcessEnv): Required<Pick<AgentRelayEnv, 'baseUrl' | 'apiKey'>> & AgentRelayEnv;
-/**
- * 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 declare function agentRelaySpawn(request: AgentRelaySpawnRequest, env?: AgentRelayEnv & {
+export declare function readAgentRelayEnv(env?: NodeJS.ProcessEnv): Required<AgentRelayEnv>;
+/** Exact Relaycast #436 HTTP contract. Only terminal GET receipts can return. */
+export declare function runAgentRelayTask(request: AgentRelayTaskRequest, options?: AgentRelayEnv & {
     fetch?: typeof fetch;
-}): Promise<AgentSpawnHandle>;
-/**
- * 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 declare function deriveAgentName(runId: string, stepId: string): string;
+    signal?: AbortSignal;
+    pollMs?: number;
+}): Promise<RelayTaskReceipt>;
 //# sourceMappingURL=agent-relay-transport.d.ts.map

package/dist/agent-relay-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-relay-transport.d.ts","sourceRoot":"","sources":["../src/agent-relay-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhD,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,GAAG,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;IAC7E,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+CAA+C;IAC/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qBAAa,wBAAyB,SAAQ,KAAK;aACJ,KAAK,CAAC,EAAE,OAAO;gBAAhD,OAAO,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,OAAO,YAAA;CAI7D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,QAAQ,CAAC,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,QAAQ,CAAC,CAAC,GAAG,aAAa,CAc3I;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,GAAG,GAAE,aAAa,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CAAO,GACjD,OAAO,CAAC,gBAAgB,CAAC,CA2E3B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAIrE"}
+{"version":3,"file":"agent-relay-transport.d.ts","sourceRoot":"","sources":["../src/agent-relay-transport.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,0BAA0B,CAAC;AAElC,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,OAAO,CAAC;AAChD,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AACD,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AACD,qBAAa,wBAAyB,SAAQ,KAAK;aAG/B,KAAK,CAAC,EAAE,OAAO;gBAD/B,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,OAAO,YAAA;CAKlC;AACD,wBAAgB,iBAAiB,CAC/B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,QAAQ,CAAC,aAAa,CAAC,CAUzB;AAED,iFAAiF;AACjF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,GAAE,aAAa,GAAG;IACvB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACZ,GACL,OAAO,CAAC,gBAAgB,CAAC,CAmN3B"}

package/dist/agent-relay-transport.js

@@ -1,134 +1,199 @@
-/**
- * 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.
- */
+import { createHash } from "node:crypto";
+import { isIP } from "node:net";
+import { setTimeout as delay } from "node:timers/promises";
+import { claimRelayTask } from "./agent-relay-state.js";
+import { canonicalize } from "./canonical.js";
+import { isRecord, nonempty, readTaskReceipt, } from "./agent-relay-receipt.js";
 export class AgentRelayTransportError extends Error {
     cause;
     constructor(message, cause) {
         super(message);
         this.cause = cause;
-        this.name = 'AgentRelayTransportError';
+        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 = process.env) {
-    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.');
-    }
+    const agentToken = env.RELAY_AGENT_TOKEN?.trim();
+    if (!agentToken)
+        throw new AgentRelayTransportError("Relay task transport requires a pre-provisioned RELAY_AGENT_TOKEN.");
     return {
-        baseUrl,
-        apiKey,
-        workspaceId: env['RELAY_DEFAULT_WORKSPACE']?.trim() || undefined,
-        agentToken: env['RELAY_AGENT_TOKEN']?.trim() || undefined,
+        baseUrl: env.RELAY_BASE_URL?.trim() || "https://cast.agentrelay.com",
+        agentToken,
     };
 }
-/**
- * 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, env = {}) {
-    // 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 = 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 = env.fetch ?? globalThis.fetch;
-    if (typeof doFetch !== 'function') {
-        throw new AgentRelayTransportError('global fetch is unavailable; provide { fetch } explicitly.');
-    }
-    const headers = {
-        '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;
-    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.message ?? String(cause)}`, cause);
-    }
-    if (response.status < 200 || response.status >= 300) {
-        let body;
-        try {
-            body = (await response.text()).slice(0, 512);
-        }
-        catch {
-            body = '<no body>';
+/** Exact Relaycast #436 HTTP contract. Only terminal GET receipts can return. */
+export async function runAgentRelayTask(request, options = {}) {
+    const env = options.agentToken
+        ? {
+            baseUrl: options.baseUrl || "https://cast.agentrelay.com",
+            agentToken: options.agentToken,
         }
-        throw new AgentRelayTransportError(`agent-relay spawn refused with status ${response.status}: ${body}`);
-    }
-    let json;
-    try {
-        json = await response.json();
+        : { ...readAgentRelayEnv(), ...options };
+    const base = new URL(env.baseUrl);
+    if (base.username ||
+        base.password ||
+        base.search ||
+        base.hash ||
+        base.pathname !== "/" ||
+        !["https:", "http:"].includes(base.protocol))
+        throw new AgentRelayTransportError("Invalid Relay task base URL");
+    const loopback = base.hostname === "[::1]" ||
+        (isIP(base.hostname) === 4 && base.hostname.startsWith("127."));
+    if (base.protocol !== "https:" && !loopback) {
+        throw new AgentRelayTransportError("Relay task credentials require HTTPS outside literal loopback addresses");
     }
-    catch (cause) {
-        throw new AgentRelayTransportError('agent-relay spawn response was not JSON', cause);
+    const baseUrl = base.origin;
+    const timeoutMs = request.timeoutMs ?? 86_400_000;
+    if (!Number.isSafeInteger(timeoutMs) ||
+        timeoutMs < 1 ||
+        timeoutMs > 86_400_000 ||
+        ![
+            request.runId,
+            request.stepId,
+            request.idempotencyKey,
+            request.dataDir,
+            request.cli,
+        ].every(nonempty)) {
+        throw new AgentRelayTransportError("Relay task requires durable dispatch identity and a valid deadline");
     }
-    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() {
-            // 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();
+    const pollMs = options.pollMs ?? 1000;
+    if (!Number.isFinite(pollMs) || pollMs < 1)
+        throw new AgentRelayTransportError("Invalid Relay task polling interval");
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const outer = options.signal ?? new AbortController().signal;
+    let deadline = Date.now() + timeoutMs + 30_000;
+    let missingDeadline = Date.now() + 30_000;
+    async function http(path, body) {
+        for (;;) {
+            outer.throwIfAborted();
+            if (Date.now() >= deadline)
+                throw new AgentRelayTransportError("Relay task status unavailable before its reconciliation deadline");
+            const bounded = AbortSignal.any([
+                outer,
+                AbortSignal.timeout(Math.min(15_000, Math.max(1, deadline - Date.now()))),
+            ]);
+            let response;
+            let value;
             try {
-                await doFetch(closeUrl, {
-                    method: 'POST',
-                    headers,
-                    body: JSON.stringify({ reason: 'sdk_transport_close' }),
+                response = await doFetch(new URL(path, baseUrl), {
+                    method: body === undefined ? "GET" : "POST",
+                    redirect: "error",
+                    signal: bounded,
+                    headers: {
+                        authorization: `Bearer ${env.agentToken}`,
+                        "content-type": "application/json",
+                        ...(body === undefined
+                            ? {}
+                            : { "Idempotency-Key": request.idempotencyKey }),
+                    },
+                    ...(body === undefined ? {} : { body: canonicalize(body) }),
                 });
+                if (response.status === 404 &&
+                    body === undefined &&
+                    path.includes("/invocations/")) {
+                    if (Date.now() >= missingDeadline)
+                        throw new AgentRelayTransportError("Relay task dispatch remains unconfirmed; no repeat POST is permitted");
+                }
+                else if (!response.ok &&
+                    response.status !== 429 &&
+                    response.status < 500) {
+                    // Never copy untrusted response bodies, URLs, or tokens into diagnostics.
+                    throw new AgentRelayTransportError(`Relay task request refused with HTTP ${response.status}`);
+                }
+                if (response.ok)
+                    value = await response.json();
+                if (body !== undefined && !response.ok)
+                    return {}; // ambiguous POST: GET only below
+            }
+            catch (error) {
+                outer.throwIfAborted();
+                if (error instanceof AgentRelayTransportError)
+                    throw error;
+                if (body !== undefined)
+                    return {}; // response loss or invalid JSON never causes another POST
+                if (response?.ok && !bounded.aborted)
+                    throw new AgentRelayTransportError("Relay task response was not valid JSON");
             }
-            catch {
-                // Deliberate: close is advisory in this minimum-viable slice.
+            outer.throwIfAborted();
+            if (response?.ok && value !== undefined) {
+                if (!isRecord(value) || value.ok !== true || !isRecord(value.data))
+                    throw new AgentRelayTransportError("Relay task response has an invalid data envelope");
+                return value.data;
             }
+            await delay(pollMs, undefined, { signal: outer });
+        }
+    }
+    // Resolving the agent is read-only. Pin identity before any invocation so a
+    // restarted runner cannot create a second task using another caller's key.
+    const agent = await http("/v1/agent");
+    if (!nonempty(agent.id))
+        throw new AgentRelayTransportError("Relay task caller identity is missing");
+    if (!nonempty(agent.workspace_id))
+        throw new AgentRelayTransportError("Relay task workspace identity is missing");
+    // Pinned action-invoke-v1 identity contract from Relaycast #436.
+    const invocationId = "inv_idem_" +
+        createHash("sha256")
+            .update([
+            "action-invoke-v1",
+            agent.workspace_id,
+            agent.id,
+            "task.run",
+            request.idempotencyKey,
+        ].join("\0"))
+            .digest("hex");
+    const input = {
+        cli: request.cli,
+        task: request.task,
+        ...(request.model === undefined ? {} : { model: request.model }),
+        ...(request.worker_cwd === undefined
+            ? {}
+            : { worker_cwd: request.worker_cwd }),
+        ...(request.result_schema === undefined
+            ? {}
+            : { result_schema: request.result_schema }),
+        task_context: {
+            run_id: request.runId,
+            step_id: request.stepId,
+            dispatch_id: request.idempotencyKey,
+            timeout_ms: timeoutMs,
         },
     };
-}
-/**
- * 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, stepId) {
-    // Keep readable + collision-safe: prefix with 'flow-' and use lower-kebab.
-    const clean = (s) => s.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
-    return `flow-${clean(runId)}-${clean(stepId)}`.slice(0, 96);
+    const { claim, created } = await claimRelayTask(request.dataDir, {
+        version: 1,
+        baseUrl,
+        callerId: agent.id,
+        workspaceId: agent.workspace_id,
+        invocationId,
+        runId: request.runId,
+        stepId: request.stepId,
+        idempotencyKey: request.idempotencyKey,
+        input,
+        startedAt: Date.now(),
+    });
+    // A restarted runner may recover a terminal receipt after the task deadline.
+    // Give that read one bounded window; never reopen or extend the remote task.
+    deadline = Math.max(claim.startedAt + timeoutMs + 30_000, Date.now() + 15_000);
+    missingDeadline = claim.startedAt + 30_000;
+    if (created) {
+        const ack = await http("/v1/actions/task.run/invoke", { input });
+        if (Object.keys(ack).length &&
+            (ack.invocation_id !== invocationId ||
+                ack.action_name !== "task.run" ||
+                canonicalize(ack.input) !== canonicalize(input))) {
+            throw new AgentRelayTransportError("Relay task acknowledgment has mismatched invocation or input");
+        }
+    }
+    let previous;
+    for (;;) {
+        const value = await http(`/v1/actions/task.run/invocations/${encodeURIComponent(invocationId)}`);
+        if (value.caller_id !== agent.id)
+            throw new AgentRelayTransportError("Relay task receipt belongs to another caller");
+        const receipt = readTaskReceipt(value, invocationId, input, previous);
+        outer.throwIfAborted();
+        if (receipt.status === "completed" || receipt.status === "failed")
+            return receipt;
+        previous = receipt;
+        await delay(pollMs, undefined, { signal: outer });
+    }
 }
 //# sourceMappingURL=agent-relay-transport.js.map