@zackbart/connecta 0.11.0 → 0.12.1

package/src/execute.ts

@@ -1,6 +1,10 @@
 import type { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import type { ActivityRequestContext } from "./activity.js";
+import {
+  PROGRAM_UI_META_KEY,
+  PROGRAM_UI_RESOURCE_URI,
+} from "./apps-shell.js";
 import {
   boundedDiscoveryText,
   CatalogService,
@@ -15,6 +19,7 @@ import {
 } from "./executor-result.js";
 import {
   ExecutorAdmissionError,
+  ExecutorExecutionError,
   isAdmittingExecutor,
 } from "./executor-admission.js";
 import { classifyCallError } from "./errors.js";
@@ -69,6 +74,7 @@ class ExecuteDiagnostics {
   setupMs = 0;
   executorWallMs = 0;
   private emitted?: { count: number; bytes: number };
+  private ui?: number;
 
   /** Numbers only, per R8 — and only once something was emitted, so a
    * non-emitting run's diagnostics stay byte-for-byte what they were. */
@@ -76,6 +82,15 @@ class ExecuteDiagnostics {
     if (count > 0) this.emitted = { count, bytes };
   }
 
+  /**
+   * U9: the UI payload gets its own aggregate — one number, the payload's
+   * serialized size. Folding it into `emitted` would desync that aggregate's
+   * pair, which reports the bytes a specific block count cost.
+   */
+  recordUi(bytes: number): void {
+    this.ui = bytes;
+  }
+
   private stats(operation: ExecuteDiagnosticOperation) {
     let stats = this.operations.get(operation);
     if (!stats) {
@@ -158,6 +173,7 @@ class ExecuteDiagnostics {
     };
     operations: ExecuteOperationDiagnostics[];
     emitted?: { count: number; bytes: number };
+    ui?: number;
   } {
     const operations = [...this.operations.values()];
     return {
@@ -174,6 +190,7 @@ class ExecuteDiagnostics {
       },
       operations,
       ...(this.emitted ? { emitted: this.emitted } : {}),
+      ...(this.ui !== undefined ? { ui: this.ui } : {}),
     };
   }
 }
@@ -231,16 +248,49 @@ function requireEmittedBlock(raw: unknown): EmittedBlock {
   return raw as EmittedBlock;
 }
 
+const UI_SHAPE_HINT =
+  "connecta.ui accepts exactly one argument: a non-empty string of HTML";
+
+/** What the argument was, named the way the emit validator names a bad field. */
+function describeUiArgument(raw: unknown): string {
+  if (raw === null) return "null";
+  if (raw === undefined) return "undefined";
+  if (Array.isArray(raw)) return "an array";
+  if (typeof raw === "string") return "an empty string";
+  const kind = typeof raw;
+  return `${/^[aeiou]/.test(kind) ? "an" : "a"} ${kind}`;
+}
+
 /**
- * Request-local collection for `connecta.emit`. Budgets fail loudly at the
- * crossing call — the block is not partially accepted and prior blocks are
- * unaffected — so a program learns it is over budget while it can still
- * choose differently (M5). Accepted blocks never ride `ExecuteResult`; the
- * handler that owns this collector appends them to the final tool result.
+ * Strict U1 validation. There is no options parameter and no sugar form, for
+ * M1's reason: sugar is how a one-shape contract grows hair. An options bag or
+ * an MCP block object is just a non-string, and fails as one.
+ */
+function requireUiHtml(raw: unknown): string {
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new Error(`${UI_SHAPE_HINT}; got ${describeUiArgument(raw)}`);
+  }
+  return raw;
+}
+
+/**
+ * Request-local collection for `connecta.emit` and `connecta.ui`. Budgets fail
+ * loudly at the crossing call — nothing is partially accepted and prior blocks
+ * are unaffected — so a program learns it is over budget while it can still
+ * choose differently (M5, U4). Accepted output never rides `ExecuteResult`; the
+ * handler that owns this collector delivers it on the final tool result.
+ *
+ * The two channels share the byte aggregate and nothing else: a UI payload is
+ * not a block, so it spends no block count, and at most one is ever accepted.
  */
 export class EmitCollector {
   readonly blocks: EmittedBlock[] = [];
+  /** The shared transport aggregate: emitted blocks plus the UI payload. */
   bytes = 0;
+  /** The one accepted UI payload (U2), delivered in result `_meta` on success. */
+  ui?: { html: string };
+  /** What the blocks alone cost, so the `emitted` aggregate stays a true pair. */
+  private blockBytes = 0;
   constructor(
     private readonly maxBytes: number,
     private readonly maxBlocks: number,
@@ -262,7 +312,38 @@ export class EmitCollector {
     }
     this.blocks.push(block);
     this.bytes += size;
-    this.diagnostics?.recordEmitted(this.blocks.length, this.bytes);
+    this.blockBytes += size;
+    this.diagnostics?.recordEmitted(this.blocks.length, this.blockBytes);
+  }
+
+  /**
+   * U2 and U4: one payload per run, measured as the serialized bytes of
+   * `{ html }` against the same aggregate emit spends. A second call throws
+   * naming the constraint rather than replacing the first — one tool result
+   * renders one view, and last-wins would silently discard a payload the
+   * program deliberately supplied.
+   *
+   * Multiplicity is checked before shape, so the second call is told what it
+   * actually broke. A program whose second payload is also malformed has one
+   * problem worth naming — that there is a second payload at all — and a
+   * complaint about its type would send the author to fix the wrong thing.
+   */
+  acceptUi(raw: unknown): void {
+    if (this.ui) {
+      throw new Error(
+        "connecta.ui accepts at most one payload per run: a view was already accepted and stands",
+      );
+    }
+    const payload = { html: requireUiHtml(raw) };
+    const size = diagnosticsEncoder.encode(JSON.stringify(payload)).byteLength;
+    if (this.bytes + size > this.maxBytes) {
+      throw new Error(
+        `connecta.ui byte budget exceeded: payload is ${size} serialized bytes with ${this.maxBytes - this.bytes} of ${this.maxBytes} remaining`,
+      );
+    }
+    this.ui = payload;
+    this.bytes += size;
+    this.diagnostics?.recordUi(size);
   }
 }
 
@@ -558,6 +639,18 @@ export async function buildSandboxProviders(
           }
           limits.emitCollector.accept(block);
         },
+        // The rendered-output channel rides the same bridge for the same
+        // reason (U7): one more provider fn, no change to ExecuteResult or
+        // the Executor contract. Delivery is the handler's job, not the
+        // guest's — nothing here becomes addressable.
+        ui: async (html: unknown) => {
+          if (!limits.emitCollector) {
+            throw new Error(
+              "connecta.ui is unavailable: no emission collector was configured for this execution",
+            );
+          }
+          limits.emitCollector.acceptUi(html);
+        },
         batch: async (calls: unknown) => {
           const started = Date.now();
           const callCount = Array.isArray(calls) ? calls.length : 0;
@@ -812,6 +905,9 @@ export function createExecuteTool(
               ? { retryAfterMs: err.retryAfterMs }
               : {}),
           },
+          ...(err instanceof ExecutorExecutionError
+            ? discardedEmits(emitted)
+            : {}),
           ...(diagnostics ? { diagnostics: diagnostics.finish() } : {}),
         });
         result.isError = true;
@@ -936,9 +1032,19 @@ export function createExecuteTool(
     const response = jsonResult({
       result,
       ...(emitted.blocks.length > 0 ? { emitted: emitted.blocks.length } : {}),
+      // U3: the model learns a view rendered without seeing its bytes. Spread
+      // conditionally so a program that never called connecta.ui produces
+      // today's byte-for-byte response.
+      ...(emitted.ui ? { ui: true } : {}),
       ...(logs ? { logs } : {}),
       ...(diagnostics ? { diagnostics: diagnostics.finish() } : {}),
     });
+    if (emitted.ui) {
+      // _meta is where the Apps spec's best practices put data "not intended
+      // for model context", and how shipped hosts behave. The shell reads
+      // exactly this key out of the tool result the host delivers to it.
+      response._meta = { [PROGRAM_UI_META_KEY]: { html: emitted.ui.html } };
+    }
     if (emitted.blocks.length > 0) {
       // Emitted image/audio blocks are valid MCP content that ToolResult's
       // text-only typing does not model — the same acknowledged gap
@@ -951,37 +1057,49 @@ export function createExecuteTool(
   };
 }
 
-/** M4: a failed program delivers no blocks, but the discard is visible. */
+/**
+ * M4 and U3: a failed program delivers no blocks and no view, but each
+ * discard is visible — and one failure can discard both.
+ */
 function discardedEmits(emitted: EmitCollector): {
   emittedDiscarded?: number;
+  uiDiscarded?: true;
 } {
-  return emitted.blocks.length > 0
-    ? { emittedDiscarded: emitted.blocks.length }
-    : {};
+  return {
+    ...(emitted.blocks.length > 0
+      ? { emittedDiscarded: emitted.blocks.length }
+      : {}),
+    ...(emitted.ui ? { uiDiscarded: true as const } : {}),
+  };
 }
 
 /** The same visibility for the plain-text error paths. */
 function discardedEmitsText(emitted: EmitCollector): string {
-  return emitted.blocks.length > 0
-    ? `\n\nemittedDiscarded: ${emitted.blocks.length}`
-    : "";
+  const lines = [
+    ...(emitted.blocks.length > 0
+      ? [`emittedDiscarded: ${emitted.blocks.length}`]
+      : []),
+    ...(emitted.ui ? ["uiDiscarded: true"] : []),
+  ];
+  return lines.length > 0 ? `\n\n${lines.join("\n")}` : "";
 }
 
 const executeDescription = (
   emitBudgets: { maxBytes: number; maxBlocks: number },
-) => `The primary surface. Use for discovery beyond one lookup, two or more calls, dependent steps, loops, joins, branching, or reducing large results before they reach the model — connecta.search and connecta.describe browse and expand catalogs in the run, and connecta.batch handles independent calls. The exception is a single call at an address already in hand: search_tools then one call_tool is cheaper than a program. Only tools explicitly annotated readOnlyHint: true are available. Each run is limited to ${EXECUTE_MAX_HOST_CALLS} host calls; connecta.batch accepts at most ${EXECUTE_MAX_BATCH_CALLS}; each host call has a ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second deadline.
+) => `The primary surface. Use for discovery beyond one lookup, two or more calls, dependent steps, loops, joins, branching, or reducing large results before they reach the model — connecta.search and connecta.describe browse and expand catalogs in the run, and connecta.batch handles independent calls. The exception is one call at an address already in hand: search_tools then one call_tool is cheaper than a program. Only tools explicitly annotated readOnlyHint: true are available. Each run is limited to ${EXECUTE_MAX_HOST_CALLS} host calls, connecta.batch to at most ${EXECUTE_MAX_BATCH_CALLS}; each host call has a ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second deadline.
 
 Write an async arrow function. It runs with NO network, filesystem, timers, or imports — the only capabilities are:
-- One global per connector: every address <connectorId>.<toolName> from search_tools is callable as <connectorId>.<toolName>(args) with a single args object matching the schema from connecta.describe. Names are sanitized to JS identifiers: characters outside [A-Za-z0-9_$] become "_" (e.g. my-service.get.thing → my_service.get_thing), leading digits get "_" prefixed, reserved words get "_" appended.
-- connecta.call(address, args) and connecta.batch(calls) — call raw addresses.
-- connecta.search(args), connecta.describe({ address: "<connectorId>.<toolName>" }), and connecta.describe({ addresses: [...] }) — load and inspect request-local catalogs on demand. Use safety: "readOnly" to avoid advertising calls this sandbox cannot execute; the filter changes results, not authority. Matches carrying schemas also list inputKeys, requiredInputKeys, and outputKeys — the same names the schema shows, ready to check against before building args. They are absent when a schema is not a plain object shape, so read the schema itself rather than assuming a missing list means no fields.
-- connecta.emit(block) — deliver rich MCP content alongside the JSON return: exactly { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }, no other fields. Blocks are appended to the result on success only, spend no host calls, and are budgeted per run (${emitBudgets.maxBlocks} blocks, ${emitBudgets.maxBytes} serialized bytes); an over-budget or invalid emit throws catchably and accepts nothing.
-- console.log(...) — captured and returned alongside the result.
+- One global per connector: call every address <connectorId>.<toolName> from search_tools as <connectorId>.<toolName>(args), with a single args object matching the schema from connecta.describe. Names are sanitized to JS identifiers: characters outside [A-Za-z0-9_$] become "_" (my-service.get.thing → my_service.get_thing), leading digits get "_" prefixed, reserved words "_" appended.
+- connecta.call(address, args) and connecta.batch(calls) — call raw addresses. Every batch entry is { address, ok: true, data } or { address, ok: false, error, errorDetails: { code, retryable } }; destructure that, not a bare result.
+- connecta.search(args) and connecta.describe, taking { address: "<connectorId>.<toolName>" } or { addresses: [...] } — load and inspect request-local catalogs on demand. Use safety: "readOnly" to avoid advertising calls this sandbox cannot execute; it changes results, not authority. Matches carrying schemas also list inputKeys, requiredInputKeys, and outputKeys — the schema's own names, checkable before building args. A missing list means the schema is not a plain object shape, not that the tool has no fields — read the schema.
+- connecta.emit(block) — deliver MCP content beside the JSON return: exactly { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }, nothing else. Blocks are appended on success only, spend no host calls, and are budgeted per run (${emitBudgets.maxBlocks} blocks, ${emitBudgets.maxBytes} serialized bytes); an over-budget or invalid emit throws catchably and accepts nothing.
+- connecta.ui(html) — hand the client one rendered view: exactly one argument, a non-empty HTML string, no options, no block object. Delivered on success only, spends no host calls, and draws on the same ${emitBudgets.maxBytes}-byte budget connecta.emit does — one budget, not two; a second, over-budget, or invalid call throws catchably and accepts nothing. The view is display-only (no network, no tool calls, no links) and out of model context — the envelope reports only ui: true, so the model reads the return value, not the view: return the summary it should reason over, built from the same variables the view renders.
+- console.log(...) — captured and returned with the result.
 
-Tool calls return plain values (MCP text content is JSON-parsed when possible) and throw on downstream errors — use try/catch to handle them. A thrown error carries only a message; connecta.batch reports each call as { address, ok: true, data } or { address, ok: false, error, errorDetails: { code, retryable } }, so use it when the program must tell a policy refusal from a transient failure. Never retry a failure whose retryable is false, and never retry a rate_limited one immediately — the sandbox has no timers. Return a JSON-serializable value; large results are truncated, so reduce data in code instead of returning raw payloads.
+Tool calls return plain values (MCP text is JSON-parsed when possible) and throw on downstream errors — use try/catch. A thrown error carries only a message, so use connecta.batch when a program must tell a policy refusal from a transient failure. Never retry a failure whose retryable is false, and never retry a rate_limited one immediately — the sandbox has no timers. Return a JSON-serializable value; large results are truncated, so reduce data in code rather than return raw payloads.
 
-Plain JavaScript only — no TypeScript syntax. For unknown-address dependent work, use one execute_code call: search inside it, read the compact schemas, and continue to the dependent calls; do not return search results for a second execute_code call. Compact schemas are TypeScript-like strings, not JSON Schema objects: write the property names they display, never a positional guess or an invented alias.
-Dependent example (only when the second call requires a value returned by the first): async () => { const { tools } = await connecta.search({ query: "pipeline run job logs", safety: "readOnly", includeSchemas: "compact" }); const pick = (suffix) => { const match = tools.find((tool) => tool.address.endsWith(suffix)); if (!match) throw new Error("no tool matching " + suffix); return match.address; }; const run = await connecta.call(pick(".get_run"), { runId: 42 }); const logs = await connecta.call(pick(".get_job_logs"), { jobId: run.failedJobId }); return [run, logs]; }`;
+Plain JavaScript only — no TypeScript syntax. For unknown-address dependent work, use one execute_code call: search inside it, read the compact schemas, continue to the dependent calls; do not return search results for a second execute_code call. Compact schemas are TypeScript-like strings, not JSON Schema objects: write the property names they display, never a positional guess or an invented alias.
+Dependent example (only when the second call requires a value returned by the first): async () => { const { tools } = await connecta.search({ query: "pipeline run job logs", safety: "readOnly", includeSchemas: "compact" }); const pick = (suffix) => { const match = tools.find((t) => t.address.endsWith(suffix)); if (!match) throw new Error("no tool for " + suffix); return match.address; }; const run = await connecta.call(pick(".get_run"), { runId: 42 }); const logs = await connecta.call(pick(".get_job_logs"), { jobId: run.failedJobId }); return [run, logs]; }`;
 
 /** Register the execute_code meta-tool. Only called when an executor is configured. */
 export function registerExecuteTool(
@@ -1055,6 +1173,18 @@ export function registerExecuteTool(
         destructiveHint: false,
         openWorldHint: true,
       },
+      // U5 and U10: declared unconditionally. A host without the Apps
+      // extension ignores unknown _meta and sees the ordinary envelope, which
+      // is the text fallback the spec mandates — and a stateless aggregator
+      // has nowhere dependable to hold a negotiation check anyway. The
+      // explicit visibility keeps hosts from being told the view may call
+      // execute_code; the default ["model","app"] would say exactly that.
+      _meta: {
+        ui: {
+          resourceUri: PROGRAM_UI_RESOURCE_URI,
+          visibility: ["model"],
+        },
+      },
     },
     async (args, extra) => {
       const controller = new AbortController();

package/src/executor-admission.ts

@@ -36,6 +36,18 @@ export class ExecutorAdmissionError extends Error {
   }
 }
 
+/**
+ * A lifecycle failure after the sandbox started running. It keeps the stable
+ * admission-error envelope while letting response assembly distinguish work
+ * torn down in flight from work that never entered the executor.
+ */
+export class ExecutorExecutionError extends ExecutorAdmissionError {
+  constructor(code: ExecutorAdmissionErrorCode, message: string) {
+    super(code, message);
+    this.name = "ExecutorExecutionError";
+  }
+}
+
 export interface AdmissionLease {
   /** Time spent waiting behind active work. Zero for immediate admission. */
   readonly waitMs: number;

package/src/executors/quickjs.ts

@@ -9,6 +9,7 @@ import { fileURLToPath } from "node:url";
 import {
   AdmissionController,
   ExecutorAdmissionError,
+  ExecutorExecutionError,
 } from "../executor-admission.js";
 import type {
   AdmittingExecutor,
@@ -737,7 +738,7 @@ class QuickJsChildPool implements AdmittingExecutor {
     if (!child) return Promise.resolve();
     this.rejectActive(
       slot,
-      new ExecutorAdmissionError(
+      new ExecutorExecutionError(
         "executor_closed",
         "Executor is shutting down.",
       ),

package/src/routes/mcp.ts

@@ -5,6 +5,12 @@ import {
   WebStandardStreamableHTTPServerTransport,
 } from "@modelcontextprotocol/server";
 import type { ActivityActor, ActivityRequestContext } from "../activity.js";
+import {
+  MCP_APPS_EXTENSION,
+  PROGRAM_UI_MIME_TYPE,
+  PROGRAM_UI_RESOURCE_URI,
+  PROGRAM_UI_SHELL_HTML,
+} from "../apps-shell.js";
 import { registerExecuteTool } from "../execute.js";
 import {
   ExecutorAdmissionError,
@@ -184,6 +190,42 @@ function toolkitRetired(logger: Logger): Response {
   );
 }
 
+/**
+ * U5: one static template, served by a handler that answers exactly one URI
+ * and fails on every other. Registering it is also what declares the
+ * `resources` capability — which is why `resources/list` has to answer, and
+ * why it answers with nothing. That is the Apps spec's permitted omission of
+ * UI-only resources from listing, taken exactly: the capability stays honest
+ * because the method answers, and nothing downstream is ever listed or
+ * aggregated. Widening this handler to proxy downstream templates is a
+ * decision (see the design record), not a diff.
+ */
+function registerProgramUiResource(server: McpServer): void {
+  server.registerResource(
+    "connecta-program-ui",
+    PROGRAM_UI_RESOURCE_URI,
+    {
+      title: "connecta program view",
+      description:
+        "The MCP Apps shell that renders HTML an execute_code program handed connecta.ui.",
+      mimeType: PROGRAM_UI_MIME_TYPE,
+    },
+    (uri) => ({
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: PROGRAM_UI_MIME_TYPE,
+          text: PROGRAM_UI_SHELL_HTML,
+        },
+      ],
+    }),
+  );
+  // The SDK's generated listing would advertise the template it just
+  // registered. Replace it rather than accept that: the URI reaches the host
+  // through tool metadata, so the listing has nothing to carry.
+  server.server.setRequestHandler("resources/list", () => ({ resources: [] }));
+}
+
 async function serveMcp(
   request: Request,
   opts: ServerOptions,
@@ -195,6 +237,23 @@ async function serveMcp(
   const createServer = (): McpServer => {
     const server = new McpServer(opts.serverInfo, {
       instructions: instructionsFor(),
+      // U11: the Apps extension must be explicitly negotiated, and a
+      // conforming client acts on an extension only when both sides declare
+      // it — without this line no host reads execute_code's _meta.ui, no host
+      // fetches the shell, and the whole design is inert. This is the one
+      // extension connecta advertises; the versioned extensions framework
+      // stays declined as a general surface (documentation/mcp-2026-07-28.md).
+      capabilities: {
+        extensions: {
+          [MCP_APPS_EXTENSION]: { mimeTypes: [PROGRAM_UI_MIME_TYPE] },
+        },
+        // Registering the shell below declares `resources` on its own, but it
+        // would default `listChanged` to true. Connecta serves one build-time
+        // template and never sends a list_changed notification, so say so:
+        // a client that subscribes on the strength of that flag would wait
+        // forever for an event this server has no way to produce.
+        resources: { listChanged: false },
+      },
       cacheHints: {
         "tools/list": {
           ttlMs: 3_600_000,
@@ -202,6 +261,7 @@ async function serveMcp(
         },
       },
     });
+    registerProgramUiResource(server);
     const activity: ActivityRequestContext | undefined = opts.activity
       ? {
           sink: opts.activity,

package/src/skills.ts

@@ -7,27 +7,31 @@ export const USAGE_SKILL = `# Connecta usage
 
 ## The surface
 
-Seven tools: \`execute_code\`, \`search_tools\`, \`call_tool\`, \`call_destructive_tool\`, \`authorize_connector\`, \`get_result\`, \`skills\`. Broad discovery and multi-call work live inside a program rather than in top-level tools.
+Seven tools: \`execute_code\`, \`search_tools\`, \`call_tool\`, \`call_destructive_tool\`, \`authorize_connector\`, \`get_result\`, \`skills\`. Broad discovery and multi-call work live in a program, not in top-level tools.
 
 ## Choose the smallest execution tool
 
-Use exact addresses returned by discovery; never invent one. Search with 2–4 distinctive action/object terms rather than the full request.
+Use exact addresses from discovery; never invent one. Search 2–4 distinctive action/object terms, not the whole request.
 
-- One read at an unknown address: \`search_tools({ query, includeSchemas: "compact" })\`, then \`call_tool\` once. A lone cold call is cheaper direct than through a program.
-- Anything wider — two or more calls, dependent steps, loops, joins, branching, browsing a whole catalog, or a result that must be reduced: one \`execute_code\` run.
-- Any unannotated, write-capable, or destructive call: \`call_destructive_tool\`, individually and only after reviewing its schema and consequences. Generated code cannot make one.
-- Truncated result: retry with \`fields\` when possible; otherwise page it with \`get_result\`.
-- \`auth_required\`: use \`authorize_connector\`, give its recovery handoff to the operator, then retry the original call.
+- One read at an unknown address: \`search_tools({ query, includeSchemas: "compact" })\`, then \`call_tool\` once — one cold call is cheaper direct than a program.
+- Anything wider — two or more calls, dependent steps, loops, joins, branching, a whole-catalog browse, or a result to reduce: one \`execute_code\` run.
+- Any unannotated, write-capable, or destructive call: \`call_destructive_tool\`, one at a time, after reviewing its schema and consequences.
+- Truncated result: retry with \`fields\`, else page it with \`get_result\`.
+- \`auth_required\`: \`authorize_connector\`, hand its recovery text to the operator, retry the call.
 
 ## Inside a program
 
-One async arrow function. The only capabilities are one global per connector (\`<connectorId>.<toolName>(args)\`), the four \`connecta\` functions, and \`console.log\`.
+One async arrow function. The only capabilities are one global per connector (\`<connectorId>.<toolName>(args)\`), the \`connecta\` functions, and \`console.log\`.
 
-- What exists: \`connecta.search({})\` browses every catalog; add \`safety: "readOnly"\` for only calls the program can execute, and \`connector: "<id>"\` to browse one. This filters discovery results, not authority, and each match carries its \`address\` and annotations.
-- Exact schemas for known addresses: \`connecta.describe({ address: "connector.tool" })\` for one or \`connecta.describe({ addresses: [...] })\` for many; \`format: "json"\` only for exact constraints.
-- Two to ten independent calls: \`connecta.batch([...])\`. Each outcome is \`{ address, ok: true, data }\` or \`{ address, ok: false, error, errorDetails: { code, retryable } }\`, which is also how a program tells a policy refusal from a transient failure.
-- Search inside the run rather than searching first, and return only the reduction the answer needs — never raw payloads.
-- Only tools annotated \`readOnlyHint: true\` are reachable; the read-only gate, credentials, and admission are enforced below the sandbox, so nothing a program does widens what it can reach.
+- \`connecta.search({})\` browses every catalog; \`safety: "readOnly"\` narrows to calls a program can execute, \`connector: "<id>"\` to one. This filters results, not authority; matches carry \`address\` and annotations.
+- Exact schemas: \`connecta.describe({ address: "connector.tool" })\` for one, \`{ addresses: [...] }\` for many; \`format: "json"\` only for exact constraints.
+- Two to ten independent calls: \`connecta.batch([...])\`. Each outcome is \`{ address, ok: true, data }\` or \`{ address, ok: false, error, errorDetails: { code, retryable } }\` — how a program tells a policy refusal from a transient failure.
+- Search inside the run, not before it; return only the reduction the answer needs, never raw payloads.
+- Only tools annotated \`readOnlyHint: true\` are reachable; the gate, credentials, and admission are enforced below the sandbox — nothing a program does widens its reach.
+
+## Rendering a view
+
+\`connecta.ui(html)\` renders one view per successful run for the client, never for the model. Fetch first, check the shape in code. On a surprise — empty array, missing key — return a trimmed first record instead of rendering: the wrong view becomes the sample you needed. Otherwise render from the variables you return; the model reads the return value, not the view.
 `;
 
 /**

package/src/version.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.11.0";
+export const CONNECTA_VERSION = "0.12.1";

package/templates/node/package.json

@@ -12,7 +12,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.11.0",
+    "@zackbart/connecta": "0.12.1",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {