@moxxy/sdk 0.1.0

package/dist/transcriber.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=transcriber.d.ts.map

package/dist/transcriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcriber.d.ts","sourceRoot":"","sources":["../src/transcriber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,UAAU,CACR,KAAK,EAAE,UAAU,GAAG,WAAW,EAC/B,IAAI,CAAC,EAAE,iBAAiB,GACvB,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC;CAC5D"}

package/dist/transcriber.js

@@ -0,0 +1,21 @@
+/**
+ * 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 {};
+//# sourceMappingURL=transcriber.js.map

package/dist/transcriber.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcriber.js","sourceRoot":"","sources":["../src/transcriber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/tunnel.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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>;
+}
+//# sourceMappingURL=tunnel.d.ts.map

package/dist/tunnel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.d.ts","sourceRoot":"","sources":["../src/tunnel.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,IAAI,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACrD,4EAA4E;IAC5E,WAAW,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAClC"}

package/dist/tunnel.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tunnel.js.map

package/dist/tunnel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.js","sourceRoot":"","sources":["../src/tunnel.ts"],"names":[],"mappings":""}

package/dist/type-contracts.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=type-contracts.d.ts.map

package/dist/type-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-contracts.d.ts","sourceRoot":"","sources":["../src/type-contracts.ts"],"names":[],"mappings":""}

package/dist/type-contracts.js

@@ -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'] });
+//# sourceMappingURL=type-contracts.js.map

package/dist/type-contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-contracts.js","sourceRoot":"","sources":["../src/type-contracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,+FAA+F;AAC/F,YAAY,CAAC,EAAE,IAAI,EAAE,0BAA0B,EAAE,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC"}

package/dist/types.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.test-d.d.ts.map

package/dist/types.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.test-d.d.ts","sourceRoot":"","sources":["../src/types.test-d.ts"],"names":[],"mappings":""}

package/dist/types.test-d.js

@@ -0,0 +1,22 @@
+import { describe, expectTypeOf, it } from 'vitest';
+describe('event union narrowing', () => {
+    it('MoxxyEventOfType narrows correctly', () => {
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+    });
+    it('switch on type narrows the union', () => {
+        const handle = (e) => {
+            if (e.type === 'user_prompt') {
+                expectTypeOf(e).toEqualTypeOf();
+                return e.text;
+            }
+            if (e.type === 'tool_call_requested') {
+                expectTypeOf(e).toEqualTypeOf();
+                return e.name;
+            }
+            return null;
+        };
+        expectTypeOf(handle).returns.toEqualTypeOf();
+    });
+});
+//# sourceMappingURL=types.test-d.js.map

package/dist/types.test-d.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.test-d.js","sourceRoot":"","sources":["../src/types.test-d.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAQpD,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,YAAY,EAAmC,CAAC,aAAa,EAAmB,CAAC;QACjF,YAAY,EAA2C,CAAC,aAAa,EAA0B,CAAC;IAClG,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,MAAM,GAAG,CAAC,CAAa,EAAE,EAAE;YAC/B,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;gBAC7B,YAAY,CAAC,CAAC,CAAC,CAAC,aAAa,EAAmB,CAAC;gBACjD,OAAO,CAAC,CAAC,IAAI,CAAC;YAChB,CAAC;YACD,IAAI,CAAC,CAAC,IAAI,KAAK,qBAAqB,EAAE,CAAC;gBACrC,YAAY,CAAC,CAAC,CAAC,CAAC,aAAa,EAA0B,CAAC;gBACxD,OAAO,CAAC,CAAC,IAAI,CAAC;YAChB,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC,CAAC;QACF,YAAY,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,aAAa,EAAiB,CAAC;IAC9D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/view-renderer.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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>;
+};
+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>;
+}
+/** Primitives — the frontend renders these directly (keymap === these tags). */
+export declare const VIEW_PRIMITIVES: ReadonlyArray<ViewTagSpec>;
+/**
+ * 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 declare const VIEW_COMPONENTS: ReadonlyArray<ViewTagSpec>;
+/** The default renderer's full allow-list (primitives + components). */
+export declare const DEFAULT_VIEW_TAGS: ReadonlyArray<ViewTagSpec>;
+//# sourceMappingURL=view-renderer.d.ts.map

package/dist/view-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-renderer.d.ts","sourceRoot":"","sources":["../src/view-renderer.ts"],"names":[],"mappings":"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"}

package/dist/view-renderer.js

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ */
+const TONE = ['default', 'muted', 'success', 'warn', 'danger'];
+const GAP = ['none', 'sm', 'md', 'lg'];
+/** Primitives — the frontend renders these directly (keymap === these tags). */
+export const VIEW_PRIMITIVES = [
+    // 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 = [
+    { 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 = [...VIEW_PRIMITIVES, ...VIEW_COMPONENTS];
+//# sourceMappingURL=view-renderer.js.map

package/dist/view-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-renderer.js","sourceRoot":"","sources":["../src/view-renderer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@moxxy/sdk",
+  "version": "0.1.0",
+  "description": "Typed public surface for the moxxy framework: event types, define* factories, lifecycle hook signatures.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "zod": "^3.24.0",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/vitest-preset": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,38 @@
+/**
+ * Agent definitions — typed templates for subagent spawning. Each
+ * `AgentDef` describes a flavor of subagent (researcher, code-reviewer,
+ * summarizer, …) so plugins can register named agent kinds and the
+ * `dispatch_agent` tool can spawn them by type instead of relying on
+ * ad-hoc prompts.
+ *
+ * Why this lives in SDK (not core): the interface is the cross-package
+ * contract. Plugins import `AgentDef` from `@moxxy/sdk`, register
+ * agents via `PluginSpec.agents`, and the core's `AgentRegistry`
+ * surfaces them at runtime.
+ */
+export interface AgentDef {
+  /** Stable name; what `dispatch_agent({ agentType })` looks up. */
+  readonly name: string;
+  /** One-line user-visible summary — surfaced in the `/agents` modal. */
+  readonly description: string;
+  /**
+   * System prompt prepended to the child's first message. Use to set
+   * persona, output format, hard constraints, etc.
+   */
+  readonly systemPrompt?: string;
+  /**
+   * Mode name for the child. Defaults to `'tool-use'`. The
+   * spawner falls back to tool-use if the named strategy isn't
+   * registered (no point failing a child over a missing block).
+   */
+  readonly mode?: string;
+  /**
+   * Restrict the child to these tools by name. Omit for full
+   * inheritance from the parent's registry.
+   */
+  readonly allowedTools?: ReadonlyArray<string>;
+  /** Default model id; overrides the parent's active model. */
+  readonly model?: string;
+  /** Per-child iteration cap. Defaults to 50. */
+  readonly maxIterations?: number;
+}

package/src/cache-strategy.ts

@@ -0,0 +1,39 @@
+import type { EventLogReader } from './log.js';
+import type { CacheHint, ProviderMessage } from './provider.js';
+
+/**
+ * Context handed to a CacheStrategy when it plans breakpoints for one call.
+ */
+export interface CacheStrategyContext {
+  readonly model: string;
+  /** Active model's context window, for strategies that scale behavior to it. */
+  readonly contextWindow: number;
+  readonly log: EventLogReader;
+  /**
+   * Index (into the `messages` array passed to `plan`) of the last message
+   * belonging to the stable, cacheable prefix — everything at or before it is
+   * byte-identical across the inner iterations of the current turn, so a
+   * rolling breakpoint placed here yields cache reads on every iteration.
+   * Undefined when the mode can't compute a boundary (e.g. no elision active);
+   * strategies should then fall back to a conservative breakpoint.
+   */
+  readonly stablePrefixMessageIndex?: number;
+}
+
+/**
+ * A swappable prompt-caching strategy. One is active per session (registered
+ * via plugins, exactly like compactors/modes). It decides *where* cache
+ * breakpoints go and returns provider-neutral {@link CacheHint}s; the provider
+ * is responsible for *how* to express them (Anthropic → `cache_control`).
+ *
+ * `plan` MUST be deterministic given identical inputs — a non-deterministic
+ * breakpoint placement shifts the cached prefix between calls and silently
+ * defeats the cache (paying 1.25x writes for 0 reads).
+ */
+export interface CacheStrategyDef {
+  readonly name: string;
+  plan(
+    messages: ReadonlyArray<ProviderMessage>,
+    ctx: CacheStrategyContext,
+  ): ReadonlyArray<CacheHint>;
+}