@kb-labs/agent-core 2.118.2 → 2.119.0-canary.2077501f1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _kb_labs_agent_contracts from '@kb-labs/agent-contracts';
-import { AgentMode, AgentSessionInfo, AgentSession, AgentEvent, Turn, FileChangeSummary, AgentEventCallback, Tracer, LLMTier, TaskPlan, SessionProgress, TaskSpec, AgentConfig, TaskResult, ModeConfig, SpecSection, StopConditionResult, LoopResult, AgentMemory, FeatureFlags, SpawnAgentRequest, SpawnAgentResult, AsyncTask, ToolPack, ToolFilter, ToolDefinition, ResolvedTool, ToolResult, IterationSnapshot, RunEvaluation } from '@kb-labs/agent-contracts';
+import { AgentMode, AgentSessionInfo, AgentSession, AgentEvent, TurnDelta, Turn, FileChangeSummary, AgentEventCallback, Tracer, LLMTier, TaskPlan, SessionProgress, TaskSpec, AgentConfig, TaskResult, ModeConfig, SpecSection, StopConditionResult, LoopResult, AgentMemory, FeatureFlags, SpawnAgentRequest, SpawnAgentResult, AsyncTask, ToolPack, ToolFilter, ToolDefinition, ResolvedTool, ToolResult, IterationSnapshot, RunEvaluation } from '@kb-labs/agent-contracts';
 import { ToolRegistry, SessionMemoryBridge } from '@kb-labs/agent-tools';
 import { RuntimeProfile, ResultMapper, StopCondition, RunContext, LLMCallResult, ExecutionLoop as ExecutionLoop$1, LoopContext as LoopContext$1, LoopResult as LoopResult$1, AgentMiddleware, ControlAction, LLMCtx, LLMCallPatch, ToolExecCtx, ToolOutput, IAgentRunner, AgentSDK, ToolGuard, OutputProcessor, InputNormalizer, ToolCallInput, ContextMeta } from '@kb-labs/agent-sdk';
 export { AgentMiddleware, ControlAction, LLMCallPatch, LLMCallResult, LLMCtx, RunContext, ToolExecCtx, ToolOutput } from '@kb-labs/agent-sdk';
@@ -40,21 +40,27 @@ interface SessionKpiBaseline {
 declare class SessionManager {
     private workingDir;
     private readonly artifactStore;
-    /** In-memory cache of per-run sequence counters (initialized lazily from NDJSON) */
-    private runSeqCounters;
-    /** In-memory cache of turn sequence counters per session (for turns.json). */
-    private turnSeqCounters;
+    /**
+     * In-memory cache of the per-session monotonic event sequence counter
+     * (initialized lazily from NDJSON line count). Backed by shared
+     * process-wide state — see SharedSessionManagerState's doc comment for
+     * why this must NOT be a plain instance field.
+     */
+    private get sessionSeqCounters();
+    /** In-memory cache of turn sequence counters per session (for turns.json). Shared — see sessionSeqCounters. */
+    private get turnSeqCounters();
     /** Turn assembler for creating turn snapshots from events */
     private assembler;
-    /** Write queue per session to prevent concurrent write race conditions */
-    private writeQueues;
+    /** Write queue per session to prevent concurrent write race conditions. Shared — see sessionSeqCounters. */
+    private get writeQueues();
     /**
      * Serialized event-processing queue per session.
      * Ensures addEvent calls for the same session are processed in arrival order
      * even when the caller fires them concurrently with void (fire-and-forget).
      * This prevents tool:end being processed by TurnAssembler before tool:start.
+     * Shared — see sessionSeqCounters.
      */
-    private eventQueues;
+    private get eventQueues();
     /** Write queue per session for artifact projection updates */
     private artifactWriteQueues;
     /** Write queue per session for KPI baseline updates */
@@ -108,22 +114,41 @@ declare class SessionManager {
         total: number;
     }>;
     /**
-     * Get next per-run sessionSeq for a specific run within a session.
-     * Each run has independent sequence counters starting from 1.
-     * Lazily initialized: reads NDJSON on first call to find max existing sessionSeq for this runId,
-     * then uses in-memory counter for subsequent calls.
-     */
+     * Get the next seq for a session — monotonic across the WHOLE session
+     * (every run, every turn), not scoped to a single run. This is the one
+     * cursor the WS protocol and REST resume/gap-recovery paths rely on;
+     * it must be a single, ever-increasing number per session for "seq > N"
+     * comparisons to mean anything.
+     *
+     * Lazily initialized from the NDJSON LINE COUNT, not the max embedded
+     * `sessionSeq` value. Old sessions were written under the previous
+     * per-run scheme, where two different runs both start their own
+     * `sessionSeq` at 1 — so the max embedded value can be far smaller than
+     * the true number of events and would hand out colliding seq numbers
+     * for old sessions. Line count is always >= any embedded per-run value
+     * and is exactly equal to it for sessions already written under this
+     * per-session scheme, so it's a safe bootstrap either way.
+     */
+    private ensureSessionSeqBootstrapped;
     private getNextSessionSeq;
+    /**
+     * Current session-wide cursor value WITHOUT advancing it. Used for the
+     * cold-start snapshot and gap-recovery projection, both of which need to
+     * hand the client a `seq` to resume from without consuming one.
+     */
+    getCurrentSessionSeq(sessionId: string): Promise<number>;
     /**
      * Add event to session (append-only, race-condition safe).
-     * Assigns per-run sessionSeq for ordering within each run.
-     * Also processes event to update turn snapshots.
+     * Assigns the session-wide monotonic sessionSeq.
+     * Also processes the event to update turn snapshots, returning whatever
+     * TurnDelta[] that produced (empty if the event didn't touch a turn) so
+     * callers can broadcast them once persistence is confirmed.
      *
      * Events for the same session are serialized via eventQueues so that
      * concurrent fire-and-forget callers (void addEvent(...)) don't cause
      * tool:end to be processed before tool:start in TurnAssembler.
      */
-    addEvent(sessionId: string, event: AgentEvent): Promise<void>;
+    addEvent(sessionId: string, event: AgentEvent): Promise<TurnDelta[]>;
     private _addEventInternal;
     /**
      * Get all events for a session
@@ -222,17 +247,47 @@ declare class SessionManager {
      * Create user turn with task/question
      * Called when user submits a task to agent
      */
-    createUserTurn(sessionId: string, task: string, runId: string): Promise<Turn>;
+    createUserTurn(sessionId: string, task: string, runId: string, clientId?: string): Promise<Turn>;
     /**
      * Reserve next turn sequence number atomically per session.
      * Uses the same serialized write queue as turns.json updates.
      */
     private reserveNextTurnSequence;
     /**
-     * Process event and update turn snapshot
-     * Returns updated turn if changed, null otherwise
-     */
-    processEventAndUpdateTurn(sessionId: string, event: AgentEvent): Promise<Turn | null>;
+     * Process event, update the turn projection, and compute the deltas this
+     * mutation produced (relative to the turn's state just before this
+     * event). Returns null when the event didn't touch any turn, or touched
+     * one without producing any externally-observable change.
+     *
+     * The "before" snapshot is captured from the assembler's live (in-place
+     * mutated) turn reference BEFORE processEventAsync runs — the assembler
+     * mutates the same object, so this is the only point at which a
+     * pre-mutation snapshot is available.
+     *
+     * Deliberately resolves the CURRENT turn via peekTurn rather than trusting
+     * processEventAsync's own return value: the assembler treats "just
+     * created, no steps yet" (a bare agent:start with nothing else to report)
+     * as "not updated" and returns null for it — but the turn WAS created as
+     * a side effect (added to activeTurns), which is itself diff-worthy: it's
+     * the only point `turn:created` can ever fire from. Without this, the
+     * turn is silently created in memory but never persisted or broadcast,
+     * and every later event sees `before !== null` (peekTurn already finds
+     * it), so `turn:created` never fires at all.
+     */
+    processEventAndUpdateTurn(sessionId: string, event: AgentEvent): Promise<{
+        turn: Turn;
+        deltas: TurnDelta[];
+    } | null>;
+    /**
+     * Current projection of a session: its full turn list plus the seq cursor
+     * it reflects. Used for the cold-start snapshot AND as the gap-recovery
+     * resume payload (see ADR note in the sync design doc) — both send the
+     * same shape, just at different points in the connection lifecycle.
+     */
+    getProjection(sessionId: string): Promise<{
+        turns: Turn[];
+        seq: number;
+    }>;
     /**
      * Store extracted trace artifacts for a completed run.
      */

package/dist/index.js

@@ -101,6 +101,24 @@ var init_turn_assembler = __esm({
         }
         return updated || completed ? turn : null;
       }
+      /**
+       * Public wrapper around getTurnId, for callers that need to snapshot the
+       * turn's pre-mutation state (e.g. to diff against post-mutation state)
+       * before calling processEventAsync.
+       */
+      getTurnIdForEvent(event) {
+        return this.getTurnId(event);
+      }
+      /**
+       * Peek at the current in-progress turn for a turn id, WITHOUT mutating
+       * anything. Returns a live reference (not a clone) — the assembler
+       * mutates turn/step objects in place, so callers that need a stable
+       * "before" snapshot must clone this themselves before calling
+       * processEventAsync.
+       */
+      peekTurn(turnId) {
+        return this.activeTurns.get(turnId);
+      }
       /**
        * Derive turn ID from event.
        * For root agents: use agentId
@@ -486,33 +504,124 @@ var init_turn_assembler = __esm({
   }
 });
 
+// src/planning/turn-diff.ts
+function stepsEqual(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+function diffTurn(before, after, seq) {
+  const deltas = [];
+  if (!before) {
+    deltas.push({ kind: "turn:created", seq, turn: { ...after, steps: [] } });
+    for (const step of after.steps) {
+      deltas.push({ kind: "turn:step:appended", seq, turnId: after.id, step });
+    }
+    if (after.status !== "streaming") {
+      deltas.push({
+        kind: "turn:status",
+        seq,
+        turnId: after.id,
+        status: after.status,
+        completedAt: after.completedAt,
+        error: after.error
+      });
+    }
+    return deltas;
+  }
+  for (let i = 0; i < after.steps.length; i++) {
+    const afterStep = after.steps[i];
+    if (!afterStep) {
+      continue;
+    }
+    const beforeStep = before.steps[i];
+    if (!beforeStep) {
+      deltas.push({ kind: "turn:step:appended", seq, turnId: after.id, step: afterStep });
+    } else if (!stepsEqual(beforeStep, afterStep)) {
+      deltas.push({ kind: "turn:step:updated", seq, turnId: after.id, step: afterStep });
+    }
+  }
+  if (before.status !== after.status || before.completedAt !== after.completedAt) {
+    deltas.push({
+      kind: "turn:status",
+      seq,
+      turnId: after.id,
+      status: after.status,
+      completedAt: after.completedAt,
+      error: after.error
+    });
+  }
+  const beforeMeta = before.metadata;
+  const afterMeta = after.metadata;
+  const metaPatch = {};
+  for (const key of Object.keys(afterMeta)) {
+    if (!stepsEqual(beforeMeta[key], afterMeta[key])) {
+      metaPatch[key] = afterMeta[key];
+    }
+  }
+  if (Object.keys(metaPatch).length > 0) {
+    deltas.push({ kind: "turn:metadata", seq, turnId: after.id, patch: metaPatch });
+  }
+  return deltas;
+}
+var init_turn_diff = __esm({
+  "src/planning/turn-diff.ts"() {
+  }
+});
+
 // src/planning/session-manager.ts
 var session_manager_exports = {};
 __export(session_manager_exports, {
   SessionManager: () => SessionManager
 });
-var SessionManager;
+function getSharedState() {
+  const g = globalThis;
+  if (!g[SHARED_STATE_KEY]) {
+    g[SHARED_STATE_KEY] = {
+      sessionSeqCounters: /* @__PURE__ */ new Map(),
+      turnSeqCounters: /* @__PURE__ */ new Map(),
+      writeQueues: /* @__PURE__ */ new Map(),
+      eventQueues: /* @__PURE__ */ new Map()
+    };
+  }
+  return g[SHARED_STATE_KEY];
+}
+var SHARED_STATE_KEY, SessionManager;
 var init_session_manager = __esm({
   "src/planning/session-manager.ts"() {
     init_turn_assembler();
+    init_turn_diff();
+    SHARED_STATE_KEY = "__kb_agent_session_manager_shared_state__";
     SessionManager = class {
       workingDir;
       artifactStore;
-      /** In-memory cache of per-run sequence counters (initialized lazily from NDJSON) */
-      runSeqCounters = /* @__PURE__ */ new Map();
-      /** In-memory cache of turn sequence counters per session (for turns.json). */
-      turnSeqCounters = /* @__PURE__ */ new Map();
+      /**
+       * In-memory cache of the per-session monotonic event sequence counter
+       * (initialized lazily from NDJSON line count). Backed by shared
+       * process-wide state — see SharedSessionManagerState's doc comment for
+       * why this must NOT be a plain instance field.
+       */
+      get sessionSeqCounters() {
+        return getSharedState().sessionSeqCounters;
+      }
+      /** In-memory cache of turn sequence counters per session (for turns.json). Shared — see sessionSeqCounters. */
+      get turnSeqCounters() {
+        return getSharedState().turnSeqCounters;
+      }
       /** Turn assembler for creating turn snapshots from events */
       assembler = new TurnAssembler();
-      /** Write queue per session to prevent concurrent write race conditions */
-      writeQueues = /* @__PURE__ */ new Map();
+      /** Write queue per session to prevent concurrent write race conditions. Shared — see sessionSeqCounters. */
+      get writeQueues() {
+        return getSharedState().writeQueues;
+      }
       /**
        * Serialized event-processing queue per session.
        * Ensures addEvent calls for the same session are processed in arrival order
        * even when the caller fires them concurrently with void (fire-and-forget).
        * This prevents tool:end being processed by TurnAssembler before tool:start.
+       * Shared — see sessionSeqCounters.
        */
-      eventQueues = /* @__PURE__ */ new Map();
+      get eventQueues() {
+        return getSharedState().eventQueues;
+      }
       /** Write queue per session for artifact projection updates */
       artifactWriteQueues = /* @__PURE__ */ new Map();
       /** Write queue per session for KPI baseline updates */
@@ -657,39 +766,54 @@ var init_session_manager = __esm({
       // Event Storage (NDJSON format - append-safe)
       // ═══════════════════════════════════════════════════════════════════════
       /**
-       * Get next per-run sessionSeq for a specific run within a session.
-       * Each run has independent sequence counters starting from 1.
-       * Lazily initialized: reads NDJSON on first call to find max existing sessionSeq for this runId,
-       * then uses in-memory counter for subsequent calls.
+       * Get the next seq for a session — monotonic across the WHOLE session
+       * (every run, every turn), not scoped to a single run. This is the one
+       * cursor the WS protocol and REST resume/gap-recovery paths rely on;
+       * it must be a single, ever-increasing number per session for "seq > N"
+       * comparisons to mean anything.
+       *
+       * Lazily initialized from the NDJSON LINE COUNT, not the max embedded
+       * `sessionSeq` value. Old sessions were written under the previous
+       * per-run scheme, where two different runs both start their own
+       * `sessionSeq` at 1 — so the max embedded value can be far smaller than
+       * the true number of events and would hand out colliding seq numbers
+       * for old sessions. Line count is always >= any embedded per-run value
+       * and is exactly equal to it for sessions already written under this
+       * per-session scheme, so it's a safe bootstrap either way.
        */
-      async getNextSessionSeq(sessionId, runId) {
-        const key = `${sessionId}:${runId}`;
-        if (!this.runSeqCounters.has(key)) {
-          let maxSeq = 0;
-          try {
-            const content = await promises.readFile(this.getEventsPath(sessionId), "utf-8");
-            const lines = content.split("\n").filter((l) => l.trim());
-            for (const line of lines) {
-              try {
-                const evt = JSON.parse(line);
-                if (evt.runId === runId && evt.sessionSeq != null && evt.sessionSeq > maxSeq) {
-                  maxSeq = evt.sessionSeq;
-                }
-              } catch {
-              }
-            }
-          } catch {
-          }
-          this.runSeqCounters.set(key, maxSeq);
+      async ensureSessionSeqBootstrapped(sessionId) {
+        if (this.sessionSeqCounters.has(sessionId)) {
+          return;
+        }
+        let lineCount = 0;
+        try {
+          const content = await promises.readFile(this.getEventsPath(sessionId), "utf-8");
+          lineCount = content.split("\n").filter((l) => l.trim()).length;
+        } catch {
         }
-        const next = this.runSeqCounters.get(key) + 1;
-        this.runSeqCounters.set(key, next);
+        this.sessionSeqCounters.set(sessionId, lineCount);
+      }
+      async getNextSessionSeq(sessionId) {
+        await this.ensureSessionSeqBootstrapped(sessionId);
+        const next = this.sessionSeqCounters.get(sessionId) + 1;
+        this.sessionSeqCounters.set(sessionId, next);
         return next;
       }
+      /**
+       * Current session-wide cursor value WITHOUT advancing it. Used for the
+       * cold-start snapshot and gap-recovery projection, both of which need to
+       * hand the client a `seq` to resume from without consuming one.
+       */
+      async getCurrentSessionSeq(sessionId) {
+        await this.ensureSessionSeqBootstrapped(sessionId);
+        return this.sessionSeqCounters.get(sessionId);
+      }
       /**
        * Add event to session (append-only, race-condition safe).
-       * Assigns per-run sessionSeq for ordering within each run.
-       * Also processes event to update turn snapshots.
+       * Assigns the session-wide monotonic sessionSeq.
+       * Also processes the event to update turn snapshots, returning whatever
+       * TurnDelta[] that produced (empty if the event didn't touch a turn) so
+       * callers can broadcast them once persistence is confirmed.
        *
        * Events for the same session are serialized via eventQueues so that
        * concurrent fire-and-forget callers (void addEvent(...)) don't cause
@@ -708,12 +832,12 @@ var init_session_manager = __esm({
         const sessionDir = this.getSessionDir(sessionId);
         await promises.mkdir(sessionDir, { recursive: true });
         await this.artifactStore.ensureSessionArtifacts(sessionId);
-        const runId = event.runId || "unknown";
-        const sessionSeq = await this.getNextSessionSeq(sessionId, runId);
+        const sessionSeq = await this.getNextSessionSeq(sessionId);
         const line = JSON.stringify({ ...event, sessionSeq }) + "\n";
         await promises.appendFile(this.getEventsPath(sessionId), line, "utf-8");
         await promises.appendFile(this.artifactStore.getArtifactPath(sessionId, "trace.ndjson"), line, "utf-8");
-        await this.processEventAndUpdateTurn(sessionId, { ...event, sessionSeq });
+        const result = await this.processEventAndUpdateTurn(sessionId, { ...event, sessionSeq });
+        return result?.deltas ?? [];
       }
       /**
        * Get all events for a session
@@ -1104,7 +1228,7 @@ ${tail}`;
        * Create user turn with task/question
        * Called when user submits a task to agent
        */
-      async createUserTurn(sessionId, task, runId) {
+      async createUserTurn(sessionId, task, runId, clientId) {
         const sequence = await this.reserveNextTurnSequence(sessionId);
         const timestamp = (/* @__PURE__ */ new Date()).toISOString();
         const userTurn = {
@@ -1125,7 +1249,8 @@ ${tail}`;
             }
           ],
           metadata: {
-            agentId: "user"
+            agentId: "user",
+            ...clientId ? { clientId } : {}
           }
         };
         await this.storeTurnSnapshot(sessionId, userTurn);
@@ -1153,21 +1278,63 @@ ${tail}`;
         return reserved;
       }
       /**
-       * Process event and update turn snapshot
-       * Returns updated turn if changed, null otherwise
+       * Process event, update the turn projection, and compute the deltas this
+       * mutation produced (relative to the turn's state just before this
+       * event). Returns null when the event didn't touch any turn, or touched
+       * one without producing any externally-observable change.
+       *
+       * The "before" snapshot is captured from the assembler's live (in-place
+       * mutated) turn reference BEFORE processEventAsync runs — the assembler
+       * mutates the same object, so this is the only point at which a
+       * pre-mutation snapshot is available.
+       *
+       * Deliberately resolves the CURRENT turn via peekTurn rather than trusting
+       * processEventAsync's own return value: the assembler treats "just
+       * created, no steps yet" (a bare agent:start with nothing else to report)
+       * as "not updated" and returns null for it — but the turn WAS created as
+       * a side effect (added to activeTurns), which is itself diff-worthy: it's
+       * the only point `turn:created` can ever fire from. Without this, the
+       * turn is silently created in memory but never persisted or broadcast,
+       * and every later event sees `before !== null` (peekTurn already finds
+       * it), so `turn:created` never fires at all.
        */
       async processEventAndUpdateTurn(sessionId, event) {
-        const turn = await this.assembler.processEventAsync(event, async (sid) => {
+        const turnId = this.assembler.getTurnIdForEvent(event);
+        if (!turnId) {
+          return null;
+        }
+        const liveBefore = this.assembler.peekTurn(turnId);
+        const before = liveBefore ? structuredClone(liveBefore) : null;
+        const returnedTurn = await this.assembler.processEventAsync(event, async (sid) => {
           return this.reserveNextTurnSequence(sid);
         });
-        if (turn) {
-          if (event.runId && turn.type === "assistant" && !turn.metadata.runId) {
-            turn.metadata.runId = event.runId;
-          }
-          await this.storeTurnSnapshot(sessionId, turn);
-          return turn;
+        const turn = returnedTurn ?? this.assembler.peekTurn(turnId);
+        if (!turn) {
+          return null;
         }
-        return null;
+        if (event.runId && turn.type === "assistant" && !turn.metadata.runId) {
+          turn.metadata.runId = event.runId;
+        }
+        const seq = event.sessionSeq ?? await this.getCurrentSessionSeq(sessionId);
+        const deltas = diffTurn(before, turn, seq);
+        if (deltas.length === 0) {
+          return null;
+        }
+        await this.storeTurnSnapshot(sessionId, turn);
+        return { turn, deltas };
+      }
+      /**
+       * Current projection of a session: its full turn list plus the seq cursor
+       * it reflects. Used for the cold-start snapshot AND as the gap-recovery
+       * resume payload (see ADR note in the sync design doc) — both send the
+       * same shape, just at different points in the connection lifecycle.
+       */
+      async getProjection(sessionId) {
+        const [turns, seq] = await Promise.all([
+          this.getTurns(sessionId),
+          this.getCurrentSessionSeq(sessionId)
+        ]);
+        return { turns, seq };
       }
       /**
        * Store extracted trace artifacts for a completed run.