@moxxy/sdk 0.14.4 → 0.14.5

package/dist/server.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Node-runtime-only surface of @moxxy/sdk.
+ *
+ * Importing `@moxxy/sdk/server` pulls in the value helpers that statically
+ * depend on Node builtins (`node:child_process`, `node:fs`, `node:os`,
+ * `node:http`, `node:crypto`, `node:path`). The MAIN barrel (`@moxxy/sdk`) is
+ * deliberately kept free of these so a browser/React-Native bundle can value-
+ * import from it (and from `@moxxy/sdk/tool-display`) without dragging a Node
+ * builtin into the bundle — Metro cannot polyfill `node:child_process`.
+ *
+ * Node-side consumers (cli, runner, desktop-host, channel/oauth/webhooks
+ * plugins, …) import these helpers from here. The corresponding *type* exports
+ * (e.g. `TunnelHandle`, `WriteFileAtomicOptions`, `ChannelTokenOptions`) remain
+ * on the main barrel because types are erased at build time and never reach a
+ * bundle.
+ */
+export { spawnCliTunnel, isCliTunnelAvailable } from './tunnel.js';
+export { writeFileAtomic, writeFileAtomicSync, moxxyHome, moxxyPath, } from './fs-utils.js';
+export { readRequestBody, bearerTokenMatches } from './http-utils.js';
+export { resolveChannelToken, rotateChannelToken, bearerGuard, encodeWsBearerProtocol, tokenFromWsProtocolHeader, MOXXY_WS_SUBPROTOCOL, MOXXY_WS_BEARER_PROTOCOL_PREFIX, } from './channel-auth.js';
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,SAAS,EACT,SAAS,GACV,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,sBAAsB,EACtB,yBAAyB,EACzB,oBAAoB,EACpB,+BAA+B,GAChC,MAAM,mBAAmB,CAAC"}

package/dist/server.js

@@ -0,0 +1,21 @@
+/**
+ * Node-runtime-only surface of @moxxy/sdk.
+ *
+ * Importing `@moxxy/sdk/server` pulls in the value helpers that statically
+ * depend on Node builtins (`node:child_process`, `node:fs`, `node:os`,
+ * `node:http`, `node:crypto`, `node:path`). The MAIN barrel (`@moxxy/sdk`) is
+ * deliberately kept free of these so a browser/React-Native bundle can value-
+ * import from it (and from `@moxxy/sdk/tool-display`) without dragging a Node
+ * builtin into the bundle — Metro cannot polyfill `node:child_process`.
+ *
+ * Node-side consumers (cli, runner, desktop-host, channel/oauth/webhooks
+ * plugins, …) import these helpers from here. The corresponding *type* exports
+ * (e.g. `TunnelHandle`, `WriteFileAtomicOptions`, `ChannelTokenOptions`) remain
+ * on the main barrel because types are erased at build time and never reach a
+ * bundle.
+ */
+export { spawnCliTunnel, isCliTunnelAvailable } from './tunnel.js';
+export { writeFileAtomic, writeFileAtomicSync, moxxyHome, moxxyPath, } from './fs-utils.js';
+export { readRequestBody, bearerTokenMatches } from './http-utils.js';
+export { resolveChannelToken, rotateChannelToken, bearerGuard, encodeWsBearerProtocol, tokenFromWsProtocolHeader, MOXXY_WS_SUBPROTOCOL, MOXXY_WS_BEARER_PROTOCOL_PREFIX, } from './channel-auth.js';
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,SAAS,EACT,SAAS,GACV,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,sBAAsB,EACtB,yBAAyB,EACzB,oBAAoB,EACpB,+BAA+B,GAChC,MAAM,mBAAmB,CAAC"}

package/dist/transcriber.d.ts

@@ -17,6 +17,19 @@
  *   - `ContentBlock` with `type: 'audio'` — provider-level wire format, only
  *     used by models that advertise `supportsAudio: true`.
  */
+/**
+ * Wire MIME tag for raw 16-bit little-endian PCM mono at 24 kHz — the lossless
+ * format the desktop/web mic capture path produces and that the Codex
+ * transcriber keys on to wrap the bytes in a WAV header before upload.
+ *
+ * This is a cross-package PROTOCOL value: client-platform-web stamps it onto
+ * the captured blob, plugin-cli forwards it as the attachment `mimeType`, and
+ * plugin-stt-whisper switches on it. It lived as an independently-redeclared
+ * literal in all three (silent transcription breakage if any drifted), so it is
+ * hoisted here to the SDK's single zero-dep typed surface as the source of
+ * truth. Consumers should import this rather than re-spell the literal.
+ */
+export declare const MOXXY_PCM16_24KHZ_MIME = "audio/x-moxxy-pcm16-24khz";
 export interface TranscriptionSegment {
     /** Segment start, in seconds from the start of the clip. */
     readonly start: number;

package/dist/transcriber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transcriber.d.ts","sourceRoot":"","sources":["../src/transcriber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,UAAU,CACR,KAAK,EAAE,UAAU,GAAG,WAAW,EAC/B,IAAI,CAAC,EAAE,iBAAiB,GACvB,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC;CAC5D"}
+{"version":3,"file":"transcriber.d.ts","sourceRoot":"","sources":["../src/transcriber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,8BAA8B,CAAC;AAElE,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,UAAU,CACR,KAAK,EAAE,UAAU,GAAG,WAAW,EAC/B,IAAI,CAAC,EAAE,iBAAiB,GACvB,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC;CAC5D"}

package/dist/transcriber.js

@@ -17,5 +17,17 @@
  *   - `ContentBlock` with `type: 'audio'` — provider-level wire format, only
  *     used by models that advertise `supportsAudio: true`.
  */
-export {};
+/**
+ * Wire MIME tag for raw 16-bit little-endian PCM mono at 24 kHz — the lossless
+ * format the desktop/web mic capture path produces and that the Codex
+ * transcriber keys on to wrap the bytes in a WAV header before upload.
+ *
+ * This is a cross-package PROTOCOL value: client-platform-web stamps it onto
+ * the captured blob, plugin-cli forwards it as the attachment `mimeType`, and
+ * plugin-stt-whisper switches on it. It lived as an independently-redeclared
+ * literal in all three (silent transcription breakage if any drifted), so it is
+ * hoisted here to the SDK's single zero-dep typed surface as the source of
+ * truth. Consumers should import this rather than re-spell the literal.
+ */
+export const MOXXY_PCM16_24KHZ_MIME = 'audio/x-moxxy-pcm16-24khz';
 //# sourceMappingURL=transcriber.js.map

package/dist/transcriber.js.map

@@ -1 +1 @@
-{"version":3,"file":"transcriber.js","sourceRoot":"","sources":["../src/transcriber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}
+{"version":3,"file":"transcriber.js","sourceRoot":"","sources":["../src/transcriber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,2BAA2B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moxxy/sdk",
-  "version": "0.14.4",
+  "version": "0.14.5",
   "description": "Typed public surface for the moxxy framework: event types, define* factories, lifecycle hook signatures.",
   "keywords": [
     "moxxy",
@@ -45,9 +45,17 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
     "./tool-display": {
       "types": "./dist/tool-display.d.ts",
       "import": "./dist/tool-display.js"
+    },
+    "./transcriber": {
+      "types": "./dist/transcriber.d.ts",
+      "import": "./dist/transcriber.js"
     }
   },
   "files": [

package/src/compactor-helpers.test.ts

@@ -9,6 +9,7 @@ import {
   isContextOverflowError,
   runCompactionIfNeeded,
   runElisionIfNeeded,
+  runManualCompaction,
   type CompactorDef,
   type EmittedEvent,
   type EventLogReader,
@@ -298,6 +299,111 @@ describe('runCompactionIfNeeded', () => {
   });
 });
 
+describe('runManualCompaction', () => {
+  // An appendable reader matching ManualCompactionInput.log — records the
+  // appended event so we can assert defensive identity-fill.
+  function appendableLog(seed: ReadonlyArray<MoxxyEvent>): EventLogReader & {
+    append(event: EmittedEvent): Promise<MoxxyEvent>;
+    appended: EmittedEvent[];
+  } {
+    const events = [...seed];
+    const appended: EmittedEvent[] = [];
+    return {
+      ...reader(events),
+      appended,
+      append: async (e: EmittedEvent) => {
+        appended.push(e);
+        const mat = { ...e, id: asEventId(`a${appended.length}`), seq: events.length, ts: events.length, sessionId: sid } as MoxxyEvent;
+        events.push(mat);
+        return mat;
+      },
+    };
+  }
+
+  const seed: MoxxyEvent[] = [
+    event(0, { type: 'user_prompt', turnId: tid, source: 'user', text: 'x'.repeat(400) }),
+    event(1, { type: 'assistant_message', turnId: tid, source: 'model', content: 'y'.repeat(400), stopReason: 'end_turn' }),
+  ];
+
+  it('returns the no-op result for an empty log', async () => {
+    const log = appendableLog([]);
+    const compactor: CompactorDef = {
+      name: 'never',
+      shouldCompact: () => false,
+      compact: async () => { throw new Error('should not run'); },
+    };
+    const res = await runManualCompaction({ compactor, log });
+    expect(res).toEqual({ compacted: false, tokensSaved: 0, eventsCompacted: 0 });
+    expect(log.appended).toHaveLength(0);
+  });
+
+  it('compacts unconditionally (no shouldCompact gate) and reports counts', async () => {
+    const log = appendableLog(seed);
+    const shouldCompact = vi.fn().mockReturnValue(false); // would block the auto path
+    const compactor: CompactorDef = {
+      name: 'fake',
+      shouldCompact,
+      compact: async () => ({
+        type: 'compaction',
+        compactor: 'fake',
+        replacedRange: [0, 1],
+        summary: 'compressed',
+        tokensSaved: 123,
+      }),
+    };
+    const res = await runManualCompaction({ compactor, log });
+    // shouldCompact is NEVER consulted — manual compaction always runs.
+    expect(shouldCompact).not.toHaveBeenCalled();
+    expect(res).toEqual({ compacted: true, tokensSaved: 123, eventsCompacted: 2 });
+    expect(log.appended).toHaveLength(1);
+    // Defensive identity fill from the log tail + source=compactor.
+    expect(log.appended[0]).toMatchObject({ type: 'compaction', source: 'compactor', sessionId: sid, turnId: tid });
+  });
+
+  it('counts only events inside the inclusive replacedRange, not the seq span', async () => {
+    // A range [0, 999] spanning a gap: only the two real events fall inside.
+    const log = appendableLog([
+      event(0, { type: 'user_prompt', turnId: tid, source: 'user', text: 'x'.repeat(400) }),
+      event(500, { type: 'assistant_message', turnId: tid, source: 'model', content: 'z'.repeat(400), stopReason: 'end_turn' }),
+    ]);
+    const compactor: CompactorDef = {
+      name: 'wide',
+      shouldCompact: () => false,
+      compact: async () => ({
+        type: 'compaction', compactor: 'wide', replacedRange: [0, 999], summary: 's', tokensSaved: 50,
+      }),
+    };
+    const res = await runManualCompaction({ compactor, log });
+    expect(res.eventsCompacted).toBe(2);
+  });
+
+  it('reports no-op (no append) when the summary is empty / tokensSaved <= 0', async () => {
+    const log = appendableLog(seed);
+    const compactor: CompactorDef = {
+      name: 'empty',
+      shouldCompact: () => true,
+      compact: async () => ({
+        type: 'compaction', compactor: 'empty', replacedRange: [0, 1], summary: '   ', tokensSaved: 0,
+      }),
+    };
+    const res = await runManualCompaction({ compactor, log });
+    expect(res.compacted).toBe(false);
+    expect(log.appended).toHaveLength(0);
+  });
+
+  it('caller-supplied sessionId/turnId override the log-tail fallback', async () => {
+    const log = appendableLog(seed);
+    const compactor: CompactorDef = {
+      name: 'fake', shouldCompact: () => false,
+      compact: async () => ({ type: 'compaction', compactor: 'fake', replacedRange: [0, 1], summary: 'ok', tokensSaved: 10 }),
+    };
+    await runManualCompaction({
+      compactor, log, sessionId: asSessionId('other'), turnId: asTurnId('explicit'),
+    });
+    expect(log.appended[0]).toMatchObject({ sessionId: 'other', turnId: 'explicit' });
+  });
+});
+
 describe('isContextOverflowError', () => {
   it('matches common provider context-overflow phrasings', () => {
     for (const msg of [

package/src/compactor-helpers.ts

@@ -7,9 +7,11 @@ import {
   toolResultStubbed,
   type ElisionState,
 } from './elision-state.js';
+import type { CompactorDef, TokenBudget } from './compactor.js';
 import type { EmittedEvent, MoxxyEvent } from './events.js';
 import type { EventLogReader } from './log.js';
 import type { ModeContext } from './mode.js';
+import type { LLMProvider } from './provider.js';
 
 /**
  * Cheap, no-network estimate of how many tokens the current event log
@@ -168,9 +170,15 @@ export async function runCompactionIfNeeded(
   const events = ctx.log.slice();
   if (events.length === 0) return false;
 
+  // Derive the elision state ONCE for this snapshot and thread it into the
+  // estimate — `computeElisionState` is memoized on the log version, but
+  // threading skips even the memo lookup and guarantees the estimate folds the
+  // exact same state the rest of this iteration uses.
+  const elisionState = computeElisionState(events);
+
   const budget = {
     contextWindow: resolved?.contextWindow ?? Number.MAX_SAFE_INTEGER,
-    estimatedTokens: estimateContextTokens(ctx.log),
+    estimatedTokens: estimateContextTokens(ctx.log, elisionState),
     reserveForOutput: resolved?.reserveForOutput ?? 0,
   } as const;
 
@@ -233,6 +241,122 @@ export async function runCompactionIfNeeded(
   }
 }
 
+/**
+ * Outcome of {@link runManualCompaction}. `compacted` is false (with the other
+ * counts at 0) whenever there was nothing to compact — empty log, no usable
+ * summary, or `tokensSaved <= 0` — so a caller can format "nothing to compact"
+ * vs "compacted N events" without re-deriving the gate.
+ */
+export interface ManualCompactionResult {
+  /** Did a CompactionEvent get appended? */
+  readonly compacted: boolean;
+  /** Estimated tokens the summary saves vs the replaced range. */
+  readonly tokensSaved: number;
+  /** Count of events whose `seq` fell inside the (inclusive) replaced range. */
+  readonly eventsCompacted: number;
+}
+
+const NO_COMPACTION: ManualCompactionResult = {
+  compacted: false,
+  tokensSaved: 0,
+  eventsCompacted: 0,
+};
+
+/**
+ * Shape a manual `/compact` needs from the session, kept structural so callers
+ * (plugin-commands) stay free of a `@moxxy/core` dependency — the host always
+ * passes a real Session that satisfies it. Mirrors the fields
+ * {@link runCompactionIfNeeded} reads off `ModeContext`, but log-first because
+ * a manual compaction has no live turn/mode context.
+ */
+export interface ManualCompactionInput {
+  readonly compactor: CompactorDef;
+  /** Authoring log the CompactionEvent is appended to. */
+  readonly log: EventLogReader & {
+    append(event: EmittedEvent): Promise<MoxxyEvent>;
+  };
+  /** Active provider/model so the default compactor writes a real summary. */
+  readonly provider?: LLMProvider;
+  readonly model?: string;
+  /** Active model's resolved context window (for `shouldCompact`). */
+  readonly contextWindow?: number;
+  readonly reserveForOutput?: number;
+  /** Cancellation signal; a fresh one is used when omitted. */
+  readonly signal?: AbortSignal;
+  /** Override the appended event's sessionId/turnId (else taken from the log tail). */
+  readonly sessionId?: string;
+  readonly turnId?: string;
+}
+
+/**
+ * Run ONE compaction now, unconditionally (the `/compact` command's force
+ * semantics — the threshold gate is skipped). The single shared implementation
+ * of the manual-compaction flow that `compactSession` in `@moxxy/plugin-commands`
+ * used to hand-roll: build the {@link TokenBudget} (with the same `estimate`
+ * + context-window fallback as the auto path), call `compactor.compact`, guard
+ * on an empty/zero-saving result, defensively fill the event's
+ * sessionId/turnId/source, append it, and report `{ compacted, tokensSaved,
+ * eventsCompacted }` so the caller only formats the message.
+ *
+ * Distinct from {@link runCompactionIfNeeded}, which is the per-iteration
+ * auto-compaction hook bound to a live `ModeContext` and gated by
+ * `shouldCompact` (unless forced). This one is log-first and always runs,
+ * matching how a user-invoked `/compact` works. Errors propagate to the caller
+ * (the command formats them); a no-op returns {@link NO_COMPACTION}.
+ */
+export async function runManualCompaction(
+  input: ManualCompactionInput,
+): Promise<ManualCompactionResult> {
+  const { compactor, log } = input;
+  const events = log.slice();
+  if (events.length === 0) return NO_COMPACTION;
+
+  // Match the auto path's window fallback: an unresolved window degrades to
+  // MAX_SAFE_INTEGER (manual compaction ignores the threshold anyway).
+  const contextWindow =
+    input.contextWindow && input.contextWindow > 0
+      ? input.contextWindow
+      : Number.MAX_SAFE_INTEGER;
+  const budget: TokenBudget = {
+    contextWindow,
+    estimatedTokens: estimateContextTokens(log),
+    reserveForOutput: input.reserveForOutput ?? 0,
+  };
+
+  const result = await compactor.compact(events, {
+    log,
+    budget,
+    signal: input.signal ?? new AbortController().signal,
+    ...(input.provider ? { provider: input.provider } : {}),
+    ...(input.model !== undefined ? { model: input.model } : {}),
+  });
+  if (result.tokensSaved <= 0 || result.summary.trim().length === 0) {
+    return NO_COMPACTION;
+  }
+
+  // Defensive-fill identity fields a spec-compliant compactor may omit
+  // (`compact` declares `Omit<CompactionEvent, keyof EventBase>`). The
+  // compactor's own values win (result spreads last). Mirrors
+  // `runCompactionIfNeeded`.
+  const lastEvent = events[events.length - 1];
+  const emittable: EmittedEvent = {
+    sessionId: input.sessionId ?? lastEvent?.sessionId,
+    turnId: input.turnId ?? lastEvent?.turnId,
+    source: 'compactor',
+    ...result,
+  } as EmittedEvent;
+  await log.append(emittable);
+
+  // `replacedRange` is an INCLUSIVE [fromSeq, toSeq] of event `seq` VALUES, not
+  // array indices — and `seq === arrayIndex` is not guaranteed for
+  // mirrors/partial views. Count the events actually inside the range rather
+  // than differencing the seqs (which would overstate across any seq gap).
+  const [fromSeq, toSeq] = result.replacedRange;
+  const eventsCompacted = events.filter((e) => e.seq >= fromSeq && e.seq <= toSeq).length;
+
+  return { compacted: true, tokensSaved: result.tokensSaved, eventsCompacted };
+}
+
 /**
  * Heuristic: does this provider error mean "the request was too big for the
  * model's context window"? Providers phrase it many ways (OpenAI "maximum

package/src/elision-helpers.ts

@@ -1,5 +1,5 @@
 import { estimateContextTokens, resolveModelContext } from './compactor-helpers.js';
-import { toolResultBytes } from './elision-state.js';
+import { computeElisionState, toolResultBytes } from './elision-state.js';
 import type { EmittedEvent, MoxxyEvent } from './events.js';
 import type { ElisionSettings, ModeContext } from './mode.js';
 
@@ -67,13 +67,22 @@ export async function runElisionIfNeeded(ctx: ModeContext): Promise<void> {
     if (!resolved) return;
     const contextWindow = resolved.contextWindow;
 
-    // Gate: below this fill the whole history fits comfortably — eliding would
-    // only add missed-context risk for no token benefit.
-    if (estimateContextTokens(ctx.log) < s.minContextRatioToElide * contextWindow) return;
-
     const events = ctx.log.slice();
     if (events.length === 0) return;
 
+    // Derive the elision state ONCE for this snapshot and thread it into the
+    // gate's estimate. The same `computeElisionState` fold otherwise runs again
+    // inside `estimateContextTokens` (and a third time in projection this
+    // iteration); threading shares the one fold. Order vs the slice is
+    // irrelevant — both read the same immutable snapshot.
+    const elisionState = computeElisionState(events);
+
+    // Gate: below this fill the whole history fits comfortably — eliding would
+    // only add missed-context risk for no token benefit.
+    if (estimateContextTokens(ctx.log, elisionState) < s.minContextRatioToElide * contextWindow) {
+      return;
+    }
+
     const priorHWM = events.reduce(
       (max, e) => (e.type === 'elision' ? Math.max(max, e.elidedThrough) : max),
       -1,

package/src/elision-state.test.ts

@@ -255,3 +255,81 @@ describe('computeElisionState (golden: fused == 4-pass reference)', () => {
     assertSameState(state, computeElisionStateOld(events));
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Memo correctness (complexity-hotspots-7 / u122-2): the single-slot memo keyed
+// on the input array's IDENTITY must (a) return the cached state for the same
+// immutable snapshot (a cache HIT — the identical reference), and (b) RECOMPUTE
+// — never serve a stale state — for any different array, including a new event
+// appended past the HWM or a re-config that reuses the same ids/seqs.
+// ─────────────────────────────────────────────────────────────────────────────
+describe('computeElisionState (memo correctness)', () => {
+  const baseLog = (): MoxxyEvent[] => [
+    event(0, { type: 'user_prompt', turnId: t1, source: 'user', text: 'the task' }),
+    event(1, { type: 'tool_call_requested', turnId: t1, source: 'model', callId: asToolCallId('ra'), name: 'recall', input: { callId: 'x' } }),
+    event(2, { type: 'tool_result', turnId: t1, source: 'tool', callId: asToolCallId('ra'), ok: true, output: 'A'.repeat(300) }),
+    event(3, {
+      type: 'elision', turnId: t2, source: 'system', elidedThrough: 2, stubbedRanges: [[0, 2]],
+      elideConversational: true, conversationalRecallThreshold: 4, maxRecallBytes: 1000, neverElideTools: [], tokensSaved: 100,
+    }),
+    event(4, { type: 'user_prompt', turnId: t2, source: 'user', text: 'recent' }),
+  ];
+
+  it('returns the cached state for the same snapshot, equal to a fresh fold', () => {
+    const events = baseLog();
+    const a = computeElisionState(events);
+    // Same array reference → memo HIT → the identical cached reference.
+    expect(computeElisionState(events)).toBe(a);
+    // …and it equals an uncached fresh fold of the same snapshot.
+    assertSameState(a, computeElisionStateOld(events));
+  });
+
+  it('invalidates (recomputes) when a new event is appended past the HWM', () => {
+    const events = baseLog();
+    const before = computeElisionState(events);
+    expect(before.hwm).toBe(2);
+    // A NEW snapshot array with one more tail event must NOT serve `before`.
+    const grown = [
+      ...events,
+      event(5, { type: 'tool_call_requested', turnId: t2, source: 'model', callId: asToolCallId('rb'), name: 'recall', input: { callId: 'y' } }),
+    ];
+    const after = computeElisionState(grown);
+    expect(after).not.toBe(before); // recomputed, not the cached ref
+    // `rb` only exists in the grown log → its presence proves invalidation.
+    expect(after.recallResultCallIds.has('rb')).toBe(true);
+    expect(before.recallResultCallIds.has('rb')).toBe(false);
+    assertSameState(after, computeElisionStateOld(grown));
+    // A new ElisionEvent that advances the HWM also invalidates.
+    const reElided = [
+      ...grown,
+      event(6, { type: 'tool_result', turnId: t2, source: 'tool', callId: asToolCallId('rb'), ok: true, output: 'B'.repeat(50) }),
+      event(7, {
+        type: 'elision', turnId: t2, source: 'system', elidedThrough: 6, stubbedRanges: [[3, 6]],
+        elideConversational: true, conversationalRecallThreshold: 4, maxRecallBytes: 1000, neverElideTools: [], tokensSaved: 200,
+      }),
+    ];
+    const advanced = computeElisionState(reElided);
+    expect(advanced.hwm).toBe(6);
+    assertSameState(advanced, computeElisionStateOld(reElided));
+  });
+
+  it('never serves a stale state for a re-config that reuses the same ids/seqs', () => {
+    // Two logically-distinct logs with byte-identical ids/seqs but different
+    // elision config — the exact case a content hash of id+seq would collide on
+    // and serve stale. Distinct array instances → distinct memo keys → correct.
+    const mk = (threshold: number): MoxxyEvent[] => [
+      event(0, { type: 'user_prompt', turnId: t1, source: 'user', text: 'the task' }),
+      event(1, { type: 'tool_call_requested', turnId: t1, source: 'model', callId: asToolCallId('s1'), name: 'recall', input: { seq: 0 } }),
+      event(2, { type: 'tool_call_requested', turnId: t1, source: 'model', callId: asToolCallId('s2'), name: 'recall', input: { seq: 0 } }),
+      event(3, {
+        type: 'elision', turnId: t2, source: 'system', elidedThrough: 2, stubbedRanges: [[0, 2]],
+        elideConversational: true, conversationalRecallThreshold: threshold, maxRecallBytes: 1000, neverElideTools: [], tokensSaved: 10,
+      }),
+      event(4, { type: 'user_prompt', turnId: t2, source: 'user', text: 'next' }),
+    ];
+    const on = computeElisionState(mk(3)); // threshold 3 > 2 seq-recalls → ON
+    const off = computeElisionState(mk(2)); // threshold 2 == 2 → OFF
+    expect(on.effectiveElideConversational).toBe(true);
+    expect(off.effectiveElideConversational).toBe(false);
+  });
+});

package/src/elision-state.ts

@@ -70,12 +70,54 @@ const EMPTY_STATE: ElisionState = {
   firstUserPromptSeq: -1,
 };
 
+/**
+ * Single-slot memo of the most recent {@link computeElisionState} result,
+ * keyed on the IDENTITY of the events array it was folded from.
+ *
+ * The event log is append-only and every held event is immutable (invariant
+ * #6: events at/below the HWM never change), so a given snapshot array is a
+ * stable, never-mutated value: the same array reference always denotes the
+ * same content and therefore the same state. A new turn produces a NEW snapshot
+ * array (the live `log.slice()` returns a fresh array each call), so the memo
+ * self-invalidates the moment the log changes — there is no way for it to serve
+ * a state that is stale for the array it is keyed on.
+ *
+ * Keying on identity (not a content hash of `id`/`seq`/payload) is the only
+ * SOUND single-slot choice for a pure fold over an arbitrary array: two
+ * logically-different logs can share ids/seqs (e.g. a test that rebuilds the
+ * same prefix with different payload, or a re-config), and a content hash that
+ * missed a payload field would serve a stale state — a correctness bug. Array
+ * identity can never collide across distinct values.
+ *
+ * The win: callers that re-ask over the SAME snapshot within an iteration
+ * (e.g. the elision/compaction gates and the estimate, when they thread the
+ * one `log.slice()` array — see `estimateContextTokens`) fold it only once;
+ * `WeakMap` would also help a held snapshot survive GC pressure, but a single
+ * slot keeps it allocation-free and matches the "one live snapshot at a time"
+ * access pattern. Threading a precomputed state is the explicit zero-cost fast
+ * path; this memo covers callers that re-pass the same array but can't thread.
+ */
+let memoEvents: ReadonlyArray<MoxxyEvent> | null = null;
+let memoState: ElisionState | null = null;
+
 /**
  * Derive elision state purely from the log: the active high-water mark + flags
  * (from the latest ElisionEvent), the callId→tool map, recall bookkeeping, the
  * adaptive conversational auto-disable, and which pinned recalls exceed the cap.
+ *
+ * Memoized on the input array's identity (see above) so repeated calls over the
+ * same immutable snapshot fold it only once. The returned state is identical
+ * (and `===` on a cache hit) to a fresh fold.
  */
 export function computeElisionState(events: ReadonlyArray<MoxxyEvent>): ElisionState {
+  if (memoEvents === events && memoState !== null) return memoState;
+  const state = computeElisionStateUncached(events);
+  memoEvents = events;
+  memoState = state;
+  return state;
+}
+
+function computeElisionStateUncached(events: ReadonlyArray<MoxxyEvent>): ElisionState {
   let hwm = -1;
   let elideConversational = false;
   let conversationalRecallThreshold = Number.POSITIVE_INFINITY;

package/src/index.ts

@@ -181,15 +181,12 @@ export type {
   SpawnCliTunnelOptions,
   CliTunnelHandle,
 } from './tunnel.js';
-export { spawnCliTunnel, isCliTunnelAvailable } from './tunnel.js';
+// Node-runtime helpers (spawnCliTunnel/isCliTunnelAvailable, writeFileAtomic*,
+// moxxyHome/moxxyPath, readRequestBody/bearerTokenMatches, channel-auth) are
+// exported from the './server' subpath, NOT the main barrel — they statically
+// reach node:* builtins and would break a browser/RN bundle. See ./server.ts.
 export { isRetryableError, toFriendlyError, zodToJsonSchema, estimateTextTokens, type StopReason } from './provider-utils.js';
-export {
-  writeFileAtomic,
-  writeFileAtomicSync,
-  moxxyHome,
-  moxxyPath,
-  type WriteFileAtomicOptions,
-} from './fs-utils.js';
+export type { WriteFileAtomicOptions } from './fs-utils.js';
 export { createMutex, type Mutex } from './mutex.js';
 export {
   createJsonFileStore,
@@ -198,17 +195,9 @@ export {
 } from './json-file-store.js';
 export { assertNever } from './assert.js';
 export { compareSemver, parseSemverCore } from './semver.js';
-export { readRequestBody, bearerTokenMatches } from './http-utils.js';
-export {
-  resolveChannelToken,
-  rotateChannelToken,
-  bearerGuard,
-  encodeWsBearerProtocol,
-  tokenFromWsProtocolHeader,
-  MOXXY_WS_SUBPROTOCOL,
-  MOXXY_WS_BEARER_PROTOCOL_PREFIX,
-  type ChannelTokenOptions,
-} from './channel-auth.js';
+// readRequestBody/bearerTokenMatches (http-utils) and the channel-auth value
+// helpers live on the './server' subpath — they reach node:http/crypto/fs/path.
+export type { ChannelTokenOptions } from './channel-auth.js';
 export {
   autoAllowResolver,
   denyByDefaultResolver,
@@ -254,7 +243,11 @@ export type { TokenBudget, CompactContext, CompactorDef } from './compactor.js';
 export {
   estimateContextTokens,
   runCompactionIfNeeded,
+  runManualCompaction,
+  resolveModelContext,
   isContextOverflowError,
+  type ManualCompactionInput,
+  type ManualCompactionResult,
 } from './compactor-helpers.js';
 export {
   runElisionIfNeeded,
@@ -403,6 +396,7 @@ export type {
   TranscriptionSegment,
   TranscribeOptions,
 } from './transcriber.js';
+export { MOXXY_PCM16_24KHZ_MIME } from './transcriber.js';
 
 export type {
   Synthesizer,