@naswerks/periscope 1.0.0 → 1.0.1

package/src/state/store.ts

@@ -0,0 +1,157 @@
+/**
+ * Where recorded transitions are kept, and where anyone asking "what happened?" reads from.
+ *
+ * Separate from the machine on purpose. A machine that both emitted and answered questions about
+ * itself would let a test prove emission by asking the thing that emitted — the assertion and the
+ * subject would be the same object. This subscribes, so "no transition without a cause" is checked
+ * against what was actually retained rather than against what a call site claims it passed.
+ *
+ * Bounded, in memory, and not durable. It holds a window per session so a long-running host does
+ * not grow without limit; durability of the transition log belongs to the persistence layer, and
+ * this deliberately does not pretend to be it. `dropped` counts what fell out of the window rather
+ * than letting a full ring look like a quiet one.
+ */
+import type { SessionTransition } from './model.js';
+import type { RejectedTransition, SessionStateMachine, Unsubscribe } from './machine.js';
+
+/** Per session. A session that outruns this loses its oldest transitions, and says how many. */
+const DEFAULT_WINDOW = 500;
+
+export interface TransitionStoreOptions {
+  readonly windowPerSession?: number;
+}
+
+/** Keyed while a session has no id yet — see SessionTransition.sessionId. */
+const UNIDENTIFIED = '(unidentified)';
+
+export class TransitionStore {
+  readonly #window: number;
+  readonly #bySession = new Map<string, SessionTransition[]>();
+  readonly #rejected: RejectedTransition[] = [];
+  #dropped = 0;
+  #droppedRejections = 0;
+
+  constructor(options: TransitionStoreOptions = {}) {
+    this.#window = options.windowPerSession ?? DEFAULT_WINDOW;
+  }
+
+  /**
+   * Retain everything one machine records, and everything it refuses.
+   *
+   * Both halves matter: a store that kept only the successes would answer "were all transitions
+   * caused?" with a yes it earned by discarding the counter-examples.
+   */
+  attach(machine: SessionStateMachine): Unsubscribe {
+    const dropTransitions = machine.onTransition((transition) => this.#retain(transition));
+    const dropRejections = machine.onRejected((rejected) => {
+      // Bounded on the same terms as the transitions, and for the same reason: a rejection arrives
+      // from whatever drives the machine, and once that is a wire path the rate is a stranger's to
+      // set. An uncapped array beside a capped ring would make the counter-examples the thing that
+      // grows without limit — the one collection nobody thinks to watch.
+      this.#rejected.push(rejected);
+      while (this.#rejected.length > this.#window) {
+        this.#rejected.shift();
+        this.#droppedRejections += 1;
+      }
+    });
+    return () => {
+      dropTransitions();
+      dropRejections();
+    };
+  }
+
+  /**
+   * One session's transitions, oldest first.
+   *
+   * Transitions recorded before the agent named itself are re-keyed when it does. They were
+   * genuinely recorded without an id — that window is real — but leaving them in a separate bucket
+   * would mean the trace of a session's own start could not be read by that session's id, which is
+   * the one thing a reader has.
+   */
+  forSession(sessionId: string): readonly SessionTransition[] {
+    return this.#bySession.get(sessionId) ?? [];
+  }
+
+  /** Transitions recorded while no session had reported itself yet, across every machine. */
+  unidentified(): readonly SessionTransition[] {
+    return this.#bySession.get(UNIDENTIFIED) ?? [];
+  }
+
+  /** Everything retained, across every session. The subject of the store-level assertions. */
+  all(): SessionTransition[] {
+    return [...this.#bySession.values()].flat();
+  }
+
+  sessionIds(): string[] {
+    return [...this.#bySession.keys()].filter((key) => key !== UNIDENTIFIED);
+  }
+
+  /** Every refused transition still held, with why. Never summarised into a count alone. */
+  rejected(): readonly RejectedTransition[] {
+    return this.#rejected;
+  }
+
+  /** How many transitions fell out of a window. A full ring must not read as a quiet one. */
+  get droppedCount(): number {
+    return this.#dropped;
+  }
+
+  /**
+   * How many rejections fell out of their window.
+   *
+   * Counted separately from `droppedCount` because the two mean opposite things: transitions
+   * falling out is an ordinary busy session, rejections falling out means something is refusing
+   * faster than anyone is reading, and collapsing them into one number would hide that.
+   */
+  get droppedRejectionCount(): number {
+    return this.#droppedRejections;
+  }
+
+  #retain(transition: SessionTransition): void {
+    const key = transition.sessionId ?? UNIDENTIFIED;
+    this.#adopt(transition);
+
+    const kept = this.#bySession.get(key) ?? [];
+    kept.push(transition);
+    while (kept.length > this.#window) {
+      kept.shift();
+      this.#dropped += 1;
+    }
+    this.#bySession.set(key, kept);
+  }
+
+  /** Move this machine's earlier, id-less transitions under the id it has just reported. */
+  #adopt(transition: SessionTransition): void {
+    const id = transition.sessionId;
+    if (id === null) return;
+
+    const orphans = this.#bySession.get(UNIDENTIFIED);
+    if (orphans === undefined) return;
+
+    // Only this machine's own: an id-less transition belongs to whichever machine produced the
+    // seq series it sits in, and a machine's seq is dense from 1. Anything at or above this
+    // transition's own seq cannot be its predecessor.
+    const mine = orphans.filter((orphan) => orphan.seq < transition.seq && sameOrigin(orphan, transition));
+    if (mine.length === 0) return;
+
+    this.#bySession.set(
+      UNIDENTIFIED,
+      orphans.filter((orphan) => !mine.includes(orphan)),
+    );
+    const kept = this.#bySession.get(id) ?? [];
+    this.#bySession.set(id, [...mine, ...kept]);
+  }
+}
+
+/**
+ * Whether two transitions came from the same machine, without either carrying a machine id.
+ *
+ * `where` is per-machine and fixed for its lifetime, and `correlationId` is whatever the controller
+ * supplied for that one session — so together they distinguish two concurrent id-less starts unless
+ * a controller starts two sessions in the same directory with no correlation id, in which case
+ * their early transitions are genuinely indistinguishable and both are adopted. That is a truthful
+ * outcome rather than a wrong one: nothing is lost, and nothing is invented to prevent it.
+ */
+function sameOrigin(left: SessionTransition, right: SessionTransition): boolean {
+  return left.correlationId === right.correlationId && left.where.cwd === right.where.cwd;
+}

package/src/telemetry/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Usage, cost and rate-limit facts — consumed from what the agent reports, never recomputed.
+ *
+ * There is no price table in this package and there must not be one. The agent reports a cost per
+ * model, with the provider and the id it priced against, so a mixed-model turn is correct without
+ * this host knowing any rate. A table would be wrong twice over and silently: stale the moment a
+ * price moves, and blind to a turn that used more than one model.
+ */
+export type { ModelSpend, RateLimitStanding, SpendTotal, TurnSpend } from './usage.js';
+export { NO_SPEND, foldSpend, spendReconciles } from './usage.js';

package/src/telemetry/usage.ts

@@ -0,0 +1,117 @@
+/**
+ * What a turn cost — consumed from what the agent reports, never computed from a price table.
+ *
+ * The whole point is that nothing here multiplies tokens by a rate. A host that keeps a per-model
+ * price table and does the arithmetic itself has two failure modes, and both are silent: a price
+ * changes and every historical figure is quietly wrong, and a mixed-model turn is costed at one
+ * model's rate because the table is keyed by "the session's model". The agent already reports a
+ * per-model cost, with the provider and the canonical id it priced against. So this reads.
+ *
+ * How that is actually proven, because "it only reads" is easy to claim and easy to regress: the
+ * tests feed a cost no price table could ever produce and assert it comes out unchanged. A
+ * reimplementation that started computing would have to reproduce an arbitrary number to stay green.
+ *
+ * No SDK types here. This is the model the layer above works in; `host/telemetry.ts` lifts it off
+ * the agent's own result message, the same way `readInitFacts` lifts the version receipt.
+ */
+
+/** What one model cost within a turn. Every number is reported, none derived. */
+export interface ModelSpend {
+  /** The model string the agent was keyed by — provider-specific ids and aliases included. */
+  readonly model: string;
+  readonly costUsd: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly cacheReadInputTokens: number;
+  readonly cacheCreationInputTokens: number;
+  /** The window this model was serving with. Absent is null, never zero. */
+  readonly contextWindow: number | null;
+  /** The id the agent priced against, when it differs from `model`. */
+  readonly canonicalModel: string | null;
+  /** Which API served it, when reported. */
+  readonly provider: string | null;
+}
+
+/** One turn's spend. */
+export interface TurnSpend {
+  /** The agent's own total. Not the sum of `byModel` — see `spendReconciles`. */
+  readonly totalCostUsd: number;
+  readonly byModel: readonly ModelSpend[];
+}
+
+/** Spend accumulated across turns. */
+export interface SpendTotal {
+  readonly totalCostUsd: number;
+  readonly turnCount: number;
+  /** Per model, summed across every turn folded in. */
+  readonly byModel: readonly ModelSpend[];
+}
+
+export const NO_SPEND: SpendTotal = { totalCostUsd: 0, turnCount: 0, byModel: [] };
+
+/**
+ * Add one turn to a running total.
+ *
+ * Models are merged by their reported key, not by the canonical id. Two entries keyed differently
+ * that price against one canonical model are genuinely two things the agent distinguished — an alias
+ * and a provider-specific id can bill differently — and collapsing them here would throw away the
+ * distinction the report was making.
+ */
+export function foldSpend(prev: SpendTotal, turn: TurnSpend): SpendTotal {
+  const byModel = new Map<string, ModelSpend>();
+  for (const spend of prev.byModel) byModel.set(spend.model, spend);
+
+  for (const spend of turn.byModel) {
+    const existing = byModel.get(spend.model);
+    byModel.set(
+      spend.model,
+      existing === undefined
+        ? spend
+        : {
+            ...existing,
+            costUsd: existing.costUsd + spend.costUsd,
+            inputTokens: existing.inputTokens + spend.inputTokens,
+            outputTokens: existing.outputTokens + spend.outputTokens,
+            cacheReadInputTokens: existing.cacheReadInputTokens + spend.cacheReadInputTokens,
+            cacheCreationInputTokens: existing.cacheCreationInputTokens + spend.cacheCreationInputTokens,
+            // Last report wins: these describe the model, not the usage, and the newest is truest.
+            contextWindow: spend.contextWindow ?? existing.contextWindow,
+            canonicalModel: spend.canonicalModel ?? existing.canonicalModel,
+            provider: spend.provider ?? existing.provider,
+          },
+    );
+  }
+
+  return {
+    totalCostUsd: prev.totalCostUsd + turn.totalCostUsd,
+    turnCount: prev.turnCount + 1,
+    byModel: [...byModel.values()],
+  };
+}
+
+/**
+ * Whether a turn's per-model costs add up to the total the agent reported.
+ *
+ * It is an observation, not a validation, and must not become one. Both numbers come from the
+ * agent; a mismatch means the agent counted something the per-model breakdown does not itemise, and
+ * that is the agent's business rather than a defect this host should refuse over. The reason to
+ * expose it is that a caller charging money wants to know which of the two it is quoting, and
+ * whether they agree.
+ *
+ * @param toleranceUsd absolute, because these are floats and an exact comparison would fail on
+ *                     arithmetic that is otherwise perfectly correct.
+ */
+export function spendReconciles(turn: TurnSpend, toleranceUsd = 1e-9): boolean {
+  const summed = turn.byModel.reduce((total, spend) => total + spend.costUsd, 0);
+  return Math.abs(summed - turn.totalCostUsd) <= toleranceUsd;
+}
+
+/** How a rate limit currently stands, as the agent reports it. */
+export interface RateLimitStanding {
+  readonly status: 'allowed' | 'allowed_warning' | 'rejected';
+  /** Epoch seconds, as reported. Null when the agent did not say. */
+  readonly resetsAt: number | null;
+  readonly limitType: string | null;
+  /** 0–1 where reported, else null. Never defaulted to 0 — that would read as "plenty left". */
+  readonly utilization: number | null;
+}