@moxxy/sdk 0.1.0

package/src/tool.ts

@@ -0,0 +1,175 @@
+import type { z } from 'zod';
+import type { EventLogReader } from './log.js';
+import type { PermissionRule } from './permission.js';
+import type { SessionId, ToolCallId, TurnId } from './ids.js';
+import type { SubagentSpawner } from './subagent.js';
+import type { ToolIsolationSpec } from './isolation.js';
+
+/**
+ * Capability-mediated filesystem operations injected by isolators that
+ * support brokering. Handlers can opt in by checking `ctx.fs` at runtime
+ * and using these instead of `node:fs`; the broker validates each call
+ * against the tool's declared `caps.fs` spec on the parent side before
+ * executing.
+ *
+ * When `ctx.fs` is undefined (the `none`/`inproc` paths today, or any
+ * isolator that hasn't implemented a broker yet), handlers fall back to
+ * unmediated direct fs access.
+ */
+export interface BrokeredFs {
+  /** Read a UTF-8 file. Throws if the path is outside `caps.fs.read`. */
+  readFile(filePath: string, opts?: { encoding?: BufferEncoding }): Promise<string>;
+  /** Write a UTF-8 file (creates parent dirs). Throws if outside `caps.fs.write`. */
+  writeFile(filePath: string, data: string): Promise<void>;
+  /** List entries in a directory. Throws if outside `caps.fs.read`. */
+  readdir(dirPath: string): Promise<ReadonlyArray<string>>;
+  /** Stat a path. Throws if outside `caps.fs.read`. */
+  stat(filePath: string): Promise<BrokeredStat>;
+}
+
+export interface BrokeredStat {
+  readonly size: number;
+  readonly mtimeMs: number;
+  readonly isFile: boolean;
+  readonly isDirectory: boolean;
+}
+
+/**
+ * Capability-mediated `fetch`. Same shape as the global, but validated
+ * against `caps.net` on the parent side before the socket is opened.
+ *
+ * Returns a plain JSON-serializable response shape rather than the
+ * standard `Response` object — that's the price of crossing a process
+ * boundary cleanly.
+ */
+export interface BrokeredFetch {
+  (url: string, init?: BrokeredFetchInit): Promise<BrokeredFetchResponse>;
+}
+
+export interface BrokeredFetchInit {
+  readonly method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly body?: string;
+}
+
+export interface BrokeredFetchResponse {
+  readonly status: number;
+  readonly statusText: string;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+}
+
+/**
+ * Capability-mediated subprocess `exec`. Validated against `caps.subprocess`
+ * (must be true) and optional `caps.commands` allowlist on the parent side.
+ * Collects stdout/stderr and the exit code; for streaming use cases the
+ * broker layer will grow a separate streaming variant later.
+ */
+export interface BrokeredExec {
+  (
+    command: string,
+    args?: ReadonlyArray<string>,
+    opts?: BrokeredExecOpts,
+  ): Promise<BrokeredExecResult>;
+}
+
+export interface BrokeredExecOpts {
+  readonly cwd?: string;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly timeoutMs?: number;
+}
+
+export interface BrokeredExecResult {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number | null;
+}
+
+export interface ToolContext {
+  readonly sessionId: SessionId;
+  readonly turnId: TurnId;
+  readonly callId: ToolCallId;
+  readonly cwd: string;
+  readonly signal: AbortSignal;
+  readonly log: EventLogReader;
+  readonly logger: {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+  };
+  /**
+   * Spawner for child agents — present when the tool was invoked inside
+   * a run-turn loop (the normal case). Tools that fan work out (e.g.
+   * `dispatch_agent`) call `subagents.spawn(...)` to start a focused
+   * child loop and stream its events back to the parent log.
+   */
+  readonly subagents?: SubagentSpawner;
+  /**
+   * Capability-mediated filesystem ops. Present only when the active
+   * isolator implements a broker (currently `@moxxy/isolator-worker`).
+   * Handlers that use this get their fs access checked against
+   * `caps.fs` at every call, regardless of whether the path appeared
+   * in the validated input. Absent → handler is on its own for fs
+   * access (today's behavior).
+   */
+  readonly fs?: BrokeredFs;
+  /**
+   * Capability-mediated network. Present only when the active
+   * isolator implements a broker. Validates every URL against
+   * `caps.net` on the parent side. Returns a serializable response
+   * shape so the same value crosses a process boundary intact.
+   */
+  readonly fetch?: BrokeredFetch;
+  /**
+   * Capability-mediated subprocess execution. Present only when the
+   * active isolator implements a broker. Validated against
+   * `caps.subprocess` + optional `caps.commands` allowlist.
+   */
+  readonly exec?: BrokeredExec;
+}
+
+/**
+ * Optional presentation hint for compact rendering in TUI/chat surfaces.
+ * When present, the channel may aggregate consecutive calls of this tool
+ * into one "live block" with a verb+count summary, rather than rendering
+ * each call separately. Opting in is per-tool: noisy small-output tools
+ * (Read, Grep, Glob, Edit) benefit; tools with rich output (Bash,
+ * dispatch_agent) generally don't.
+ *
+ * Channels MAY ignore this hint — it's purely presentational. The event
+ * log and provider serialization don't see it.
+ */
+export interface ToolCompactPresentation {
+  /** Present-participle verb used in summary, e.g. "Reading", "Searching for". */
+  readonly verb: string;
+  /** Noun for the count, pluralized e.g. `{ one: 'file', other: 'files' }`. */
+  readonly noun: { readonly one: string; readonly other: string };
+  /** Input field whose value previews the latest call (the line under the summary).
+   *  e.g. `"file_path"` for Read so the preview shows the file just read. */
+  readonly previewKey?: string;
+}
+
+export interface ToolDef {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: z.ZodTypeAny;
+  /**
+   * Optional native JSON Schema. When present, providers serializing tools to
+   * their API should use this instead of converting `inputSchema` via zod.
+   * Useful for tools originating from external systems (e.g., MCP) that already
+   * carry a JSON Schema and where zod conversion would be lossy.
+   */
+  readonly inputJsonSchema?: unknown;
+  readonly outputSchema?: z.ZodTypeAny;
+  readonly permission?: PermissionRule;
+  readonly handler: (input: unknown, ctx: ToolContext) => Promise<unknown> | unknown;
+  /** Opt-in presentation hint. See `ToolCompactPresentation`. */
+  readonly compact?: ToolCompactPresentation;
+  /**
+   * Optional capability declaration. Advisory unless the user enables
+   * `@moxxy/plugin-security`, at which point the active `Isolator`
+   * enforces these bounds at every call. See `ToolIsolationSpec`.
+   */
+  readonly isolation?: ToolIsolationSpec;
+}

package/src/transcriber.ts

@@ -0,0 +1,71 @@
+/**
+ * Transcribers convert audio bytes into text. They are a separate capability
+ * from `LLMProvider` because (a) most providers (Anthropic today) do not yet
+ * accept native audio, (b) users frequently want to pair a text provider with
+ * a dedicated STT backend (Whisper, Deepgram, AssemblyAI, local whisper.cpp),
+ * and (c) the same transcript may be used in many places — channels feeding
+ * voice notes into a turn, skills processing recorded meetings, etc.
+ *
+ * Plugins register a `TranscriberDef` via `PluginSpec.transcribers`. The
+ * core `TranscriberRegistry` holds them; channels call
+ * `session.transcribers.getActive()` (or `.get(name)`) to use one.
+ *
+ * Audio input is represented in two places once a `Transcriber` is wired:
+ *   - `UserPromptAttachment` with `kind: 'audio'` — channel-level handoff,
+ *     consumed by the channel and either transcribed or sent through as a
+ *     native audio block (provider-permitting).
+ *   - `ContentBlock` with `type: 'audio'` — provider-level wire format, only
+ *     used by models that advertise `supportsAudio: true`.
+ */
+
+export interface TranscriptionSegment {
+  /** Segment start, in seconds from the start of the clip. */
+  readonly start: number;
+  /** Segment end, in seconds. */
+  readonly end: number;
+  readonly text: string;
+  /** Optional speaker label when the backend supports diarization. */
+  readonly speaker?: string;
+}
+
+export interface TranscriptionResult {
+  /** Full concatenated transcript. */
+  readonly text: string;
+  /** BCP-47 language tag when the backend reports one (e.g. `en`, `pl`). */
+  readonly language?: string;
+  /** Clip length in seconds when known. */
+  readonly durationSec?: number;
+  /** Optional per-segment breakdown for richer downstream use. */
+  readonly segments?: ReadonlyArray<TranscriptionSegment>;
+}
+
+export interface TranscribeOptions {
+  /** MIME type of the audio bytes (e.g. `audio/ogg`, `audio/webm`). */
+  readonly mimeType?: string;
+  /** Hint the recognizer with a BCP-47 language tag. */
+  readonly language?: string;
+  /** Vocabulary / context hint passed to backends that support it (Whisper). */
+  readonly prompt?: string;
+  /** Cancellation signal — channels propagate the turn's abort here. */
+  readonly signal?: AbortSignal;
+}
+
+export interface Transcriber {
+  /** Short stable name, e.g. `openai-whisper-1`. */
+  readonly name: string;
+  transcribe(
+    audio: Uint8Array | ArrayBuffer,
+    opts?: TranscribeOptions,
+  ): Promise<TranscriptionResult>;
+}
+
+/**
+ * Plugin-side definition. Mirrors `ProviderDef`: a `createClient(config)`
+ * factory the registry calls when the user activates this transcriber.
+ */
+export interface TranscriberDef {
+  readonly name: string;
+  /** Optional human-readable label for UI surfaces. */
+  readonly displayName?: string;
+  createClient(config: Record<string, unknown>): Transcriber;
+}

package/src/tunnel.ts

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+export interface TunnelOpenOptions {
+  readonly port: number;
+  readonly host: string;
+}
+
+export interface TunnelHandle {
+  /** The publicly reachable base URL (e.g. https://abc.trycloudflare.com). */
+  readonly url: string;
+  /** Tear the tunnel down (kill the subprocess, close the connection). */
+  close(): Promise<void>;
+}
+
+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). */
+  isAvailable?(): Promise<boolean>;
+}

package/src/type-contracts.ts

@@ -0,0 +1,4 @@
+import { definePlugin } from './define.js';
+
+// @ts-expect-error dependsOn was replaced by requirements and is no longer part of PluginSpec.
+definePlugin({ name: 'legacy-dependency-plugin', dependsOn: ['base'] });

package/src/types.test-d.ts

@@ -0,0 +1,29 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  MoxxyEvent,
+  MoxxyEventOfType,
+  ToolCallRequestedEvent,
+  UserPromptEvent,
+} from './events.js';
+
+describe('event union narrowing', () => {
+  it('MoxxyEventOfType narrows correctly', () => {
+    expectTypeOf<MoxxyEventOfType<'user_prompt'>>().toEqualTypeOf<UserPromptEvent>();
+    expectTypeOf<MoxxyEventOfType<'tool_call_requested'>>().toEqualTypeOf<ToolCallRequestedEvent>();
+  });
+
+  it('switch on type narrows the union', () => {
+    const handle = (e: MoxxyEvent) => {
+      if (e.type === 'user_prompt') {
+        expectTypeOf(e).toEqualTypeOf<UserPromptEvent>();
+        return e.text;
+      }
+      if (e.type === 'tool_call_requested') {
+        expectTypeOf(e).toEqualTypeOf<ToolCallRequestedEvent>();
+        return e.name;
+      }
+      return null;
+    };
+    expectTypeOf(handle).returns.toEqualTypeOf<string | null>();
+  });
+});

package/src/view-renderer.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+import {
+  VIEW_PRIMITIVES,
+  VIEW_COMPONENTS,
+  DEFAULT_VIEW_TAGS,
+  defineViewRenderer,
+  defineTunnelProvider,
+  type ViewTagSpec,
+} from './index.js';
+
+describe('view vocabulary integrity', () => {
+  const all = DEFAULT_VIEW_TAGS;
+
+  it('DEFAULT_VIEW_TAGS is primitives + components', () => {
+    expect(all.length).toBe(VIEW_PRIMITIVES.length + VIEW_COMPONENTS.length);
+  });
+
+  it('has no duplicate tag names', () => {
+    const names = all.map((t) => t.tag);
+    expect(new Set(names).size).toBe(names.length);
+  });
+
+  it('every tag has a valid allowedChildren', () => {
+    for (const t of all) {
+      const ac = t.allowedChildren;
+      const valid = ac === 'any' || ac === 'none' || Array.isArray(ac);
+      expect(valid, `${t.tag} allowedChildren`).toBe(true);
+    }
+  });
+
+  it('every array allowedChildren references known tags', () => {
+    const known = new Set(all.map((t) => t.tag));
+    for (const t of all) {
+      if (Array.isArray(t.allowedChildren)) {
+        for (const child of t.allowedChildren) {
+          expect(known.has(child), `${t.tag} -> ${child}`).toBe(true);
+        }
+      }
+    }
+  });
+
+  it('enum attrs declare their allowed values; number attrs may declare bounds', () => {
+    for (const t of all) {
+      for (const [name, spec] of Object.entries(t.attrs)) {
+        if (spec.type === 'enum') {
+          expect(Array.isArray(spec.values) && spec.values.length > 0, `${t.tag}.${name}`).toBe(true);
+        }
+      }
+    }
+  });
+
+  it('marks interactive elements and rich components correctly', () => {
+    const byTag = (tag: string): ViewTagSpec => all.find((t) => t.tag === tag)!;
+    expect(byTag('form').interactive).toBe(true);
+    expect(byTag('button').interactive).toBe(true);
+    expect(byTag('text').interactive).toBeUndefined();
+    expect(VIEW_COMPONENTS.every((c) => c.component)).toBe(true);
+    expect(VIEW_PRIMITIVES.every((p) => !p.component)).toBe(true);
+  });
+
+  it('declares the expected required attributes', () => {
+    const required = (tag: string) =>
+      Object.entries(DEFAULT_VIEW_TAGS.find((t) => t.tag === tag)!.attrs)
+        .filter(([, s]) => s.required)
+        .map(([n]) => n)
+        .sort();
+    expect(required('input')).toEqual(['name']);
+    expect(required('form')).toEqual(['action']);
+    // action is optional on button now (a button may navigate via `to` instead).
+    expect(required('button')).toEqual(['label']);
+    expect(required('image')).toEqual(['src']);
+    expect(required('option')).toEqual(['value']);
+    expect(required('result')).toEqual(['title']);
+  });
+});
+
+describe('define factories freeze their specs', () => {
+  it('defineViewRenderer', () => {
+    const def = defineViewRenderer({ name: 'x', allowList: [], parse: () => ({ ok: false, errors: [] }), validate: () => [] });
+    expect(Object.isFrozen(def)).toBe(true);
+    expect(() => {
+      (def as { name: string }).name = 'y';
+    }).toThrow();
+  });
+
+  it('defineTunnelProvider', () => {
+    const def = defineTunnelProvider({ name: 't', open: () => Promise.resolve({ url: 'http://x', close: () => Promise.resolve() }) });
+    expect(Object.isFrozen(def)).toBe(true);
+  });
+});

package/src/view-renderer.ts

@@ -0,0 +1,156 @@
+/**
+ * Agent-authored UI view-spec — the contract shared by the parser (core) and
+ * the renderer (web channel frontend).
+ *
+ * An agent emits a small JSX/XML-like document; a {@link ViewRendererDef} parses
+ * it into a validated {@link ViewDoc} AST against a strict tag/attribute
+ * **allow-list** (no raw HTML / script passthrough). One renderer is active per
+ * session, registered via plugins exactly like compactors / cache-strategies.
+ *
+ * The tag vocabulary ({@link VIEW_PRIMITIVES} / {@link VIEW_COMPONENTS}) is plain
+ * data so the browser frontend can import the SAME allow-list the parser
+ * validates against — preventing the two-list drift that would open an XSS gap.
+ */
+
+/** A node in the validated view AST. After parsing, only primitives remain. */
+export type ViewNode =
+  | {
+      readonly kind: 'element';
+      readonly tag: string;
+      readonly props: Readonly<Record<string, string | number | boolean>>;
+      readonly children: ReadonlyArray<ViewNode>;
+      /** Present on interactive elements (`form`, `button`) — drives an agent turn. */
+      readonly action?: ViewAction;
+      /**
+       * Client-side navigation target (a `view` `name`). Set from a `to` attr on
+       * `link`/`button`. The frontend switches to the named cached view WITHOUT an
+       * agent turn; if it isn't cached yet it falls back to a `navigate:<name>` turn.
+       */
+      readonly nav?: string;
+    }
+  | { readonly kind: 'text'; readonly value: string };
+
+/** Declared on an interactive element; the transport turns it into a turn. */
+export interface ViewAction {
+  /** Opaque name the agent chose, e.g. `search_flights`, `select:UA42`. */
+  readonly name: string;
+  /** Input `name`s whose current values this action carries back. */
+  readonly fields: ReadonlyArray<string>;
+}
+
+export interface ViewDoc {
+  readonly root: ViewNode;
+  readonly title?: string;
+}
+
+export interface ViewParseError {
+  readonly message: string;
+  readonly line?: number;
+  readonly col?: number;
+}
+
+export type ViewParseResult =
+  | { readonly ok: true; readonly doc: ViewDoc }
+  | { readonly ok: false; readonly errors: ReadonlyArray<ViewParseError> };
+
+// ---------------------------------------------------------------------------
+// Shared vocabulary — plain data, the single source of truth.
+// ---------------------------------------------------------------------------
+
+export type AttrType = 'string' | 'number' | 'boolean' | 'enum';
+
+export interface AttrSpec {
+  readonly type: AttrType;
+  readonly required?: boolean;
+  /** Allowed values when `type === 'enum'`. */
+  readonly values?: ReadonlyArray<string>;
+  /** Inclusive bounds when `type === 'number'`. */
+  readonly min?: number;
+  readonly max?: number;
+}
+
+export interface ViewTagSpec {
+  readonly tag: string;
+  readonly attrs: Readonly<Record<string, AttrSpec>>;
+  /** Allowed child tags; `'any'` = any element + text, `'none'` = void. */
+  readonly allowedChildren: ReadonlyArray<string> | 'any' | 'none';
+  /** Carries a {@link ViewAction} (the parser synthesizes `node.action`). */
+  readonly interactive?: boolean;
+  /** A rich component the renderer expands into primitives at parse time. */
+  readonly component?: boolean;
+}
+
+/**
+ * A swappable view-spec renderer. `parse` turns source into a validated AST
+ * (rich components already expanded to primitives); `validate` re-checks an
+ * already-built AST against {@link allowList} — note it runs on EXPANDED
+ * primitives, a contract replacement renderers must preserve.
+ */
+export interface ViewRendererDef {
+  readonly name: string;
+  readonly allowList: ReadonlyArray<ViewTagSpec>;
+  parse(source: string): ViewParseResult;
+  validate(doc: ViewDoc): ReadonlyArray<ViewParseError>;
+}
+
+const TONE = ['default', 'muted', 'success', 'warn', 'danger'] as const;
+const GAP = ['none', 'sm', 'md', 'lg'] as const;
+
+/** Primitives — the frontend renders these directly (keymap === these tags). */
+export const VIEW_PRIMITIVES: ReadonlyArray<ViewTagSpec> = [
+  // layout / containers
+  { tag: 'view', attrs: { title: { type: 'string' }, name: { type: 'string' } }, allowedChildren: 'any' },
+  { tag: 'stack', attrs: { gap: { type: 'enum', values: GAP }, align: { type: 'enum', values: ['start', 'center', 'end', 'stretch'] } }, allowedChildren: 'any' },
+  { tag: 'row', attrs: { gap: { type: 'enum', values: GAP }, align: { type: 'enum', values: ['start', 'center', 'end', 'stretch'] }, justify: { type: 'enum', values: ['start', 'center', 'end', 'between'] } }, allowedChildren: 'any' },
+  { tag: 'grid', attrs: { cols: { type: 'number', required: true, min: 1, max: 6 }, gap: { type: 'enum', values: GAP } }, allowedChildren: 'any' },
+  { tag: 'card', attrs: { title: { type: 'string' }, accent: { type: 'enum', values: TONE } }, allowedChildren: 'any' },
+  { tag: 'divider', attrs: {}, allowedChildren: 'none' },
+  // loading states (show while fetching real data, then replace with results)
+  { tag: 'spinner', attrs: { label: { type: 'string' } }, allowedChildren: 'none' },
+  { tag: 'skeleton', attrs: { rows: { type: 'number', min: 1, max: 12 } }, allowedChildren: 'none' },
+  // display
+  { tag: 'heading', attrs: { level: { type: 'number', min: 1, max: 3 } }, allowedChildren: 'any' },
+  { tag: 'text', attrs: { tone: { type: 'enum', values: TONE }, weight: { type: 'enum', values: ['normal', 'bold'] } }, allowedChildren: 'any' },
+  { tag: 'badge', attrs: { tone: { type: 'enum', values: TONE } }, allowedChildren: 'any' },
+  { tag: 'image', attrs: { src: { type: 'string', required: true }, alt: { type: 'string' }, w: { type: 'number' }, h: { type: 'number' } }, allowedChildren: 'none' },
+  { tag: 'link', attrs: { href: { type: 'string' }, to: { type: 'string' } }, allowedChildren: 'any' },
+  { tag: 'list', attrs: { ordered: { type: 'boolean' } }, allowedChildren: ['item'] },
+  { tag: 'item', attrs: {}, allowedChildren: 'any' },
+  { tag: 'table', attrs: {}, allowedChildren: ['tr'] },
+  { tag: 'tr', attrs: {}, allowedChildren: ['th', 'td'] },
+  { tag: 'th', attrs: { align: { type: 'enum', values: ['left', 'center', 'right'] } }, allowedChildren: 'any' },
+  { tag: 'td', attrs: { align: { type: 'enum', values: ['left', 'center', 'right'] } }, allowedChildren: 'any' },
+  // inputs (only meaningful inside `form`)
+  { tag: 'form', attrs: { action: { type: 'string', required: true }, submit: { type: 'string' } }, allowedChildren: 'any', interactive: true },
+  { tag: 'input', attrs: { name: { type: 'string', required: true }, type: { type: 'enum', values: ['text', 'number', 'date', 'email'] }, label: { type: 'string' }, placeholder: { type: 'string' }, value: { type: 'string' }, required: { type: 'boolean' } }, allowedChildren: 'none' },
+  { tag: 'select', attrs: { name: { type: 'string', required: true }, label: { type: 'string' }, value: { type: 'string' }, required: { type: 'boolean' } }, allowedChildren: ['option'] },
+  { tag: 'option', attrs: { value: { type: 'string', required: true }, selected: { type: 'boolean' } }, allowedChildren: 'any' },
+  { tag: 'checkbox', attrs: { name: { type: 'string', required: true }, label: { type: 'string' }, checked: { type: 'boolean' } }, allowedChildren: 'none' },
+  // `action` drives an agent turn; `to` navigates client-side to a named view.
+  { tag: 'button', attrs: { action: { type: 'string' }, to: { type: 'string' }, label: { type: 'string', required: true }, variant: { type: 'enum', values: ['primary', 'secondary', 'danger'] }, fields: { type: 'string' } }, allowedChildren: 'none', interactive: true },
+];
+
+/**
+ * Rich components — accepted by the parser, expanded to primitives, never reach the
+ * frontend. Generic + domain-agnostic: a `results` list of selectable `result`s is
+ * the backbone of any "search engine / platform for X" the agent builds.
+ */
+export const VIEW_COMPONENTS: ReadonlyArray<ViewTagSpec> = [
+  { tag: 'results', attrs: {}, allowedChildren: ['result'], component: true },
+  {
+    tag: 'result',
+    attrs: {
+      title: { type: 'string', required: true },
+      subtitle: { type: 'string' },
+      badge: { type: 'string' },
+      id: { type: 'string' },
+      action: { type: 'string' }, // agent turn on select (default: open:<id>)
+      to: { type: 'string' }, // or client-side nav to a named view
+    },
+    allowedChildren: 'none',
+    component: true,
+  },
+];
+
+/** The default renderer's full allow-list (primitives + components). */
+export const DEFAULT_VIEW_TAGS: ReadonlyArray<ViewTagSpec> = [...VIEW_PRIMITIVES, ...VIEW_COMPONENTS];