@zackbart/connecta 0.12.0 → 0.12.2

package/src/meta-tools.ts

@@ -1484,6 +1484,7 @@ export function registerMetaTools(
       description: describedFor(registry, SKILLS_DESC, "skills"),
       inputSchema: z.object({ name: z.string().optional() }),
       annotations: READ_ONLY_LOCAL,
+      _meta: { ui: { visibility: ["model"] } },
     },
     async (args) => mt.skills(args as SkillArgs),
   );
@@ -1508,6 +1509,7 @@ export function registerMetaTools(
         includeSchemas: z.enum(["compact", "json"]).optional(),
       }),
       annotations: READ_ONLY_REMOTE,
+      _meta: { ui: { visibility: ["model"] } },
     },
     async (args) => mt.searchTools(args as SearchArgs),
   );
@@ -1520,6 +1522,10 @@ export function registerMetaTools(
       // call_tool admits only tools that are themselves explicitly read-only;
       // anything else is refused and routed to call_destructive_tool.
       annotations: READ_ONLY_REMOTE,
+      // The trusted program-view shell delegates bounded named reads here.
+      // It is already one of the seven model tools; app visibility adds no
+      // tool and this handler repeats ordinary fail-closed read admission.
+      _meta: { ui: { visibility: ["model", "app"] } },
     },
     async (args) => mt.callTool(args as CallArgs),
   );
@@ -1541,6 +1547,7 @@ export function registerMetaTools(
         readOnlyHint: false,
         openWorldHint: true,
       },
+      _meta: { ui: { visibility: ["model"] } },
     },
     async (args) => {
       // `reason` is the host's to display and connecta's to keep out of the
@@ -1568,6 +1575,7 @@ export function registerMetaTools(
         destructiveHint: false,
         openWorldHint: true,
       },
+      _meta: { ui: { visibility: ["model"] } },
     },
     async (args) => mt.authorizeConnector(args as AuthorizeArgs),
   );
@@ -1586,6 +1594,7 @@ export function registerMetaTools(
         maxBytes: z.number().int().min(MIN_MAX_RESULT_BYTES).optional(),
       }),
       annotations: READ_ONLY_LOCAL,
+      _meta: { ui: { visibility: ["model"] } },
     },
     async (args) => mt.getResult(args as GetResultArgs),
   );

package/src/skills.ts

@@ -1,33 +1,38 @@
 import type { Connector } from "./types.js";
 
 export const CONNECTA_INSTRUCTIONS =
-  'Connecta exposes integrations behind seven meta-tools, and execute_code is the primary one: write an async arrow function and use connecta.search (empty query browses every catalog), connecta.describe, connecta.call, and connecta.batch inside it for discovery, two or more calls, dependent steps, loops, joins, and reducing large results before they reach you. For a single read at an unknown address, search_tools with 2–4 distinctive action/object terms and includeSchemas="compact", then one call_tool — a lone cold call is cheaper direct than through a program. Use call_destructive_tool individually for unannotated, write-capable, or destructive tools; authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: "usage" }).';
+  'Connecta exposes seven meta-tools. execute_code is primary: use connecta.search, describe, call, and batch for discovery, multiple or dependent calls, loops, joins, and result reduction. connecta.ui(html) is a guest function inside execute_code, never a connector address or search_tools result; pass one HTML string for display-only, or bind named read-only refresh/drill-down calls in its optional reads argument, and return the same initial summary data the HTML renders. For one read at an unknown address, search_tools with 2–4 distinctive action/object terms and includeSchemas="compact", then one call_tool — a lone cold call is cheaper direct than a program. Use call_destructive_tool individually for unannotated, write-capable, or destructive tools; authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: "usage" }).';
 
 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\`.
+
+- \`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 a display-only view on success 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.
 
-- 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.
 `;
 
 /**

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.12.0";
+export const CONNECTA_VERSION = "0.12.2";

package/templates/node/package.json

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