@relayflows/sdk 2.0.0

package/src/protocol.ts

@@ -0,0 +1,364 @@
+// Journal protocol v0 — the SDK boundary (kernel DESIGN.md §5).
+//
+// Transport: newline-delimited JSON over a unix socket at
+// `<data-dir>/relayflowd.sock`. Requests `{id, verb, params}`; responses
+// `{id, ok: true, result}` or `{id, ok: false, error: {code, message}}`;
+// server-pushed events `{event, data}` (no `id`). Any verb whose journal
+// append fails returns `error{code: "journal_write_failed"}` and the affected
+// step fails — the protocol is fail-closed like everything behind it.
+//
+// This module is the typed wire surface; `journal-client.ts` implements it.
+
+import type { KernelRunSpec, StepType } from './spec.js';
+
+/** Stamped per segment; readers read every past version, writers write newest. */
+export const PROTOCOL_VERSION = 0 as const;
+
+/** A journal append that fails fails the step (AGENTS.md rule 4). */
+export const JOURNAL_WRITE_FAILED = 'journal_write_failed' as const;
+
+export type ProtocolError = { code: string; message: string };
+
+/** Client -> server. */
+export interface Request<P = unknown> {
+  id: string;
+  verb: string;
+  params: P;
+}
+
+/** Server -> client response, correlated by `id`. */
+export type Response<R = unknown> =
+  | { id: string; ok: true; result: R }
+  | { id: string; ok: false; error: ProtocolError };
+
+/** Server -> client push (no `id`). */
+export interface ServerEvent {
+  event: string;
+  data: unknown;
+}
+
+// --- Verb set (gate 1 minimal) ---------------------------------------------
+// Verb names mirror kernel DESIGN.md §5 verbatim.
+
+export type Verb =
+  | 'hello'
+  | 'run.start'
+  | 'run.resume'
+  | 'run.cancel'
+  | 'run.get'
+  | 'run.watch'
+  | 'worker.attach'
+  | 'step.heartbeat'
+  | 'effect.record'
+  | 'effect.confirm'
+  | 'step.complete'
+  | 'event.emit'
+  | 'event.submit'
+  | 'stream.append'
+  | 'stream.read'
+  | 'journal.read';
+
+// --- Typed params / results -------------------------------------------------
+
+export interface HelloParams {
+  protocol: 0;
+  client: string;
+}
+export interface HelloResult {
+  protocol: 0;
+  server: string;
+}
+
+export interface RunStartParams {
+  /**
+   * The kernel spec dialect — the ONE boundary shape `RunSpec::parse`
+   * accepts (snake_case, flat v0 verification, defaults materialized).
+   * The authoring `FlowSpec` never crosses the wire; `JournalClient.runStart`
+   * converts via `toKernelSpec`.
+   */
+  spec: KernelRunSpec;
+}
+export type RunStatus = 'running' | 'completed' | 'failed' | 'interrupted' | 'parked';
+export type RunCompletionReason = 'success' | 'step_failed' | 'canceled' | 'budget_exceeded';
+
+export interface RunOutcome {
+  run_id: string;
+  status: RunStatus;
+  completion_reason: RunCompletionReason | null;
+  completed_steps: number;
+}
+export type RunStartResult = RunOutcome;
+
+export interface RunResumeParams {
+  run_id: string;
+}
+export type RunResumeResult = RunOutcome;
+
+export interface RunCancelParams {
+  run_id: string;
+}
+export type RunCancelResult = RunOutcome;
+
+export interface RunGetParams {
+  run_id: string;
+}
+export type StepStatus =
+  | 'pending'
+  | 'runnable'
+  | 'running'
+  | 'backoff'
+  | 'waiting'
+  | 'needs_human'
+  | 'done';
+export interface StepSnapshot {
+  type: StepType;
+  state: StepStatus;
+  lease_deadline_ms?: number;
+}
+export interface RunGetResult {
+  run_id: string;
+  status: RunStatus;
+  steps: Record<string, StepSnapshot>;
+  budget: { tokens_in: number; tokens_out: number; dollars: string };
+}
+
+export interface RunWatchParams {
+  run_id: string;
+}
+export interface RunWatchResult {
+  watching: string;
+}
+/** `run.watch` opens a push stream of `{event: "entry", data: Entry}`. */
+
+export interface WorkerAttachParams {
+  worker_id: string;
+  step_types: StepType[];
+  /** Maximum concurrent assignments. Omitted means the conservative default 1. */
+  capacity?: number;
+  /**
+   * The surfaces this worker holds, as opaque revisions/offsets. Required when
+   * `step_types` includes `agent` — an agent attempt's start pins come from
+   * here (Appendix A rule 2), so an agent worker with no pins is refused at
+   * attach rather than failing in the middle of a run.
+   */
+  pins?: Pins;
+}
+export interface WorkerAttachResult {
+  worker_id: string;
+}
+/**
+ * Wake-context payload assembled kernel-side at `subscription.matched`.
+ * The two fields typed below are the ones every current consumer keys
+ * against; additional kernel-side fields flow through as extra
+ * properties without breaking this type.
+ */
+export interface WakeContext {
+  triggering_event?: {
+    type: string;
+    payload?: unknown;
+  };
+  epoch_summary?: {
+    open_steps?: string[];
+  };
+  [additionalKernelFields: string]: unknown;
+}
+
+/** Server then pushes `step.dispatch` events to the attached worker. */
+export interface StepDispatchEvent {
+  run_id: string;
+  step_id: string;
+  attempt: number;
+  step_type: StepType;
+  spec: unknown;
+  lease_id: string;
+  idempotency_key: string;
+  pins: Pins;
+  /**
+   * The `wake_context` payload from the run's `subscription.matched`
+   * journal entry — carries the triggering event and any epoch summary
+   * the flow needs to know why this step is running. Present when the
+   * run was spawned by an event; `undefined` for runs started directly
+   * (no trigger fired). A real agent needs this to see the event
+   * payload (e.g. the HN story ID).
+   *
+   * Shape is assembled kernel-side in
+   * `kernel/relayflowd/src/engine/wake.rs` (grep for
+   * `wake_context` — the Rust field is written with quoted
+   * JSON keys so `"wake_context":` hits the assembly site
+   * directly). The narrow type below pins the two fields
+   * every consumer currently reads —
+   * `triggering_event.type`/`payload` and `epoch_summary` — while
+   * keeping the container `unknown`-permissive so a kernel-side
+   * addition (a new nested field) does not break the SDK type. A
+   * kernel-side RENAME of these two fields does break every
+   * consumer; that is deliberate and preferable to silent drift.
+   */
+  wake_context?: WakeContext;
+  recovery?: {
+    mode: 'reset' | 'inspect' | 'manual';
+    restore_pins?: Pins;
+    previous_completion_reason?: CompletionReason;
+    trajectory_tail?: unknown;
+  };
+  lease_deadline_ms: number;
+}
+
+export interface StepHeartbeatParams {
+  run_id: string;
+  step_id: string;
+  attempt: number;
+  lease_id: string;
+}
+export interface StepHeartbeatResult {
+  lease_deadline_ms: number;
+}
+
+/** completionReason mirrors kernel DESIGN.md §1.3. */
+export type CompletionReason =
+  | 'success'
+  | 'verification_failed'
+  | 'retries_exhausted'
+  | 'lease_expired'
+  | 'crashed'
+  | 'timeout'
+  | 'worker_error'
+  | 'budget_exceeded'
+  | 'canceled';
+
+export interface Pins {
+  workspace?: { surface: string; revision_id: string }[];
+  streams?: { stream: string; read_offset: number }[];
+}
+
+export interface EffectRef {
+  surface_path: string;
+  idempotency_key: string;
+}
+
+export interface EffectRecordParams {
+  run_id: string;
+  step_id: string;
+  attempt: number;
+  idempotency_key: string;
+  surface_path: string;
+  revision_before: string;
+  revision_after: string;
+}
+export interface EffectRecordResult {
+  /**
+   * True only when a *confirmed* election already covers this
+   * `(step_id, idempotency_key, surface_path)`: the writeback provably
+   * happened, so this attempt must not call the provider. An election that was
+   * never confirmed does not dedupe — this attempt reclaims it and owes the
+   * call, which is what keeps an effect from being lost to a worker that died
+   * between recording and performing.
+   */
+  deduped: boolean;
+}
+
+/** Phase two: the elected attempt performed the writeback. */
+export interface EffectConfirmParams {
+  run_id: string;
+  step_id: string;
+  attempt: number;
+  idempotency_key: string;
+  surface_path: string;
+}
+export interface EffectConfirmResult {
+  confirmed: string;
+}
+
+export interface StepCompleteParams {
+  run_id: string;
+  step_id: string;
+  attempt: number;
+  idempotency_key: string;
+  completionReason: CompletionReason;
+  output?: unknown;
+  usage?: { tokens_in: number; tokens_out: number; dollars: string };
+  started_pins?: Pins;
+  end_pins?: Pins;
+  effects?: EffectRef[];
+  /** `inspect` evidence for the next attempt. Rejected over 16 KiB of JSON. */
+  trajectory_tail?: unknown;
+}
+export type StepCompleteResult = RunOutcome;
+
+export interface EventEmitParams {
+  run_id: string;
+  event_key: string;
+  payload: unknown;
+}
+export interface EventEmitResult {
+  matched: number;
+}
+
+/**
+ * Submit an external event to a flow that declares an event trigger. The
+ * kernel matches it against the spec's subscriptions and, on a first match,
+ * spawns a run; a repeat of the same (flow, subscription, key) is deduped.
+ */
+export interface EventSubmitParams {
+  spec: unknown;
+  event: {
+    type: string;
+    payload?: unknown;
+    /** Overrides the subscription's dedupeKeyTemplate when supplied. */
+    key?: string;
+  };
+}
+export interface EventSubmitResult {
+  matched: boolean;
+  deduped: boolean;
+  subscription_id?: string | null;
+  run?: unknown;
+}
+
+export interface StreamAppendParams {
+  run_id: string;
+  stream: string;
+  message: unknown;
+}
+export interface StreamAppendResult {
+  offset: number;
+}
+
+export interface StreamReadParams {
+  run_id: string;
+  stream: string;
+  from_offset: number;
+  limit?: number;
+}
+export interface StreamReadResult {
+  messages: unknown[];
+  next_offset: number;
+}
+
+export interface JournalReadParams {
+  run_id: string;
+  from_seq: number;
+  limit?: number;
+}
+export interface JournalReadResult {
+  entries: unknown[];
+}
+
+/** Typed map of verb -> { params, result }. Used by the client for type-safety. */
+export interface VerbContract {
+  hello: { params: HelloParams; result: HelloResult };
+  'run.start': { params: RunStartParams; result: RunStartResult };
+  'run.resume': { params: RunResumeParams; result: RunResumeResult };
+  'run.cancel': { params: RunCancelParams; result: RunCancelResult };
+  'run.get': { params: RunGetParams; result: RunGetResult };
+  'run.watch': { params: RunWatchParams; result: RunWatchResult };
+  'worker.attach': { params: WorkerAttachParams; result: WorkerAttachResult };
+  'step.heartbeat': { params: StepHeartbeatParams; result: StepHeartbeatResult };
+  'effect.record': { params: EffectRecordParams; result: EffectRecordResult };
+  'effect.confirm': { params: EffectConfirmParams; result: EffectConfirmResult };
+  'step.complete': { params: StepCompleteParams; result: StepCompleteResult };
+  'event.emit': { params: EventEmitParams; result: EventEmitResult };
+  'event.submit': { params: EventSubmitParams; result: EventSubmitResult };
+  'stream.append': { params: StreamAppendParams; result: StreamAppendResult };
+  'stream.read': { params: StreamReadParams; result: StreamReadResult };
+  'journal.read': { params: JournalReadParams; result: JournalReadResult };
+}

package/src/spec.ts

@@ -0,0 +1,343 @@
+// Spec types for Relayflows — data, not code (RFC-0001 settled decision #5).
+//
+// Mirrors RFC-0001 §1's ladder. Every rung is a legal relayflow:
+//   deterministic step          # a pure script — no LLM anywhere (legal)
+//     + llm step                # a bare model call — prompt in, verified output out
+//       + agent step            # a harnessed agent in a workspace — artifact + diff + trajectory
+//
+// Step types are exactly `deterministic | llm | agent` (AGENTS.md rule 7).
+// Zero-agent flows are legal: a spec with only `deterministic` (and/or `llm`)
+// steps is valid. Nothing here requires an `agent` step.
+
+import type { JsonOutputSchema } from './output-schema.js';
+export type { JsonOutputSchema } from './output-schema.js';
+
+/** The three rungs of the ladder (RFC §1; AGENTS.md rule 7). */
+export type StepType = 'deterministic' | 'llm' | 'agent';
+
+/**
+ * Verification is control flow, not decoration (kernel DESIGN.md §3).
+ * v0 gates are deterministic so verification is kernel-side and replayable.
+ */
+export type VerificationGateType = 'exit_code' | 'output_contains' | 'json_schema';
+
+/**
+ * `exit_code == 0` — the implicit gate for deterministic steps. v0 judges
+ * exactly zero (kernel DESIGN.md §4); it is not configurable, so this gate
+ * carries no parameters. Writing it explicitly is allowed and compiles to the
+ * same kernel spec as omitting it.
+ */
+export interface ExitCodeGate {
+  type: 'exit_code';
+}
+
+/** Step output (stdout_tail / llm value, stringified) contains `value`. */
+export interface OutputContainsGate {
+  type: 'output_contains';
+  value: string;
+}
+
+/** Step output validates against a JSON Schema. Used for `llm` structured output. */
+export interface JsonSchemaGate {
+  type: 'json_schema';
+  schema: boolean | Record<string, unknown>;
+}
+
+export type VerificationSpec = ExitCodeGate | OutputContainsGate | JsonSchemaGate;
+export type OutputVerificationSpec = OutputContainsGate | JsonSchemaGate;
+
+/**
+ * Agent-step recovery modes (RFC Appendix A rule 4). Default is `reset`.
+ * `deterministic` / `llm` steps have no workspace, so these do not apply.
+ */
+export type RecoveryMode = 'reset' | 'inspect' | 'manual';
+
+/**
+ * Declared mutable surfaces for an agent step (RFC Appendix A rule 1).
+ * Anything undeclared is outside the contract and outside the step's
+ * permissions (gate 8 makes this enforceable, not advisory).
+ */
+export interface WorkspaceSurface {
+  /** Relayfile mount path, or a named worktree. */
+  surface: string;
+}
+
+export interface StreamSurface {
+  /** Durable channel the agent may write (kernel DESIGN.md §1.8). */
+  stream: string;
+}
+
+export interface AgentSurfaces {
+  workspace?: WorkspaceSurface[];
+  streams?: StreamSurface[];
+  /** Integration writeback paths — mount writes per gate 6. */
+  external?: string[];
+}
+
+/** Permission model for an agent step (gate 8). `readonly` provably cannot write. */
+export interface PermissionsSpec {
+  fileGlobs?: string[];
+  networkAllowlist?: string[];
+  accessPreset?: 'readonly' | 'readwrite';
+}
+
+/**
+ * Budget envelope. Per decision #10 every token has exactly one owner: an
+ * injected context pack spends the consuming step's budget. Money is a decimal
+ * string at the boundary (kernel DESIGN.md §1: no floats for money); tokens
+ * are integers.
+ */
+export interface BudgetSpec {
+  maxTokensIn?: number;
+  maxTokensOut?: number;
+  /** Decimal string, e.g. "1.50". */
+  maxDollars?: string;
+}
+
+/** Fields shared by every step on the ladder. */
+export interface BaseStepSpec {
+  /** Stable step identity; journaled as `step_id` and hashed into the idempotency key. */
+  id: string;
+  type: StepType;
+  /** Step dependencies — a step runs only after these complete. */
+  dependsOn?: string[];
+  /** Semantic retry bound (kernel DESIGN.md §1.2 `max_iterations`). Default 1. */
+  maxIterations?: number;
+}
+
+/**
+ * Rung 1 — a pure script. Executed by the `relayflowd` binary: spawn command,
+ * capture stdout/exit code. Output = `{exit_code, stdout_tail}`. Gate-1
+ * deterministic steps are pure (no pins).
+ */
+export interface DeterministicStepSpec extends BaseStepSpec {
+  type: 'deterministic';
+  command: string;
+  /** Wall-clock command timeout; worker-backed verbs own their dispatch timeout. */
+  timeoutMs?: number;
+  /** Omit to get the implicit `exit_code` gate. */
+  verification?: VerificationSpec;
+}
+
+/**
+ * Rung 2 — a bare model call. No workspace, output is a value. The kernel
+ * never calls a model: it dispatches to an attached SDK worker (§5) which
+ * returns `{output, usage}`; the kernel then runs the verification gate.
+ */
+export interface LlmStepSpec extends BaseStepSpec {
+  type: 'llm';
+  prompt: string;
+  verification?: OutputVerificationSpec;
+  model?: string;
+  /** Inert preflight declaration; overrides the flow/project CLI default. */
+  cli?: string;
+  /**
+   * Structured-output authoring sugar. Compiles to the existing `json_schema`
+   * verification primitive and is removed before the kernel boundary.
+   */
+  output?: JsonOutputSchema;
+}
+
+/**
+ * Rung 3 — a harnessed agent in a workspace. Dispatched like `llm`, plus
+ * Appendix A in full: pins declared workspace revisions and stream offsets;
+ * every writeback is a journaled `effect.recorded` deduped by
+ * `(step_id, idempotency_key, surface_path)`.
+ */
+export interface AgentStepSpec extends BaseStepSpec {
+  type: 'agent';
+  instruction: string;
+  verification?: OutputVerificationSpec;
+  /** Named authoring declaration selected from `FlowSpec.agents`. Compiled away. */
+  agent?: string;
+  /** Inert preflight declaration; overrides the flow/project CLI default. */
+  cli?: string;
+  /**
+   * Model the declared CLI must use. Raw Claude/Codex adapters receive their
+   * real model flag; an identified Relayflows wrapper receives it in its
+   * same-process execution request. Declared here so the choice is journaled with the step
+   * instead of being ambient host state.
+   */
+  model?: string;
+  surfaces?: AgentSurfaces;
+  recoveryMode?: RecoveryMode;
+  permissions?: PermissionsSpec;
+  /**
+   * Structured-output authoring sugar. A successful CLI JSON object is the parsed
+   * value; the kernel persists it only after `json_schema` verification.
+   */
+  output?: JsonOutputSchema;
+}
+
+export type StepSpec = DeterministicStepSpec | LlmStepSpec | AgentStepSpec;
+
+/**
+ * Reusable authoring declaration for an agent CLI/model pair. Both fields are
+ * required so selecting a named agent can never inherit a host model. The
+ * compiler lowers these values into the selected kernel agent step at the
+ * journal boundary; the kernel never receives this map or a new step field.
+ */
+export interface NamedAgentSpec {
+  cli: string;
+  model: string;
+}
+
+/**
+ * A trigger is an entry condition, not a scheduler (RFC-0001 gate 2). It names
+ * the event type that wakes the flow, the payload subset that must match, the
+ * template that derives the dedupe key, and the silence budget after which the
+ * kernel's liveness sweep declares the subscription dead.
+ *
+ * The event-subscription fields were shipped in `testdata/` long before this
+ * interface described them: `hn-monitor.flow.yaml`, `dir-watcher.flow.yaml`
+ * and `event-triggered-flow.yaml` all carry `eventType`, `pattern` and
+ * `dedupeKeyTemplate`, and `validate.ts` has always accepted them. The type
+ * still said "inert gate-1 declaration" with only `id` and `executor`, so the
+ * authoring dialect disagreed with both the shipped specs and the kernel.
+ */
+export interface TriggerSpec {
+  id: string;
+  /** Executor registration required before this trigger may start a run. */
+  executor: string;
+  /** Event type this trigger subscribes to. Lowers to `event_type`. */
+  eventType?: string;
+  /** Recursive-subset match against the event payload. Lowers to `pattern`. */
+  pattern?: Record<string, unknown>;
+  /** Derives the dedupe key. Lowers to `dedupe_key_template`. */
+  dedupeKeyTemplate?: string;
+  /**
+   * Silence budget in milliseconds. When no matching event arrives inside it,
+   * the kernel's liveness sweep journals `subscription.stale` and emits a
+   * `relayflowd: subscription.stale ...` line
+   * (`kernel/relayflowd/src/server/liveness.rs`). Omitted means the engine
+   * default (`DEFAULT_STALE_AFTER_MS`, 5 minutes) applies — which is a
+   * decision the author did not make, not the absence of a budget.
+   *
+   * A flow that is never triggered is silently zero (RFC-0001 §"Trigger
+   * liveness"), so declaring this is how a schedule stops being able to die
+   * quietly. Lowers to `stale_after_ms`.
+   */
+  staleAfterMs?: number;
+}
+
+/**
+ * A Relayflow spec in the authoring shape — the composable unit (RFC settled
+ * decision #5). Schema-validated, diffable, signable (gate 8), and emittable
+ * by a step (gate 9 self-authoring). What the kernel inlines in `run.spawned`
+ * is this spec mapped to the kernel dialect (`toKernelSpec`).
+ */
+export interface FlowSpec {
+  /** Spec schema semver (RFC §7). Compilers always emit latest. */
+  version: string;
+  name?: string;
+  description?: string;
+  /** Inert preflight default for llm/agent steps that do not declare a CLI. */
+  cli?: string;
+  /** Named authoring declarations. Compiled into agent steps, never journaled as a new primitive. */
+  agents?: Record<string, NamedAgentSpec>;
+  /** Declarations checked by preflight; gate 1 never dispatches them. */
+  triggers?: TriggerSpec[];
+  steps: StepSpec[];
+  budget?: BudgetSpec;
+}
+
+/** Current spec schema version emitted by this SDK. */
+export const SPEC_SCHEMA_VERSION = '0.1.0';
+
+// --- The kernel dialect ------------------------------------------------------
+//
+// The authoring types above are TypeScript-idiomatic (camelCase, tagged
+// verification sugar). The *boundary artifact* is singular: the kernel's spec
+// dialect — snake_case keys, semver `version`, flat v0 verification, defaults
+// materialized. `toKernelSpec` (compile.ts) maps authoring → kernel; parity
+// with `kernel/relayflowd-core/src/spec.rs` is pinned bit-for-bit by
+// `tests/spec-parity.test.ts` and the kernel's `tests/spec_parity.rs` over the
+// shared `testdata/` fixture.
+
+export interface KernelRetryPolicy {
+  initial_backoff_ms: number;
+  max_backoff_ms: number;
+  multiplier: number;
+  jitter_percent: number;
+}
+
+/**
+ * Flat v0 gates (kernel DESIGN.md §4): `exit_code == 0` is implicit for
+ * deterministic steps; these two are optional and combinable. An empty object
+ * means "implicit gates only".
+ */
+export interface KernelVerificationSpec {
+  output_contains?: string;
+  json_schema?: boolean | Record<string, unknown>;
+}
+
+export interface KernelStepCommon {
+  id: string;
+  depends_on: string[];
+  max_iterations: number;
+  retry: KernelRetryPolicy;
+  verification: KernelVerificationSpec;
+}
+
+export interface KernelDeterministicStep extends KernelStepCommon {
+  type: 'deterministic';
+  command: string;
+  timeout_ms?: number;
+}
+
+export interface KernelLlmStep extends KernelStepCommon {
+  type: 'llm';
+  prompt: string;
+  model?: string;
+  cli?: string;
+}
+
+export interface KernelAgentSurfaces {
+  workspace?: { surface: string }[];
+  streams?: { stream: string }[];
+  external?: string[];
+}
+
+export interface KernelPermissionsSpec {
+  file_globs?: string[];
+  network_allowlist?: string[];
+  access_preset?: 'readonly' | 'readwrite';
+}
+
+export interface KernelAgentStep extends KernelStepCommon {
+  type: 'agent';
+  instruction: string;
+  cli?: string;
+  model?: string;
+  recovery_mode: RecoveryMode;
+  surfaces?: KernelAgentSurfaces;
+  permissions?: KernelPermissionsSpec;
+}
+
+export type KernelStepSpec = KernelDeterministicStep | KernelLlmStep | KernelAgentStep;
+
+export interface KernelBudgetSpec {
+  max_tokens_in?: number;
+  max_tokens_out?: number;
+  max_dollars?: string;
+}
+
+export interface KernelTriggerSpec {
+  id: string;
+  executor: string;
+  event_type?: string;
+  pattern?: Record<string, unknown>;
+  dedupe_key_template?: string;
+  stale_after_ms?: number;
+}
+
+/** The compiled spec as the kernel parses, journals, and hashes it. */
+export interface KernelRunSpec {
+  version: string;
+  name?: string;
+  description?: string;
+  cli?: string;
+  triggers?: KernelTriggerSpec[];
+  steps: KernelStepSpec[];
+  budget?: KernelBudgetSpec;
+}