@naswerks/periscope 1.0.0 → 1.0.1

package/src/control/queue.ts

@@ -0,0 +1,248 @@
+/**
+ * The retention buffer between producers and the wire.
+ *
+ * Bounded, because an unbounded buffer is an out-of-memory kill in a process whose whole job is to
+ * still be running when the controller comes back. Bounded means something gets dropped, and which
+ * thing is a decision rather than an accident: see DROPPABLE_KINDS in frames.ts.
+ *
+ * Entries live in one of two states, and the split is what keeps the wire's numbering dense:
+ *   - pending: accepted for delivery, not yet written. It has no `seq` and never had one, so
+ *     discarding it costs the content and nothing else.
+ *   - written: stamped with its `seq` at the moment of its first socket write, and held until the
+ *     controller acknowledges it. A written frame is never discarded here: it may already be at the
+ *     receiver, so forgetting it would break replay's completeness. Only an ack (`pruneUpTo`) or
+ *     session end (`forget`) releases it.
+ */
+import type { Result } from '../core/result.js';
+import { ok, refuse } from '../core/result.js';
+import type { SessionFrame, SessionPayload, SessionPayloadKind } from './frames.js';
+import { isDroppable } from './frames.js';
+
+export interface QueueStats {
+  readonly depth: number;
+  /** Of `depth`, how many entries are still waiting for their first write. */
+  readonly pendingDepth: number;
+  readonly capacity: number;
+  /** Deltas discarded under pressure. Expected under load; worth watching, not alarming. */
+  readonly droppedDroppable: number;
+  /** Frames that could not be held and could not be dropped. Always a real problem. */
+  readonly refusedUndroppable: number;
+}
+
+/** What an admission displaced, when it displaced anything. Named so the caller can say it out loud. */
+export interface EvictedPending {
+  readonly sessionId: string;
+  readonly kind: SessionPayloadKind;
+}
+
+export interface QueueAdmission {
+  /** The pending droppable discarded to make room, or null when nothing was displaced. */
+  readonly evicted: EvictedPending | null;
+}
+
+/** Builds the frame for a pending entry at the moment it is written. The caller supplies the seq. */
+export type StampFrame = (sessionId: string, at: string, payload: SessionPayload) => SessionFrame;
+
+interface PendingEntry {
+  readonly written: false;
+  readonly sessionId: string;
+  readonly at: string;
+  readonly payload: SessionPayload;
+}
+
+interface WrittenEntry {
+  readonly written: true;
+  readonly frame: SessionFrame;
+}
+
+type HeldEntry = PendingEntry | WrittenEntry;
+
+export class BoundedFrameQueue {
+  /**
+   * Written entries are a prefix and pending entries the suffix: a push appends, a stamp converts the
+   * first pending entry in place, and every removal keeps the two runs contiguous. `#writtenCount` is
+   * the boundary, so the next entry to stamp is found without a scan and a prune reads only the
+   * written run.
+   */
+  readonly #entries: HeldEntry[] = [];
+  #writtenCount = 0;
+  readonly #capacity: number;
+  #droppedDroppable = 0;
+  #refusedUndroppable = 0;
+
+  constructor(capacity: number) {
+    if (!Number.isInteger(capacity) || capacity < 1) {
+      throw new RangeError(`queue capacity must be a positive integer, got ${capacity}`);
+    }
+    this.#capacity = capacity;
+  }
+
+  /**
+   * Admit a payload for delivery. It enters pending, with no `seq`.
+   *
+   * At capacity the order of preference is: discard the incoming payload if it is droppable; else
+   * discard the oldest pending droppable to make room; else refuse, loudly. Refusing is the honest
+   * end of the ladder, because the alternative is discarding a transition or a receipt and
+   * reporting success, which is a lie about what the session did. Written frames are never
+   * candidates: a frame that has touched the wire may already be at the receiver, and the numbering
+   * stays dense only because nothing numbered is ever quietly withdrawn.
+   */
+  push(sessionId: string, at: string, payload: SessionPayload): Result<QueueAdmission> {
+    if (this.#entries.length < this.#capacity) {
+      this.#entries.push({ written: false, sessionId, at, payload });
+      return ok({ evicted: null });
+    }
+
+    if (isDroppable(payload.kind)) {
+      this.#droppedDroppable += 1;
+      return refuse(
+        'queue-dropped-droppable',
+        `queue full at ${this.#capacity}; discarded an incoming ${payload.kind}`,
+      );
+    }
+
+    let victim = -1;
+    for (let index = this.#writtenCount; index < this.#entries.length; index += 1) {
+      const entry = this.#entries[index] as PendingEntry;
+      if (isDroppable(entry.payload.kind)) {
+        victim = index;
+        break;
+      }
+    }
+    if (victim >= 0) {
+      const evicted = this.#entries[victim] as PendingEntry;
+      this.#entries.splice(victim, 1);
+      this.#droppedDroppable += 1;
+      this.#entries.push({ written: false, sessionId, at, payload });
+      return ok({ evicted: { sessionId: evicted.sessionId, kind: evicted.payload.kind } });
+    }
+
+    this.#refusedUndroppable += 1;
+    return refuse(
+      'queue-overflow-undroppable',
+      `queue full at ${this.#capacity} with nothing droppable to discard; cannot hold ` +
+        `${payload.kind} for session ${sessionId}`,
+    );
+  }
+
+  /**
+   * Stamp the oldest pending entry and hand back its frame for the write.
+   *
+   * Stamping and writing are one act: the entry becomes written before the caller touches the
+   * socket, so however the write itself goes, a stamped frame is retained and replayable — a seq,
+   * once minted, is always accounted for. Returns null when nothing is pending.
+   */
+  stampNext(stamp: StampFrame): SessionFrame | null {
+    const index = this.#writtenCount;
+    const pending = this.#entries[index];
+    if (pending === undefined || pending.written) return null;
+    const frame = stamp(pending.sessionId, pending.at, pending.payload);
+    this.#entries[index] = { written: true, frame };
+    this.#writtenCount += 1;
+    return frame;
+  }
+
+  /** Every written frame still held, oldest first — what replay re-sends after a reconnect. */
+  writtenFrames(): readonly SessionFrame[] {
+    return this.#entries.filter((entry): entry is WrittenEntry => entry.written).map((entry) => entry.frame);
+  }
+
+  get hasPending(): boolean {
+    return this.#writtenCount < this.#entries.length;
+  }
+
+  /**
+   * Forget frames the controller has confirmed, per session.
+   *
+   * This is what bounds the retention window. Frames are held after being written, because a frame
+   * in flight when the socket dies is exactly the one replay has to produce — so "sent" is not
+   * "safe to forget"; only an ack is.
+   */
+  pruneUpTo(sessionId: string, seq: number): number {
+    return this.#removeWritten((frame) => frame.sessionId === sessionId && frame.seq <= seq);
+  }
+
+  /** One pass over the written run, keeping what the predicate does not name; the pending run is untouched. */
+  #removeWritten(remove: (frame: SessionFrame) => boolean): number {
+    const kept: HeldEntry[] = [];
+    for (let index = 0; index < this.#writtenCount; index += 1) {
+      const held = this.#entries[index] as WrittenEntry;
+      if (!remove(held.frame)) kept.push(held);
+    }
+    const removed = this.#writtenCount - kept.length;
+    if (removed > 0) {
+      this.#entries.splice(0, this.#writtenCount, ...kept);
+      this.#writtenCount = kept.length;
+    }
+    return removed;
+  }
+
+  /** One pass over the pending run, keeping what the predicate does not name; the written run is untouched. */
+  #removePending(remove: (entry: PendingEntry) => boolean): number {
+    const kept: HeldEntry[] = [];
+    for (let index = this.#writtenCount; index < this.#entries.length; index += 1) {
+      const held = this.#entries[index] as PendingEntry;
+      if (!remove(held)) kept.push(held);
+    }
+    const removed = this.#entries.length - this.#writtenCount - kept.length;
+    if (removed > 0)
+      this.#entries.splice(this.#writtenCount, this.#entries.length - this.#writtenCount, ...kept);
+    return removed;
+  }
+
+  /**
+   * Drop a session's pending entries at session end. Written-and-unacked frames are kept.
+   *
+   * Two rules collide here and this is which one wins. "Nothing keyed by a session outlives it"
+   * bounds a long-running host; "a transition is never dropped" is what makes the trace true. At
+   * session end they meet, because the last frames a session produces (its `-> ended` transition,
+   * the result that preceded it) are exactly the ones still unacked if the link happens to be
+   * down. Dropping them would lose the record of how a session ended, silently, in precisely the
+   * case somebody is going to ask about. So the never-drop rule wins for anything stamped.
+   *
+   * This does not reopen the unbounded problem: a written frame is retained only until the
+   * controller acks it, and an ended session produces no more frames — so what is kept is a fixed,
+   * already-bounded set that the next `link_ack` prunes to nothing. Pending entries are dropped
+   * because they never touched the wire and never had a seq: nothing on the other side is waiting
+   * for them, and there is no hole for them to leave.
+   *
+   * Returns how many entries were dropped.
+   */
+  forget(sessionId: string): number {
+    return this.#removePending((entry) => entry.sessionId === sessionId);
+  }
+
+  /**
+   * Drop everything this session holds, written frames included. Returns how many were written.
+   *
+   * This is the one method here that discards a stamped frame, and it exists for a bound rather
+   * than for convenience. `forget` deliberately keeps written-and-unacked frames because a
+   * session's last frames are the ones replay has to produce; `pruneUpTo` releases them on an ack.
+   * Neither has a bound, and nothing in the protocol obliges a peer to ack, so an ended session
+   * nobody acks is held forever, and written frames are never eviction candidates, so those holds
+   * accumulate until the queue refuses live traffic.
+   *
+   * Call this only for an ended session past its retention bound, and never as a tidy-up: for a
+   * live session this reintroduces the permanent-hole defect the whole retention window exists to
+   * prevent. `link.ts`'s sweep is the only caller, and it names what it dropped on the refusal lane.
+   */
+  releaseSession(sessionId: string): number {
+    this.#removePending((entry) => entry.sessionId === sessionId);
+    return this.#removeWritten((frame) => frame.sessionId === sessionId);
+  }
+
+  /** How many written-but-unacked frames this session still holds. Zero once the controller acks. */
+  retainedFor(sessionId: string): number {
+    return this.#entries.filter((entry) => entry.written && entry.frame.sessionId === sessionId).length;
+  }
+
+  get stats(): QueueStats {
+    return {
+      depth: this.#entries.length,
+      pendingDepth: this.#entries.length - this.#writtenCount,
+      capacity: this.#capacity,
+      droppedDroppable: this.#droppedDroppable,
+      refusedUndroppable: this.#refusedUndroppable,
+    };
+  }
+}

package/src/control/seq.ts

@@ -0,0 +1,76 @@
+/**
+ * `seq` accounting, used identically on both ends and in both directions.
+ *
+ * Outbound it hands out numbers; inbound it judges them. Symmetric on purpose: the controller's
+ * commands get the same duplicate-suppression and gap-detection the host's events do, from one
+ * implementation rather than two that can disagree.
+ */
+import type { SessionCursor } from './frames.js';
+
+export type InboundCheck =
+  /** In order. Deliver it. */
+  | { readonly disposition: 'accept' }
+  /** Already seen. Replay after a reconnect is expected, so this is normal and silent. */
+  | { readonly disposition: 'duplicate'; readonly seq: number }
+  /** Something was lost between the two ends. Loud: this is the condition replay exists to prevent. */
+  | { readonly disposition: 'gap'; readonly expected: number; readonly received: number };
+
+export class SeqTracker {
+  readonly #lastBySession = new Map<string, number>();
+
+  /** The next number to stamp on an outbound frame for this session. First is 1. */
+  next(sessionId: string): number {
+    const next = (this.#lastBySession.get(sessionId) ?? 0) + 1;
+    this.#lastBySession.set(sessionId, next);
+    return next;
+  }
+
+  /** The highest number issued or accepted so far, or 0 when the session is new. */
+  last(sessionId: string): number {
+    return this.#lastBySession.get(sessionId) ?? 0;
+  }
+
+  /**
+   * Judge an inbound frame. Dense sequencing is what makes this arithmetic rather than a guess:
+   * expected is always `last + 1`, so a gap needs no timestamps and no heuristics.
+   */
+  accept(sessionId: string, seq: number): InboundCheck {
+    const last = this.last(sessionId);
+    const expected = last + 1;
+
+    if (seq === expected) {
+      this.#lastBySession.set(sessionId, seq);
+      return { disposition: 'accept' };
+    }
+    if (seq <= last) {
+      return { disposition: 'duplicate', seq };
+    }
+    return { disposition: 'gap', expected, received: seq };
+  }
+
+  /** What this side holds, for the hello handshake and for resume after a drop. */
+  cursors(): SessionCursor[] {
+    return [...this.#lastBySession].map(([sessionId, seq]) => ({ sessionId, seq }));
+  }
+
+  /** Adopt a peer's cursors on reconnect, so replay starts from what it actually has. */
+  adopt(cursors: readonly SessionCursor[]): void {
+    for (const cursor of cursors) {
+      this.#lastBySession.set(cursor.sessionId, cursor.seq);
+    }
+  }
+
+  /**
+   * Drop a session's counter at session end.
+   *
+   * Nothing keyed by session may outlive the session — an unbounded map is how a long-running host
+   * dies of something nobody can attribute to any one session.
+   */
+  forget(sessionId: string): void {
+    this.#lastBySession.delete(sessionId);
+  }
+
+  get trackedSessions(): number {
+    return this.#lastBySession.size;
+  }
+}

package/src/control/stream-routing.ts

@@ -0,0 +1,216 @@
+/**
+ * The stream routing table. Every message the agent can emit rides a declared lane, in writing.
+ *
+ * An absent row is a gap, not a default, and it cannot happen, because this is declared
+ * `satisfies Record<MessageDiscriminator, RoutingRow>` against the discriminator set derived from
+ * the SDK's own union. A message added by an SDK upgrade breaks the build rather than silently
+ * falling through to whichever lane a branch happened to end on.
+ *
+ * This is not `state/coverage.ts` and must not be merged with it. They answer different
+ * questions and disagree in both directions:
+ *   - `coverage.ts`: does this message move the state machine?
+ *   - this table: does this message go on the wire, and on which lane?
+ * `assistant` is declined there (it changes no state) and forwarded here (it is the turn's text).
+ * `system/session_state_changed` is wired there and declined here (the transition it causes already
+ * carries the fact, and two names for one fact is how a vocabulary drifts apart). A single table
+ * would have to pick one question and would silently answer the other one wrongly.
+ *
+ * The three lanes, and the rule that assigns them.
+ *
+ *   `delta`     Superseded by something that settles the same fact, and high-frequency with it.
+ *               Losing one costs a repaint, never a fact — which is exactly what makes it the one
+ *               droppable kind. ~20 per turn, so putting these in a bounded replay ring would evict
+ *               real events with token fragments.
+ *
+ *   `update`    A fact of the turn that nothing later restates. Durable: retained until acked,
+ *               replayed after a reconnect.
+ *
+ *   `declined`  Only where the fact demonstrably reaches the wire another way, or where
+ *               forwarding it would echo the host's own decisions back at the controller that made
+ *               them. Never "judged uninteresting": this host is deliberately ignorant, and
+ *               `state/reporter.ts` states the reason: a host that decides what matters is a host
+ *               that must be rebuilt for the next product. So `update` is the default, and a
+ *               declined row owes a reason a stranger can check.
+ */
+import type { MessageDiscriminator, SDKMessage } from '../host/agent-process.js';
+import { discriminatorOf } from '../host/agent-process.js';
+
+export type StreamLane = 'delta' | 'update' | 'declined';
+
+export interface RoutingRow {
+  readonly lane: StreamLane;
+  /** Why this lane. Required on every row, including the declined ones. */
+  readonly note: string;
+}
+
+export const MESSAGE_ROUTING = {
+  // --- delta: superseded, high-frequency, broadcast-only ---------------------
+  stream_event: {
+    lane: 'delta',
+    note: 'the incremental lane — text_delta, thinking_delta, input_json_delta, and the block start/stop markers around them. Every fragment is superseded by the assistant message that settles it, so a lost one costs a repaint. Exists at all only under includePartialMessages.',
+  },
+  'system/thinking_tokens': {
+    lane: 'delta',
+    note: 'a running thinking-token estimate, emitted per thinking delta. Its own docs call it approximate progress for spinners rather than the billed count, and the next one supersedes it.',
+  },
+  'system/status': {
+    lane: 'delta',
+    note: 'the requesting/compacting ticker. Each value supersedes the last and the transition it causes is the durable record; this lane exists so a view can show the spinner without waiting for one.',
+  },
+  tool_progress: {
+    lane: 'delta',
+    note: 'elapsed seconds for a running tool call, re-emitted while it runs. Superseded by the next tick and finally by the tool closing.',
+  },
+  'system/task_progress': {
+    lane: 'delta',
+    note: 'progress for a background task, re-emitted while it runs. Same shape as tool_progress and superseded the same way.',
+  },
+  'system/hook_progress': {
+    lane: 'delta',
+    note: 'progress while a hook handler runs — a ticker, superseded by the hook resolving.',
+  },
+
+  // --- update: facts of the turn that nothing later restates -----------------
+  'system/init': {
+    lane: 'update',
+    note: 'the per-spawn receipt — session id, CLI version, model, tool/skill/plugin inventory, apiKeySource. It arrives once and nothing restates it.',
+  },
+  assistant: {
+    lane: 'update',
+    note: 'the settled assistant message. The fact the deltas were fragments of; a consumer with no delta lane still renders a turn from these.',
+  },
+  user: {
+    lane: 'update',
+    note: "tool results — that is what this row carries in practice. Observed on a live session: the queued prompt does not come back on the output stream for this host's input lane, so no SDKUserMessageReplay arrives to deduplicate against. This host still synthesizes no user echo of its own, because the controller queued the prompt and already holds the operator's turn — a synthesized event would be a second name for it.",
+  },
+  result: {
+    lane: 'update',
+    note: "the turn's outcome, and the telemetry that arrives with it: total_cost_usd, modelUsage[].costUSD per model, permission_denials, ttft_ms, user_message_uuid and terminal_reason (19 values). Forwarded whole so the layer that owns cost consumes these rather than re-deriving them.",
+  },
+  rate_limit_event: {
+    lane: 'update',
+    note: 'rate-limit state with resetsAt and utilization, in-stream. Losing one loses a reset time nothing else carries.',
+  },
+  'system/compact_boundary': {
+    lane: 'update',
+    note: 'compaction happened and this is where. A durable fact about the transcript, and the boundary anything reading history has to know about.',
+  },
+  'system/api_retry': {
+    lane: 'update',
+    note: 'a request failed and is being retried. Nothing else carries it, and an unattended run that is quietly retrying looks identical to one that is thinking.',
+  },
+  'system/model_refusal_fallback': {
+    lane: 'update',
+    note: 'the model refused and a fallback ran. The counterpart of model_refusal_no_fallback, which moves the machine; this one does not, so forwarding is the only way the fact travels.',
+  },
+  'system/model_refusal_no_fallback': {
+    lane: 'update',
+    note: 'the model refused and nothing ran. It also causes a transition, but the message names the original model, which the transition does not.',
+  },
+  'system/local_command_output': {
+    lane: 'update',
+    note: 'output of a local command, which is content a consumer renders. Not restated anywhere.',
+  },
+  'system/session_state_changed': {
+    lane: 'declined',
+    note: 'its entire content is state: idle|running|requires_action, and the transition it causes carries exactly that in `to`. Forwarding it too would put two names for one fact on the wire — the reason session_started and session_ended were removed from the payload kinds.',
+  },
+  'system/task_started': {
+    lane: 'update',
+    note: 'the only message carrying task_id AND tool_use_id together — the join a consumer needs to attribute later task reports. The transition lane deliberately records nothing here.',
+  },
+  'system/task_updated': {
+    lane: 'update',
+    note: 'a task changed status or was backgrounded. It causes a transition, and it also carries the patch itself, which the transition does not.',
+  },
+  'system/task_notification': {
+    lane: 'update',
+    note: 'a background task finished and says how. Causes a transition; the message carries the status text.',
+  },
+  'system/background_tasks_changed': {
+    lane: 'update',
+    note: 'the set of background tasks changed. Nothing else enumerates them, and a session whose work moved to the background is the case this whole split exists for.',
+  },
+  'system/worker_shutting_down': {
+    lane: 'update',
+    note: 'the worker is going away, with its reason. Causes a transition; the reason is worth carrying verbatim.',
+  },
+  'system/permission_denied': {
+    lane: 'update',
+    note: "the SDK's own auto-deny short-circuit — a different path from this host's gate, which the SDK's docs say explicitly does not produce this message. Nothing this package emits restates it.",
+  },
+  'system/elicitation_complete': {
+    lane: 'update',
+    note: 'an MCP elicitation resolved, with what it resolved to. The transition records the exit; the answer rides here.',
+  },
+  'system/plugin_install': {
+    lane: 'update',
+    note: 'a plugin was installed mid-session, so the inventory init reported is now stale. Nothing else says so.',
+  },
+  'system/commands_changed': {
+    lane: 'update',
+    note: 'the available command set changed. init carries the opening inventory and this carries the change; a consumer showing commands has no other source.',
+  },
+  'system/notification': {
+    lane: 'update',
+    note: 'a notification aimed at whoever is watching. Withholding it would be this host deciding what a controller finds worth showing.',
+  },
+  'system/memory_recall': {
+    lane: 'update',
+    note: 'what the agent recalled and used. Content, and part of explaining a turn a reader is trying to understand.',
+  },
+  'system/mirror_error': {
+    lane: 'update',
+    note: 'a mirror write failed. A degrade is a named outcome and never a silent pass, so it goes on the wire even though this host takes no action on it.',
+  },
+  'system/informational': {
+    lane: 'update',
+    note: "an informational message from the agent. Forwarded for the same reason as notification: the judgement is the controller's.",
+  },
+  tool_use_summary: {
+    lane: 'update',
+    note: 'a settled summary of a tool call — what a cold reader sees instead of raw arguments.',
+  },
+  auth_status: {
+    lane: 'update',
+    note: 'the credential state changed under a running session. An unattended run whose auth lapsed must not look like one that went quiet.',
+  },
+  prompt_suggestion: {
+    lane: 'update',
+    note: "a suggested next turn. Product surface, and whether to show it is the controller's call rather than this host's.",
+  },
+  conversation_reset: {
+    lane: 'update',
+    note: 'the conversation was reset, so everything a consumer has accumulated for this session is now history rather than context.',
+  },
+
+  // --- declined: the fact reaches the wire another way, or it is the host's own ---
+  'system/control_request_progress': {
+    lane: 'declined',
+    note: "progress on the SDK's internal control protocol between this host and its own CLI subprocess. It describes the host's transport, not the session, and a controller can do nothing with it.",
+  },
+  'system/hook_started': {
+    lane: 'declined',
+    note: "reports one of this host's own hooks starting. Forwarding it would echo the observer and the gate back at the controller that configured them. The gate's outcomes are recorded as transitions in the machine, and forwardSession's machine subscription carries every recorded transition to the wire whatever caused it — so this message would arrive as a second copy of a fact the transition already states.",
+  },
+  'system/hook_response': {
+    lane: 'declined',
+    note: "the answer this host's own hook just returned. Same echo reason as hook_started — and the decision's transition already rides the wire via the machine subscription, so re-reporting the answer here would invite a consumer to count one decision twice.",
+  },
+  'system/files_persisted': {
+    lane: 'declined',
+    note: 'a checkpointing receipt. It belongs to the layer that owns the receipt read path, which reads local records rather than the live stream.',
+  },
+} as const satisfies Record<MessageDiscriminator, RoutingRow>;
+
+/** The lane one message rides. Total by construction — every discriminator has a row. */
+export function laneFor(message: SDKMessage): StreamLane {
+  return MESSAGE_ROUTING[discriminatorOf(message)].lane;
+}
+
+/** Every discriminator on one lane, in declaration order. The subject of the routing pin. */
+export function discriminatorsOn(lane: StreamLane): MessageDiscriminator[] {
+  return (Object.keys(MESSAGE_ROUTING) as MessageDiscriminator[]).filter(
+    (key) => MESSAGE_ROUTING[key].lane === lane,
+  );
+}