@zocomputer/agent-sdk 0.5.0

package/src/state.ts

@@ -0,0 +1,96 @@
+// External-state declarations — the `agent/state/<name>.ts` file-per-capability
+// convention from plans/dcosson/external-state.md. A declaration names what the
+// agent's code depends on (interface, access, the author's visibility intent);
+// which engine/store actually serves it is bound by the Zo control plane, never
+// declared here. eve has no `state` discovery slot, so discovery is Zo-built end
+// to end: deploy validation extracts the declaration with a strict literal
+// parser (apps/api/src/state/declaration-parse.ts), which is why the argument to
+// `defineExternalState` must stay a statically analyzable literal — no spreads,
+// no computed values, no identifiers. The runtime (`@zo/state`, later) imports
+// the module and reads the same object.
+
+/** What the agent's code programs against. A small, closed, slowly growing set. */
+export type StateInterface = "files" | "sql" | "kv" | "http" | "exec";
+
+/** Read-only or read-write, as the code needs. */
+export type StateAccess = "r" | "rw";
+
+/**
+ * The visibility model the author designed for. Drives the zero-config default
+ * and consent copy; never a constraint — the data's owner can override it.
+ */
+export type StateIntent = "private" | "shared";
+
+/** How instances subdivide. There is deliberately no `turn` (use eve's defineState). */
+export type StatePartition = "none" | "team" | "user" | "session";
+
+/**
+ * The author's preferred engine/partition/lifecycle, consumed at rung two of
+ * the binding resolution ladder. Hints, not constraints.
+ */
+export interface SuggestedStateDefaults {
+  /** Engine catalog key, e.g. "zo-blob-r2". Free-form: the catalog is control-plane code. */
+  readonly engine?: string;
+  readonly partition?: StatePartition;
+  /** Per-transition lifecycle overrides on the (engine, partition) defaults. */
+  readonly lifecycle?: Readonly<Record<string, string | number | boolean>>;
+}
+
+export interface ExternalStateDeclaration {
+  /**
+   * What tools reference at runtime. Must equal the declaring filename
+   * (`agent/state/<name>.ts`) — deploy validation enforces the match, which
+   * also makes duplicate names structurally impossible.
+   */
+  readonly name: string;
+  readonly interface: StateInterface;
+  readonly access: StateAccess;
+  readonly intent: StateIntent;
+  readonly suggestedDefaults?: SuggestedStateDefaults;
+}
+
+/** Mirrors the deploy parser's name rule: lowercase, digit/underscore/hyphen tail. */
+export const STATE_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+
+const INTERFACES: readonly StateInterface[] = ["files", "sql", "kv", "http", "exec"];
+const ACCESSES: readonly StateAccess[] = ["r", "rw"];
+const INTENTS: readonly StateIntent[] = ["private", "shared"];
+const PARTITIONS: readonly StatePartition[] = ["none", "team", "user", "session"];
+
+/**
+ * The declaration helper an agent default-exports from `agent/state/<name>.ts`.
+ * Validates eagerly so a bad declaration fails at module load in local dev, not
+ * first at deploy; deploy validation re-checks the source statically regardless
+ * (it never executes agent code).
+ */
+export function defineExternalState(
+  declaration: ExternalStateDeclaration,
+): ExternalStateDeclaration {
+  if (!STATE_NAME_PATTERN.test(declaration.name)) {
+    throw new Error(
+      `external-state declaration name "${declaration.name}" must match ${STATE_NAME_PATTERN} and equal the declaring filename`,
+    );
+  }
+  if (!INTERFACES.includes(declaration.interface)) {
+    throw new Error(
+      `external-state declaration "${declaration.name}": unknown interface "${String(declaration.interface)}" (expected ${INTERFACES.join(" | ")})`,
+    );
+  }
+  if (!ACCESSES.includes(declaration.access)) {
+    throw new Error(
+      `external-state declaration "${declaration.name}": unknown access "${String(declaration.access)}" (expected ${ACCESSES.join(" | ")})`,
+    );
+  }
+  if (!INTENTS.includes(declaration.intent)) {
+    throw new Error(
+      `external-state declaration "${declaration.name}": unknown intent "${String(declaration.intent)}" (expected ${INTENTS.join(" | ")})`,
+    );
+  }
+  const partition = declaration.suggestedDefaults?.partition;
+  if (partition !== undefined && !PARTITIONS.includes(partition)) {
+    throw new Error(
+      `external-state declaration "${declaration.name}": unknown suggested partition "${String(partition)}" (expected ${PARTITIONS.join(" | ")})`,
+    );
+  }
+  return Object.freeze(declaration);
+}

package/src/steer-inbox.ts

@@ -0,0 +1,105 @@
+// The steer inbox: a per-session NDJSON file under a caller-owned dir. Writers
+// (a cockpit API route, a TUI) append one line per steered message; the tool
+// wrapper (./steer-tool.ts) and the park-delivery hook (./hooks.ts) drain it.
+// Drain is race-safe against concurrent appends: rename the live file to a
+// temp name first, so an append that races the drain recreates the live file
+// and nothing is lost — it just waits for the next drain.
+
+import {
+  appendFileSync,
+  linkSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+} from "node:fs";
+import { join } from "node:path";
+import { parseSteerLine, serializeSteerLine, type SteerMessage } from "./steer";
+
+export interface SteerInboxOptions {
+  /** Directory holding the per-session inbox files (created on first append). */
+  dir: string;
+  /** Injectable clock for tests; defaults to `Date.now`. */
+  now?: () => number;
+  /** Injectable id source for tests; defaults to `crypto.randomUUID`. */
+  newId?: () => string;
+  /** Injectable file reader for tests (drain's failure path); defaults to `readFileSync`. */
+  readFile?: (path: string) => string;
+}
+
+export interface SteerInbox {
+  /** Queue a new steered message for a session; returns the stored message. */
+  append(sessionId: string, text: string): SteerMessage;
+  /** Re-queue an existing message (failed delivery), keeping its id and time. */
+  appendMessage(sessionId: string, message: SteerMessage): void;
+  /** Take every queued message for a session; `[]` when none are queued. */
+  drain(sessionId: string): SteerMessage[];
+}
+
+// Process-wide so two inbox instances over one dir can't collide on temp names.
+let drainSequence = 0;
+
+export function createSteerInbox(options: SteerInboxOptions): SteerInbox {
+  const now = options.now ?? Date.now;
+  const newId = options.newId ?? (() => crypto.randomUUID());
+  const readFile = options.readFile ?? ((path: string) => readFileSync(path, "utf8"));
+
+  // Session ids are opaque; encode so they can't traverse or collide as paths.
+  const fileFor = (sessionId: string) =>
+    join(options.dir, `${encodeURIComponent(sessionId)}.ndjson`);
+
+  function appendMessage(sessionId: string, message: SteerMessage): void {
+    mkdirSync(options.dir, { recursive: true });
+    appendFileSync(fileFor(sessionId), `${serializeSteerLine(message)}\n`, "utf8");
+  }
+
+  return {
+    append(sessionId, text) {
+      const message: SteerMessage = { id: newId(), text, at: now() };
+      appendMessage(sessionId, message);
+      return message;
+    },
+    appendMessage,
+    drain(sessionId) {
+      const file = fileFor(sessionId);
+      const claimed = `${file}.drain-${process.pid}-${drainSequence++}`;
+      try {
+        renameSync(file, claimed);
+      } catch {
+        // Nothing queued (ENOENT) — or another drainer claimed it first.
+        return [];
+      }
+      let raw: string;
+      try {
+        raw = readFile(claimed);
+      } catch {
+        // The claim succeeded but the read failed (transient I/O). Put the
+        // claimed lines back under the live name so they survive for the next
+        // drain — deleting them here would drop user messages on the floor.
+        // linkSync (not renameSync) because rename clobbers: a racing append
+        // may have recreated the live file, and link atomically refuses
+        // (EEXIST) instead of overwriting the racer's messages.
+        try {
+          linkSync(claimed, file);
+          rmSync(claimed, { force: true });
+        } catch {
+          // Live file exists again — splice our lines in via append (the
+          // retry read may succeed where the first didn't).
+          try {
+            appendFileSync(file, readFileSync(claimed));
+            rmSync(claimed, { force: true });
+          } catch {
+            // Leave the claimed file on disk as a last resort — an orphaned
+            // temp file beats silently dropped user messages.
+          }
+        }
+        return [];
+      }
+      rmSync(claimed, { force: true });
+      return raw
+        .split("\n")
+        .map(parseSteerLine)
+        .filter((message): message is SteerMessage => message !== null);
+    },
+  };
+}

package/src/steer-tool.ts

@@ -0,0 +1,83 @@
+// The delivery half of steering: wrap a tool so that when its execute
+// resolves, any steered messages queued for the session ride out on the
+// result — the model reads them before its next inference step (eve has no
+// pre-inference injection; see ./steer.ts). Two seams per tool:
+//
+// - `execute`: after the original resolves, drain the session's inbox and
+//   attach the messages to the raw output (UI clients read them off
+//   `action.result` events). Only successful results participate — a thrown
+//   error is eve-owned and can't carry fields.
+// - `toModelOutput`: a tool's own projection narrows the raw result, which
+//   would silently drop the attached field (read strips unknown keys, for
+//   example). The wrapper strips the steer, delegates to the original
+//   projection, then re-merges — text outputs get the rendered block
+//   appended, json outputs get the field re-attached.
+//
+// eve's defineTool brands the definition object, so the wrapper re-stamps a
+// copy instead of mutating the original.
+
+import { defineTool, type ToolDefinition, type ToolModelOutput } from "eve/tools";
+import {
+  attachSteerToOutput,
+  mergeSteerIntoModelOutput,
+  readSteerMessages,
+  stripSteerFromOutput,
+} from "./steer";
+import type { SteerInbox } from "./steer-inbox";
+
+/** The drain-side subset of the inbox the wrapper needs. */
+export type SteerSource = Pick<SteerInbox, "drain">;
+
+/**
+ * Wrap one tool with steer delivery. Structurally output-preserving for
+ * record outputs (the steer field spreads in alongside the tool's own keys);
+ * a non-record output is wrapped when steers are pending, which the
+ * `toModelOutput` seam undoes before the tool's own projection runs.
+ */
+export function withSteerDelivery<TInput, TOutput>(
+  tool: ToolDefinition<TInput, TOutput>,
+  inbox: SteerSource,
+): ToolDefinition<TInput, TOutput> {
+  const originalToModelOutput = tool.toModelOutput?.bind(tool);
+
+  const wrapped: ToolDefinition<TInput, TOutput> = {
+    ...tool,
+    async execute(input, ctx) {
+      const output = await tool.execute(input, ctx);
+      const messages = inbox.drain(ctx.session.id);
+      if (messages.length === 0) return output;
+      // The one type-level concession: an attached record output is TOutput
+      // plus the steer field; a non-record output becomes the recoverable
+      // wrapper shape. eve treats tool outputs as unknown on the wire, and
+      // the toModelOutput wrapper below recovers the original before the
+      // tool's own projection sees it.
+      return attachSteerToOutput(output, messages) as TOutput;
+    },
+    ...(originalToModelOutput
+      ? {
+          async toModelOutput(output: TOutput): Promise<ToolModelOutput> {
+            const messages = readSteerMessages(output);
+            if (!messages) return originalToModelOutput(output);
+            const original = stripSteerFromOutput(
+              // readSteerMessages returning non-null proves output is a record.
+              output as Record<string, unknown>,
+            ) as TOutput;
+            const narrowed = await originalToModelOutput(original);
+            return mergeSteerIntoModelOutput(narrowed, messages);
+          },
+        }
+      : {}),
+  };
+  return defineTool(wrapped);
+}
+
+/**
+ * A conditional wrapper for wiring call sites: identity when no inbox is
+ * configured, `withSteerDelivery` otherwise.
+ */
+export function createSteerWrapper(
+  inbox: SteerSource | null,
+): <TInput, TOutput>(tool: ToolDefinition<TInput, TOutput>) => ToolDefinition<TInput, TOutput> {
+  if (!inbox) return (tool) => tool;
+  return (tool) => withSteerDelivery(tool, inbox);
+}

package/src/steer.ts

@@ -0,0 +1,146 @@
+// The steer contract: pure types and helpers for delivering a user's
+// mid-turn messages to the model as soon as possible. eve has no
+// pre-inference injection — hooks are observe-only for model context, and
+// send() rejects while a turn is running — so a steered message rides the
+// next completing tool result instead (./steer-tool.ts attaches it under
+// STEER_FIELD), with leftovers a turn ends before delivering going out on
+// park (./hooks.ts). Dependency-free and exported at the
+// `@zocomputer/agent-sdk/steer` subpath so UI clients (which write the inbox
+// and read `user_steer` off `action.result` events) consume it without the
+// extraction deps.
+
+/** Result key carrying steered messages on a tool output. */
+export const STEER_FIELD = "user_steer";
+
+/** Key the original output hides under when it isn't a record. */
+export const STEER_WRAPPED_OUTPUT_FIELD = "steer_wrapped_output";
+
+/** Conventional inbox dirname under an agent's state dir. */
+export const STEER_DIRNAME = "steer";
+
+/** The note the model reads alongside steered messages. */
+export const STEER_NOTE =
+  "The user sent these messages while this tool was running. They take priority: address them now and adjust your current approach before continuing.";
+
+/** One steered message, as queued by a UI and delivered to the model. */
+export interface SteerMessage {
+  /** Unique id — the park-delivery dedupe key (`steer:<id>`). */
+  id: string;
+  /** The user's message, verbatim. */
+  text: string;
+  /** Queue time (epoch ms). */
+  at: number;
+}
+
+/** What rides under STEER_FIELD on a tool output. */
+export interface SteerPayload {
+  note: string;
+  messages: SteerMessage[];
+}
+
+export function buildSteerPayload(messages: readonly SteerMessage[]): SteerPayload {
+  return { note: STEER_NOTE, messages: [...messages] };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isSteerMessage(value: unknown): value is SteerMessage {
+  return (
+    isRecord(value) &&
+    typeof value.id === "string" &&
+    typeof value.text === "string" &&
+    typeof value.at === "number"
+  );
+}
+
+/**
+ * Attach steered messages to a tool output. A record output keeps its own
+ * keys with the payload spread in alongside (merging with any messages a
+ * previous attach already carried); a non-record output is wrapped so
+ * `stripSteerFromOutput` can recover it exactly.
+ */
+export function attachSteerToOutput(
+  output: unknown,
+  messages: readonly SteerMessage[],
+): Record<string, unknown> {
+  if (isRecord(output)) {
+    const existing = readSteerMessages(output) ?? [];
+    return { ...output, [STEER_FIELD]: buildSteerPayload([...existing, ...messages]) };
+  }
+  return {
+    [STEER_WRAPPED_OUTPUT_FIELD]: output,
+    [STEER_FIELD]: buildSteerPayload(messages),
+  };
+}
+
+/**
+ * Inverse of `attachSteerToOutput`: drop the steer field and unwrap a
+ * non-record original. Only unwraps when the wrapper key is the sole
+ * remaining key, so a record that legitimately contains it survives.
+ */
+export function stripSteerFromOutput(record: Record<string, unknown>): unknown {
+  const { [STEER_FIELD]: _steer, ...rest } = record;
+  const keys = Object.keys(rest);
+  if (keys.length === 1 && keys[0] === STEER_WRAPPED_OUTPUT_FIELD) {
+    return rest[STEER_WRAPPED_OUTPUT_FIELD];
+  }
+  return rest;
+}
+
+/**
+ * Read the steered messages off a tool output, structurally validated.
+ * Returns null when the output isn't a record, carries no steer payload, or
+ * the payload holds no well-formed message; malformed entries are dropped.
+ */
+export function readSteerMessages(output: unknown): SteerMessage[] | null {
+  if (!isRecord(output)) return null;
+  const payload = output[STEER_FIELD];
+  if (!isRecord(payload) || !Array.isArray(payload.messages)) return null;
+  const messages = payload.messages.filter(isSteerMessage);
+  return messages.length > 0 ? messages : null;
+}
+
+/** Render steered messages as a text block (for text-mode model outputs). */
+export function formatSteerText(messages: readonly SteerMessage[]): string {
+  const lines = messages.map((message) => `- ${message.text}`);
+  return `[${STEER_FIELD}] ${STEER_NOTE}\n${lines.join("\n")}`;
+}
+
+/** The shape eve's `toModelOutput` produces — mirrored here to stay dependency-free. */
+export type SteerModelOutput =
+  | { type: "text"; value: string }
+  | { type: "json"; value: unknown };
+
+/**
+ * Merge steered messages into a tool's already-narrowed model output: text
+ * outputs get the rendered block appended, json outputs get the field
+ * re-attached.
+ */
+export function mergeSteerIntoModelOutput(
+  output: SteerModelOutput,
+  messages: readonly SteerMessage[],
+): SteerModelOutput {
+  if (output.type === "text") {
+    return { type: "text", value: `${output.value}\n\n${formatSteerText(messages)}` };
+  }
+  return { type: "json", value: attachSteerToOutput(output.value, messages) };
+}
+
+/** Serialize one message as an NDJSON line (no trailing newline). */
+export function serializeSteerLine(message: SteerMessage): string {
+  return JSON.stringify(message);
+}
+
+/** Parse one NDJSON line; null on blank or malformed input. */
+export function parseSteerLine(line: string): SteerMessage | null {
+  const trimmed = line.trim();
+  if (trimmed === "") return null;
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    return isSteerMessage(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}