@moxxy/plugin-view 0.26.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { type LifecycleHooks, type Plugin, type ViewDoc, type ViewRendererDef } from '@moxxy/sdk';
+/**
+ * A live view surface the tool can query for the public URL + the next view id
+ * (supplied by the web channel once it co-attaches). Optional: when absent,
+ * `present_view` still parses + validates, it just returns no URL.
+ */
+export interface ViewSurface {
+    /** The currently reachable URL of the surface, or null if not yet up. */
+    readonly url: string | null;
+    /** Allocate the next view id for the turn that is presenting. */
+    nextViewId(): string;
+}
+export interface BuildViewPluginOptions {
+    /**
+     * Returns the session's active view renderer. A closure (not the renderer
+     * itself) so `setActive`/plugin replacement is honored at call time —
+     * ToolContext exposes no session handle, so this is how the tool reaches it.
+     */
+    getRenderer: () => ViewRendererDef | null;
+    /** Returns the live web surface, if one is co-attached. */
+    getSurface?: () => ViewSurface | null;
+}
+export declare function buildViewPlugin(opts: BuildViewPluginOptions, hooks?: LifecycleHooks): Plugin;
+/**
+ * Discovery-loadable default export. Resolves the active view-renderer registry
+ * (`'viewRenderers'`) and the shared web-surface ref (`'viewSurface'`, published
+ * by the host + written by the web channel) from the inter-plugin service
+ * registry in `onInit`, so `present_view` reaches them without a host-injected
+ * `{ getRenderer, getSurface }` closure. Both reads are lazy (at tool-call time),
+ * and degrade to "no renderer"/"no surface" if the host hasn't published them.
+ */
+export declare const viewPlugin: Plugin;
+export interface PresentViewResult {
+    readonly ok: boolean;
+    /**
+     * Whether a live web surface is ATTACHED (false = parsed only, no surface).
+     * NOT a delivery confirmation: the view is handed to the surface
+     * asynchronously when the channel's projector observes this tool_result, so
+     * `rendered: true` only means a surface exists to deliver to — a browser may
+     * not yet be connected to it. Do not treat it as "the user definitely sees
+     * the screen".
+     */
+    readonly rendered: boolean;
+    readonly url?: string;
+    readonly viewId?: string;
+    readonly nodeCount?: number;
+    /** Validated AST — the web surface reads this from the tool_result. */
+    readonly ast?: ViewDoc;
+    readonly errors?: ReadonlyArray<{
+        message: string;
+        line?: number;
+    }>;
+}
+export default viewPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,MAAM,EACX,KAAK,OAAO,EAGZ,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AAiCpB;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,iEAAiE;IACjE,UAAU,IAAI,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,WAAW,EAAE,MAAM,eAAe,GAAG,IAAI,CAAC;IAC1C,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;CACvC;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,MAAM,CAkH5F;AAUD;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAE,MAgBrB,CAAC;AAEL,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrE;AAGD,eAAe,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,173 @@
+import { defineTool, definePlugin, z, } from '@moxxy/sdk';
+/**
+ * Hard ceiling on the validated AST size. The zod `spec` cap (20k chars) only
+ * bounds the *source* — rich components (e.g. `results`) expand at parse time
+ * into many primitives, and a swapped-in custom renderer is not bound by core's
+ * parse-depth cap at all. The full AST is JSON-serialized into the tool_result,
+ * round-trips back into model context, and is streamed verbatim to every
+ * web-surface client, so it must be bounded independently of the source length.
+ */
+const MAX_VIEW_NODES = 2_000;
+/**
+ * Iterative (stack-safe) node count. Unlike the recursive `countNodes` in the
+ * SDK, this cannot overflow the call stack on a pathologically deep AST that a
+ * custom renderer might return (core's default parser caps depth, but a
+ * swapped-in renderer need not). Short-circuits once `limit` is exceeded so a
+ * huge tree is rejected without walking all of it.
+ */
+function countNodesBounded(root, limit) {
+    const stack = [root];
+    let count = 0;
+    while (stack.length > 0) {
+        const node = stack.pop();
+        count++;
+        if (count > limit)
+            return count;
+        if (node.kind === 'element') {
+            for (const child of node.children)
+                stack.push(child);
+        }
+    }
+    return count;
+}
+export function buildViewPlugin(opts, hooks) {
+    const presentView = defineTool({
+        name: 'present_view',
+        description: 'Render a screen of a generative UI (a "generative / dynamic / agentic UI") from a view-spec ' +
+            '(JSX-like, allow-listed tags). Read the `generative-ui` skill first. Use this only when the ' +
+            'user explicitly asks for a generative / dynamic / agentic UI (or interactive UI) for X — NOT ' +
+            "for ordinary searches or questions, which stay plain text. Give each screen a <view name>; " +
+            'call once per screen. The view appears on the user’s web surface; share the returned `url` ' +
+            'with them. When the user interacts (submits a form / clicks a button) it arrives as a normal ' +
+            'follow-up user message containing a `[ui-action]` block — read it and respond, usually by ' +
+            'calling present_view again under the same `name` to update the screen in place.',
+        inputSchema: z.object({
+            spec: z
+                .string()
+                .min(1)
+                .max(20_000)
+                .describe('The view-spec source, a single <view>…</view> root with allow-listed tags.'),
+            fallbackText: z
+                .string()
+                .max(2_000)
+                .optional()
+                .describe('Plain-text summary shown on channels that cannot render views.'),
+        }),
+        handler: (input, ctx) => {
+            // Short-circuit a cancelled turn before the heaviest work (parse + count
+            // + AST serialization on a near-20k spec). ctx is optional only so unit
+            // tests can call the handler bare; the registry always supplies it.
+            if (ctx?.signal?.aborted) {
+                return { ok: false, rendered: false, errors: [{ message: 'aborted' }] };
+            }
+            const renderer = opts.getRenderer();
+            if (!renderer) {
+                return { ok: false, rendered: false, errors: [{ message: 'no active view renderer' }] };
+            }
+            // `renderer.parse` is a caller-supplied closure: core's default renderer
+            // never throws (it wraps everything, even a RangeError, into a structured
+            // result), but a swapped-in custom renderer carries no such guarantee. A
+            // throw here would surface as a generic turn-level error instead of a
+            // structured tool result, so guard it like every other external closure.
+            let result;
+            try {
+                result = renderer.parse(input.spec);
+            }
+            catch (e) {
+                const message = e instanceof Error && e.message ? e.message : 'view renderer failed';
+                return { ok: false, rendered: false, errors: [{ message }] };
+            }
+            if (!result.ok) {
+                // `errors` may be malformed (custom renderer); degrade to a single
+                // generic error rather than throwing on a non-iterable `.map`.
+                const errs = Array.isArray(result.errors)
+                    ? result.errors.map((e) => ({ message: e?.message ?? 'parse error', line: e?.line }))
+                    : [{ message: 'view renderer reported a parse failure' }];
+                return { ok: false, rendered: false, errors: errs };
+            }
+            // A custom renderer can return `ok:true` with a missing/null doc or root;
+            // reject with an honest message instead of letting the count below crash
+            // and report "too deeply nested".
+            const root = result.doc?.root;
+            if (root == null || (root.kind !== 'element' && root.kind !== 'text')) {
+                return { ok: false, rendered: false, errors: [{ message: 'view renderer returned a malformed AST' }] };
+            }
+            // Bound the AST independently of the source length. countNodesBounded is
+            // iterative so a deep tree from a custom renderer cannot overflow the
+            // stack; we still wrap defensively so the handler can never throw.
+            let nodeCount;
+            try {
+                nodeCount = countNodesBounded(root, MAX_VIEW_NODES);
+            }
+            catch {
+                return { ok: false, rendered: false, errors: [{ message: 'view too deeply nested' }] };
+            }
+            if (nodeCount > MAX_VIEW_NODES) {
+                return {
+                    ok: false,
+                    rendered: false,
+                    errors: [{ message: `view too large (${nodeCount}+ nodes; max ${MAX_VIEW_NODES})` }],
+                };
+            }
+            // The surface closures are caller-supplied and read mutable shared state
+            // (web channel minter); never let a fault there turn a successful parse
+            // into a turn-level throw — degrade to the documented parsed-only result.
+            let surface = null;
+            let viewId;
+            try {
+                surface = opts.getSurface?.() ?? null;
+                viewId = surface?.nextViewId();
+                // An empty-string id is a minter fault, not "no surface": treat the
+                // surface as absent rather than claiming rendered:true with no id.
+                if (surface != null && (viewId == null || viewId === '')) {
+                    surface = null;
+                    viewId = undefined;
+                }
+            }
+            catch {
+                surface = null;
+                viewId = undefined;
+            }
+            return {
+                ok: true,
+                rendered: surface != null,
+                ...(surface?.url ? { url: surface.url } : {}),
+                ...(viewId != null ? { viewId } : {}),
+                nodeCount,
+                ast: result.doc,
+            };
+        },
+    });
+    // No hardcoded `version`: it only ever drifts from package.json. The real
+    // package version is captured from the resolved plugin manifest at load time.
+    return definePlugin({
+        name: '@moxxy/plugin-view',
+        tools: [presentView],
+        ...(hooks ? { hooks } : {}),
+    });
+}
+/**
+ * Discovery-loadable default export. Resolves the active view-renderer registry
+ * (`'viewRenderers'`) and the shared web-surface ref (`'viewSurface'`, published
+ * by the host + written by the web channel) from the inter-plugin service
+ * registry in `onInit`, so `present_view` reaches them without a host-injected
+ * `{ getRenderer, getSurface }` closure. Both reads are lazy (at tool-call time),
+ * and degrade to "no renderer"/"no surface" if the host hasn't published them.
+ */
+export const viewPlugin = (() => {
+    let renderers = null;
+    let surface = null;
+    const hooks = {
+        onInit: (ctx) => {
+            renderers = ctx.services.get('viewRenderers') ?? null;
+            surface = ctx.services.get('viewSurface') ?? null;
+        },
+    };
+    return buildViewPlugin({
+        getRenderer: () => renderers?.getActive() ?? null,
+        getSurface: () => surface?.current ?? null,
+    }, hooks);
+})();
+// Discovery entry: `createPluginLoader` requires a default Plugin export.
+export default viewPlugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@moxxy/plugin-view",
+  "version": "0.26.0",
+  "description": "Agent-authored UIs for moxxy. A present_view tool parses the agent's JSX-like view-spec (via the active view renderer) into a validated AST that channels render as rich interactive UI.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "tools",
+    "ui",
+    "present-view"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-view"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "tools"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.24.0",
+    "@moxxy/sdk": "0.26.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/vitest-preset": "0.0.0",
+    "@moxxy/core": "0.26.0",
+    "@moxxy/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/discovery.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ServiceRegistry } from '@moxxy/sdk';
+import { viewPlugin } from './index.js';
+
+/**
+ * The discovery-loadable default export resolves the active view-renderer
+ * registry + the shared web-surface ref from the service registry in onInit,
+ * instead of the host `{ getRenderer, getSurface }` closure.
+ */
+describe('viewPlugin (discovery-loadable)', () => {
+  it('exposes present_view + an onInit hook', () => {
+    expect(viewPlugin.tools?.map((t) => t.name)).toEqual(['present_view']);
+    expect(typeof viewPlugin.hooks?.onInit).toBe('function');
+  });
+
+  it('onInit resolves viewRenderers + viewSurface from the registry', () => {
+    const get = vi.fn((name: string) =>
+      name === 'viewRenderers'
+        ? { getActive: () => null }
+        : name === 'viewSurface'
+          ? { current: null }
+          : undefined,
+    );
+    const services = { get, register: () => {}, require: () => undefined, has: () => true } as unknown as ServiceRegistry;
+    viewPlugin.hooks!.onInit!({ services } as never);
+    expect(get).toHaveBeenCalledWith('viewRenderers');
+    expect(get).toHaveBeenCalledWith('viewSurface');
+  });
+});

package/src/index.test.ts

@@ -0,0 +1,229 @@
+import { describe, expect, it } from 'vitest';
+import type { ToolContext, ToolDef, ViewNode, ViewParseResult, ViewRendererDef } from '@moxxy/sdk';
+import { defaultViewRenderer } from '@moxxy/core';
+import { buildViewPlugin, type PresentViewResult } from './index.js';
+
+function toolOf(plugin: ReturnType<typeof buildViewPlugin>): ToolDef {
+  const tool = plugin.tools?.find((t) => t.name === 'present_view');
+  if (!tool) throw new Error('present_view tool not found');
+  return tool;
+}
+
+const ctx = {} as ToolContext;
+
+/** A renderer whose parse returns the supplied doc unconditionally — lets us
+ * feed the handler ASTs that core's depth/node caps would normally reject. */
+function fixedRenderer(root: ViewNode): ViewRendererDef {
+  return {
+    name: 'fixed',
+    allowList: [],
+    parse: (): ViewParseResult => ({ ok: true, doc: { root } }),
+    validate: () => [],
+  };
+}
+
+/** A linearly-nested `stack` chain `depth` levels deep. */
+function deepChain(depth: number): ViewNode {
+  let node: ViewNode = { kind: 'text', value: 'leaf' };
+  for (let i = 0; i < depth; i++) {
+    node = { kind: 'element', tag: 'stack', props: {}, children: [node] };
+  }
+  return node;
+}
+
+/** A wide `stack` with `n` direct text children. */
+function wideStack(n: number): ViewNode {
+  const children: ViewNode[] = [];
+  for (let i = 0; i < n; i++) children.push({ kind: 'text', value: 'x' });
+  return { kind: 'element', tag: 'stack', props: {}, children };
+}
+
+describe('present_view tool', () => {
+  const tool = toolOf(buildViewPlugin({ getRenderer: () => defaultViewRenderer }));
+  const call = (spec: string) => tool.handler({ spec }, ctx) as PresentViewResult;
+
+  it('returns the validated AST for a good spec', () => {
+    const r = call(`<view title="x"><text>hi</text></view>`);
+    expect(r.ok).toBe(true);
+    expect(r.ast?.title).toBe('x');
+    expect(r.nodeCount).toBeGreaterThan(0);
+    // No surface attached → parsed only.
+    expect(r.rendered).toBe(false);
+  });
+
+  it('returns errors for a bad spec without throwing', () => {
+    const r = call(`<view><script>x</script></view>`);
+    expect(r.ok).toBe(false);
+    expect(r.errors?.[0]?.message).toMatch(/unknown tag/);
+  });
+
+  it('surfaces the url + viewId when a surface is attached', () => {
+    const t = toolOf(
+      buildViewPlugin({
+        getRenderer: () => defaultViewRenderer,
+        getSurface: () => ({ url: 'https://x.trycloudflare.com/?t=abc', nextViewId: () => 'v_1' }),
+      }),
+    );
+    const r = t.handler({ spec: `<view><text>hi</text></view>` }, ctx) as PresentViewResult;
+    expect(r.ok).toBe(true);
+    expect(r.url).toContain('trycloudflare');
+    expect(r.viewId).toBe('v_1');
+    expect(r.rendered).toBe(true);
+  });
+
+  it('reports no active renderer gracefully', () => {
+    const t = toolOf(buildViewPlugin({ getRenderer: () => null }));
+    const r = t.handler({ spec: `<view><text>hi</text></view>` }, ctx) as PresentViewResult;
+    expect(r.ok).toBe(false);
+    expect(r.errors?.[0]?.message).toMatch(/no active view renderer/);
+  });
+
+  it('rejects an over-large AST (node-count ceiling) without serializing it', () => {
+    // A custom renderer can emit an AST far past what the 20k-char source cap
+    // implies; the handler must reject on node count, not return the AST.
+    const t = toolOf(buildViewPlugin({ getRenderer: () => fixedRenderer(wideStack(5_000)) }));
+    const r = t.handler({ spec: '<view/>' }, ctx) as PresentViewResult;
+    expect(r.ok).toBe(false);
+    expect(r.rendered).toBe(false);
+    expect(r.ast).toBeUndefined();
+    expect(r.errors?.[0]?.message).toMatch(/view too large/);
+  });
+
+  it('does not throw (no stack overflow) on a pathologically deep AST', () => {
+    // Deeper than any recursion limit; iterative counting + node cap must turn
+    // this into a structured error, never a RangeError out of the handler.
+    const t = toolOf(buildViewPlugin({ getRenderer: () => fixedRenderer(deepChain(200_000)) }));
+    let r: PresentViewResult;
+    expect(() => {
+      r = t.handler({ spec: '<view/>' }, ctx) as PresentViewResult;
+    }).not.toThrow();
+    expect(r!.ok).toBe(false);
+    expect(r!.ast).toBeUndefined();
+  });
+
+  it('accepts an AST exactly at the ceiling', () => {
+    // 1 (stack) + 1999 text children = 2000 nodes — must pass.
+    const t = toolOf(buildViewPlugin({ getRenderer: () => fixedRenderer(wideStack(1_999)) }));
+    const r = t.handler({ spec: '<view/>' }, ctx) as PresentViewResult;
+    expect(r.ok).toBe(true);
+    expect(r.nodeCount).toBe(2_000);
+  });
+
+  it('degrades to rendered:false when getSurface throws', () => {
+    const t = toolOf(
+      buildViewPlugin({
+        getRenderer: () => defaultViewRenderer,
+        getSurface: () => {
+          throw new Error('surface mid-teardown');
+        },
+      }),
+    );
+    const r = t.handler({ spec: '<view><text>hi</text></view>' }, ctx) as PresentViewResult;
+    expect(r.ok).toBe(true);
+    expect(r.rendered).toBe(false);
+    expect(r.viewId).toBeUndefined();
+    expect(r.url).toBeUndefined();
+  });
+
+  it('degrades to rendered:false when nextViewId throws', () => {
+    const t = toolOf(
+      buildViewPlugin({
+        getRenderer: () => defaultViewRenderer,
+        getSurface: () => ({
+          url: 'https://x.trycloudflare.com/?t=k',
+          nextViewId: () => {
+            throw new Error('minter corrupted');
+          },
+        }),
+      }),
+    );
+    const r = t.handler({ spec: '<view><text>hi</text></view>' }, ctx) as PresentViewResult;
+    expect(r.ok).toBe(true);
+    expect(r.rendered).toBe(false);
+    expect(r.viewId).toBeUndefined();
+  });
+
+  it('treats an empty-string viewId as a surface fault (rendered:false, no id)', () => {
+    const t = toolOf(
+      buildViewPlugin({
+        getRenderer: () => defaultViewRenderer,
+        getSurface: () => ({ url: 'https://x.trycloudflare.com/?t=k', nextViewId: () => '' }),
+      }),
+    );
+    const r = t.handler({ spec: '<view><text>hi</text></view>' }, ctx) as PresentViewResult;
+    expect(r.ok).toBe(true);
+    expect(r.rendered).toBe(false);
+    expect(r.viewId).toBeUndefined();
+    expect(r.url).toBeUndefined();
+  });
+
+  it('degrades to a structured error when a custom renderer.parse throws', () => {
+    // The default renderer never throws, but a swapped-in custom renderer is
+    // not bound by that guarantee — a throw must become a tool error, not a
+    // turn-level exception out of the handler.
+    const throwing: ViewRendererDef = {
+      name: 'throwing',
+      allowList: [],
+      parse: () => {
+        throw new Error('renderer exploded');
+      },
+      validate: () => [],
+    };
+    const t = toolOf(buildViewPlugin({ getRenderer: () => throwing }));
+    let r: PresentViewResult;
+    expect(() => {
+      r = t.handler({ spec: '<view/>' }, ctx) as PresentViewResult;
+    }).not.toThrow();
+    expect(r!.ok).toBe(false);
+    expect(r!.rendered).toBe(false);
+    expect(r!.errors?.[0]?.message).toMatch(/renderer exploded/);
+  });
+
+  it('rejects a malformed AST (missing root) with an honest message', () => {
+    // A custom renderer claims ok:true but returns no usable root; the handler
+    // must reject cleanly (and NOT mislabel it "too deeply nested").
+    const malformed: ViewRendererDef = {
+      name: 'malformed',
+      allowList: [],
+      parse: () => ({ ok: true, doc: { root: undefined } as unknown as ViewParseResult['doc'] }) as ViewParseResult,
+      validate: () => [],
+    };
+    const t = toolOf(buildViewPlugin({ getRenderer: () => malformed }));
+    let r: PresentViewResult;
+    expect(() => {
+      r = t.handler({ spec: '<view/>' }, ctx) as PresentViewResult;
+    }).not.toThrow();
+    expect(r!.ok).toBe(false);
+    expect(r!.ast).toBeUndefined();
+    expect(r!.errors?.[0]?.message).toMatch(/malformed AST/);
+  });
+
+  it('degrades when a custom renderer reports a failure with non-iterable errors', () => {
+    // ok:false but `errors` is not an array — the handler must not throw on
+    // `.map` and must surface a generic failure instead.
+    const bad: ViewRendererDef = {
+      name: 'bad-errors',
+      allowList: [],
+      parse: () => ({ ok: false, errors: null as unknown as [] }) as ViewParseResult,
+      validate: () => [],
+    };
+    const t = toolOf(buildViewPlugin({ getRenderer: () => bad }));
+    let r: PresentViewResult;
+    expect(() => {
+      r = t.handler({ spec: '<view/>' }, ctx) as PresentViewResult;
+    }).not.toThrow();
+    expect(r!.ok).toBe(false);
+    expect(r!.errors?.[0]?.message).toMatch(/parse failure/);
+  });
+
+  it('short-circuits when the turn is already aborted', () => {
+    const t = toolOf(buildViewPlugin({ getRenderer: () => defaultViewRenderer }));
+    const ac = new AbortController();
+    ac.abort();
+    const abortedCtx = { signal: ac.signal } as unknown as ToolContext;
+    const r = t.handler({ spec: '<view><text>hi</text></view>' }, abortedCtx) as PresentViewResult;
+    expect(r.ok).toBe(false);
+    expect(r.rendered).toBe(false);
+    expect(r.errors?.[0]?.message).toMatch(/aborted/);
+  });
+});

package/src/index.ts

@@ -0,0 +1,237 @@
+import {
+  defineTool,
+  definePlugin,
+  z,
+  type LifecycleHooks,
+  type Plugin,
+  type ViewDoc,
+  type ViewNode,
+  type ToolContext,
+  type ViewRendererDef,
+} from '@moxxy/sdk';
+
+/**
+ * Hard ceiling on the validated AST size. The zod `spec` cap (20k chars) only
+ * bounds the *source* — rich components (e.g. `results`) expand at parse time
+ * into many primitives, and a swapped-in custom renderer is not bound by core's
+ * parse-depth cap at all. The full AST is JSON-serialized into the tool_result,
+ * round-trips back into model context, and is streamed verbatim to every
+ * web-surface client, so it must be bounded independently of the source length.
+ */
+const MAX_VIEW_NODES = 2_000;
+
+/**
+ * Iterative (stack-safe) node count. Unlike the recursive `countNodes` in the
+ * SDK, this cannot overflow the call stack on a pathologically deep AST that a
+ * custom renderer might return (core's default parser caps depth, but a
+ * swapped-in renderer need not). Short-circuits once `limit` is exceeded so a
+ * huge tree is rejected without walking all of it.
+ */
+function countNodesBounded(root: ViewNode, limit: number): number {
+  const stack: ViewNode[] = [root];
+  let count = 0;
+  while (stack.length > 0) {
+    const node = stack.pop()!;
+    count++;
+    if (count > limit) return count;
+    if (node.kind === 'element') {
+      for (const child of node.children) stack.push(child);
+    }
+  }
+  return count;
+}
+
+/**
+ * A live view surface the tool can query for the public URL + the next view id
+ * (supplied by the web channel once it co-attaches). Optional: when absent,
+ * `present_view` still parses + validates, it just returns no URL.
+ */
+export interface ViewSurface {
+  /** The currently reachable URL of the surface, or null if not yet up. */
+  readonly url: string | null;
+  /** Allocate the next view id for the turn that is presenting. */
+  nextViewId(): string;
+}
+
+export interface BuildViewPluginOptions {
+  /**
+   * Returns the session's active view renderer. A closure (not the renderer
+   * itself) so `setActive`/plugin replacement is honored at call time —
+   * ToolContext exposes no session handle, so this is how the tool reaches it.
+   */
+  getRenderer: () => ViewRendererDef | null;
+  /** Returns the live web surface, if one is co-attached. */
+  getSurface?: () => ViewSurface | null;
+}
+
+export function buildViewPlugin(opts: BuildViewPluginOptions, hooks?: LifecycleHooks): Plugin {
+  const presentView = defineTool({
+    name: 'present_view',
+    description:
+      'Render a screen of a generative UI (a "generative / dynamic / agentic UI") from a view-spec ' +
+      '(JSX-like, allow-listed tags). Read the `generative-ui` skill first. Use this only when the ' +
+      'user explicitly asks for a generative / dynamic / agentic UI (or interactive UI) for X — NOT ' +
+      "for ordinary searches or questions, which stay plain text. Give each screen a <view name>; " +
+      'call once per screen. The view appears on the user’s web surface; share the returned `url` ' +
+      'with them. When the user interacts (submits a form / clicks a button) it arrives as a normal ' +
+      'follow-up user message containing a `[ui-action]` block — read it and respond, usually by ' +
+      'calling present_view again under the same `name` to update the screen in place.',
+    inputSchema: z.object({
+      spec: z
+        .string()
+        .min(1)
+        .max(20_000)
+        .describe('The view-spec source, a single <view>…</view> root with allow-listed tags.'),
+      fallbackText: z
+        .string()
+        .max(2_000)
+        .optional()
+        .describe('Plain-text summary shown on channels that cannot render views.'),
+    }),
+    handler: (input, ctx?: ToolContext): PresentViewResult => {
+      // Short-circuit a cancelled turn before the heaviest work (parse + count
+      // + AST serialization on a near-20k spec). ctx is optional only so unit
+      // tests can call the handler bare; the registry always supplies it.
+      if (ctx?.signal?.aborted) {
+        return { ok: false, rendered: false, errors: [{ message: 'aborted' }] };
+      }
+      const renderer = opts.getRenderer();
+      if (!renderer) {
+        return { ok: false, rendered: false, errors: [{ message: 'no active view renderer' }] };
+      }
+      // `renderer.parse` is a caller-supplied closure: core's default renderer
+      // never throws (it wraps everything, even a RangeError, into a structured
+      // result), but a swapped-in custom renderer carries no such guarantee. A
+      // throw here would surface as a generic turn-level error instead of a
+      // structured tool result, so guard it like every other external closure.
+      let result: ReturnType<ViewRendererDef['parse']>;
+      try {
+        result = renderer.parse(input.spec);
+      } catch (e) {
+        const message = e instanceof Error && e.message ? e.message : 'view renderer failed';
+        return { ok: false, rendered: false, errors: [{ message }] };
+      }
+      if (!result.ok) {
+        // `errors` may be malformed (custom renderer); degrade to a single
+        // generic error rather than throwing on a non-iterable `.map`.
+        const errs = Array.isArray(result.errors)
+          ? result.errors.map((e) => ({ message: e?.message ?? 'parse error', line: e?.line }))
+          : [{ message: 'view renderer reported a parse failure' }];
+        return { ok: false, rendered: false, errors: errs };
+      }
+      // A custom renderer can return `ok:true` with a missing/null doc or root;
+      // reject with an honest message instead of letting the count below crash
+      // and report "too deeply nested".
+      const root = result.doc?.root;
+      if (root == null || (root.kind !== 'element' && root.kind !== 'text')) {
+        return { ok: false, rendered: false, errors: [{ message: 'view renderer returned a malformed AST' }] };
+      }
+      // Bound the AST independently of the source length. countNodesBounded is
+      // iterative so a deep tree from a custom renderer cannot overflow the
+      // stack; we still wrap defensively so the handler can never throw.
+      let nodeCount: number;
+      try {
+        nodeCount = countNodesBounded(root, MAX_VIEW_NODES);
+      } catch {
+        return { ok: false, rendered: false, errors: [{ message: 'view too deeply nested' }] };
+      }
+      if (nodeCount > MAX_VIEW_NODES) {
+        return {
+          ok: false,
+          rendered: false,
+          errors: [{ message: `view too large (${nodeCount}+ nodes; max ${MAX_VIEW_NODES})` }],
+        };
+      }
+      // The surface closures are caller-supplied and read mutable shared state
+      // (web channel minter); never let a fault there turn a successful parse
+      // into a turn-level throw — degrade to the documented parsed-only result.
+      let surface: ViewSurface | null = null;
+      let viewId: string | undefined;
+      try {
+        surface = opts.getSurface?.() ?? null;
+        viewId = surface?.nextViewId();
+        // An empty-string id is a minter fault, not "no surface": treat the
+        // surface as absent rather than claiming rendered:true with no id.
+        if (surface != null && (viewId == null || viewId === '')) {
+          surface = null;
+          viewId = undefined;
+        }
+      } catch {
+        surface = null;
+        viewId = undefined;
+      }
+      return {
+        ok: true,
+        rendered: surface != null,
+        ...(surface?.url ? { url: surface.url } : {}),
+        ...(viewId != null ? { viewId } : {}),
+        nodeCount,
+        ast: result.doc,
+      };
+    },
+  });
+
+  // No hardcoded `version`: it only ever drifts from package.json. The real
+  // package version is captured from the resolved plugin manifest at load time.
+  return definePlugin({
+    name: '@moxxy/plugin-view',
+    tools: [presentView],
+    ...(hooks ? { hooks } : {}),
+  });
+}
+
+/** Minimal views of the services view consumes — avoids importing @moxxy/core. */
+interface ActiveRendererSource {
+  getActive(): ViewRendererDef | null;
+}
+interface ViewSurfaceRef {
+  readonly current: ViewSurface | null;
+}
+
+/**
+ * Discovery-loadable default export. Resolves the active view-renderer registry
+ * (`'viewRenderers'`) and the shared web-surface ref (`'viewSurface'`, published
+ * by the host + written by the web channel) from the inter-plugin service
+ * registry in `onInit`, so `present_view` reaches them without a host-injected
+ * `{ getRenderer, getSurface }` closure. Both reads are lazy (at tool-call time),
+ * and degrade to "no renderer"/"no surface" if the host hasn't published them.
+ */
+export const viewPlugin: Plugin = (() => {
+  let renderers: ActiveRendererSource | null = null;
+  let surface: ViewSurfaceRef | null = null;
+  const hooks: LifecycleHooks = {
+    onInit: (ctx) => {
+      renderers = ctx.services.get<ActiveRendererSource>('viewRenderers') ?? null;
+      surface = ctx.services.get<ViewSurfaceRef>('viewSurface') ?? null;
+    },
+  };
+  return buildViewPlugin(
+    {
+      getRenderer: () => renderers?.getActive() ?? null,
+      getSurface: () => surface?.current ?? null,
+    },
+    hooks,
+  );
+})();
+
+export interface PresentViewResult {
+  readonly ok: boolean;
+  /**
+   * Whether a live web surface is ATTACHED (false = parsed only, no surface).
+   * NOT a delivery confirmation: the view is handed to the surface
+   * asynchronously when the channel's projector observes this tool_result, so
+   * `rendered: true` only means a surface exists to deliver to — a browser may
+   * not yet be connected to it. Do not treat it as "the user definitely sees
+   * the screen".
+   */
+  readonly rendered: boolean;
+  readonly url?: string;
+  readonly viewId?: string;
+  readonly nodeCount?: number;
+  /** Validated AST — the web surface reads this from the tool_result. */
+  readonly ast?: ViewDoc;
+  readonly errors?: ReadonlyArray<{ message: string; line?: number }>;
+}
+
+// Discovery entry: `createPluginLoader` requires a default Plugin export.
+export default viewPlugin;

package/src/integration.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { Session } from '@moxxy/core';
+import { buildViewPlugin, type PresentViewResult } from './index.js';
+
+/**
+ * Integration: a REAL Session (which seeds the default view renderer) with the
+ * view plugin registered, exercising present_view through the real tool
+ * registry — input is validated by the tool's zod schema, the handler reaches
+ * the session's active renderer via the closure, and returns the AST.
+ */
+function sessionWithView(): Session {
+  const session = new Session({ cwd: '/tmp', silent: true });
+  session.pluginHost.registerStatic(
+    buildViewPlugin({ getRenderer: () => session.viewRenderers.getActive() }),
+  );
+  return session;
+}
+
+describe('plugin-view integration with a real Session', () => {
+  it('registers present_view and the default renderer is active', () => {
+    const session = sessionWithView();
+    expect(session.tools.has('present_view')).toBe(true);
+    expect(session.viewRenderers.getActive()?.name).toBe('moxxy/default');
+  });
+
+  it('executes present_view end-to-end and returns a validated AST', async () => {
+    const session = sessionWithView();
+    const out = (await session.tools.execute(
+      'present_view',
+      { spec: '<view title="Trip"><stack><text>hi</text></stack></view>' },
+      new AbortController().signal,
+    )) as PresentViewResult;
+    expect(out.ok).toBe(true);
+    expect(out.ast?.title).toBe('Trip');
+    expect(out.ast?.root.kind === 'element' && out.ast.root.tag).toBe('view');
+  });
+
+  it('returns parse errors (not a throw) for a disallowed tag', async () => {
+    const session = sessionWithView();
+    const out = (await session.tools.execute(
+      'present_view',
+      { spec: '<view><iframe/></view>' },
+      new AbortController().signal,
+    )) as PresentViewResult;
+    expect(out.ok).toBe(false);
+    expect(out.errors?.some((e) => /unknown tag <iframe>/.test(e.message))).toBe(true);
+  });
+
+  it('rejects schema-invalid input at the registry boundary', async () => {
+    const session = sessionWithView();
+    await expect(
+      session.tools.execute('present_view', { spec: '' }, new AbortController().signal),
+    ).rejects.toThrow(/Invalid input/);
+  });
+
+  it('honours a swapped-in renderer via setActive', async () => {
+    const session = sessionWithView();
+    session.viewRenderers.replace({
+      name: 'stub',
+      allowList: [],
+      parse: () => ({ ok: true, doc: { root: { kind: 'element', tag: 'view', props: {}, children: [] } } }),
+      validate: () => [],
+    });
+    session.viewRenderers.setActive('stub');
+    const out = (await session.tools.execute(
+      'present_view',
+      { spec: 'anything the stub ignores' },
+      new AbortController().signal,
+    )) as PresentViewResult;
+    expect(out.ok).toBe(true);
+    expect(out.ast?.root.kind === 'element' && out.ast.root.tag).toBe('view');
+  });
+});

package/src/present-view.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+import type { ToolContext, ToolDef } from '@moxxy/sdk';
+import { defaultViewRenderer } from '@moxxy/core';
+import { buildViewPlugin, type PresentViewResult, type ViewSurface } from './index.js';
+
+const ctx = {} as ToolContext;
+function tool(surface?: ViewSurface | null): ToolDef {
+  const plugin = buildViewPlugin({
+    getRenderer: () => defaultViewRenderer,
+    ...(surface !== undefined ? { getSurface: () => surface } : {}),
+  });
+  const t = plugin.tools?.find((x) => x.name === 'present_view');
+  if (!t) throw new Error('present_view missing');
+  return t;
+}
+const run = (t: ToolDef, spec: string) => t.handler({ spec }, ctx) as PresentViewResult;
+
+describe('present_view — input schema', () => {
+  const t = tool();
+  it('requires a non-empty spec', () => {
+    expect(t.inputSchema.safeParse({ spec: '' }).success).toBe(false);
+    expect(t.inputSchema.safeParse({ spec: '<view/>' }).success).toBe(true);
+  });
+  it('caps spec length at 20k', () => {
+    expect(t.inputSchema.safeParse({ spec: 'x'.repeat(20_001) }).success).toBe(false);
+    expect(t.inputSchema.safeParse({ spec: 'x'.repeat(20_000) }).success).toBe(true);
+  });
+  it('accepts an optional fallbackText (capped)', () => {
+    expect(t.inputSchema.safeParse({ spec: '<view/>', fallbackText: 'summary' }).success).toBe(true);
+    expect(t.inputSchema.safeParse({ spec: '<view/>', fallbackText: 'x'.repeat(2_001) }).success).toBe(false);
+  });
+});
+
+describe('present_view — output', () => {
+  it('returns a view-rooted AST and an accurate nodeCount', () => {
+    const r = run(tool(), '<view title="t"><stack><text>a</text><text>b</text></stack></view>');
+    expect(r.ok).toBe(true);
+    expect(r.ast?.root.kind).toBe('element');
+    expect(r.ast?.root.kind === 'element' && r.ast.root.tag).toBe('view');
+    // view > stack > (text>txt, text>txt) = 1 + 1 + (2 + 2) = 6
+    expect(r.nodeCount).toBe(6);
+  });
+
+  it('surfaces parse errors with messages', () => {
+    const r = run(tool(), '<view><iframe/></view>');
+    expect(r.ok).toBe(false);
+    expect(r.rendered).toBe(false);
+    expect(r.errors?.some((e) => /unknown tag <iframe>/.test(e.message))).toBe(true);
+  });
+
+  it('reports no active renderer', () => {
+    const plugin = buildViewPlugin({ getRenderer: () => null });
+    const t = plugin.tools!.find((x) => x.name === 'present_view')!;
+    const r = run(t, '<view/>');
+    expect(r.ok).toBe(false);
+    expect(r.errors?.[0]?.message).toMatch(/no active view renderer/);
+  });
+
+  it('without a surface: rendered=false, no url/viewId', () => {
+    const r = run(tool(null), '<view/>');
+    expect(r.ok).toBe(true);
+    expect(r.rendered).toBe(false);
+    expect(r.url).toBeUndefined();
+    expect(r.viewId).toBeUndefined();
+  });
+
+  it('with a surface: returns url and a fresh viewId each call', () => {
+    let n = 0;
+    const surface: ViewSurface = { url: 'https://x.trycloudflare.com/?t=k', nextViewId: () => `v_${++n}` };
+    const t = tool(surface);
+    const a = run(t, '<view/>');
+    const b = run(t, '<view/>');
+    expect(a.rendered).toBe(true);
+    expect(a.url).toBe('https://x.trycloudflare.com/?t=k');
+    expect(a.viewId).toBe('v_1');
+    expect(b.viewId).toBe('v_2');
+  });
+});
+
+describe('present_view — plugin shape', () => {
+  it('contributes exactly the present_view tool', () => {
+    const plugin = buildViewPlugin({ getRenderer: () => defaultViewRenderer });
+    expect(plugin.tools?.map((t) => t.name)).toEqual(['present_view']);
+    expect(plugin.name).toBe('@moxxy/plugin-view');
+  });
+});