@relayflows/sdk 2.0.9 → 2.0.11

package/src/agent-relay-transport.ts

@@ -0,0 +1,273 @@
+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,
+  type RelayTaskReceipt,
+} from "./agent-relay-receipt.js";
+
+export type AgentTransport = "direct" | "relay";
+export interface AgentRelayTaskRequest {
+  cli: string;
+  task: string;
+  model?: string;
+  worker_cwd?: 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 {
+  baseUrl?: string;
+  agentToken?: string;
+}
+export class AgentRelayTransportError extends Error {
+  constructor(
+    message: string,
+    public readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = "AgentRelayTransportError";
+  }
+}
+export function readAgentRelayEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): Required<AgentRelayEnv> {
+  const agentToken = env.RELAY_AGENT_TOKEN?.trim();
+  if (!agentToken)
+    throw new AgentRelayTransportError(
+      "Relay task transport requires a pre-provisioned RELAY_AGENT_TOKEN.",
+    );
+  return {
+    baseUrl: env.RELAY_BASE_URL?.trim() || "https://cast.agentrelay.com",
+    agentToken,
+  };
+}
+
+/** Exact Relaycast #436 HTTP contract. Only terminal GET receipts can return. */
+export async function runAgentRelayTask(
+  request: AgentRelayTaskRequest,
+  options: AgentRelayEnv & {
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+    pollMs?: number;
+  } = {},
+): Promise<RelayTaskReceipt> {
+  const env = options.agentToken
+    ? {
+        baseUrl: options.baseUrl || "https://cast.agentrelay.com",
+        agentToken: options.agentToken,
+      }
+    : { ...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",
+    );
+  }
+  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 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: string,
+    body?: unknown,
+  ): Promise<Record<string, unknown>> {
+    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: Response | undefined;
+      let value: unknown;
+      try {
+        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",
+          );
+      }
+      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,
+    },
+  };
+  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: RelayTaskReceipt | undefined;
+  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 });
+  }
+}

package/src/authored-budget.ts

@@ -0,0 +1,69 @@
+import { BudgetSyntaxError, parseBudget, toKernelBudget } from './budget.js';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import type { JournalClient } from './journal-client.js';
+import type { RunOutcome } from './protocol.js';
+import type { KernelBudgetSpec, KernelRunSpec } from './spec.js';
+
+/** Serialized admission for the internal authored runner's separate step runs. */
+export class AuthoredBudget {
+  private readonly limit: KernelBudgetSpec | undefined;
+  private failed = false;
+  private tail: Promise<unknown> = Promise.resolve();
+  private charges: { input: bigint; output: bigint; micro: bigint; ms: bigint; day: number }[] = [];
+
+  constructor(header: unknown) {
+    try {
+      this.limit = header === undefined ? undefined : toKernelBudget(parseBudget(header));
+    } catch (error) {
+      if (error instanceof BudgetSyntaxError) throw new AuthoredFlowExecutionError('budget_syntax_invalid', error.message);
+      throw error;
+    }
+  }
+
+  async execute<T>(journal: JournalClient, spec: KernelRunSpec, consume: (outcome: RunOutcome) => Promise<T>): Promise<T> {
+    if (this.limit === undefined) return consume(await journal.runStart(spec));
+    const previous = this.tail;
+    let release!: () => void;
+    this.tail = new Promise<void>(resolve => { release = resolve; });
+    await previous;
+    try {
+      if (this.failed) throw new AuthoredFlowExecutionError('step_failed', 'A prior budgeted step did not finish successfully.');
+      // Window selection follows journal timestamps, never the SDK host clock.
+      const day = this.charges.at(-1)?.day;
+      const total = this.charges.filter(c => this.limit!.window !== 'day' || c.day === day)
+        .reduce((s, c) => ({ input: s.input + c.input, output: s.output + c.output, micro: s.micro + c.micro, ms: s.ms + c.ms }),
+          { input: 0n, output: 0n, micro: 0n, ms: 0n });
+      const exactNumber = (n: bigint) => { if (n > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error('budget counter overflow'); return Number(n); };
+      const outcome = await journal.runStart({ ...spec, budget: { ...this.limit, prior_spend: {
+        tokens_in: exactNumber(total.input), tokens_out: exactNumber(total.output),
+        dollars: `${total.micro / 1_000_000n}.${String(total.micro % 1_000_000n).padStart(6, '0')}`,
+        wallclock_ms: exactNumber(total.ms), ...(this.limit.window === 'day' && day !== undefined ? { day } : {}),
+      } } });
+      try {
+        if (outcome.completion_reason === 'budget_exceeded') throw new AuthoredFlowExecutionError('step_failed', 'Flow budget exceeded before the next step.', 'budget_exceeded', outcome.run_id);
+        return await consume(outcome);
+      } finally {
+        let seq = 1;
+        for (;;) {
+          const { entries } = await journal.journalRead(outcome.run_id, seq);
+          if (entries.length === 0) break;
+          for (const raw of entries) {
+            const e = raw as {seq: number; entry_type: string; at_ms: number; payload: {budget?: {tokens_in: number; tokens_out: number; dollars: string}; spend?: {wallclock_ms: number}}};
+            seq = e.seq + 1;
+            if (!['step.completed', 'memory.injected'].includes(e.entry_type)) continue;
+            const b = e.payload.budget;
+            if (b === undefined) throw new Error('journal completion missing budget');
+            const [whole, fraction = ''] = b.dollars.split('.');
+            if (fraction.length > 6 && /[1-9]/.test(fraction.slice(6))) throw new Error('budget accounting requires microdollar precision');
+            this.charges.push({input: BigInt(b.tokens_in), output: BigInt(b.tokens_out),
+              micro: BigInt(whole!) * 1_000_000n + BigInt(fraction.slice(0, 6).padEnd(6, '0')),
+              ms: BigInt(e.payload.spend?.wallclock_ms ?? 0), day: Math.floor(e.at_ms / 86_400_000)});
+          }
+        }
+      }
+    } catch (error) {
+      this.failed = true;
+      throw error;
+    } finally { release(); }
+  }
+}

package/src/authored-flow-error.ts

@@ -1,18 +1,27 @@
-import type { CheckFailureKind } from './failure-kinds.js';
 import type {
   CompletionReason as ProtocolCompletionReason,
   RunCompletionReason as ProtocolRunCompletionReason,
 } from './protocol.js';
 
 export type AuthoredFlowExecutionErrorCode =
+  | 'helper_provider.mount_required'
+  | 'helper_provider.unsupported'
+  | 'helper_slack.credential_missing'
+  | 'helper_slack.mount_required'
+  | 'budget_syntax_invalid'
+  | 'budget_missing_price'
   | 'agent_cli_unresolved'
   | 'agent_parked'
+  | 'llm_cli_unresolved'
+  | 'llm_parked'
   | 'duplicate_completion'
   | 'journal_protocol_violation'
   | 'missing_completion'
+  | 'memory_unreachable'
   | 'operation_after_completion'
   | 'operation_callback_failed'
   | 'step_failed'
+  | 'lease_exceeded'
   | 'unsupported_completion'
   | 'unsupported_gate'
   | 'unsupported_header'
@@ -28,15 +37,6 @@ export class AuthoredFlowExecutionError extends Error {
     message: string,
     readonly completionReason?: ProtocolCompletionReason | ProtocolRunCompletionReason,
     readonly runId?: string,
-    /**
-     * Set only for `code === 'agent_cli_unresolved'`: the specific preflight
-     * refusal kind (`cli_missing`, `model_unknown`, `model_unavailable`, ...)
-     * `checkAuthoredFlow` actually produced, so a caller can distinguish a bad
-     * model declaration from a missing CLI the same way the declarative
-     * `flows check` path's `report.diagnostics[].kind` already lets it —
-     * collapsing every refusal to one generic code would lose that taxonomy.
-     */
-    readonly refusalKind?: CheckFailureKind,
   ) {
     super(`${code}: ${message}`);
     this.name = 'AuthoredFlowExecutionError';