@data-club/ai-hub-server 0.0.1

package/dist/letta/eventTranslator.d.ts

@@ -0,0 +1,166 @@
+/**
+ * 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, RunningPhase, TurnStatus } from "@data-club/ai-hub";
+import type { SDKMessage } from "@letta-ai/letta-code-sdk";
+/**
+ * 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 declare function initialTranslatorState(): TranslatorState;
+/** 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;
+/**
+ * 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 declare function translateSdkMessage(msg: SDKMessage, state: TranslatorState): TranslateStep;
+/**
+ * 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 declare function finalizeAssistantMessage(state: TranslatorState, terminalStatus?: TurnStatus): ReadonlyArray<UnsequencedEvent>;
+/**
+ * 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 declare function finalizeTerminal(msg: Extract<SDKMessage, {
+    type: "result";
+}>, state: TranslatorState): TranslateStep;
+//# sourceMappingURL=eventTranslator.d.ts.map

package/dist/letta/eventTranslator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventTranslator.d.ts","sourceRoot":"","sources":["../../src/letta/eventTranslator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EACV,UAAU,EAGV,YAAY,EACZ,UAAU,EACX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAM3D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,MAAM,EAAE,UAAU,CAAC;IACnB,mCAAmC;IACnC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3B,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B;;;OAGG;IACH,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC;;;;;OAKG;IACH,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC;;;;OAIG;IACH,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED,yCAAyC;AACzC,wBAAgB,sBAAsB,IAAI,eAAe,CAWxD;AAED,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACxC,6BAA6B;IAC7B,KAAK,EAAE,eAAe,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,SAAS,MAAM,CAAC,GACrD,CAAC,SAAS,UAAU,GAClB,CAAC,SAAS;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,CAAA;CAAE,GACzC,IAAI,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,YAAY,CAAC,CAAA;CAAE,GACzD,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,GAChB,KAAK,GACP,KAAK,CAAC;AAMV;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,eAAe,GACrB,aAAa,CAsBf;AAkTD;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,eAAe,EACtB,cAAc,GAAE,UAAmB,GAClC,aAAa,CAAC,gBAAgB,CAAC,CAejC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,EAC5C,KAAK,EAAE,eAAe,GACrB,aAAa,CA0Df"}