@moxxy/plugin-channel-web 0.27.0

package/src/projector.ts

@@ -0,0 +1,95 @@
+import { isFileDiffDisplay, type MoxxyEvent, type ViewDoc } from '@moxxy/sdk';
+import type { ServerFrame } from './protocol.js';
+
+/**
+ * Cap on in-flight present_view calls awaiting their tool_result. A normal turn
+ * has at most a handful; entries only linger when a turn is aborted/errors before
+ * the tool resolves (no matching tool_result ever arrives). Bound it so an
+ * accumulation of aborts over a very long session can't leak unboundedly.
+ */
+const MAX_PENDING_CALLS = 64;
+
+/**
+ * Folds the session's event stream into {@link ServerFrame}s for the browser.
+ * Stateful: it correlates a `present_view` `tool_call_requested` with its
+ * `tool_result` (to read the validated AST) and tracks the last view id so each
+ * new view `replaces` the prior one. One projector per channel (single-user
+ * surface); it renders ANY turn on the shared log, including ones the surface
+ * didn't initiate — that is what gives mirror-to-both for free.
+ */
+export class EventProjector {
+  private readonly presentCalls = new Map<string, { fallbackText?: string }>();
+  private lastViewId: string | null = null;
+  private viewSeq = 0;
+
+  project(event: MoxxyEvent): ServerFrame[] {
+    switch (event.type) {
+      case 'user_prompt': {
+        // Hide the synthesized ui-action turns; show real user prompts.
+        if (!event.text.trim() || event.text.startsWith('[ui-action]')) return [];
+        return [{ kind: 'message', turnId: String(event.turnId), role: 'user', text: event.text }];
+      }
+      case 'tool_call_requested': {
+        if (event.name === 'present_view') {
+          const input = event.input as { fallbackText?: string } | undefined;
+          this.presentCalls.set(String(event.callId), { fallbackText: input?.fallbackText });
+          // Evict the oldest pending call(s) if a long run of aborted/errored
+          // turns left their tool_result-less entries stranded.
+          while (this.presentCalls.size > MAX_PENDING_CALLS) {
+            const oldest = this.presentCalls.keys().next().value;
+            if (oldest === undefined) break;
+            this.presentCalls.delete(oldest);
+          }
+          return [];
+        }
+        return [{ kind: 'status', turnId: String(event.turnId), phase: 'tool', text: `${event.name}…` }];
+      }
+      case 'tool_result': {
+        // Rich tool results (Write/Edit) carry a structured `display`; render
+        // the diff in the chat stream, independent of present_view correlation.
+        const display = (event.output as { display?: unknown } | undefined)?.display;
+        if (event.ok && isFileDiffDisplay(display)) {
+          return [{ kind: 'file-diff', turnId: String(event.turnId), display }];
+        }
+        const pending = this.presentCalls.get(String(event.callId));
+        if (!pending) return [];
+        this.presentCalls.delete(String(event.callId));
+        if (!event.ok) {
+          return [{ kind: 'status', turnId: String(event.turnId), phase: 'error', text: 'view failed to render' }];
+        }
+        const doc = (event.output as { ast?: ViewDoc } | undefined)?.ast;
+        if (!doc) return [];
+        const viewId = `v_${String(event.turnId)}_${++this.viewSeq}`;
+        const replaces = this.lastViewId;
+        this.lastViewId = viewId;
+        const name = doc.root.kind === 'element' && typeof doc.root.props.name === 'string' ? doc.root.props.name : undefined;
+        return [
+          {
+            kind: 'view',
+            viewId,
+            turnId: String(event.turnId),
+            replaces,
+            ...(name ? { name } : {}),
+            doc,
+            ...(pending.fallbackText ? { fallbackText: pending.fallbackText } : {}),
+          },
+        ];
+      }
+      case 'assistant_message': {
+        const frames: ServerFrame[] = [];
+        if (event.content.trim()) {
+          frames.push({ kind: 'message', turnId: String(event.turnId), role: 'assistant', text: event.content });
+        }
+        if (event.stopReason !== 'tool_use') {
+          frames.push({ kind: 'status', turnId: String(event.turnId), phase: 'done', text: '' });
+        }
+        return frames;
+      }
+      case 'error': {
+        return [{ kind: 'status', turnId: String(event.turnId), phase: 'error', text: event.message }];
+      }
+      default:
+        return [];
+    }
+  }
+}

package/src/protocol.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import { actionPrompt, clientFrameSchema } from './protocol.js';
+
+describe('clientFrameSchema', () => {
+  it('accepts a well-formed prompt frame', () => {
+    const r = clientFrameSchema.safeParse({ kind: 'prompt', text: 'hi' });
+    expect(r.success).toBe(true);
+  });
+
+  it('accepts a well-formed action frame (with and without params)', () => {
+    const base = { kind: 'action', actionId: 'a1', viewId: null, formValues: { from: 'SFO' } };
+    expect(clientFrameSchema.safeParse({ ...base, action: { name: 'go' } }).success).toBe(true);
+    expect(
+      clientFrameSchema.safeParse({ ...base, viewId: 'v1', action: { name: 'go', params: { id: 1 } } })
+        .success,
+    ).toBe(true);
+  });
+
+  it.each([
+    ['prompt without text (the crasher)', { kind: 'prompt' }],
+    ['prompt with non-string text', { kind: 'prompt', text: 42 }],
+    ['action without action', { kind: 'action', actionId: 'a', viewId: null, formValues: {} }],
+    ['action without actionId', { kind: 'action', viewId: null, action: { name: 'x' }, formValues: {} }],
+    ['action with non-string formValues', { kind: 'action', actionId: 'a', viewId: null, action: { name: 'x' }, formValues: { a: 1 } }],
+    ['action with non-string action.name', { kind: 'action', actionId: 'a', viewId: null, action: { name: 7 }, formValues: {} }],
+    ['unknown kind', { kind: 'nonsense' }],
+    ['missing kind', {}],
+    ['non-object', 'hello'],
+    ['null', null],
+  ])('rejects %s', (_label, frame) => {
+    expect(clientFrameSchema.safeParse(frame).success).toBe(false);
+  });
+});
+
+describe('actionPrompt', () => {
+  it('embeds the action + values as a fenced [ui-action] block', () => {
+    const p = actionPrompt({ name: 'search_flights' }, { from: 'SFO', to: 'JFK' });
+    expect(p).toContain('[ui-action]');
+    expect(p).toContain('```json');
+    const json = p.slice(p.indexOf('{'), p.lastIndexOf('}') + 1);
+    const parsed = JSON.parse(json) as { action: string; values: Record<string, string> };
+    expect(parsed.action).toBe('search_flights');
+    expect(parsed.values).toEqual({ from: 'SFO', to: 'JFK' });
+  });
+
+  it('includes params when present and is round-trippable JSON', () => {
+    const p = actionPrompt({ name: 'select', params: { id: 'UA42' } }, {});
+    const json = p.slice(p.indexOf('{'), p.lastIndexOf('}') + 1);
+    const parsed = JSON.parse(json) as { action: string; params: Record<string, unknown>; values: unknown };
+    expect(parsed.params).toEqual({ id: 'UA42' });
+    expect(parsed.values).toEqual({});
+  });
+
+  it('omits params key when absent', () => {
+    const p = actionPrompt({ name: 'x' }, { a: '1' });
+    const json = p.slice(p.indexOf('{'), p.lastIndexOf('}') + 1);
+    expect(JSON.parse(json)).not.toHaveProperty('params');
+  });
+});

package/src/protocol.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import type { FileDiffDisplay, ViewDoc } from '@moxxy/sdk';
+
+/**
+ * Wire protocol between the web surface server and the browser. Plain JSON over
+ * a WebSocket. Shared by the channel (Node) and the frontend (browser); keep it
+ * DOM-free so esbuild can bundle it for the browser. (The frontend imports
+ * ONLY types from this module, so the zod runtime never reaches the browser
+ * bundle.)
+ */
+
+/** Server → browser. */
+export type ServerFrame =
+  | { readonly kind: 'hello'; readonly sessionId?: string }
+  /**
+   * A new view to render.
+   *
+   * INVARIANT: the in-place-vs-push decision is driven SOLELY by the logical
+   * `name` (a re-render of the screen already on top updates in place; a
+   * different name pushes a history entry — see `applyView`). `replaces`
+   * carries the prior `viewId` purely as provenance/diagnostic context (the
+   * single-user projector emits the id of the view this one supersedes); it
+   * is NOT a navigation directive and the frontend reducer does not branch on
+   * it. Do not reintroduce `replaces`-based in-place logic without reconciling
+   * it with the name-keyed history/back model in view-store.ts.
+   */
+  | {
+      readonly kind: 'view';
+      readonly viewId: string;
+      readonly turnId: string;
+      readonly replaces: string | null;
+      /** Logical screen name (from `<view name>`), for client-side navigation/caching. */
+      readonly name?: string;
+      readonly doc: ViewDoc;
+      readonly fallbackText?: string;
+    }
+  /** Lightweight turn status (thinking / running a tool / done / error). */
+  | {
+      readonly kind: 'status';
+      readonly turnId: string;
+      readonly phase: 'thinking' | 'tool' | 'done' | 'error';
+      readonly text: string;
+    }
+  /** Assistant or user prose, mirrored into the transcript. */
+  | { readonly kind: 'message'; readonly turnId: string; readonly role: 'assistant' | 'user'; readonly text: string }
+  /** A structured file diff (from a Write/Edit tool result), rendered in the chat stream. */
+  | { readonly kind: 'file-diff'; readonly turnId: string; readonly display: FileDiffDisplay }
+  /** Acknowledge an inbound action. */
+  | { readonly kind: 'ack'; readonly actionId: string; readonly accepted: boolean; readonly reason?: string };
+
+/** Browser → server. */
+export type ClientFrame =
+  /** Free-text prompt typed into the surface's input box. */
+  | { readonly kind: 'prompt'; readonly text: string }
+  /** A form submission / button click from a rendered view. */
+  | {
+      readonly kind: 'action';
+      readonly actionId: string;
+      readonly viewId: string | null;
+      readonly action: { readonly name: string; readonly params?: Record<string, unknown> };
+      readonly formValues: Record<string, string>;
+    };
+
+/**
+ * Runtime validator for browser → server frames. The WS endpoint is
+ * internet-exposed via tunnels, so every inbound frame MUST be validated
+ * before any field access — a cast after JSON.parse let `{"kind":"prompt"}`
+ * throw inside the ws 'message' listener and take the whole process down.
+ * Mirrors {@link ClientFrame}; the drift guard below keeps them in sync.
+ */
+export const clientFrameSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('prompt'), text: z.string() }),
+  z.object({
+    kind: z.literal('action'),
+    actionId: z.string(),
+    viewId: z.string().nullable(),
+    action: z.object({ name: z.string(), params: z.record(z.unknown()).optional() }),
+    formValues: z.record(z.string()),
+  }),
+]);
+
+/** Compile-time drift guard: schema output and ClientFrame must stay mutually assignable. */
+type AssertTrue<T extends true> = T;
+export type _ClientFrameSchemaInSync = AssertTrue<
+  z.infer<typeof clientFrameSchema> extends ClientFrame
+    ? ClientFrame extends z.infer<typeof clientFrameSchema>
+      ? true
+      : false
+    : false
+>;
+
+/**
+ * Synthesize the user-turn prompt for a view action. The agent is taught (via
+ * the build-view skill) to read `[ui-action]` blocks and respond by calling
+ * present_view again. Kept here so the channel and any test share one format.
+ */
+export function actionPrompt(action: { name: string; params?: Record<string, unknown> }, formValues: Record<string, string>): string {
+  const payload = JSON.stringify({ action: action.name, ...(action.params ? { params: action.params } : {}), values: formValues });
+  return [
+    '[ui-action] The user interacted with the presented view.',
+    '```json',
+    payload,
+    '```',
+  ].join('\n');
+}

package/src/tunnel-settings.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { normalizeTunnelName, readTunnelSetting, readWebSettings, writeTunnelSetting } from './tunnel-settings.js';
+
+let dir: string;
+let file: string;
+beforeEach(() => {
+  dir = mkdtempSync(path.join(os.tmpdir(), 'mox-web-'));
+  file = path.join(dir, 'web.json');
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('tunnel-settings', () => {
+  it('normalizes "none"/local aliases to localhost', () => {
+    for (const a of ['none', 'None', 'local', 'off', 'loopback', 'LOOPBACK']) {
+      expect(normalizeTunnelName(a)).toBe('localhost');
+    }
+    expect(normalizeTunnelName('Proxy')).toBe('proxy');
+  });
+
+  it('returns undefined / {} when the file is missing', () => {
+    expect(readTunnelSetting(file)).toBeUndefined();
+    expect(readWebSettings(file)).toEqual({});
+  });
+
+  it('round-trips a written setting (normalized)', async () => {
+    await writeTunnelSetting('proxy', file);
+    expect(readTunnelSetting(file)).toBe('proxy');
+    await writeTunnelSetting('none', file);
+    expect(readTunnelSetting(file)).toBe('localhost');
+  });
+
+  it('tolerates a corrupt file', async () => {
+    await writeTunnelSetting('proxy', file);
+    // overwrite with garbage
+    rmSync(file);
+    expect(readTunnelSetting(file)).toBeUndefined();
+  });
+
+  // invariant 5: concurrent read-merge-write of web.json must not lose an
+  // update. Without the mutex the two writes both read the same snapshot and
+  // the second clobbers the first; with it the file ends last-writer-wins and
+  // stays well-formed.
+  it('serializes concurrent writeTunnelSetting (well-formed, one wins)', async () => {
+    await Promise.all([
+      writeTunnelSetting('cloudflared', file),
+      writeTunnelSetting('ngrok', file),
+    ]);
+    const survivor = readTunnelSetting(file);
+    expect(['cloudflared', 'ngrok']).toContain(survivor);
+    // The file must be valid JSON of the expected shape (no torn/partial write).
+    expect(readWebSettings(file)).toEqual({ tunnel: survivor });
+  });
+
+  it('survives many overlapping writers with a well-formed result', async () => {
+    const names = ['cloudflared', 'ngrok', 'localhost', 'cloudflared', 'ngrok'];
+    await Promise.all(names.map((n) => writeTunnelSetting(n, file)));
+    const survivor = readTunnelSetting(file);
+    expect(names).toContain(survivor);
+    expect(readWebSettings(file)).toEqual({ tunnel: survivor });
+  });
+});

package/src/tunnel-settings.ts

@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs';
+import { createMutex, z } from '@moxxy/sdk';
+import { moxxyPath, writeFileAtomic } from '@moxxy/sdk/server';
+
+/** Validates the on-disk web.json shape; a corrupt/foreign file is discarded. */
+const webSettingsSchema = z.object({ tunnel: z.string().optional() });
+
+/**
+ * Per-instance mutex serializing the read-merge-write of `web.json`. The atomic
+ * write prevents torn files, but two concurrent writes would otherwise both
+ * read the same snapshot and the second would clobber the first's merge.
+ * Mirrors provider-admin/store.ts.
+ */
+const writeMutex = createMutex();
+
+/**
+ * Persisted, user/agent-changeable choice of tunnel provider for the web
+ * surface — stored at `~/.moxxy/web.json`. Mirrors the providers.json pattern:
+ * the agent's `web_set_tunnel` tool writes it; the web plugin's onInit applies
+ * it on boot. Absent file → callers fall back to defaults.
+ */
+export interface WebSettings {
+  /** Active tunnel provider name (e.g. 'proxy', 'localhost'). */
+  readonly tunnel?: string;
+}
+
+export function webSettingsPath(): string {
+  return moxxyPath('web.json');
+}
+
+/** Normalize user-friendly aliases for "no tunnel" to the localhost provider. */
+export function normalizeTunnelName(name: string): string {
+  const n = name.trim().toLowerCase();
+  if (n === 'none' || n === 'local' || n === 'off' || n === 'loopback') return 'localhost';
+  return n;
+}
+
+export function readWebSettings(file = webSettingsPath()): WebSettings {
+  try {
+    const parsed = webSettingsSchema.safeParse(JSON.parse(readFileSync(file, 'utf8')));
+    return parsed.success ? parsed.data : {};
+  } catch {
+    return {};
+  }
+}
+
+export function readTunnelSetting(file = webSettingsPath()): string | undefined {
+  const t = readWebSettings(file).tunnel;
+  return typeof t === 'string' && t ? normalizeTunnelName(t) : undefined;
+}
+
+export async function writeTunnelSetting(name: string, file = webSettingsPath()): Promise<void> {
+  await writeMutex.run(async () => {
+    const next: WebSettings = { ...readWebSettings(file), tunnel: normalizeTunnelName(name) };
+    await writeFileAtomic(file, JSON.stringify(next, null, 2));
+  });
+}

package/src/tunnel-tools.test.ts

@@ -0,0 +1,120 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import type { LifecycleHooks, ToolContext, ToolDef } from '@moxxy/sdk';
+import { buildWebChannelPlugin, readTunnelSetting, writeTunnelSetting, type TunnelControls } from './index.js';
+
+const ctx = {} as ToolContext;
+
+/** In-memory tunnel registry for the tools to drive. */
+function fakeTunnels(available = new Set(['localhost', 'proxy'])): TunnelControls {
+  let active = 'localhost';
+  return {
+    list: () => ['localhost', 'proxy'],
+    active: () => active,
+    setActive: (n) => {
+      active = n;
+    },
+    isAvailable: (n) => Promise.resolve(available.has(n)),
+  };
+}
+
+let dir: string;
+let file: string;
+beforeEach(() => {
+  dir = mkdtempSync(path.join(os.tmpdir(), 'mox-tt-'));
+  file = path.join(dir, 'web.json');
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+function build(opts: Parameters<typeof buildWebChannelPlugin>[0]) {
+  const plugin = buildWebChannelPlugin(opts);
+  const tool = (n: string): ToolDef => {
+    const t = plugin.tools?.find((x) => x.name === n);
+    if (!t) throw new Error(`missing tool ${n}`);
+    return t;
+  };
+  return { plugin, set: tool('web_set_tunnel'), status: tool('web_tunnel_status') };
+}
+
+describe('web_tunnel_status', () => {
+  it('reports the active provider and options', () => {
+    const { status } = build({ tunnels: fakeTunnels(), settingsFile: file });
+    expect(status.handler({}, ctx)).toEqual({ active: 'localhost', available: ['none', 'localhost', 'proxy'] });
+  });
+});
+
+describe('web_set_tunnel', () => {
+  it('switches provider, persists, and reports the url via live retunnel', async () => {
+    const tunnels = fakeTunnels();
+    let retunnelled = 0;
+    const { set } = build({
+      tunnels,
+      settingsFile: file,
+      getControls: () => ({
+        retunnel: () => {
+          retunnelled++;
+          return Promise.resolve('https://abc123.proxy.moxxy.ai/web');
+        },
+      }),
+    });
+    const r = (await set.handler({ provider: 'proxy' }, ctx)) as { ok: boolean; active: string; url?: string };
+    expect(r.ok).toBe(true);
+    expect(r.active).toBe('proxy');
+    expect(r.url).toContain('proxy.moxxy.ai');
+    expect(retunnelled).toBe(1);
+    expect(tunnels.active()).toBe('proxy');
+    expect(readTunnelSetting(file)).toBe('proxy');
+  });
+
+  it('maps "none" to localhost', async () => {
+    const tunnels = fakeTunnels();
+    const { set } = build({ tunnels, settingsFile: file });
+    const r = (await set.handler({ provider: 'none' }, ctx)) as { active: string };
+    expect(r.active).toBe('localhost');
+    expect(readTunnelSetting(file)).toBe('localhost');
+  });
+
+  it('rejects an unknown provider', async () => {
+    const { set } = build({ tunnels: fakeTunnels(), settingsFile: file });
+    const r = (await set.handler({ provider: 'wireguard' }, ctx)) as { ok: boolean; error: string };
+    expect(r.ok).toBe(false);
+    expect(r.error).toMatch(/unknown tunnel/);
+  });
+
+  it('rejects an unavailable provider and does not persist', async () => {
+    const tunnels = fakeTunnels(new Set(['localhost'])); // proxy relay unreachable
+    const { set } = build({ tunnels, settingsFile: file });
+    const r = (await set.handler({ provider: 'proxy' }, ctx)) as { ok: boolean; error?: string };
+    expect(r.ok).toBe(false);
+    expect(r.error).toMatch(/not available/i);
+    expect(readTunnelSetting(file)).toBeUndefined();
+  });
+});
+
+describe('onInit applies the persisted / default tunnel', () => {
+  const fireInit = (hooks: LifecycleHooks | undefined) => (hooks?.onInit as (() => void) | undefined)?.();
+
+  it('applies a persisted setting on boot', async () => {
+    await writeTunnelSetting('proxy', file);
+    const tunnels = fakeTunnels();
+    const { plugin } = build({ tunnels, settingsFile: file });
+    fireInit(plugin.hooks);
+    expect(tunnels.active()).toBe('proxy');
+  });
+
+  it('falls back to the configured default when nothing is persisted', () => {
+    const tunnels = fakeTunnels();
+    const { plugin } = build({ tunnels, settingsFile: file, defaultTunnel: 'proxy' });
+    fireInit(plugin.hooks);
+    expect(tunnels.active()).toBe('proxy');
+  });
+
+  it('keeps the seeded default when neither is set', () => {
+    const tunnels = fakeTunnels();
+    const { plugin } = build({ tunnels, settingsFile: file });
+    fireInit(plugin.hooks);
+    expect(tunnels.active()).toBe('localhost');
+  });
+});