@moxxy/core 0.3.0

package/src/surfaces/host.test.ts

@@ -0,0 +1,330 @@
+import { describe, it, expect } from 'vitest';
+import {
+  defineSurface,
+  type SurfaceDataMessage,
+  type SurfaceInstance,
+  type SurfaceSize,
+} from '@moxxy/sdk';
+import { SurfaceHostImpl } from './host.js';
+import { SurfaceRegistryImpl } from '../registries/surfaces.js';
+
+/**
+ * A fake surface whose instance records the input it receives and whether it has
+ * been closed — enough to assert that the host routes a viewer's keystrokes to
+ * the live instance and only tears it down when the last viewer detaches.
+ */
+function fakeSurface(kind = 'terminal') {
+  const state = { inputs: [] as unknown[], closed: 0, opens: 0 };
+  const def = defineSurface({
+    kind,
+    open: () => {
+      state.opens += 1;
+      const instance: SurfaceInstance = {
+        id: kind,
+        kind,
+        onData: () => () => {},
+        snapshot: () => ({ type: 'snapshot' }),
+        input: (msg) => {
+          state.inputs.push(msg);
+        },
+        close: () => {
+          state.closed += 1;
+        },
+      };
+      return instance;
+    },
+  });
+  return { def, state };
+}
+
+function makeHost(def: ReturnType<typeof fakeSurface>['def']): SurfaceHostImpl {
+  const registry = new SurfaceRegistryImpl();
+  registry.register(def);
+  return new SurfaceHostImpl(registry, { cwd: '/tmp' });
+}
+
+describe('SurfaceHostImpl viewer ref-counting', () => {
+  it('keeps a shared instance alive until the last viewer closes', async () => {
+    const { def, state } = fakeSurface();
+    const host = makeHost(def);
+
+    const a = await host.open('terminal');
+    const b = await host.open('terminal');
+    expect(state.opens).toBe(1); // shared: one underlying instance
+    expect(a.surfaceId).toBe(b.surfaceId);
+
+    // First viewer detaches — instance must survive for the second.
+    await host.close(a.surfaceId);
+    expect(state.closed).toBe(0);
+
+    // Input from the still-attached viewer reaches the live instance.
+    await host.input(b.surfaceId, { type: 'data', data: 'ls\n' });
+    expect(state.inputs).toEqual([{ type: 'data', data: 'ls\n' }]);
+
+    // Last viewer detaches — now it tears down.
+    await host.close(b.surfaceId);
+    expect(state.closed).toBe(1);
+  });
+
+  it('survives the StrictMode mount→unmount→remount close race', async () => {
+    // React StrictMode double-invokes effects: the first mount opens, unmounts
+    // (its late-resolving open then fires a close), and a second mount opens the
+    // shared instance. The stray close must NOT destroy the instance the live
+    // mount is using — otherwise input/resize silently vanish.
+    const { def, state } = fakeSurface();
+    const host = makeHost(def);
+
+    const first = await host.open('terminal'); // mount A
+    const second = await host.open('terminal'); // mount B (remount)
+    await host.close(first.surfaceId); // mount A's disposed-open close
+
+    expect(state.closed).toBe(0); // instance survived
+    await host.input(second.surfaceId, { type: 'data', data: 'x' });
+    expect(state.inputs).toEqual([{ type: 'data', data: 'x' }]); // input still lands
+  });
+
+  it('closeAll tears down regardless of outstanding viewer refs', async () => {
+    const { def, state } = fakeSurface();
+    const host = makeHost(def);
+    await host.open('terminal');
+    await host.open('terminal'); // ref count 2
+    await host.closeAll();
+    expect(state.closed).toBe(1);
+  });
+});
+
+/**
+ * A controllable surface whose instance lets the test PUSH frames (`emit`),
+ * record resize calls, and run unsubscribe on close — enough to assert the
+ * host's multiplex fan-out, the per-instance unsub drop, and id-based routing.
+ */
+function controllableSurface(kind = 'terminal') {
+  const subscribers = new Set<(payload: unknown) => void>();
+  const state = {
+    opens: 0,
+    closed: 0,
+    inputs: [] as unknown[],
+    resizes: [] as SurfaceSize[],
+    unsubs: 0,
+  };
+  const instance: SurfaceInstance = {
+    id: `${kind}-id`,
+    kind,
+    onData: (cb) => {
+      subscribers.add(cb);
+      return () => {
+        subscribers.delete(cb);
+        state.unsubs += 1;
+      };
+    },
+    snapshot: () => ({ scrollback: 'hello' }),
+    input: (msg) => {
+      state.inputs.push(msg);
+    },
+    resize: (size) => {
+      state.resizes.push(size);
+    },
+    close: () => {
+      state.closed += 1;
+    },
+  };
+  const def = defineSurface({
+    kind,
+    description: 'controllable',
+    open: () => {
+      state.opens += 1;
+      return instance;
+    },
+  });
+  /** Push one frame as the underlying instance would. */
+  const emit = (payload: unknown): void => {
+    for (const cb of subscribers) cb(payload);
+  };
+  return { def, state, instance, emit };
+}
+
+describe('SurfaceHostImpl open() idempotence + snapshot', () => {
+  it('returns the existing instance + its snapshot on a second open(kind)', async () => {
+    const { def, state } = controllableSurface();
+    const host = makeHost(def);
+
+    const a = await host.open('terminal');
+    const b = await host.open('terminal');
+
+    expect(state.opens).toBe(1); // def.open ran exactly once
+    expect(a.surfaceId).toBe(b.surfaceId);
+    expect(a.kind).toBe('terminal');
+    // The catch-up snapshot rides back to a late-joining viewer.
+    expect(a.snapshot).toEqual({ scrollback: 'hello' });
+    expect(b.snapshot).toEqual({ scrollback: 'hello' });
+  });
+
+  it('two concurrent open(kind) calls share ONE instance (def.open runs once)', async () => {
+    const { def, state } = controllableSurface();
+    const host = makeHost(def);
+
+    const [a, b] = await Promise.all([host.open('terminal'), host.open('terminal')]);
+
+    expect(state.opens).toBe(1);
+    expect(a.surfaceId).toBe(b.surfaceId);
+  });
+
+  it('throws a clear error opening an unregistered kind', async () => {
+    const { def } = controllableSurface();
+    const host = makeHost(def);
+    await expect(host.open('browser')).rejects.toThrow(/No surface registered for kind: browser/);
+  });
+});
+
+describe('SurfaceHostImpl onData multiplex fan-out', () => {
+  it('re-emits each instance frame as a SurfaceDataMessage carrying surfaceId/kind/payload', async () => {
+    const { def, emit } = controllableSurface();
+    const host = makeHost(def);
+    const { surfaceId } = await host.open('terminal');
+
+    const seen: SurfaceDataMessage[] = [];
+    host.onData((msg) => seen.push(msg));
+    emit({ bytes: 'ls\n' });
+
+    expect(seen).toEqual([{ surfaceId, kind: 'terminal', payload: { bytes: 'ls\n' } }]);
+  });
+
+  it('fans every frame out to all subscribers', async () => {
+    const { def, emit } = controllableSurface();
+    const host = makeHost(def);
+    await host.open('terminal');
+
+    const a: SurfaceDataMessage[] = [];
+    const b: SurfaceDataMessage[] = [];
+    host.onData((m) => a.push(m));
+    host.onData((m) => b.push(m));
+    emit({ x: 1 });
+
+    expect(a).toHaveLength(1);
+    expect(b).toHaveLength(1);
+  });
+
+  it('a throwing listener does not suppress delivery to the others', async () => {
+    const { def, emit } = controllableSurface();
+    const host = makeHost(def);
+    await host.open('terminal');
+
+    const good: SurfaceDataMessage[] = [];
+    host.onData(() => {
+      throw new Error('bad listener');
+    });
+    host.onData((m) => good.push(m));
+
+    expect(() => emit({ x: 1 })).not.toThrow();
+    expect(good).toHaveLength(1);
+  });
+
+  it('the onData unsubscribe stops further frames for that subscriber', async () => {
+    const { def, emit } = controllableSurface();
+    const host = makeHost(def);
+    await host.open('terminal');
+
+    const seen: SurfaceDataMessage[] = [];
+    const off = host.onData((m) => seen.push(m));
+    emit({ n: 1 });
+    off();
+    emit({ n: 2 });
+
+    expect(seen).toHaveLength(1);
+  });
+
+  it('drops the per-instance unsub on close so no frames flow after teardown', async () => {
+    const { def, state, emit } = controllableSurface();
+    const host = makeHost(def);
+    const { surfaceId } = await host.open('terminal');
+
+    const seen: SurfaceDataMessage[] = [];
+    host.onData((m) => seen.push(m));
+    await host.close(surfaceId); // last viewer → real teardown
+
+    expect(state.closed).toBe(1);
+    expect(state.unsubs).toBe(1); // the host ran the stored unsub
+    emit({ late: true }); // frame from a still-live resource, post-close
+    expect(seen).toHaveLength(0); // host no longer forwards it
+  });
+});
+
+describe('SurfaceHostImpl input/resize routing', () => {
+  it('routes input + resize to the instance by surfaceId', async () => {
+    const { def, state } = controllableSurface();
+    const host = makeHost(def);
+    const { surfaceId } = await host.open('terminal');
+
+    await host.input(surfaceId, { type: 'data', data: 'x' });
+    await host.resize(surfaceId, { cols: 80, rows: 24 });
+
+    expect(state.inputs).toEqual([{ type: 'data', data: 'x' }]);
+    expect(state.resizes).toEqual([{ cols: 80, rows: 24 }]);
+  });
+
+  it('no-ops on an unknown surfaceId (input + resize)', async () => {
+    const { def, state } = controllableSurface();
+    const host = makeHost(def);
+    await host.open('terminal');
+
+    await host.input('does-not-exist', { type: 'data', data: 'x' });
+    await host.resize('does-not-exist', { cols: 1, rows: 1 });
+
+    expect(state.inputs).toEqual([]);
+    expect(state.resizes).toEqual([]);
+  });
+
+  it('close on an unknown surfaceId is a no-op (does not tear down the live one)', async () => {
+    const { def, state } = controllableSurface();
+    const host = makeHost(def);
+    await host.open('terminal');
+
+    await host.close('does-not-exist');
+    expect(state.closed).toBe(0);
+  });
+});
+
+describe('SurfaceHostImpl list()', () => {
+  it('reports the registered kinds with availability', async () => {
+    const registry = new SurfaceRegistryImpl();
+    registry.register(controllableSurface('terminal').def);
+    registry.register(
+      defineSurface({
+        kind: 'browser',
+        description: 'headless browser',
+        open: () => {
+          throw new Error('unused');
+        },
+        isAvailable: () => ({ ok: false, reason: 'node-pty missing' }),
+      }),
+    );
+    const host = new SurfaceHostImpl(registry, { cwd: '/tmp' });
+
+    const list = await host.list();
+    const byKind = new Map(list.map((i) => [i.kind, i]));
+    expect(byKind.get('terminal')).toMatchObject({ available: true, description: 'controllable' });
+    expect(byKind.get('browser')).toMatchObject({
+      available: false,
+      reason: 'node-pty missing',
+    });
+  });
+
+  it('treats a throwing isAvailable as unavailable with the error as reason', async () => {
+    const registry = new SurfaceRegistryImpl();
+    registry.register(
+      defineSurface({
+        kind: 'terminal',
+        open: () => {
+          throw new Error('unused');
+        },
+        isAvailable: () => {
+          throw new Error('probe blew up');
+        },
+      }),
+    );
+    const host = new SurfaceHostImpl(registry, { cwd: '/tmp' });
+
+    const [info] = await host.list();
+    expect(info).toMatchObject({ kind: 'terminal', available: false, reason: 'probe blew up' });
+  });
+});

package/src/surfaces/host.ts

@@ -0,0 +1,192 @@
+import type {
+  OpenSurfaceResult,
+  SurfaceContext,
+  SurfaceDataMessage,
+  SurfaceHost,
+  SurfaceInfo,
+  SurfaceInputMessage,
+  SurfaceInstance,
+  SurfaceKind,
+  SurfaceSize,
+} from '@moxxy/sdk';
+import type { Logger } from '../logger.js';
+import type { SurfaceRegistryImpl } from '../registries/surfaces.js';
+
+/**
+ * Manages the live, open {@link SurfaceInstance}s for a Session and multiplexes
+ * every instance's output through a single {@link onData} fan-out. The runner
+ * subscribes once and rebroadcasts each frame as a `surface.data` notification;
+ * the agent's tools reach the SAME underlying resource (PTY, page) through their
+ * plugin's module state, so a `terminal`/`browser_session` tool call appears in
+ * the very pane the user is watching.
+ *
+ * Opening a kind is idempotent: a second `open` returns the instance the first
+ * created (surfaces are shared), so a late-joining viewer attaches to the
+ * existing resource and gets its {@link SurfaceInstance.snapshot}.
+ */
+export class SurfaceHostImpl implements SurfaceHost {
+  /** Open instances, keyed by kind (one shared instance per kind). */
+  private readonly instances = new Map<SurfaceKind, SurfaceInstance>();
+  /** Per-instance unsubscribe from its onData, dropped on close. */
+  private readonly unsubs = new Map<string, () => void>();
+  private readonly dataListeners = new Set<(msg: SurfaceDataMessage) => void>();
+  /** In-flight opens, so concurrent `open(kind)` calls share one instance. */
+  private readonly opening = new Map<SurfaceKind, Promise<OpenSurfaceResult>>();
+  /**
+   * Viewer attach count per kind. A surface is SHARED (the agent's tool + every
+   * attached viewer drive the same PTY/page), so `open` retains and `close`
+   * releases; the instance is only torn down when the last viewer detaches.
+   * Without this, a single viewer's `close` would destroy the resource out from
+   * under the others — and React StrictMode (dev) makes that routine: it
+   * mounts → unmounts → remounts, so the first mount's late-resolving `open`
+   * closes the very instance the remount just attached to, leaving `input`/
+   * `resize` to hit a now-missing instance (output still flows from the
+   * snapshot, but keystrokes/navigation silently vanish).
+   */
+  private readonly refs = new Map<SurfaceKind, number>();
+
+  constructor(
+    private readonly registry: SurfaceRegistryImpl,
+    private readonly ctx: SurfaceContext,
+    private readonly logger?: Logger,
+  ) {}
+
+  async list(): Promise<ReadonlyArray<SurfaceInfo>> {
+    const out: SurfaceInfo[] = [];
+    for (const def of this.registry.list()) {
+      let available = true;
+      let reason: string | undefined;
+      if (def.isAvailable) {
+        try {
+          const a = await def.isAvailable(this.ctx);
+          available = a.ok;
+          reason = a.reason;
+        } catch (err) {
+          available = false;
+          reason = err instanceof Error ? err.message : String(err);
+        }
+      }
+      out.push({
+        kind: def.kind,
+        ...(def.description ? { description: def.description } : {}),
+        available,
+        ...(reason ? { reason } : {}),
+      });
+    }
+    return out;
+  }
+
+  async open(kind: SurfaceKind): Promise<OpenSurfaceResult> {
+    const existing = this.instances.get(kind);
+    if (existing) {
+      this.retain(kind);
+      return this.describe(existing);
+    }
+    const pending = this.opening.get(kind);
+    if (pending) {
+      // Ride the in-flight create, but still count this viewer's attach.
+      const res = await pending;
+      this.retain(kind);
+      return res;
+    }
+
+    const def = this.registry.get(kind);
+    if (!def) throw new Error(`No surface registered for kind: ${kind}`);
+
+    const promise = (async (): Promise<OpenSurfaceResult> => {
+      const instance = await def.open(this.ctx);
+      this.instances.set(kind, instance);
+      this.refs.set(kind, 1);
+      // Re-emit this instance's frames as multiplexed SurfaceDataMessages.
+      const unsub = instance.onData((payload) =>
+        this.emit({ surfaceId: instance.id, kind: instance.kind, payload }),
+      );
+      this.unsubs.set(instance.id, unsub);
+      return this.describe(instance);
+    })();
+    this.opening.set(kind, promise);
+    try {
+      return await promise;
+    } finally {
+      this.opening.delete(kind);
+    }
+  }
+
+  async input(surfaceId: string, msg: SurfaceInputMessage): Promise<void> {
+    const instance = this.byId(surfaceId);
+    if (!instance) return;
+    await instance.input(msg);
+  }
+
+  async resize(surfaceId: string, size: SurfaceSize): Promise<void> {
+    const instance = this.byId(surfaceId);
+    if (!instance?.resize) return;
+    await instance.resize(size);
+  }
+
+  async close(surfaceId: string): Promise<void> {
+    const instance = this.byId(surfaceId);
+    if (!instance) return;
+    const kind = instance.kind;
+    // Release this viewer; keep the shared instance alive while others hold it.
+    const remaining = (this.refs.get(kind) ?? 1) - 1;
+    if (remaining > 0) {
+      this.refs.set(kind, remaining);
+      return;
+    }
+    this.refs.delete(kind);
+    this.unsubs.get(surfaceId)?.();
+    this.unsubs.delete(surfaceId);
+    this.instances.delete(kind);
+    try {
+      await instance.close();
+    } catch (err) {
+      this.logger?.warn?.('SurfaceHost: close failed', {
+        surfaceId,
+        err: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  /** Bump the viewer attach count for an already-open kind. */
+  private retain(kind: SurfaceKind): void {
+    this.refs.set(kind, (this.refs.get(kind) ?? 0) + 1);
+  }
+
+  private describe(instance: SurfaceInstance): OpenSurfaceResult {
+    return {
+      surfaceId: instance.id,
+      kind: instance.kind,
+      ...(instance.snapshot ? { snapshot: instance.snapshot() } : {}),
+    };
+  }
+
+  onData(cb: (msg: SurfaceDataMessage) => void): () => void {
+    this.dataListeners.add(cb);
+    return () => this.dataListeners.delete(cb);
+  }
+
+  async closeAll(): Promise<void> {
+    // Session shutdown: tear every instance down regardless of viewer refs.
+    for (const kind of [...this.instances.keys()]) this.refs.set(kind, 1);
+    const ids = [...this.unsubs.keys()];
+    for (const id of ids) await this.close(id);
+  }
+
+  private byId(surfaceId: string): SurfaceInstance | undefined {
+    for (const instance of this.instances.values()) {
+      if (instance.id === surfaceId) return instance;
+    }
+    return undefined;
+  }
+
+  private emit(msg: SurfaceDataMessage): void {
+    for (const fn of this.dataListeners) {
+      try {
+        fn(msg);
+      } catch {
+        /* a bad listener must not break the stream */
+      }
+    }
+  }
+}

package/src/tunnel/localhost.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { localhostTunnel } from './localhost.js';
+
+describe('localhostTunnel', () => {
+  it('returns the local URL and a no-op close', async () => {
+    const handle = await localhostTunnel.open({ host: '127.0.0.1', port: 4040 });
+    expect(handle.url).toBe('http://127.0.0.1:4040');
+    await expect(handle.close()).resolves.toBeUndefined();
+  });
+
+  it('brackets an IPv6 literal host so the URL is valid', async () => {
+    // u49-1: a bare IPv6 host yields an ambiguous, unparseable URL.
+    const handle = await localhostTunnel.open({ host: '::1', port: 4040 });
+    expect(handle.url).toBe('http://[::1]:4040');
+    // …and the result actually parses.
+    expect(new URL(handle.url).hostname).toBe('[::1]');
+  });
+
+  it('is always available', async () => {
+    expect(await localhostTunnel.isAvailable?.()).toBe(true);
+  });
+});

package/src/tunnel/localhost.ts

@@ -0,0 +1,21 @@
+import { defineTunnelProvider } from '@moxxy/sdk';
+
+/**
+ * The default tunnel provider: no tunnel at all, just the local URL. Used when
+ * the surface and the user share a machine (TUI), or when no real tunnel
+ * (cloudflared) is configured/installed.
+ */
+export const localhostTunnel = defineTunnelProvider({
+  name: 'localhost',
+  open: (opts) => {
+    // Bracket an IPv6 literal host (e.g. `::1` → `[::1]`) so the `:port`
+    // delimiter is unambiguous and the result is a valid URL. A bare IPv6
+    // host (`http://::1:4040`) is rejected by most URL parsers.
+    const host = opts.host.includes(':') ? `[${opts.host}]` : opts.host;
+    return Promise.resolve({
+      url: `http://${host}:${opts.port}`,
+      close: () => Promise.resolve(),
+    });
+  },
+  isAvailable: () => Promise.resolve(true),
+});

package/src/usage-stats.test.ts

@@ -0,0 +1,77 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { clearUsageStats, loadUsageStats, mergeUsageStats } from './usage-stats.js';
+import type { ModelUsageTotals } from '@moxxy/sdk';
+
+const totals = (over: Partial<ModelUsageTotals> = {}): ModelUsageTotals => ({
+  calls: 1,
+  inputTokens: 0,
+  outputTokens: 0,
+  cacheReadTokens: 0,
+  cacheCreationTokens: 0,
+  ...over,
+});
+
+let tmpDir: string;
+let statsPath: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-usage-'));
+  statsPath = path.join(tmpDir, 'usage.json');
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+describe('usage-stats store', () => {
+  it('returns an empty aggregate when the file is missing', async () => {
+    const file = await loadUsageStats(statsPath);
+    expect(file.models).toEqual({});
+    expect(file.version).toBe(1);
+  });
+
+  it('merges a delta and round-trips through disk', async () => {
+    await mergeUsageStats({ 'anthropic/opus': totals({ inputTokens: 100, outputTokens: 10 }) }, statsPath);
+    const file = await loadUsageStats(statsPath);
+    expect(file.models['anthropic/opus']!.inputTokens).toBe(100);
+    expect(file.models['anthropic/opus']!.firstSeen).toBeTruthy();
+    expect(file.models['anthropic/opus']!.lastSeen).toBeTruthy();
+  });
+
+  it('accumulates additively across merges and preserves firstSeen', async () => {
+    const first = await mergeUsageStats(
+      { 'anthropic/opus': totals({ inputTokens: 100 }) },
+      statsPath,
+    );
+    const firstSeen = first.models['anthropic/opus']!.firstSeen;
+
+    await mergeUsageStats({ 'anthropic/opus': totals({ inputTokens: 50, calls: 2 }) }, statsPath);
+    const file = await loadUsageStats(statsPath);
+
+    expect(file.models['anthropic/opus']!.inputTokens).toBe(150);
+    expect(file.models['anthropic/opus']!.calls).toBe(3);
+    expect(file.models['anthropic/opus']!.firstSeen).toBe(firstSeen);
+  });
+
+  it('ignores empty deltas and zero-call entries', async () => {
+    await mergeUsageStats({}, statsPath);
+    expect((await loadUsageStats(statsPath)).models).toEqual({});
+
+    await mergeUsageStats({ 'a/m': totals({ calls: 0, inputTokens: 5 }) }, statsPath);
+    expect((await loadUsageStats(statsPath)).models).toEqual({});
+  });
+
+  it('clears the aggregate', async () => {
+    await mergeUsageStats({ 'anthropic/opus': totals({ inputTokens: 100 }) }, statsPath);
+    await clearUsageStats(statsPath);
+    expect((await loadUsageStats(statsPath)).models).toEqual({});
+  });
+
+  it('reads as empty when the file is malformed', async () => {
+    await fs.writeFile(statsPath, '{ not json', 'utf8');
+    expect((await loadUsageStats(statsPath)).models).toEqual({});
+  });
+});