@moxxy/sdk 0.15.1 → 0.16.0

package/src/requirements.ts

@@ -13,16 +13,28 @@ export type RequirementKind =
 
 export type RequirementState = 'registered' | 'active' | 'ready';
 
-export interface MoxxyRequirement {
-  readonly kind: RequirementKind;
+/** Fields common to every requirement kind. */
+interface RequirementBase {
   readonly name: string;
   readonly state?: RequirementState;
-  readonly version?: string;
   readonly optional?: boolean;
   readonly reason?: string;
   readonly hint?: string;
 }
 
+/**
+ * A declared dependency a plugin/config can require be present (and optionally
+ * active/ready). It is a discriminated union on `kind`: `version` is ONLY valid
+ * on the `plugin` kind, because that is the sole kind whose target resolves a
+ * version (see core's `RequirementRegistry.targetInfo`). A `version` on any
+ * other kind would compare against an always-undefined target version and
+ * report a permanent spurious `version_mismatch`, so the type forbids it at
+ * compile time rather than letting it silently slip through.
+ */
+export type MoxxyRequirement =
+  | (RequirementBase & { readonly kind: 'plugin'; readonly version?: string })
+  | (RequirementBase & { readonly kind: Exclude<RequirementKind, 'plugin'> });
+
 export interface RequirementIssue {
   readonly requirement: MoxxyRequirement;
   readonly code: 'missing' | 'inactive' | 'not_ready' | 'version_mismatch';

package/src/server.ts

@@ -15,7 +15,6 @@
  * bundle.
  */
 
-export { spawnCliTunnel, isCliTunnelAvailable } from './tunnel.js';
 export {
   writeFileAtomic,
   writeFileAtomicSync,

package/src/tool-display.test.ts

@@ -68,4 +68,28 @@ describe('guards', () => {
     expect(isToolDisplayResult({ forModel: 'x' })).toBe(false);
     expect(isToolDisplayResult('wrote 12 chars')).toBe(false);
   });
+
+  it('rejects malformed file-diff objects (not just the right `kind`)', () => {
+    // Right kind, but the rest of the shape is bogus — must not be trusted as a
+    // structured diff (channels would otherwise render garbage / the model loses
+    // the real output).
+    expect(isFileDiffDisplay({ kind: 'file-diff' })).toBe(false); // no path/counts/hunks
+    expect(isFileDiffDisplay({ kind: 'file-diff', path: 1, added: 1, removed: 0, hunks: [] })).toBe(false); // path not a string
+    expect(isFileDiffDisplay({ kind: 'file-diff', path: 'a', added: '1', removed: 0, hunks: [] })).toBe(false); // added not numeric
+    expect(isFileDiffDisplay({ kind: 'file-diff', path: 'a', added: 1, removed: 0, hunks: 'nope' })).toBe(false); // hunks not an array
+    expect(isFileDiffDisplay({ kind: 'file-diff', path: 'a', added: 1, removed: 0, hunks: [{ lines: 'x' }] })).toBe(false); // hunk.lines not an array
+    expect(isFileDiffDisplay({ kind: 'file-diff', path: 'a', added: 1, removed: 0, hunks: [null] })).toBe(false); // bad hunk entry
+    // A malformed display must also fail the wrapping ToolDisplayResult guard.
+    expect(isToolDisplayResult({ forModel: 'x', display: { kind: 'file-diff' } })).toBe(false);
+    // A well-formed hunk passes.
+    expect(
+      isFileDiffDisplay({
+        kind: 'file-diff',
+        path: 'a',
+        added: 1,
+        removed: 0,
+        hunks: [{ oldStart: 1, oldLines: 1, newStart: 1, newLines: 1, lines: [] }],
+      }),
+    ).toBe(true);
+  });
 });

package/src/tool-display.ts

@@ -72,12 +72,28 @@ export function isToolDisplay(x: unknown): x is ToolDisplay {
 }
 
 export function isFileDiffDisplay(x: unknown): x is FileDiffDisplay {
-  return (
-    typeof x === 'object' &&
-    x !== null &&
-    (x as { kind?: unknown }).kind === 'file-diff' &&
-    Array.isArray((x as { hunks?: unknown }).hunks)
-  );
+  if (typeof x !== 'object' || x === null) return false;
+  const d = x as {
+    kind?: unknown;
+    path?: unknown;
+    added?: unknown;
+    removed?: unknown;
+    hunks?: unknown;
+  };
+  if (d.kind !== 'file-diff') return false;
+  // Validate the load-bearing shape, not just `kind` + a `hunks` array: this
+  // guard decides whether a tool result is TRUSTED as a structured diff (the
+  // model is then shown only `forModel`, and channels render the payload). A
+  // malformed object with a bogus path / non-numeric counts / a non-array hunk
+  // must be rejected, not silently rendered.
+  if (typeof d.path !== 'string') return false;
+  if (typeof d.added !== 'number' || typeof d.removed !== 'number') return false;
+  if (!Array.isArray(d.hunks)) return false;
+  for (const hunk of d.hunks) {
+    if (typeof hunk !== 'object' || hunk === null) return false;
+    if (!Array.isArray((hunk as { lines?: unknown }).lines)) return false;
+  }
+  return true;
 }
 
 /** Human summary, e.g. "Added 10 lines, removed 1 line". */

package/src/tunnel.ts

@@ -1,21 +1,31 @@
 /**
- * A swappable way to expose a locally-bound surface (the web channel) to the
- * user over the public internet — so an agent on Telegram/TUI can hand the user
- * a URL they can open. One provider is active per session (registered via
- * plugins, like every other block); core seeds a `localhost` no-op provider so
- * `getActive()` is non-null.
+ * A swappable way to expose a locally-bound surface (the web channel, the mobile
+ * bridge, the webhooks listener) to the user over the public internet — so an
+ * agent on Telegram/TUI can hand the user a URL they can open. One provider is
+ * active per session (registered via plugins, like every other block); core
+ * seeds a `localhost` no-op provider so `getActive()` is non-null.
+ *
+ * The shipped provider is `@moxxy/plugin-tunnel-proxy` (the self-hosted proxy
+ * relay). The old cloudflared/ngrok subprocess providers — and the
+ * `spawnCliTunnel` helper that backed them — were removed.
  */
-import { spawn, type ChildProcess } from 'node:child_process';
 
 export interface TunnelOpenOptions {
   readonly port: number;
   readonly host: string;
+  /**
+   * Optional routing label for tunnels that multiplex several local services
+   * under one public endpoint (the proxy relay): the returned URL is
+   * `…/<label>` and inbound requests under that path segment route back to this
+   * `host:port`. Providers that expose a single port (or none) ignore it.
+   */
+  readonly label?: string;
 }
 
 export interface TunnelHandle {
-  /** The publicly reachable base URL (e.g. https://abc.trycloudflare.com). */
+  /** The publicly reachable base URL (e.g. https://abc123.proxy.moxxy.ai/mobile). */
   readonly url: string;
-  /** Tear the tunnel down (kill the subprocess, close the connection). */
+  /** Tear the tunnel down (deregister the target / close the connection). */
   close(): Promise<void>;
 }
 
@@ -23,195 +33,6 @@ export interface TunnelProviderDef {
   readonly name: string;
   /** Open a tunnel to `http://host:port`, resolving once the public URL is known. */
   open(opts: TunnelOpenOptions): Promise<TunnelHandle>;
-  /** Optional readiness gate (e.g. the `cloudflared` binary is installed). */
+  /** Optional readiness gate (e.g. the relay is reachable). */
   isAvailable?(): Promise<boolean>;
 }
-
-// ---------------------------------------------------------------------------
-// Shared CLI-tunnel subprocess management
-//
-// cloudflared/ngrok (channel-web) and the webhooks tunnel all do the same
-// thing: spawn a CLI, watch its stdout/stderr for the assigned public URL,
-// resolve once it's seen (or reject on timeout/exit/error), and guarantee the
-// child is killed on close *and* on process exit (Node does not reap children).
-// `spawnCliTunnel` is the single implementation they all share.
-// ---------------------------------------------------------------------------
-
-/**
- * Guarantees spawned tunnel children (cloudflared/ngrok/…) never orphan or
- * leak. Node does NOT kill child processes when the parent exits, so we track
- * every live child and kill any survivors on process teardown — in addition to
- * the explicit `close()` path. Each tracked child is also force-killed
- * (SIGKILL) if it ignores SIGTERM, so a wedged tunnel can't drain
- * memory/handles.
- */
-const liveChildren = new Set<ChildProcess>();
-let exitHookInstalled = false;
-
-function killChild(child: ChildProcess): void {
-  if (child.exitCode != null || child.signalCode != null) return;
-  try {
-    child.kill('SIGTERM');
-  } catch {
-    /* already gone */
-  }
-  // Escalate if it doesn't exit promptly. unref so this timer never holds the
-  // event loop open on its own.
-  const t = setTimeout(() => {
-    try {
-      child.kill('SIGKILL');
-    } catch {
-      /* gone */
-    }
-  }, 2000);
-  t.unref?.();
-  child.once('exit', () => clearTimeout(t));
-}
-
-function ensureExitHook(): void {
-  if (exitHookInstalled) return;
-  exitHookInstalled = true;
-  const killAll = (): void => {
-    for (const child of liveChildren) {
-      try {
-        child.kill('SIGKILL'); // process is exiting; be decisive, no async escalation
-      } catch {
-        /* gone */
-      }
-    }
-    liveChildren.clear();
-  };
-  process.once('exit', killAll);
-  // Registering a SIGINT/SIGTERM listener suppresses Node's default
-  // terminate-on-signal behavior, so an entrypoint that spawns a tunnel but
-  // installs no exit handler of its own would swallow the first Ctrl-C and hang
-  // with the process still alive. Re-raise the signal after cleanup so the
-  // default termination still fires. `process.once` removes the listener before
-  // it runs, so re-raising hits Node's default disposition (terminate).
-  const onSignal = (sig: 'SIGINT' | 'SIGTERM') => (): void => {
-    killAll();
-    process.kill(process.pid, sig);
-  };
-  process.once('SIGINT', onSignal('SIGINT'));
-  process.once('SIGTERM', onSignal('SIGTERM'));
-}
-
-/** Track a spawned child; returns an `untrack()` that also kills it cleanly. */
-function trackChild(child: ChildProcess): () => Promise<void> {
-  ensureExitHook();
-  liveChildren.add(child);
-  child.once('exit', () => liveChildren.delete(child));
-  return () =>
-    new Promise<void>((resolve) => {
-      liveChildren.delete(child);
-      if (child.exitCode != null || child.signalCode != null) return resolve();
-      child.once('exit', () => resolve());
-      killChild(child);
-    });
-}
-
-export interface SpawnCliTunnelOptions {
-  /** Executable to spawn (e.g. `cloudflared`, `ngrok`). */
-  readonly cmd: string;
-  /** Arguments passed to the executable. */
-  readonly args: ReadonlyArray<string>;
-  /** Matches the assigned public URL in a chunk of the CLI's stdout/stderr. */
-  readonly urlRegex: RegExp;
-  /** How long to wait for the URL before giving up. Default 30s. */
-  readonly timeoutMs?: number;
-  /** Human-readable name used in error messages. Defaults to `cmd`. */
-  readonly name?: string;
-}
-
-/** A spawned CLI tunnel: the public-URL handle plus the child's pid. */
-export interface CliTunnelHandle extends TunnelHandle {
-  /** Spawned process id (-1 if the platform didn't assign one). */
-  readonly pid: number;
-}
-
-const DEFAULT_TUNNEL_URL_TIMEOUT_MS = 30_000;
-
-/**
- * Spawn a CLI tunnel, parse the assigned public URL out of its output, and
- * resolve a {@link CliTunnelHandle}. The child is tracked so it is killed on
- * `close()`, on tunnel-switch, and on process exit (no orphans). Rejects on
- * timeout, spawn error, or premature exit (the child is killed in every reject
- * path). This is the single spawn-and-parse implementation behind the
- * cloudflared/ngrok tunnel providers and the webhooks tunnel.
- */
-export function spawnCliTunnel(opts: SpawnCliTunnelOptions): Promise<CliTunnelHandle> {
-  const { cmd, args, urlRegex } = opts;
-  const name = opts.name ?? cmd;
-  const timeoutMs = opts.timeoutMs ?? DEFAULT_TUNNEL_URL_TIMEOUT_MS;
-
-  return new Promise<CliTunnelHandle>((resolve, reject) => {
-    let child: ChildProcess;
-    try {
-      child = spawn(cmd, args as string[], { stdio: ['ignore', 'pipe', 'pipe'] });
-    } catch (err) {
-      reject(
-        new Error(
-          `failed to spawn ${name} — is it installed? (${err instanceof Error ? err.message : String(err)})`,
-        ),
-      );
-      return;
-    }
-
-    const untrack = trackChild(child);
-    let settled = false;
-
-    const timer = setTimeout(() => {
-      if (settled) return;
-      settled = true;
-      void untrack();
-      reject(new Error(`${name}: timed out after ${timeoutMs}ms waiting for the tunnel URL`));
-    }, timeoutMs);
-    timer.unref?.();
-
-    // 'data' events are not line-buffered: the assigned URL can straddle two
-    // chunk boundaries (large URL, fragmented flush). Match against a rolling
-    // accumulation rather than each lone chunk, capped so a chatty tunnel that
-    // never prints a URL can't grow this unboundedly while we wait.
-    const MAX_BUF = 8192;
-    let acc = '';
-    const onData = (buf: Buffer): void => {
-      if (settled) return; // drain quietly once resolved so the pipe never fills
-      acc += buf.toString('utf8');
-      if (acc.length > MAX_BUF) acc = acc.slice(acc.length - MAX_BUF);
-      const url = urlRegex.exec(acc)?.[0] ?? null;
-      if (!url) return;
-      settled = true;
-      acc = '';
-      clearTimeout(timer);
-      resolve({ url, pid: child.pid ?? -1, close: untrack });
-    };
-
-    child.stdout?.on('data', onData);
-    child.stderr?.on('data', onData);
-    child.on('error', (err) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      void untrack();
-      reject(err);
-    });
-    child.on('exit', (code) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      reject(new Error(`${name} exited (code ${code ?? 'null'}) before emitting a URL`));
-    });
-  });
-}
-
-/**
- * Probe whether a tunnel CLI is installed and runnable (`<cmd> --version`
- * exits 0). Used as the `isAvailable()` gate by CLI-backed tunnel providers.
- */
-export function isCliTunnelAvailable(cmd: string): Promise<boolean> {
-  return new Promise<boolean>((resolve) => {
-    const child = spawn(cmd, ['--version'], { stdio: 'ignore' });
-    child.once('error', () => resolve(false));
-    child.once('exit', (code) => resolve(code === 0));
-  });
-}

package/src/view-renderer.test.ts

@@ -33,6 +33,18 @@ describe('countNodes', () => {
   it('counts a leaf element as 1', () => {
     expect(countNodes(el('hr'))).toBe(1);
   });
+
+  it('does not throw (RangeError) on a deeply nested AST', () => {
+    // A hand-built/corrupt AST can be arbitrarily deep; the count must be
+    // iterative so a deep chain never blows the call stack. 100k deep would
+    // overflow naive recursion.
+    const depth = 100_000;
+    let node: ViewNode = text('leaf');
+    for (let i = 0; i < depth; i++) node = el('wrap', [node]);
+    // depth wrapping elements + the leaf text node.
+    expect(() => countNodes(node)).not.toThrow();
+    expect(countNodes(node)).toBe(depth + 1);
+  });
 });
 
 describe('view vocabulary integrity', () => {

package/src/view-renderer.ts

@@ -188,8 +188,22 @@ export const DEFAULT_VIEW_TAGS: ReadonlyArray<ViewTagSpec> = [...VIEW_PRIMITIVES
  * Count element + text nodes in a view tree (the `nodeCount` a `present_view`
  * tool reports). Single source of truth: core's parser and the plugin-view tool
  * both import this rather than re-implementing the recursion.
+ *
+ * Iterative (explicit stack) rather than recursive: a deeply nested
+ * hand-built/corrupt AST would blow the call stack with a `RangeError`, and this
+ * runs on untrusted agent-authored input. Each node counts as 1; an element's
+ * children are pushed for later counting. Order-independent (we only sum), so
+ * the count is byte-identical to the old recursion for any normal tree.
  */
 export function countNodes(node: ViewNode): number {
-  if (node.kind === 'text') return 1;
-  return 1 + node.children.reduce((sum, child) => sum + countNodes(child), 0);
+  let count = 0;
+  const stack: ViewNode[] = [node];
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    count += 1;
+    if (current.kind === 'element') {
+      for (const child of current.children) stack.push(child);
+    }
+  }
+  return count;
 }

package/src/tunnel.test.ts

@@ -1,99 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { isCliTunnelAvailable, spawnCliTunnel } from './tunnel.js';
-
-const URL_RE = /https:\/\/[a-z0-9-]+\.example\.test/i;
-
-describe('spawnCliTunnel', () => {
-  it('resolves the parsed URL + pid when the child prints a matching line', async () => {
-    const handle = await spawnCliTunnel({
-      cmd: process.execPath,
-      // Print a noise line, then the URL, then stay alive so close() can kill it.
-      args: ['-e', 'console.log("starting up"); console.log("url=https://abc-123.example.test ready"); setInterval(()=>{}, 1000);'],
-      urlRegex: URL_RE,
-      name: 'faketunnel',
-      timeoutMs: 5_000,
-    });
-    expect(handle.url).toBe('https://abc-123.example.test');
-    expect(handle.pid).toBeGreaterThan(0);
-    await handle.close();
-  });
-
-  it('parses URLs printed on stderr too', async () => {
-    const handle = await spawnCliTunnel({
-      cmd: process.execPath,
-      args: ['-e', 'console.error("https://err-host.example.test"); setInterval(()=>{}, 1000);'],
-      urlRegex: URL_RE,
-      timeoutMs: 5_000,
-    });
-    expect(handle.url).toBe('https://err-host.example.test');
-    await handle.close();
-  });
-
-  it('u125-1: resolves a URL split across two stdout chunks', async () => {
-    // Write the URL in two separate process.stdout.write calls, split
-    // mid-host, with a tick gap so they surface as distinct 'data' events.
-    // Matching each chunk in isolation would miss it; the rolling buffer must
-    // stitch them.
-    const handle = await spawnCliTunnel({
-      cmd: process.execPath,
-      args: [
-        '-e',
-        'process.stdout.write("ready https://abc-1");' +
-          'setTimeout(()=>{process.stdout.write("23.example.test\\n");},50);' +
-          'setInterval(()=>{}, 1000);',
-      ],
-      urlRegex: URL_RE,
-      name: 'splittunnel',
-      timeoutMs: 5_000,
-    });
-    expect(handle.url).toBe('https://abc-123.example.test');
-    await handle.close();
-  });
-
-  it('rejects when the child exits before emitting a URL', async () => {
-    await expect(
-      spawnCliTunnel({
-        cmd: process.execPath,
-        args: ['-e', 'process.exit(3)'],
-        urlRegex: URL_RE,
-        name: 'faketunnel',
-        timeoutMs: 5_000,
-      }),
-    ).rejects.toThrow(/faketunnel exited \(code 3\) before emitting a URL/);
-  });
-
-  it('rejects when the executable cannot be spawned', async () => {
-    await expect(
-      spawnCliTunnel({
-        cmd: 'definitely-not-a-real-binary-xyz',
-        args: [],
-        urlRegex: URL_RE,
-        name: 'nope',
-        timeoutMs: 2_000,
-      }),
-    ).rejects.toThrow();
-  });
-
-  it('rejects on timeout when no URL is ever printed (and kills the child)', async () => {
-    await expect(
-      spawnCliTunnel({
-        cmd: process.execPath,
-        args: ['-e', 'setInterval(()=>{}, 1000);'],
-        urlRegex: URL_RE,
-        name: 'slowtunnel',
-        timeoutMs: 150,
-      }),
-    ).rejects.toThrow(/slowtunnel: timed out after 150ms/);
-  });
-});
-
-describe('isCliTunnelAvailable', () => {
-  it('resolves true for an installed runnable binary', async () => {
-    // node is always present in the test runtime and supports --version.
-    expect(await isCliTunnelAvailable(process.execPath)).toBe(true);
-  });
-
-  it('resolves false for a missing binary', async () => {
-    expect(await isCliTunnelAvailable('definitely-not-a-real-binary-xyz')).toBe(false);
-  });
-});