@relayflows/sdk 2.0.9 → 2.0.11

package/src/authored-plugin-effect.ts

@@ -0,0 +1,152 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { compileSpec, toKernelSpec } from './compile.js';
+import { invokePlugin, type LoadedPlugin } from './plugin-loader.js';
+import type { PluginVerb } from './plugin-manifest.js';
+import type { AuthoredBudget } from './authored-budget.js';
+import { SPEC_SCHEMA_VERSION } from './spec.js';
+import type { JournalClient } from './journal-client.js';
+import type { StepDispatchEvent } from './protocol.js';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
+import { readCompletedStepOutput } from './authored-step-output.js';
+import { withWorkerLease } from './worker-lease.js';
+
+export class PluginStepError extends AuthoredFlowExecutionError {
+  constructor(readonly diagnostic: string, runId: string) {
+    super('step_failed', diagnostic, 'worker_error', runId);
+  }
+}
+
+/** Helpers lower to an existing agent effect, never a fourth kernel primitive.
+ * The Plugin receipt lives in step.completed.output: { type, input, output, ... }.
+ * A private stream routes the step to this short-lived SDK worker exclusively.
+ */
+export async function runPluginEffect(
+  journal: JournalClient, flowName: string, id: string, plugin: LoadedPlugin, verb: PluginVerb,
+  args: unknown, journalSteps: AuthoredFlowJournalStep[], budget: AuthoredBudget,
+): Promise<unknown> {
+  const server = verb.namespace;
+  const tool = verb.method;
+  const idempotencyKey = `plugin:${server}:${tool}:${createHash('sha256').update(JSON.stringify(args)).digest('hex')}`;
+  const surfacePath = `/plugins/${pathPart(server)}/${pathPart(tool)}`;
+  const stream = `plugin-worker-${randomUUID()}`;
+  const instruction = JSON.stringify({ type: 'effect', server, tool, input: args });
+  const peer = journal.createPeer();
+  let diagnostic: string | undefined;
+  let settled!: () => void;
+  let failed!: (error: unknown) => void;
+  const completed = new Promise<void>((resolve, reject) => { settled = resolve; failed = reject; });
+  void completed.catch(() => undefined);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let work: Promise<void> | undefined;
+  let dispatchExpired = false;
+  const dispatch = (event: StepDispatchEvent): void => {
+    if (dispatchExpired) return;
+    const dispatched = event.spec as { instruction?: string; surfaces?: { streams?: { stream: string }[] } };
+    if (event.step_id !== id || event.step_type !== 'agent' || work !== undefined
+      || dispatched?.instruction !== instruction
+      || !dispatched.surfaces?.streams?.some(pin => pin.stream === stream)) {
+      failed(new Error('Plugin worker received an unexpected dispatch'));
+      return;
+    }
+    clearTimeout(timer);
+    timer = undefined;
+    work = execute(event);
+    void work.then(settled, failed);
+  };
+  async function execute(event: StepDispatchEvent): Promise<void> {
+    const receipt = { type: 'effect' as const, plugin: plugin.manifest.name, version: plugin.manifest.version,
+      namespace: server, method: tool, input: args, idempotencyKey: event.idempotency_key };
+    let output: unknown;
+    let confirmed = false;
+    try {
+      // Renew the worker lease while the Plugin tool is in flight. Without this,
+      // a tool that runs longer than the initial lease loses ownership and
+      // the write-back path fails — see worker-lease.ts for the renewal contract.
+      confirmed = await withWorkerLease(peer, event, async () => {
+        return peer.performEffect({
+          runId: event.run_id, stepId: id, attempt: event.attempt, idempotencyKey: event.idempotency_key,
+          surfacePath, revisionBefore: 'pending', revisionAfter: idempotencyKey,
+        }, async () => {
+          try { output = await invokePlugin(plugin, verb, args, event.idempotency_key); }
+          catch { diagnostic = 'plugin_execution_failed'; throw new PluginExecutionFailure(); }
+        });
+      });
+      // A confirmed election without its receipt is an interrupted writeback,
+      // not a successful result we may invent or a call we may safely repeat.
+      if (!confirmed) throw new Error('plugin_result_unavailable');
+    } catch (error) {
+      if (error instanceof PluginExecutionFailure) diagnostic = 'plugin_execution_failed';
+      else if (error instanceof Error && error.message === 'plugin_result_unavailable') diagnostic = error.message;
+      else throw error; // Journal failures remain fail-closed, never provider errors.
+    }
+    await peer.stepComplete(event.run_id, id, event.attempt, event.idempotency_key,
+      diagnostic === undefined ? 'success' : 'worker_error', {
+        output: { ...receipt, output: output ?? null, ...(diagnostic ? { diagnostic } : {}) },
+        started_pins: event.pins, end_pins: event.pins,
+        ...(diagnostic ? { trajectory_tail: { ...receipt, diagnostic } } : {}),
+        effects: confirmed ? [{ surface_path: surfacePath, idempotency_key: event.idempotency_key }] : [],
+      });
+  }
+  let childRunId: string | undefined;
+  async function cancelChildRun(): Promise<void> {
+    const runId = childRunId;
+    childRunId = undefined;
+    if (runId !== undefined) {
+      try { await journal.runCancel(runId); } catch { /* fail-open on cleanup */ }
+    }
+  }
+  const deadlineError = new Error('Plugin worker dispatch deadline exceeded');
+  let finishDeadline!: () => void;
+  const deadline = new Promise<void>((resolve, reject) => {
+    finishDeadline = resolve;
+    // One deadline covers connection, initialization, run creation and dispatch.
+    timer = setTimeout(() => {
+      dispatchExpired = true;
+      failed(deadlineError);
+      reject(deadlineError);
+    }, 30_000);
+  });
+  try {
+    await Promise.race([peer.connect(), deadline]);
+    await Promise.race([peer.hello('flows-plugin'), deadline]);
+    peer.on('step.dispatch', dispatch);
+    await Promise.race([peer.workerAttach(stream, ['agent'], { workspace: [], streams: [{ stream, read_offset: 0 }] }, 1), deadline]);
+    const spec = toKernelSpec(compileSpec({ version: SPEC_SCHEMA_VERSION, name: `${flowName}/${id}`,
+      steps: [{ id, type: 'agent', instruction,
+        surfaces: { streams: [{ stream }], external: [surfacePath] }, maxIterations: 1 }],
+    }));
+    return await Promise.race([budget.execute(journal, spec, async outcome => {
+      childRunId = outcome.run_id;
+      // run.start may answer after the deadline and the outer cleanup.
+      if (dispatchExpired) await cancelChildRun();
+      await completed;
+      if (diagnostic !== undefined) {
+        try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps); }
+        catch (error) {
+          if (!(error instanceof AuthoredFlowExecutionError) || error.code !== 'step_failed') throw error;
+          throw new PluginStepError(diagnostic, outcome.run_id);
+        }
+      }
+      const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps) as { output: unknown };
+      return receipt.output;
+    }), deadline]);
+  } finally {
+    clearTimeout(timer);
+    finishDeadline();
+    peer.off('step.dispatch', dispatch);
+    // If the dispatch deadline fired we started a child run that will never
+    // be worked -- cancel it so its journal doesn't stay indeterminate.
+    // Best-effort: the parent flow already surfaced the deadline via the
+    // rejected `completed` promise, so a cancel error here must not mask it.
+    if (dispatchExpired) await cancelChildRun();
+    peer.close();
+    await work?.catch(() => undefined);
+  }
+}
+
+function pathPart(value: string): string {
+  return encodeURIComponent(value).replaceAll('.', '%2E');
+}
+
+class PluginExecutionFailure extends Error {}

package/src/authored-step-output.ts

@@ -0,0 +1,107 @@
+import { COMPLETION_REASONS, RUN_COMPLETION_REASONS } from '@relayflows/surface';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import type { JournalClient } from './journal-client.js';
+import type { CompletionReason as ProtocolCompletionReason, RunCompletionReason as ProtocolRunCompletionReason, RunOutcome } from './protocol.js';
+import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
+
+/**
+ * Shared by every `f.*` verb that lowers to one kernel step run in isolation:
+ * find its `step.completed` entry, record it, and refuse anything but a
+ * clean success before handing the raw `output` back for verb-specific
+ * extraction (a plain string for `f.run`, an `AgentResult` for `f.agent`).
+ *
+ * Callers are responsible for having already established that the RUN
+ * reached a terminal, successful state before calling this — `f.run`'s
+ * caller relies on `runStart`'s own immediate response (the kernel drives a
+ * deterministic step to completion inline, no race); `f.agent`'s caller
+ * relies on `classifyOutcome` (cli/run.ts) having already polled to a true
+ * terminal state. Given that, a single read from the start of this run's
+ * (small, single-step) journal is enough — no polling here, and no run
+ * outcome ever needs re-checking.
+ */
+export async function readCompletedStepOutput(
+  journal: JournalClient,
+  runId: string,
+  stepId: string,
+  journalSteps: AuthoredFlowJournalStep[],
+): Promise<unknown> {
+  const entries = (await journal.journalRead(runId, 1)).entries;
+  const completed = entries.find((entry) => isStepCompleted(entry, stepId));
+  if (!isStepCompleted(completed, stepId)) {
+    throw protocolViolation(runId, `journal has no step.completed for "${stepId}"`);
+  }
+
+  const reason = completed.payload.completionReason;
+  journalSteps.push(Object.freeze({ id: stepId, runId, completionReason: reason }));
+  if (reason !== 'success') {
+    throw new AuthoredFlowExecutionError(
+      'step_failed',
+      `journal step "${stepId}" completed with ${reason}`,
+      reason,
+      runId,
+    );
+  }
+  return completed.payload.output;
+}
+
+export async function readSuccessfulOutput(
+  journal: JournalClient,
+  outcome: RunOutcome,
+  stepId: string,
+  journalSteps: AuthoredFlowJournalStep[],
+): Promise<string> {
+  const output = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps).catch(error => {
+    if (error instanceof AuthoredFlowExecutionError
+      && (error.completionReason === 'timeout' || error.completionReason === 'lease_expired')) {
+      throw new AuthoredFlowExecutionError('lease_exceeded',
+        `f.run step "${stepId}" exceeded its command timeout.`, error.completionReason, error.runId);
+    }
+    throw error;
+  });
+  if (!isRecord(output) || typeof output['stdout_tail'] !== 'string') {
+    throw protocolViolation(outcome.run_id, `step "${stepId}" has no string stdout_tail`);
+  }
+  return output['stdout_tail'];
+}
+
+interface StepCompletedEntry {
+  entry_type: 'step.completed';
+  step_id: string;
+  payload: {
+    completionReason: ProtocolCompletionReason;
+    output: unknown;
+  };
+}
+
+function isStepCompleted(value: unknown, stepId: string): value is StepCompletedEntry {
+  if (!isRecord(value) || value['entry_type'] !== 'step.completed' || value['step_id'] !== stepId) {
+    return false;
+  }
+  const payload = value['payload'];
+  return isRecord(payload)
+    && isSurfaceCompletionReason(payload['completionReason'])
+    && 'output' in payload;
+}
+
+export function isSurfaceCompletionReason(value: unknown): value is ProtocolCompletionReason {
+  return typeof value === 'string'
+    && (COMPLETION_REASONS as readonly string[]).includes(value);
+}
+
+export function isSurfaceRunCompletionReason(value: unknown): value is ProtocolRunCompletionReason {
+  return typeof value === 'string'
+    && (RUN_COMPLETION_REASONS as readonly string[]).includes(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function protocolViolation(runId: string, detail: string): AuthoredFlowExecutionError {
+  return new AuthoredFlowExecutionError(
+    'journal_protocol_violation',
+    detail,
+    undefined,
+    runId,
+  );
+}

package/src/authored-worker-step.ts

@@ -0,0 +1,181 @@
+import type { AuthoredBudget } from './authored-budget.js';
+import { parseBudget } from './budget.js';
+import type { AgentOptions, AgentResult, LlmOptions, NamedGate } from '@relayflows/surface';
+import { compileSpec, toKernelSpec } from './compile.js';
+import { checkAuthoredFlow } from './cli/check.js';
+import { classifyOutcome, type RunLifecycleOptions } from './cli/run.js';
+import type { PreflightDiagnostic } from './preflight.js';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import type { JournalClient } from './journal-client.js';
+import { SPEC_SCHEMA_VERSION, type FlowSpec, type StepSpec } from './spec.js';
+import { isSurfaceCompletionReason, readCompletedStepOutput, readSuccessfulOutput } from './authored-step-output.js';
+import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
+import { snapshotJsonValue } from './json-value.js';
+
+const WORKSPACE_PERMISSION_ANNOTATION = /:\s*(readonly|readwrite)\s*$/i;
+
+/** Agent and LLM calls share the exact declarative preflight and lease wait. */
+export function authoredWorkerRunner(
+  definition: { name: string }, journal: JournalClient, flowPath: string,
+  journalSteps: AuthoredFlowJournalStep[], waitOptions: RunLifecycleOptions,
+  localAgentStream?: string, budget?: AuthoredBudget, headerBudget?: unknown,
+) {
+  async function run(step: StepSpec): Promise<unknown> {
+    const id = step.id;
+    const authoring: FlowSpec = { version: SPEC_SCHEMA_VERSION, name: `${definition.name}/${id}`, steps: [step], ...(headerBudget === undefined ? {} : { budget: parseBudget(headerBudget) }) };
+    // The kernel never resolves a `cli` on its own — every declarative
+    // `flows run`/`flows check` binds it first via this exact function
+    // (cli/check.ts), searching for the nearest flows.json from `flowPath`
+    // and real-probing auth/model readiness. An authored agent step gets
+    // nothing for free just because it was declared in TS instead of YAML.
+    const { report, flow: resolved } = checkAuthoredFlow(authoring, flowPath);
+    if (!report.ok || resolved === undefined) {
+      const refusal = report.diagnostics.find(
+        (diagnostic): diagnostic is PreflightDiagnostic & { severity: 'refusal' } =>
+          diagnostic.severity === 'refusal',
+      );
+      throw new AuthoredFlowExecutionError(
+        refusal?.kind === 'budget_missing_price' || refusal?.kind === 'budget_syntax_invalid' ? refusal.kind
+          : step.type === 'llm' ? 'llm_cli_unresolved' : 'agent_cli_unresolved',
+        refusal?.message
+          ?? `flow "${definition.name}" step "${id}": no CLI could be resolved for f.${step.type} `
+            + `(searched for flows.json from "${flowPath}")`,
+      );
+    }
+    const spec = toKernelSpec(resolved);
+    const consume = async (outcome: import('./protocol.js').RunOutcome) => {
+    // Reuse the declarative CLI's own wait/classification (cli/run.ts) rather
+    // than a hand-rolled poll: `step.completed` and the run's own terminal
+    // state are appended as two SEPARATE actions (kernel/relayflowd-core/src/machine.rs
+    // completion_actions vs complete_run_actions), so a naive read right
+    // after runStart can race a real, valid completion — and a genuinely
+    // long-running agent has no reason to be bounded by anything other than
+    // its own worker's lease, which classifyOutcome already follows
+    // (renewing as the lease renews, per docs/SURFACE.md §5's WAITING
+    // [worker_lease] contract), never an unrelated fixed deadline.
+    const execution = await classifyOutcome(journal, 'run', outcome, report, '', waitOptions);
+    if (execution.exitCode === 3) {
+      const parked = execution.report.parkedStep;
+      throw new AuthoredFlowExecutionError(
+        step.type === 'llm' ? 'llm_parked' : 'agent_parked',
+        execution.report.diagnostics.at(-1)?.message
+          ?? `flow "${definition.name}" step "${id}" parked`
+            + (parked !== undefined ? ` (${parked.type})` : '')
+            + ': no worker is attached to run it.',
+        undefined,
+        outcome.run_id,
+      );
+    }
+    if (execution.exitCode !== 0) {
+      const reason = execution.report.completionReason;
+      throw new AuthoredFlowExecutionError(
+        'step_failed',
+        execution.report.diagnostics.at(-1)?.message
+          ?? `flow "${definition.name}" step "${id}" did not complete successfully `
+            + `(status: ${execution.report.status ?? 'unknown'})`,
+        isSurfaceCompletionReason(reason) ? reason : undefined,
+        outcome.run_id,
+      );
+    }
+    return readCompletedStepOutput(journal, outcome.run_id, id, journalSteps);
+    };
+    return budget === undefined ? consume(await journal.runStart(spec)) : budget.execute(journal, spec, consume);
+  }
+
+  return {
+    async agent(id: string, options: AgentOptions, verification?: NamedGate): Promise<AgentResult> {
+      if (options.workspace !== undefined && localAgentStream !== undefined) {
+        throw new AuthoredFlowExecutionError('unsupported_workspace_permission',
+          'The local agent worker accepts stream-only steps. Remove workspace or attach a worker that holds its revision pins.');
+      }
+      if (options.workspace !== undefined && WORKSPACE_PERMISSION_ANNOTATION.test(options.workspace)) {
+        throw new AuthoredFlowExecutionError(
+          'unsupported_workspace_permission',
+          `flow "${definition.name}" step "${id}": workspace "${options.workspace}" declares a `
+            + 'permission annotation ("...: readonly" / "...: readwrite"), but nothing enforces it — '
+            + 'no parser anywhere in this package turns that annotation into a real restriction '
+            + '(kernel/DAEMON-LIFECYCLE.md\'s permission model is untouched by f.agent). '
+            + 'Silently accepting and ignoring it would let a flow believe a restriction is in effect '
+            + "when it is not. Declare a bare surface name (no trailing \": readonly\"/\": readwrite\") "
+            + 'if you do not need enforcement, or use the declarative spec\'s `permissions` field, which is real.',
+        );
+      }
+      if (options.cli !== undefined && typeof options.cli !== 'string') {
+        throw new AuthoredFlowExecutionError(
+          'agent_cli_unresolved',
+          `f.agent options.cli must be a string when set (got ${typeof options.cli}).`,
+        );
+      }
+      if (options.model !== undefined && typeof options.model !== 'string') {
+        throw new AuthoredFlowExecutionError(
+          'agent_cli_unresolved',
+          `f.agent options.model must be a string when set (got ${typeof options.model}).`,
+        );
+      }
+      if (options.cwd !== undefined && typeof options.cwd !== 'string') {
+        throw new AuthoredFlowExecutionError(
+          'agent_cli_unresolved',
+          `f.agent options.cwd must be a string when set (got ${typeof options.cwd}).`,
+        );
+      }
+      if (options.transport !== undefined && options.transport !== 'direct' && options.transport !== 'relay') {
+        throw new AuthoredFlowExecutionError(
+          'agent_cli_unresolved',
+          `f.agent options.transport must be 'direct' or 'relay' (got ${JSON.stringify(options.transport)}).`,
+        );
+      }
+      const output = await run({
+        id, type: 'agent', instruction: options.task,
+        ...(localAgentStream === undefined ? {} : { surfaces: { streams: [{ stream: localAgentStream }] } }),
+        ...(options.workspace === undefined ? {} : { surfaces: { workspace: [{ surface: options.workspace }] } }),
+        ...(options.cli === undefined ? {} : { cli: options.cli }),
+        ...(options.model === undefined ? {} : { model: options.model }),
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        ...(options.transport === undefined ? {} : { transport: options.transport }),
+        ...(verification === undefined ? {} : { verification }),
+      });
+      if (typeof output !== 'object' || output === null || Array.isArray(output)) {
+        throw new AuthoredFlowExecutionError('journal_protocol_violation', `step "${id}" produced a non-object output`);
+      }
+      const stdout = 'stdout_tail' in output ? output.stdout_tail : undefined;
+      return { summary: typeof stdout === 'string' ? stdout : JSON.stringify(output), artifacts: [] };
+    },
+    async llm(id: string, prompt: string, options?: LlmOptions, verification?: NamedGate): Promise<unknown> {
+      if (options !== undefined && (typeof options !== 'object' || options === null || options.output === undefined)) {
+        throw new AuthoredFlowExecutionError('llm_cli_unresolved', 'f.llm(prompt, options) requires an output JSON Schema.');
+      }
+      const snapshot = options === undefined ? undefined : snapshotJsonValue(options, 'f.llm options');
+      if (snapshot !== undefined && (typeof snapshot !== 'object' || snapshot === null || Array.isArray(snapshot)
+        || Object.keys(snapshot).some(key => !['output', 'cli', 'model'].includes(key)))) {
+        throw new AuthoredFlowExecutionError('llm_cli_unresolved', 'f.llm options accepts only output, cli, and model.');
+      }
+      const output = await run({
+        id, type: 'llm', prompt, ...snapshot as unknown as LlmOptions,
+        ...(verification === undefined ? {} : { verification }),
+      });
+      if (options === undefined && typeof output !== 'string') {
+        throw new AuthoredFlowExecutionError('journal_protocol_violation', `text step "${id}" produced a non-string output`);
+      }
+      return output;
+    },
+  };
+}
+
+/** Deterministic commands execute inline under their per-invocation lease. */
+export function authoredDeterministicRunner(
+  name: string, journal: JournalClient, journalSteps: AuthoredFlowJournalStep[], budget: AuthoredBudget,
+) {
+  return async (id: string, command: string, terminal = false, leaseMs?: number, verification?: NamedGate): Promise<string> => {
+    const spec = toKernelSpec(compileSpec({
+      version: SPEC_SCHEMA_VERSION,
+      name: `${name}/${id}`,
+      steps: [{
+        id, type: 'deterministic', command,
+        ...(leaseMs === undefined ? {} : { lease_ms: leaseMs }),
+        ...(verification === undefined ? {} : { verification }),
+      }],
+    }));
+    if (terminal) return readSuccessfulOutput(journal, await journal.runStart(spec), id, journalSteps);
+    return budget.execute(journal, spec, outcome => readSuccessfulOutput(journal, outcome, id, journalSteps));
+  };
+}

package/src/budget-preflight.ts

@@ -0,0 +1,31 @@
+import type { CompiledFlowSpec } from './compile.js';
+import type { PreflightRefusal } from './preflight.js';
+import { MODEL_PRICING } from './model-pricing.js';
+
+/** Legacy explicit envelopes keep their worker-supplied pricing contract. */
+export function budgetDiagnostics(flow: CompiledFlowSpec): PreflightRefusal[] {
+  if (flow.budget?.pricing !== 'frozen') return [];
+  const diagnostics: PreflightRefusal[] = [];
+  const declared = [
+    ...Object.entries(flow.agents ?? {}).map(([agent, d]) => ({ agent, model: d.model })),
+    ...flow.steps.flatMap(s => s.type !== 'deterministic' && s.model !== undefined
+      ? [{ stepId: s.id, model: s.model }] : []),
+  ];
+  for (const step of flow.steps) {
+    if (step.type === 'deterministic' || flow.budget.maxDollars === undefined) continue;
+    const model = step.model ?? (step.type === 'agent' && step.agent !== undefined
+      ? flow.agents?.[step.agent]?.model : undefined);
+    if (model === undefined) diagnostics.push({
+      severity: 'refusal', kind: 'budget_missing_price', stepId: step.id,
+      message: `Step "${step.id}" needs a declared, priced model for its dollar budget.`,
+    });
+  }
+  for (const declaration of declared) {
+    if (Object.hasOwn(MODEL_PRICING, declaration.model)) continue;
+    diagnostics.push({
+      severity: 'refusal', kind: 'budget_missing_price', ...declaration,
+      message: `Model "${declaration.model}" has no frozen price for budget accounting.`,
+    });
+  }
+  return diagnostics;
+}

package/src/budget.ts

@@ -0,0 +1,49 @@
+import type { BudgetSpec, KernelBudgetSpec } from './spec.js';
+
+export type HeaderBudget = string | { tokens?: number; dollars?: number; wallclock?: string };
+
+export class BudgetSyntaxError extends Error {
+  constructor() { super('budget_syntax_invalid: expected $<amount>/run, $<amount>/day, or { tokens, dollars, wallclock }'); }
+}
+
+/** Normalize surface sugar; existing explicit envelopes remain supported. */
+export function parseBudget(value: unknown): BudgetSpec {
+  if (typeof value === 'string') {
+    const match = /^\$(\d+(?:\.\d{1,6})?)\/(run|day)$/.exec(value);
+    if (!match) throw new BudgetSyntaxError();
+    return { pricing: 'frozen', maxDollars: match[1]!, ...(match[2] === 'day' ? { window: 'day' as const } : {}) };
+  }
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new BudgetSyntaxError();
+  const b = value as Record<string, unknown>;
+  const legacy = ['maxTokensIn', 'maxTokensOut', 'maxTokens', 'maxDollars', 'maxWallclockMs', 'window', 'pricing'];
+  if (Object.keys(b).some(k => legacy.includes(k))) {
+    if (Object.keys(b).some(k => !legacy.includes(k))) throw new BudgetSyntaxError();
+    return b as BudgetSpec;
+  }
+  if (Object.keys(b).some(k => !['tokens', 'dollars', 'wallclock'].includes(k))) throw new BudgetSyntaxError();
+  if (b.tokens !== undefined && (!Number.isSafeInteger(b.tokens) || (b.tokens as number) < 0)) throw new BudgetSyntaxError();
+  if (b.dollars !== undefined && (typeof b.dollars !== 'number' || !Number.isFinite(b.dollars) || b.dollars < 0 || !/^\d+(?:\.\d{1,6})?$/.test(String(b.dollars)))) throw new BudgetSyntaxError();
+  let ms: number | undefined;
+  if (b.wallclock !== undefined) {
+    const match = typeof b.wallclock === 'string' && /^(\d+)(ms|s|m|h|d)$/.exec(b.wallclock);
+    if (!match) throw new BudgetSyntaxError();
+    ms = Number(match[1]) * ({ms:1,s:1000,m:60000,h:3600000,d:86400000}[match[2]!]!);
+    if (!Number.isSafeInteger(ms)) throw new BudgetSyntaxError();
+  }
+  return { pricing: 'frozen', ...(b.tokens === undefined ? {} : {maxTokens: b.tokens as number}),
+    ...(b.dollars === undefined ? {} : {maxDollars: String(b.dollars)}),
+    ...(ms === undefined ? {} : {maxWallclockMs: ms}) };
+}
+
+/** Lower a normalized envelope to the existing kernel protocol. */
+export function toKernelBudget(budget: BudgetSpec): KernelBudgetSpec {
+  return {
+    ...(budget.pricing !== undefined ? { pricing: budget.pricing } : {}),
+    ...(budget.maxTokens !== undefined ? { max_tokens: budget.maxTokens } : {}),
+    ...(budget.maxWallclockMs !== undefined ? { max_wallclock_ms: budget.maxWallclockMs } : {}),
+    ...(budget.window !== undefined ? { window: budget.window } : {}),
+    ...(budget.maxTokensIn !== undefined ? { max_tokens_in: budget.maxTokensIn } : {}),
+    ...(budget.maxTokensOut !== undefined ? { max_tokens_out: budget.maxTokensOut } : {}),
+    ...(budget.maxDollars !== undefined ? { max_dollars: budget.maxDollars } : {}),
+  };
+}

package/src/bundle-transport.ts

@@ -0,0 +1,79 @@
+import { constants } from 'node:fs';
+import { access, cp, lstat, mkdir, mkdtemp, rename, rm } from 'node:fs/promises';
+import { dirname, isAbsolute, join } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { verifyBundle } from './bundle.js';
+
+export type BundleFailureKind = 'bucket_unconfigured' | 'bucket_unreachable'
+  | 'bundle_missing_locally' | 'bundle_signature_invalid' | 'bundle_unsupported' | 'deploy_partial';
+export class BundleFailure extends Error {
+  constructor(readonly kind: BundleFailureKind, message: string) { super(message); }
+}
+export interface DigestReference { name: string; digest: string }
+export function parseDigestReference(value: string): DigestReference | undefined {
+  // Match the safe single-component name grammar used by sealBundle.
+  const match = /^([A-Za-z0-9][A-Za-z0-9._-]*)@sha256:([0-9a-f]{64})$/.exec(value);
+  return match ? { name: match[1]!, digest: match[2]! } : undefined;
+}
+export function bucketDirectory(uri: string, ref: DigestReference): string {
+  try {
+    const url = new URL(uri);
+    if (url.protocol !== 'file:' || url.search || url.hash) throw new Error('expected file:// URI');
+    const path = fileURLToPath(url);
+    if (!isAbsolute(path)) throw new Error('expected absolute bucket path');
+    return join(path, ref.name, 'sha256', ref.digest);
+  } catch {
+    throw new BundleFailure('bucket_unreachable', 'This slice requires an absolute file:// bucket URI.');
+  }
+}
+export async function exists(path: string): Promise<boolean> {
+  try { await lstat(path); return true; }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false; throw error; }
+}
+export async function verifyDigest(directory: string, digest: string): Promise<void> {
+  try { await verifyBundle(directory, digest); }
+  catch (error) { throw new BundleFailure('bundle_signature_invalid', String(error)); }
+}
+/** Publish only a complete, verified directory. Concurrent identical writers converge. */
+export async function copyBundle(source: string, target: string, digest: string): Promise<boolean> {
+  if (await exists(target)) { await verifyDigest(target, digest); return false; }
+  await mkdir(dirname(target), { recursive: true });
+  const staging = await mkdtemp(join(dirname(target), '.bundle-'));
+  try {
+    await cp(source, staging, { recursive: true, dereference: false, verbatimSymlinks: true });
+    await verifyDigest(staging, digest);
+    try { await rename(staging, target); }
+    catch (error) {
+      if (!['EEXIST', 'ENOTEMPTY'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+      await verifyDigest(target, digest);
+      return false;
+    }
+    return true;
+  } finally { await rm(staging, { recursive: true, force: true }); }
+}
+export async function writableBucket(target: string): Promise<void> {
+  try {
+    await mkdir(dirname(target), { recursive: true });
+    await access(dirname(target), constants.W_OK);
+    const probe = await mkdtemp(join(dirname(target), '.probe-'));
+    await rm(probe, { recursive: true });
+  } catch (error) { throw new BundleFailure('bucket_unreachable', String(error)); }
+}
+export async function fetchBundle(ref: DigestReference, bucket: string): Promise<string> {
+  const cacheRoot = process.env['XDG_CACHE_HOME'];
+  const cache = join(cacheRoot && isAbsolute(cacheRoot) ? cacheRoot : join(homedir(), '.cache'),
+    'flows', 'bundles', ref.digest);
+  // Verify every hit; a corrupt cache never executes or silently falls back.
+  if (await exists(cache)) { await verifyDigest(cache, ref.digest); return cache; }
+  const source = bucketDirectory(bucket, ref);
+  try {
+    if (!await exists(source)) throw new BundleFailure('bucket_unreachable', `Bundle is absent at ${bucket}.`);
+    await verifyDigest(source, ref.digest);
+    await copyBundle(source, cache, ref.digest);
+    return cache;
+  } catch (error) {
+    if (error instanceof BundleFailure) throw error;
+    throw new BundleFailure('bucket_unreachable', String(error));
+  }
+}