@moxxy/sdk 0.14.4 → 0.15.0

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,
@@ -357,9 +350,11 @@ export type {
   ResolvedPluginManifest,
 } from './plugin.js';
 
+export { startChannelWith } from './channel.js';
 export type {
   Channel,
   ChannelHandle,
+  ChannelStartArgs,
   ChannelStartOptsBase,
   ChannelFactoryDeps,
   ChannelDef,
@@ -403,6 +398,7 @@ export type {
   TranscriptionSegment,
   TranscribeOptions,
 } from './transcriber.js';
+export { MOXXY_PCM16_24KHZ_MIME } from './transcriber.js';
 
 export type {
   Synthesizer,

package/src/mode/project-messages.ts

@@ -61,6 +61,15 @@ export interface ProjectMessagesOptions {
   readonly systemPrompt?: string;
   /** Optional trailing user message — useful for plan-execute's "Focus on this step now: X". */
   readonly trailingUserText?: string;
+  /**
+   * Optional precomputed elision state for THIS exact log snapshot. When a
+   * caller already derived it within the same loop iteration (e.g. the
+   * compaction/elision gates), threading it here skips a redundant
+   * `computeElisionState` fold. MUST be the state of the same log — a stale one
+   * would mis-render stubs — so it is purely an opt-in fast path; omitting it
+   * recomputes (memoized on the log version), byte-identically.
+   */
+  readonly precomputedElisionState?: ElisionState;
 }
 
 interface CompactionRange {
@@ -260,7 +269,10 @@ export function projectMessages(
   const compactions = activeCompactionRanges(allEvents);
   const compactionFor = makeCompactionLookup(compactions);
   const emittedCompactions = new Set<CompactionRange>();
-  const el = computeElisionState(allEvents);
+  // Reuse a threaded state when the caller already derived it for this exact
+  // snapshot; otherwise `computeElisionState` is memoized on the log version so
+  // the in-iteration projection still folds only once.
+  const el = opts.precomputedElisionState ?? computeElisionState(allEvents);
 
   const messages: ProviderMessage[] = [];
   // The stable prefix is every message produced from events at/below the

package/src/package-root.test.ts

@@ -37,4 +37,41 @@ describe('@moxxy/sdk package root', () => {
 
     expect(check.issues[0]?.requirement.name).toBe('auth:provider:openai-codex');
   });
+
+  // The main barrel is the browser/RN-safe surface: a value import of any of
+  // these would drag a node:* builtin into a Metro/browser bundle. They live on
+  // the './server' subpath instead. This pins the split so a future accidental
+  // re-export on the main barrel is caught (see .dependency-cruiser.cjs
+  // `no-node-builtins-in-renderer`).
+  const NODE_ONLY_VALUE_EXPORTS = [
+    'spawnCliTunnel',
+    'isCliTunnelAvailable',
+    'writeFileAtomic',
+    'writeFileAtomicSync',
+    'moxxyHome',
+    'moxxyPath',
+    'readRequestBody',
+    'bearerTokenMatches',
+    'resolveChannelToken',
+    'rotateChannelToken',
+    'bearerGuard',
+    'encodeWsBearerProtocol',
+    'tokenFromWsProtocolHeader',
+    'MOXXY_WS_SUBPROTOCOL',
+    'MOXXY_WS_BEARER_PROTOCOL_PREFIX',
+  ] as const;
+
+  it('does NOT expose Node-runtime values on the browser/RN-safe main barrel', async () => {
+    const sdk: Record<string, unknown> = await import('@moxxy/sdk');
+    for (const name of NODE_ONLY_VALUE_EXPORTS) {
+      expect(sdk[name], `${name} must not be on the @moxxy/sdk main barrel`).toBeUndefined();
+    }
+  });
+
+  it('exposes the Node-runtime helpers on the @moxxy/sdk/server subpath', async () => {
+    const server: Record<string, unknown> = await import('@moxxy/sdk/server');
+    for (const name of NODE_ONLY_VALUE_EXPORTS) {
+      expect(server[name], `${name} must be exported from @moxxy/sdk/server`).toBeDefined();
+    }
+  });
 });

package/src/server.ts

@@ -0,0 +1,34 @@
+/**
+ * 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';

package/src/transcriber.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+import { MOXXY_PCM16_24KHZ_MIME } from './transcriber.js';
+
+describe('MOXXY_PCM16_24KHZ_MIME', () => {
+  it('locks the cross-package wire value', () => {
+    // This is a PROTOCOL constant: the desktop/web capture path stamps it onto
+    // the audio blob and the Codex transcriber keys on it to wrap the raw PCM
+    // samples in a WAV header. Drift in the literal silently breaks
+    // transcription with no compile-time signal — so pin the exact bytes here.
+    expect(MOXXY_PCM16_24KHZ_MIME).toBe('audio/x-moxxy-pcm16-24khz');
+  });
+});

package/src/transcriber.ts

@@ -18,6 +18,20 @@
  *     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 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;