@data-club/ai-hub-server 0.0.1

package/src/letta/eventTranslator.ts

@@ -0,0 +1,667 @@
+/**
+ * Pure function: Letta Code SDK message → ai-hub SSE events (§9).
+ *
+ * Input type: `SDKMessage` (Letta Code SDK's stdin/stdout JSON wire
+ * shape). Output type: ai-hub's stable SSE events from §9.
+ *
+ * The translator has **no I/O** — it takes one `SDKMessage` and the
+ * current translation state (running text length, open tool-call ids)
+ * and returns zero or more ai-hub event payloads + the next state.
+ * Persistence, `seq` assignment, and SSE writing are the caller's
+ * responsibility (see `state/turnRunner.ts`).
+ *
+ * ## SDK message variants we handle
+ *
+ * - `assistant` — streaming chunk of assistant text. Same `uuid` across
+ *   chunks of one logical assistant message; different `uuid` signals a
+ *   new logical step (multi-step turn). Emits `assistant_delta`.
+ * - `reasoning` — same as `assistant` but for the reasoning channel.
+ *   Emits `reasoning_delta`. Phase → `model_reasoning`.
+ * - `tool_call` — incremental tool-call event. Same `toolCallId` across
+ *   chunks; `rawArguments` carries one chunk of the partial JSON
+ *   arguments. First sighting emits `tool_call_started`; subsequent
+ *   sightings (or first sighting with a non-empty `rawArguments`) emit
+ *   `tool_call_input_delta`. Phase → `model_tool_input`.
+ * - `tool_result` — one event per call. Emits `tool_call_dispatched`
+ *   (if not already emitted for this id, with the assembled JSON input)
+ *   then `tool_call_result` (success or error variant).
+ * - `result` — terminal. `success: true` → `assistant_message_complete`
+ *   followed by `stream_end {done}`. `success: false` with
+ *   `errorCode: "interrupted"` → `stream_end {cancelled}`. Any other
+ *   failure → `error` + `stream_end {error}`.
+ * - `error` — non-terminal error inside the stream (rare; Letta Code
+ *   surfaces most errors through the terminal `result` event). Emits
+ *   `error` and does NOT change phase — the runner decides whether the
+ *   turn fails based on subsequent events.
+ * - `retry` — Letta Code's internal retry notice (its own TPM
+ *   recovery). We drop it; users don't need to see it in v1.x.
+ * - `init` — never appears on `stream()`; it's the return of
+ *   `session.initialize()`. We don't process it here.
+ * - `stream_event` — only emitted when `--include-partial-messages` is
+ *   set on the CLI. We don't enable that flag.
+ *
+ * @see SPECIFICATIONS.md §9 — wire protocol
+ * @see SPECIFICATIONS.md §10 — state machine
+ */
+
+import type {
+  AIHubEvent,
+  AIHubEventState,
+  AIHubMessage,
+  RunningPhase,
+  TurnStatus,
+} from "@data-club/ai-hub";
+import type { SDKMessage } from "@letta-ai/letta-code-sdk";
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Translator state                                                          */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Carried across events for a single turn. The translator is otherwise
+ * pure — no module-level mutable state.
+ *
+ * The shape is preserved verbatim from the pre-migration translator so
+ * `state/turnRunner.ts` keeps its existing call sites unchanged. The
+ * `assistantText` / `reasoningText` accumulators are still the canonical
+ * assembled payloads (the SDK delivers deltas in `content`); the
+ * step-boundary detection now uses `uuid` change instead of Letta's
+ * `id` field on `assistant_message`.
+ */
+export interface TranslatorState {
+  /** Current `(status, phase)` pair. Pre-emission state. */
+  status: TurnStatus;
+  /** Current sub-phase or `null`. */
+  phase: RunningPhase | null;
+  /** Running concatenation of assistant deltas across the current step. */
+  assistantText: string;
+  /** Same idea for reasoning content (only populated when effort != none). */
+  reasoningText: string;
+  /**
+   * Tool-call ids we've already announced via `tool_call_started`. The
+   * translator only emits `started` on first sight; subsequent arrivals
+   * with the same id emit deltas.
+   */
+  openToolCalls: Set<string>;
+  /**
+   * Per-id accumulator for the tool-call's `rawArguments` chunks. Used
+   * to assemble the full JSON input we send on `tool_call_dispatched`.
+   */
+  toolCallArguments: Map<string, string>;
+  /**
+   * Tool-call ids we've already emitted `tool_call_dispatched` for. The
+   * runner doesn't depend on per-call timing, just "dispatched yet or
+   * not"; we transition phase → `tool_executing` on first sighting of
+   * a `tool_result` for an undispatched call.
+   */
+  dispatchedToolCalls: Set<string>;
+  /**
+   * Stable `uuid` of the assistant message currently being assembled,
+   * if any. Used by the step-boundary detector to spot when a new
+   * logical step starts (new uuid means new step).
+   */
+  assistantMessageUuid: string | null;
+}
+
+/** Builds the per-turn initial state. */
+export function initialTranslatorState(): TranslatorState {
+  return {
+    status: "running",
+    phase: "model_text",
+    assistantText: "",
+    reasoningText: "",
+    openToolCalls: new Set(),
+    toolCallArguments: new Map(),
+    dispatchedToolCalls: new Set(),
+    assistantMessageUuid: null,
+  };
+}
+
+/** Output of a single translation step. */
+export interface TranslateStep {
+  /** Zero-or-more ai-hub event payloads (without `seq` — the runner assigns). */
+  events: ReadonlyArray<UnsequencedEvent>;
+  /** Next translator state. */
+  state: TranslatorState;
+}
+
+/**
+ * An ai-hub event without the `seq` field. The runner assigns seq when
+ * it persists + writes the event. The `error` event additionally
+ * carries a required `request_id` that only the runner knows — we
+ * strip it from the translator surface so the per-variant translators
+ * stay pure (no need to thread the requestId through every call).
+ * `emit()` in the runner stamps it on every error event before it goes
+ * out on the wire.
+ *
+ * Uses a distributive conditional so each variant of `AIHubEvent` is
+ * mapped independently — without this, the default non-distributive
+ * `Omit` would collapse the union to just the keys common to every
+ * variant (which loses `data` on every variant except `heartbeat`).
+ */
+export type UnsequencedEvent = AIHubEvent extends infer T
+  ? T extends AIHubEvent
+    ? T extends { event: "error"; data: infer D }
+      ? Omit<T, "seq" | "data"> & { data: Omit<D, "request_id"> }
+      : Omit<T, "seq">
+    : never
+  : never;
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Entry point                                                               */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Translates one SDK message into zero-or-more ai-hub events.
+ *
+ * Pure: no I/O, no module state, no clocks (the caller stamps
+ * timestamps).
+ *
+ * @param msg - the Letta Code SDK message.
+ * @param state - the translator state.
+ * @returns the events to emit + the next state.
+ */
+export function translateSdkMessage(
+  msg: SDKMessage,
+  state: TranslatorState,
+): TranslateStep {
+  // Mid-stream step-boundary detection. A turn that runs in multiple
+  // steps (reasoning + tool + assistant text, then reasoning + tool +
+  // assistant text again …) produces multiple logical assistant
+  // messages within one streaming response. The boundary fires when
+  // we've already accumulated assistant text and the next event is
+  // either:
+  //
+  // - a `reasoning` chunk (new step's reasoning starting), or
+  // - a `tool_call` chunk (new step's first tool call), or
+  // - an `assistant` chunk with a different `uuid` than the one
+  //   currently being assembled.
+  if (isStepBoundary(msg, state)) {
+    const boundaryEvents = finalizeAssistantMessageMidStream(state);
+    const fresh = resetForNewStep(state);
+    const inner = translateInner(msg, fresh);
+    return {
+      events: [...boundaryEvents, ...inner.events],
+      state: inner.state,
+    };
+  }
+  return translateInner(msg, state);
+}
+
+/**
+ * Returns true when `msg` signals that the current logical assistant
+ * step is done and a new one is starting. Triggers only when the
+ * translator already has accumulated assistant text — otherwise there's
+ * nothing to finalize and the message just enters the current step.
+ */
+function isStepBoundary(msg: SDKMessage, state: TranslatorState): boolean {
+  if (state.assistantText.length === 0) return false;
+  switch (msg.type) {
+    case "reasoning":
+    case "tool_call":
+      return true;
+    case "assistant":
+      return (
+        state.assistantMessageUuid !== null &&
+        msg.uuid !== state.assistantMessageUuid
+      );
+    default:
+      return false;
+  }
+}
+
+/**
+ * Resets the per-step accumulators for a new logical step. Carries
+ * `status`/`phase` through — the next event will set them via its
+ * variant translator.
+ */
+function resetForNewStep(state: TranslatorState): TranslatorState {
+  return {
+    ...state,
+    assistantText: "",
+    reasoningText: "",
+    openToolCalls: new Set(),
+    toolCallArguments: new Map(),
+    dispatchedToolCalls: new Set(),
+    assistantMessageUuid: null,
+  };
+}
+
+/**
+ * Mid-stream sibling of `finalizeAssistantMessage`. Emits the same
+ * `assistant_message_complete` for the accumulated step but snapshots
+ * the state as `{ status: "running", phase: <current> }` — the turn
+ * isn't done yet, only this logical step is. Returns empty when no
+ * assistant text was accumulated.
+ */
+function finalizeAssistantMessageMidStream(
+  state: TranslatorState,
+): ReadonlyArray<UnsequencedEvent> {
+  if (state.assistantText.length === 0) return [];
+  const message: AIHubMessage = {
+    id: state.assistantMessageUuid ?? "",
+    role: "assistant",
+    content: state.assistantText,
+    created_at: new Date().toISOString(),
+  };
+  return [
+    {
+      event: "assistant_message_complete",
+      data: { message },
+      state: snapshot(state),
+    },
+  ];
+}
+
+/** The original per-variant switch — extracted so the entry-point can
+ *  wrap it with the step-boundary check above. */
+function translateInner(msg: SDKMessage, state: TranslatorState): TranslateStep {
+  switch (msg.type) {
+    case "assistant":
+      return translateAssistant(msg, state);
+    case "reasoning":
+      return translateReasoning(msg, state);
+    case "tool_call":
+      return translateToolCall(msg, state);
+    case "tool_result":
+      return translateToolResult(msg, state);
+    case "error":
+      return translateError(msg, state);
+    case "result":
+    case "init":
+    case "retry":
+    case "stream_event":
+    default:
+      // `result` is terminal — the runner detects it and calls
+      // `finalizeAssistantMessage` + `finalizeTerminal` itself. The
+      // others are either no-ops (`init` never appears in stream();
+      // `retry` is internal; `stream_event` requires a flag we don't
+      // set) or unknown future variants we pass through.
+      return { events: [], state };
+  }
+}
+
+/* ── per-variant translators ──────────────────────────────────────────────── */
+
+/**
+ * `assistant` → `assistant_delta`. Each chunk carries the **delta** text
+ * in `content` (not cumulative); we forward the delta verbatim and
+ * accumulate the full text in `assistantText` for the eventual
+ * `assistant_message_complete`.
+ */
+function translateAssistant(
+  msg: Extract<SDKMessage, { type: "assistant" }>,
+  state: TranslatorState,
+): TranslateStep {
+  if (!msg.content || msg.content.length === 0) {
+    return { events: [], state };
+  }
+  const next: TranslatorState = {
+    ...state,
+    status: "running",
+    phase: "model_text",
+    assistantText: state.assistantText + msg.content,
+    assistantMessageUuid: state.assistantMessageUuid ?? msg.uuid,
+  };
+  return {
+    events: [
+      {
+        event: "assistant_delta",
+        data: { delta: msg.content },
+        state: snapshot(next),
+      },
+    ],
+    state: next,
+  };
+}
+
+/**
+ * `reasoning` → `reasoning_delta`. Phase transitions to
+ * `model_reasoning` while the block is in flight; the next non-
+ * reasoning message drives it back to `model_text`.
+ */
+function translateReasoning(
+  msg: Extract<SDKMessage, { type: "reasoning" }>,
+  state: TranslatorState,
+): TranslateStep {
+  if (!msg.content || msg.content.length === 0) {
+    return { events: [], state };
+  }
+  const next: TranslatorState = {
+    ...state,
+    status: "running",
+    phase: "model_reasoning",
+    reasoningText: state.reasoningText + msg.content,
+  };
+  return {
+    events: [
+      {
+        event: "reasoning_delta",
+        data: { delta: msg.content },
+        state: snapshot(next),
+      },
+    ],
+    state: next,
+  };
+}
+
+/**
+ * `tool_call` → `tool_call_started` on first sighting of the id, then
+ * `tool_call_input_delta` for each chunk of `rawArguments`. The
+ * SDK delivers tool-call arguments in multiple chunks (e.g. 3 events
+ * for `{"path": "/etc/hostname"}`) sharing the same `toolCallId`.
+ *
+ * We accumulate `rawArguments` per id so `translateToolResult` can
+ * include the assembled parsed input in `tool_call_dispatched`.
+ */
+function translateToolCall(
+  msg: Extract<SDKMessage, { type: "tool_call" }>,
+  state: TranslatorState,
+): TranslateStep {
+  const id = msg.toolCallId;
+  if (!id) return { events: [], state };
+
+  const events: UnsequencedEvent[] = [];
+  let next: TranslatorState = {
+    ...state,
+    status: "running",
+    phase: "model_tool_input",
+  };
+
+  if (!next.openToolCalls.has(id)) {
+    events.push({
+      event: "tool_call_started",
+      data: { tool_call_id: id, tool_name: msg.toolName },
+      state: snapshot(next),
+    });
+    const opened = new Set(next.openToolCalls);
+    opened.add(id);
+    next = { ...next, openToolCalls: opened };
+  }
+
+  // Per-chunk rawArguments accumulation. The 1st event sometimes
+  // arrives with toolInput={raw:""} and no rawArguments; subsequent
+  // events carry chunks of the JSON args string.
+  const chunk = msg.rawArguments ?? "";
+  if (chunk.length > 0) {
+    const accumulated = (next.toolCallArguments.get(id) ?? "") + chunk;
+    const nextArgs = new Map(next.toolCallArguments);
+    nextArgs.set(id, accumulated);
+    next = { ...next, toolCallArguments: nextArgs };
+
+    events.push({
+      event: "tool_call_input_delta",
+      data: { tool_call_id: id, partial_json: chunk },
+      state: snapshot(next),
+    });
+  }
+
+  return { events, state: next };
+}
+
+/**
+ * `tool_result` → `tool_call_dispatched` (if not already) +
+ * `tool_call_result`.
+ *
+ * Phase transitions: `model_tool_input` → `tool_executing` (on
+ * dispatched) → `model_text` (after the result lands). Per §10.3 a
+ * tool error does NOT fail the turn — phase reverts to `model_text`
+ * either way.
+ */
+function translateToolResult(
+  msg: Extract<SDKMessage, { type: "tool_result" }>,
+  state: TranslatorState,
+): TranslateStep {
+  const id = msg.toolCallId;
+  if (!id) return { events: [], state };
+
+  const events: UnsequencedEvent[] = [];
+  let next: TranslatorState = { ...state };
+
+  if (!next.dispatchedToolCalls.has(id)) {
+    const assembled = next.toolCallArguments.get(id);
+    events.push({
+      event: "tool_call_dispatched",
+      data: {
+        tool_call_id: id,
+        input: tryParseJson(assembled),
+      },
+      state: snapshot({ ...next, phase: "tool_executing" }),
+    });
+    const dispatched = new Set(next.dispatchedToolCalls);
+    dispatched.add(id);
+    next = {
+      ...next,
+      phase: "tool_executing",
+      dispatchedToolCalls: dispatched,
+    };
+  }
+
+  if (msg.isError) {
+    events.push({
+      event: "tool_call_result",
+      data: {
+        tool_call_id: id,
+        error: { code: "tool_error", message: msg.content ?? "" },
+      },
+      state: snapshot({ ...next, phase: "model_text" }),
+    });
+  } else {
+    events.push({
+      event: "tool_call_result",
+      data: { tool_call_id: id, output: msg.content ?? "" },
+      state: snapshot({ ...next, phase: "model_text" }),
+    });
+  }
+
+  next = { ...next, phase: "model_text" };
+  return { events, state: next };
+}
+
+/**
+ * `error` SDK message → `error` SSE event.
+ *
+ * Letta Code surfaces most errors through the terminal `result` event
+ * (see `finalizeTerminal`), but a few error conditions also produce a
+ * mid-stream `error` event with `stopReason` and an optional
+ * `apiError`. We pass them through as ai-hub `error` events; the
+ * runner decides whether the turn should fail (it typically does, but
+ * the terminal `result` event is the authoritative signal).
+ */
+function translateError(
+  msg: Extract<SDKMessage, { type: "error" }>,
+  state: TranslatorState,
+): TranslateStep {
+  const code = classifyErrorCode(msg.errorCode, msg.stopReason);
+  return {
+    events: [
+      {
+        event: "error",
+        data: {
+          code,
+          message: msg.message ?? "Letta Code reported an error.",
+        },
+        state: snapshot(state),
+      },
+    ],
+    state,
+  };
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Finalizers                                                                */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Emits the closing `assistant_message_complete` event for a turn that
+ * accumulated assistant text. Called by the runner exactly once when
+ * the terminal `result` SDK message arrives — but only when the turn
+ * succeeded. For a cancelled / failed turn we still emit it (the user
+ * deserves to see whatever partial text was generated), but the
+ * snapshot reflects the terminal status.
+ *
+ * @param state - the translator state at end-of-stream.
+ * @param terminalStatus - the status to snapshot into the envelope.
+ * @returns the closing events (empty if no assistant text was produced).
+ */
+export function finalizeAssistantMessage(
+  state: TranslatorState,
+  terminalStatus: TurnStatus = "done",
+): ReadonlyArray<UnsequencedEvent> {
+  if (state.assistantText.length === 0) return [];
+  const message: AIHubMessage = {
+    id: state.assistantMessageUuid ?? "",
+    role: "assistant",
+    content: state.assistantText,
+    created_at: new Date().toISOString(),
+  };
+  return [
+    {
+      event: "assistant_message_complete",
+      data: { message },
+      state: snapshot({ ...state, status: terminalStatus, phase: null }),
+    },
+  ];
+}
+
+/**
+ * Interprets the terminal SDK `result` message into the right closing
+ * sequence: `assistant_message_complete` (if any) + the final
+ * `stream_end` with the appropriate reason. Pure function — no I/O.
+ *
+ * Behavior matrix:
+ *
+ * | result.success | result.errorCode | Emitted closing events |
+ * |---|---|---|
+ * | true  | — | assistant_message_complete + stream_end{done} |
+ * | false | "interrupted" | assistant_message_complete (with partial text, if any) + stream_end{cancelled} |
+ * | false | anything else | (assistant_message_complete if partial text) + error + stream_end{error} |
+ *
+ * @param msg - the terminal SDK result message.
+ * @param state - the translator state right before the result arrived.
+ * @returns the events to emit + the (terminal) state.
+ */
+export function finalizeTerminal(
+  msg: Extract<SDKMessage, { type: "result" }>,
+  state: TranslatorState,
+): TranslateStep {
+  if (msg.success) {
+    const completion = finalizeAssistantMessage(state, "done");
+    const finalState: TranslatorState = { ...state, status: "done", phase: null };
+    return {
+      events: [
+        ...completion,
+        {
+          event: "stream_end",
+          data: { reason: "done" },
+          state: snapshot(finalState),
+        },
+      ],
+      state: finalState,
+    };
+  }
+
+  if (msg.errorCode === "interrupted") {
+    const completion = finalizeAssistantMessage(state, "cancelled");
+    const finalState: TranslatorState = { ...state, status: "cancelled", phase: null };
+    return {
+      events: [
+        ...completion,
+        {
+          event: "stream_end",
+          data: { reason: "cancelled" },
+          state: snapshot(finalState),
+        },
+      ],
+      state: finalState,
+    };
+  }
+
+  // Any other failure (llm_api_error, max_steps, protocol_error,
+  // stream_closed, …) is a hard fail. Still emit the partial assistant
+  // text if any was produced, then the error and stream_end.
+  const partial = finalizeAssistantMessage(state, "failed");
+  const finalState: TranslatorState = { ...state, status: "failed", phase: null };
+  const code = classifyErrorCode(msg.errorCode, msg.stopReason);
+  return {
+    events: [
+      ...partial,
+      {
+        event: "error",
+        data: {
+          code,
+          message: msg.errorDetail ?? msg.error ?? "Letta Code reported a terminal error.",
+        },
+        state: snapshot(finalState),
+      },
+      {
+        event: "stream_end",
+        data: { reason: "error" },
+        state: snapshot(finalState),
+      },
+    ],
+    state: finalState,
+  };
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Internal helpers                                                          */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Snapshots `(status, phase)` for the SSE event envelope. */
+function snapshot(state: TranslatorState): AIHubEventState {
+  return { status: state.status, phase: state.phase };
+}
+
+/**
+ * Best-effort JSON parse. Returns `undefined` on failure so the
+ * `tool_call_dispatched.data.input` is null-shaped rather than
+ * throwing. If `raw` is `undefined` we also return `undefined` —
+ * happens when the tool was called with no args at all.
+ */
+function tryParseJson(raw: string | undefined): unknown {
+  if (raw === undefined || raw === "") return undefined;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * Maps the SDK's `errorCode` + `stopReason` strings onto ai-hub's
+ * stable `error.code` enum.
+ *
+ * SDK error codes we know about:
+ * - `approval_conflict` — non-fatal approval flow snag; treat as `internal`
+ *   (ai-hub doesn't surface approvals to end-users in v1).
+ * - `protocol_error` — SDK ↔ CLI wire-shape mismatch; `internal`.
+ * - `llm_api_error` — the underlying LLM call failed; `provider_error`.
+ * - `max_steps` — agent hit its step ceiling; `internal` for now (a
+ *   `max_steps` ai-hub code is a future v1.x enhancement).
+ * - `interrupted` — handled separately in `finalizeTerminal`.
+ * - `stream_closed` — SDK pump closed early; `internal`.
+ * - `error` (generic) — fall back to `stopReason` sniffing.
+ *
+ * The set of legitimate ai-hub `error.code` values lives in
+ * `@data-club/ai-hub` (§9.4). We keep `tpm_exhausted` reserved for
+ * future use (it is no longer emitted post-migration — the recovery
+ * loop is gone — but we keep the enum value so a future restore can
+ * use it without protocol-version churn).
+ */
+function classifyErrorCode(
+  errorCode: string | undefined,
+  stopReason: string | undefined,
+): "tpm_exhausted" | "provider_error" | "internal" {
+  if (errorCode === "llm_api_error") return "provider_error";
+  if (errorCode === "approval_conflict" || errorCode === "approval_conflict_terminal") return "internal";
+  if (errorCode === "protocol_error" || errorCode === "stream_closed") return "internal";
+  if (errorCode === "max_steps") return "internal";
+  if (errorCode && errorCode !== "error" && errorCode !== "interrupted") return "internal";
+  // Fall back on stopReason heuristics. Future Letta Code versions may
+  // expose richer error codes; we'll extend the map here.
+  const l = (stopReason ?? "").toLowerCase();
+  if (l.includes("rate") || l.includes("limit") || l.includes("429")) return "tpm_exhausted";
+  if (l.includes("provider") || l.includes("upstream") || l.includes("llm")) return "provider_error";
+  return "internal";
+}