@zackbart/connecta 0.12.1 → 0.13.0

package/src/execute.ts

@@ -28,6 +28,8 @@ import {
   InvocationService,
 } from "./invocation.js";
 import type { RegistryView } from "./registry.js";
+import { hasConnectorGuides } from "./skills.js";
+import { isExplicitlyReadOnly } from "./tool-safety.js";
 import type {
   Executor,
   ExecutorProvider,
@@ -249,7 +251,23 @@ function requireEmittedBlock(raw: unknown): EmittedBlock {
 }
 
 const UI_SHAPE_HINT =
-  "connecta.ui accepts exactly one argument: a non-empty string of HTML";
+  "connecta.ui accepts exactly one HTML argument and, optionally, one read-binding options object";
+
+const MAX_UI_READ_BINDINGS = 32;
+const MAX_UI_VIEW_ARGS = 32;
+const UI_READ_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+const FORBIDDEN_UI_KEY = new Set(["__proto__", "constructor", "prototype"]);
+
+interface UiReadBinding {
+  address: string;
+  fixedArgs: Record<string, unknown>;
+  viewArgs: string[];
+}
+
+interface UiPayload {
+  html: string;
+  reads?: Record<string, UiReadBinding>;
+}
 
 /** What the argument was, named the way the emit validator names a bad field. */
 function describeUiArgument(raw: unknown): string {
@@ -262,9 +280,9 @@ function describeUiArgument(raw: unknown): string {
 }
 
 /**
- * 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.
+ * Strict U1/V1 validation. The first argument remains HTML; the only second
+ * argument is one read-binding manifest. There are no alternate object or MCP
+ * block forms.
  */
 function requireUiHtml(raw: unknown): string {
   if (typeof raw !== "string" || raw.length === 0) {
@@ -273,6 +291,125 @@ function requireUiHtml(raw: unknown): string {
   return raw;
 }
 
+function requireRecord(raw: unknown, label: string): Record<string, unknown> {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return raw as Record<string, unknown>;
+}
+
+function requireExactKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  label: string,
+): void {
+  const extras = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (extras.length > 0) {
+    throw new Error(
+      `${label} carries unsupported field(s) ${extras.map((key) => JSON.stringify(key)).join(", ")}`,
+    );
+  }
+}
+
+function requireUiReadKey(raw: unknown, label: string): string {
+  if (
+    typeof raw !== "string" ||
+    raw.length === 0 ||
+    raw.length > 128 ||
+    FORBIDDEN_UI_KEY.has(raw)
+  ) {
+    throw new Error(
+      `${label} must be a non-empty string of at most 128 characters and cannot be __proto__, constructor, or prototype`,
+    );
+  }
+  return raw;
+}
+
+function requireUiReads(raw: unknown): Record<string, UiReadBinding> {
+  const record = requireRecord(raw, "connecta.ui options.reads");
+  const names = Object.keys(record);
+  if (names.length === 0 || names.length > MAX_UI_READ_BINDINGS) {
+    throw new Error(
+      `connecta.ui options.reads must contain from 1 through ${MAX_UI_READ_BINDINGS} named bindings`,
+    );
+  }
+  const reads = Object.create(null) as Record<string, UiReadBinding>;
+  for (const name of names) {
+    if (!UI_READ_NAME.test(name) || FORBIDDEN_UI_KEY.has(name)) {
+      throw new Error(
+        `connecta.ui read binding name ${JSON.stringify(name)} must match ${UI_READ_NAME}`,
+      );
+    }
+    const value = requireRecord(
+      record[name],
+      `connecta.ui read binding ${JSON.stringify(name)}`,
+    );
+    requireExactKeys(
+      value,
+      ["address", "fixedArgs", "viewArgs"],
+      `connecta.ui read binding ${JSON.stringify(name)}`,
+    );
+    if (typeof value.address !== "string" || value.address.length === 0) {
+      throw new Error(
+        `connecta.ui read binding ${JSON.stringify(name)} address must be a non-empty string`,
+      );
+    }
+    const fixedArgs =
+      value.fixedArgs === undefined
+        ? {}
+        : requireRecord(
+            value.fixedArgs,
+            `connecta.ui read binding ${JSON.stringify(name)} fixedArgs`,
+          );
+    const rawViewArgs = value.viewArgs ?? [];
+    if (!Array.isArray(rawViewArgs) || rawViewArgs.length > MAX_UI_VIEW_ARGS) {
+      throw new Error(
+        `connecta.ui read binding ${JSON.stringify(name)} viewArgs must be an array of at most ${MAX_UI_VIEW_ARGS} strings`,
+      );
+    }
+    const viewArgs = rawViewArgs.map((key) =>
+      requireUiReadKey(
+        key,
+        `connecta.ui read binding ${JSON.stringify(name)} viewArgs entry`,
+      )
+    );
+    if (new Set(viewArgs).size !== viewArgs.length) {
+      throw new Error(
+        `connecta.ui read binding ${JSON.stringify(name)} viewArgs must not repeat a key`,
+      );
+    }
+    for (const key of viewArgs) {
+      if (Object.prototype.hasOwnProperty.call(fixedArgs, key)) {
+        throw new Error(
+          `connecta.ui read binding ${JSON.stringify(name)} view argument ${JSON.stringify(key)} cannot override a fixed argument`,
+        );
+      }
+    }
+    reads[name] = {
+      address: value.address,
+      fixedArgs,
+      viewArgs,
+    };
+  }
+  return reads;
+}
+
+function requireUiPayload(values: unknown[]): UiPayload {
+  if (values.length !== 1 && values.length !== 2) {
+    throw new Error(
+      `${UI_SHAPE_HINT}; got ${values.length} arguments`,
+    );
+  }
+  const html = requireUiHtml(values[0]);
+  if (values.length === 1) return { html };
+  const options = requireRecord(values[1], "connecta.ui options");
+  requireExactKeys(options, ["reads"], "connecta.ui options");
+  if (!Object.prototype.hasOwnProperty.call(options, "reads")) {
+    throw new Error("connecta.ui options must contain reads");
+  }
+  return { html, reads: requireUiReads(options.reads) };
+}
+
 /**
  * Request-local collection for `connecta.emit` and `connecta.ui`. Budgets fail
  * loudly at the crossing call — nothing is partially accepted and prior blocks
@@ -288,7 +425,7 @@ export class EmitCollector {
   /** 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 };
+  ui?: UiPayload;
   /** What the blocks alone cost, so the `emitted` aggregate stays a true pair. */
   private blockBytes = 0;
   constructor(
@@ -328,14 +465,28 @@ export class EmitCollector {
    * 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 {
+  acceptUi(...values: unknown[]): void {
+    if (this.ui) {
+      throw new Error(
+        "connecta.ui accepts at most one payload per run: a view was already accepted and stands",
+      );
+    }
+    this.acceptUiPayload(requireUiPayload(values));
+  }
+
+  acceptUiPayload(payload: UiPayload): 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;
+    let serialized: string;
+    try {
+      serialized = JSON.stringify(payload);
+    } catch {
+      throw new Error("connecta.ui payload must be JSON-serializable");
+    }
+    const size = diagnosticsEncoder.encode(serialized).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`,
@@ -619,6 +770,41 @@ export async function buildSandboxProviders(
     return outcome.value;
   };
 
+  /**
+   * A read binding is admitted while the program still owns the request. The
+   * shell later calls the ordinary `call_tool`, which repeats this same
+   * fail-closed check against the then-current catalog; validating here keeps
+   * a typo or destructive address from producing a view whose controls can
+   * never work, while validation at use keeps a stale view from retaining old
+   * authority.
+   */
+  const validateUiReads = async (payload: UiPayload): Promise<UiPayload> => {
+    if (!payload.reads) return payload;
+    const reads = Object.create(null) as Record<string, UiReadBinding>;
+    for (const [name, binding] of Object.entries(payload.reads)) {
+      const resolution = await catalog.resolveTool(
+        binding.address,
+        limits.signal !== undefined ? { signal: limits.signal } : {},
+      );
+      if (!resolution.ok) {
+        throw new Error(
+          `connecta.ui read binding ${JSON.stringify(name)} could not resolve ${JSON.stringify(binding.address)}: ${resolution.error.message}`,
+        );
+      }
+      if (!isExplicitlyReadOnly(resolution.resolved.definition)) {
+        throw new Error(
+          `connecta.ui read binding ${JSON.stringify(name)} refuses ${JSON.stringify(binding.address)}: the tool is not explicitly read-only`,
+        );
+      }
+      reads[name] = {
+        ...binding,
+        address:
+          `${resolution.resolved.connector.id}.${resolution.resolved.toolName}`,
+      };
+    }
+    return { html: payload.html, reads };
+  };
+
   return [
     {
       name: "connecta",
@@ -643,13 +829,14 @@ export async function buildSandboxProviders(
         // 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) => {
+        ui: async (...values: unknown[]) => {
           if (!limits.emitCollector) {
             throw new Error(
               "connecta.ui is unavailable: no emission collector was configured for this execution",
             );
           }
-          limits.emitCollector.acceptUi(html);
+          const payload = await validateUiReads(requireUiPayload(values));
+          limits.emitCollector.acceptUiPayload(payload);
         },
         batch: async (calls: unknown) => {
           const started = Date.now();
@@ -1043,7 +1230,7 @@ export function createExecuteTool(
       // _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 } };
+      response._meta = { [PROGRAM_UI_META_KEY]: emitted.ui };
     }
     if (emitted.blocks.length > 0) {
       // Emitted image/audio blocks are valid MCP content that ToolResult's
@@ -1086,20 +1273,22 @@ function discardedEmitsText(emitted: EmitCollector): string {
 
 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 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.
+  connectorGuides: boolean,
+) => `Choose the route before discovery. Exactly one unknown-address read uses top-level search_tools then call_tool; a known address uses call_tool directly. This is the primary surface for everything wider. If any result will be reduced — even from one connector call — or work has dependent/multiple calls, loops, joins, or branches, make exactly one execute_code call that searches, selects, calls, and reduces before returning. A discovery-only program wastes its round trip: finish here, don't return catalog matches for a later call. Only readOnlyHint: true tools are available. Limits: ${EXECUTE_MAX_HOST_CALLS} host calls per run, ${EXECUTE_MAX_BATCH_CALLS} per batch, ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second host deadline.
 
 Write an async arrow function. It runs with NO network, filesystem, timers, or imports — the only capabilities are:
-- 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.
+- Connector globals call <connectorId>.<toolName>(args) with one schema-matching args object. Sanitization: non-[A-Za-z0-9_$] → "_" (my-service.get.thing → my_service.get_thing), leading digit → "_" prefix, reserved word → "_" suffix.
 - 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.
+- connecta.search(args) loads catalogs and must be followed by selection and calls in this program; set connector to the obvious id to load one, otherwise it loads all. For distinct operations, make separate short searches here. Require address/description to match the operation, then check requiredInputKeys, truncation, safety, and outputs; never take the first lexical or merely input-compatible match. Choose the best compatible match; do not require it to be the only match. Missing outputKeys means inspect outputSchema, not discard the candidate. Compatible means every required key has a task/prior-result value; do not prefer zero required keys. Put every requiredInputKey in call args. For dependencies, match an earlier outputKey to the later requiredInputKey. Use displayed names; [] means no required keys, not permission to invent args. Describe only a truncated/insufficient compact shape. Reducers use declared outputKeys, never guessed items/results roots. connecta.describe takes { address: "<connectorId>.<toolName>" } or { addresses: [...] }. Use safety: "readOnly" to avoid advertising calls this sandbox cannot execute; it changes results, not authority. A missing key list means a non-object shape, not no fields — read the schema.${connectorGuides ? " A match with guideRequired: true is a hard stop: do not call it; describing the exact schema clears only a schema_truncated reason, so for any other reason return the exact guide name, fetch that guide with the top-level skills tool, then write the informed call." : ""}
+- connecta.emit(block) — emit exactly { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }. Success-only, no host call, ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes; invalid or over-budget throws before accepting.
+- connecta.ui(html, options?) — one success-only view. One arg is display-only; live reads use { reads: { name: { address, fixedArgs?, viewArgs? } } }, then markup calls connecta.read(name, args). Read admission is enforced; fixed keys cannot be overridden and undeclared keys fail. It shares the ${emitBudgets.maxBytes}-byte emit budget — one budget, not two; a second, over-budget, or invalid call throws catchably. Bytes stay out of context, so the model reads the return value, not the view: return the initial summary from its variables; later reads update only the view.
 - console.log(...) — captured and returned with the result.
 
-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.
+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]; }
+
+Calls return plain values (JSON-parsing MCP text when possible) and throw; catch errors. A thrown error is only a message; connecta.batch tells a policy refusal from a transient failure. Never retry retryable: false or rate_limited immediately — there are no timers. Return JSON; large results truncate, so reduce instead of returning 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, 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]; }`;
+Plain JS, no TypeScript. Compact schemas are TypeScript-like, not JSON Schema: write the property names they display; never guess positions or aliases.`;
 
 /** Register the execute_code meta-tool. Only called when an executor is configured. */
 export function registerExecuteTool(
@@ -1154,11 +1343,16 @@ export function registerExecuteTool(
   server.registerTool(
     "execute_code",
     {
-      description: executeDescription(emitBudgets),
+      description: executeDescription(
+        emitBudgets,
+        hasConnectorGuides(registry.listConnectors()),
+      ),
       inputSchema: z.object({
         code: z
           .string()
-          .describe("A JavaScript async arrow function to execute."),
+          .describe(
+            "One complete JavaScript async arrow function. Consume search/describe results and finish the task inside it; returning catalog data for a later call spends a round trip and buys nothing.",
+          ),
         diagnostics: z
           .boolean()
           .optional()

package/src/index.ts

@@ -630,6 +630,7 @@ export type {
   ConnectorCredentialFieldConfig,
   ConnectorCredentialValues,
   ConnectorContext,
+  ConnectorUsageGuide,
   ConnectorStatus,
   CredentialTestResult,
   AdmittingExecutor,

package/src/meta-tools.ts

@@ -1372,7 +1372,7 @@ export function createMetaTools(
   };
 }
 
-const SEARCH_DESC = `Unknown address: use 2–4 distinctive action/object terms, not the full request; omit limit initially (default ${DEFAULT_SEARCH_LIMIT}) and page only if needed, up to ${MAX_SEARCH_LIMIT}. Partial and no-match searches report term coverage and next-step guidance. safety="readOnly" returns only calls available to call_tool and generated code; "approvalRequired" returns everything else; omitted or "all" preserves the complete catalog. This filters results, not authority. includeSchemas="compact" adds the input and any declared output shape, each bounded; plain-object schemas also expose inputKeys, requiredInputKeys, and outputKeys, while inputSchemaTruncated/outputSchemaTruncated mark shapes that need exact retrieval; matches also carry declared annotations. Call directly when sufficient. Empty query browses all.`;
+const SEARCH_DESC = `Use top-level search only for exactly one unreduced read, then call_tool, or for write-capable work, then call_destructive_tool. For read-only reduction, dependent or multiple calls, never search here: make one execute_code program that searches and calls. Use 2–4 distinctive action/object terms, not the full request; set connector to the obvious integration id to load one catalog instead of all; omit limit initially (default ${DEFAULT_SEARCH_LIMIT}), page to ${MAX_SEARCH_LIMIT} if needed. safety="readOnly" returns only calls available to call_tool/code; "approvalRequired" returns the rest; omitted/"all" returns all. This filters results, not authority. includeSchemas="compact" adds the input and any declared output shape, bounded; plain objects expose inputKeys, requiredInputKeys, and outputKeys; truncation flags mark incomplete shapes; matches also carry declared annotations. Require purpose/address fit plus compatible inputs, truncation, safety, and outputs — never the first lexical match. Empty query browses all.`;
 const CALL_DESC =
   'Use for ONE tool explicitly annotated readOnlyHint: true — the cheapest path for a single cold call. For two or more calls, dependent steps, loops, joins, or data reduction use execute_code, whose connecta.call and connecta.batch reach the same tools. Unannotated, write-capable, and destructive tools are refused and require call_destructive_tool. fields selects JSON dot-paths; traverse arrays with [] (for example results[].id). Misses return data plus `$connecta` feedback. resultMode "value" unwraps results, timeoutMs sets a deadline, safe maxRetries are annotation-gated, diagnostics adds timing, and large results page through get_result.';
 const CALL_DESTRUCTIVE_DESC =
@@ -1396,9 +1396,11 @@ const SEARCH_WITH_DESCRIBE_DESC = `${SEARCH_DESC} Expand an ambiguous compact sh
  */
 const GUIDE_NOTES = {
   skills:
-    ' skills({}) also lists this deployment\'s per-connector usage guides as "connector:<connectorId>"; fetch the guide for a connector before working with it for the first time.',
+    " skills({}) also lists this deployment's scoped connector guides; fetch only an exact name listed there or carried by discovery, never one inferred from a connector id.",
   search:
-    " A connector group carrying `guide` has a usage guide; fetch it with skills({ name: <guide> }).",
+    " A result carrying `guide` also carries a bounded `guideSummary`. `guideRequired: true` is a hard stop: fetch that exact guide before calling. `guideRequiredReasons` explains why — `connector_required` and `approval_required` stand however you expand the schema; `schema_truncated` clears once describe returns the exact one. Otherwise fetch only when the summary names a connector convention relevant to the task. A complete, unambiguous read-only schema needs no otherwise-irrelevant guide fetch.",
+  destructive:
+    " Before a consequential call, inspect the address through discovery or describe and fetch any connector guide it names.",
 } as const;
 
 /** `base`, plus its guide note when any VISIBLE connector carries a guide. */
@@ -1484,6 +1486,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 +1511,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 +1524,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),
   );
@@ -1527,7 +1535,11 @@ export function registerMetaTools(
   server.registerTool(
     "call_destructive_tool",
     {
-      description: CALL_DESTRUCTIVE_DESC,
+      description: describedFor(
+        registry,
+        CALL_DESTRUCTIVE_DESC,
+        "destructive",
+      ),
       inputSchema: z.object({
         ...CALL_INPUT_SCHEMA,
         // Bounded above, but with no lower bound: a model that sends `""` or
@@ -1541,6 +1553,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 +1581,7 @@ export function registerMetaTools(
         destructiveHint: false,
         openWorldHint: true,
       },
+      _meta: { ui: { visibility: ["model"] } },
     },
     async (args) => mt.authorizeConnector(args as AuthorizeArgs),
   );
@@ -1586,6 +1600,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/providers/mixpanel.ts

@@ -0,0 +1,220 @@
+import {
+  remoteMcp,
+  type RemoteMcpAuth,
+} from "../connectors/remote-mcp.js";
+import type {
+  Connector,
+  ConnectorCallAdmissionPolicy,
+  ToolDef,
+} from "../types.js";
+
+export type MixpanelRegion = "us" | "eu" | "in";
+
+export const MIXPANEL_MCP_ENDPOINTS: Readonly<
+  Record<MixpanelRegion, string>
+> = {
+  us: "https://mcp.mixpanel.com/mcp",
+  eu: "https://mcp-eu.mixpanel.com/mcp",
+  in: "https://mcp-in.mixpanel.com/mcp",
+};
+
+export interface MixpanelOptions {
+  /** Human-readable display name; defaults to "Mixpanel". */
+  title?: string;
+  /** Who should use this account and for what decisions. */
+  purpose: string;
+  /** Mixpanel data residency region. Defaults to "us". */
+  region?: MixpanelRegion;
+  /** OAuth by default; static headers support Mixpanel service accounts. */
+  auth?: RemoteMcpAuth;
+  /** Account-specific conventions appended to the maintained provider guide. */
+  instructions?: string;
+  /** Connector-specific inline result limit; omit to inherit the deployment. */
+  maxResultBytes?: number;
+}
+
+// Budget-only: a rejection computes its own retry-after from the window, and
+// declaring `retryAfterMs` here would be a queue setting without a queue —
+// which the admission controller refuses at construction.
+const MIXPANEL_ADMISSION: ConnectorCallAdmissionPolicy = {
+  rules: [
+    {
+      budget: {
+        kind: "rolling-window",
+        maxCalls: 600,
+        windowMs: 3_600_000,
+      },
+    },
+  ],
+};
+
+/** Tools whose official contract is observational rather than mutating. */
+const READ_ONLY_TOOLS = new Set([
+  "Run-Query",
+  "Get-Query-Schema",
+  "Get-Report",
+  "Display-Query",
+  "List-Dashboards",
+  "Get-Dashboard",
+  "Get-Business-Context",
+  "Get-Projects",
+  "List-Organizations",
+  "Get-Events",
+  "List-Properties",
+  "Get-Property-Values",
+  "Search-Entities",
+  "Get-Issues",
+  "Get-Lexicon-URL",
+  "Find-Duplicate-Groups",
+  "Get-Custom-Property",
+  "Get-Cohort",
+  "List-Cohorts",
+  "Describe-Cohort-Schema",
+  "Get-Lookup-Table",
+  "Get-Metric",
+  "List-Metrics",
+  "Get-User-Replays-Data",
+  "List-Experiments",
+  "Get-Experiment",
+  "Get-Experiment-Setup-Guidance",
+  "Get-Experiment-Results-Interpretation-Guidance",
+  "Explain-Experiment-Health-Check",
+  "Run-Experiment-Pre-Launch-Checks",
+  "Search-Prior-Experiments",
+  "List-Feature-Flags",
+  "Get-Feature-Flag",
+  "Get-Feature-Flag-Setup-Guidance",
+  "Get-Feature-Flag-Lifecycle-Guidance",
+]);
+
+/**
+ * The maintained write catalog. `"destructive"` tools modify or remove state
+ * that already exists; `"additive"` ones only bring something new into being.
+ * Both leave the read-only path — the distinction only decides whether the
+ * connection asserts `destructiveHint`, which shapes the host's approval copy.
+ */
+const WRITE_TOOLS: ReadonlyMap<string, "additive" | "destructive"> = new Map([
+  ["Create-Dashboard", "additive"],
+  ["Update-Dashboard", "destructive"],
+  ["Duplicate-Dashboard", "additive"],
+  ["Delete-Dashboard", "destructive"],
+  ["Edit-Event", "destructive"],
+  ["Edit-Property", "destructive"],
+  ["Bulk-Edit-Events", "destructive"],
+  ["Bulk-Edit-Properties", "destructive"],
+  ["Create-Tag", "additive"],
+  ["Rename-Tag", "destructive"],
+  ["Delete-Tag", "destructive"],
+  ["Dismiss-Issues", "destructive"],
+  ["Update-Business-Context", "destructive"],
+  ["Dismiss-Duplicate-Group", "destructive"],
+  ["Merge-Group", "destructive"],
+  ["Create-Custom-Property", "additive"],
+  ["Update-Custom-Property", "destructive"],
+  ["Create-Cohort", "additive"],
+  ["Update-Cohort", "destructive"],
+  ["Delete-Cohort", "destructive"],
+  ["Create-Lookup-Table", "additive"],
+  ["Update-Lookup-Table", "destructive"],
+  ["Create-Metric", "additive"],
+  ["Update-Metric", "destructive"],
+  ["Create-Experiment", "additive"],
+  ["Update-Experiment", "destructive"],
+  ["Create-Feature-Flag", "additive"],
+  ["Update-Feature-Flag", "destructive"],
+]);
+
+/**
+ * Fill in what the downstream leaves unsaid; never argue with what it says.
+ *
+ * A vetted classification may always tighten — that direction only ever routes
+ * more calls through `call_destructive_tool`. Loosening is the direction that
+ * needs the downstream's silence: an explicit `destructiveHint: true` or
+ * `readOnlyHint: false` on an allowlisted read name is the downstream telling
+ * us this release's allowlist is wrong, and it wins.
+ */
+function vettedSafety(definition: ToolDef): ToolDef {
+  const downstream = definition.annotations ?? {};
+  if (READ_ONLY_TOOLS.has(definition.name)) {
+    if (
+      downstream.destructiveHint === true ||
+      downstream.readOnlyHint === false
+    ) {
+      return definition;
+    }
+    return {
+      ...definition,
+      annotations: {
+        ...downstream,
+        readOnlyHint: true,
+        destructiveHint: downstream.destructiveHint ?? false,
+      },
+    };
+  }
+  if (WRITE_TOOLS.get(definition.name) === "destructive") {
+    return {
+      ...definition,
+      annotations: {
+        ...downstream,
+        readOnlyHint: false,
+        destructiveHint: true,
+      },
+    };
+  }
+  // Maintained additive creates and tools this release has never seen land
+  // here alike: not read-only, so the ordinary fail-closed path keeps them
+  // approval-visible, without claiming a create destroys anything.
+  return {
+    ...definition,
+    annotations: {
+      ...downstream,
+      readOnlyHint: false,
+    },
+  };
+}
+
+function usageGuide(purpose: string, instructions: string | undefined): string {
+  const accountInstructions = instructions?.trim();
+  return `# Mixpanel usage
+
+Account purpose: ${purpose}
+
+- Start with \`Get-Projects\`, then use \`Get-Business-Context\` for the selected project before interpreting its events or metrics.
+- Discover names with \`Get-Events\`, \`List-Properties\`, and \`Get-Property-Values\`; do not guess event or property spelling.
+- For a new analysis, fetch \`Get-Query-Schema\` before \`Run-Query\`. Reduce query results inside \`execute_code\` before returning them.
+- Use \`Get-Report\` when the request names an existing saved report. Use \`Run-Query\` for a new question.
+- Mixpanel limits MCP traffic to 600 requests per user per hour. Reuse discovery results within a run and avoid speculative fan-out.
+- Treat every create, update, edit, merge, dismiss, duplicate, or delete operation as a write. Connecta routes the maintained write catalog through \`call_destructive_tool\`; newly added tools also fail closed until classified.
+${
+    accountInstructions
+      ? `\n## Account instructions\n\n${accountInstructions}\n`
+      : ""
+  }`;
+}
+
+/** A maintained Mixpanel hosted-MCP connection. */
+export function mixpanel(id: string, options: MixpanelOptions): Connector {
+  const purpose = options.purpose.trim();
+  if (!purpose) {
+    throw new Error("mixpanel() requires a non-empty account purpose.");
+  }
+  const region = options.region ?? "us";
+  const connector = remoteMcp(id, {
+    url: MIXPANEL_MCP_ENDPOINTS[region],
+    title: options.title ?? "Mixpanel",
+    description: `Mixpanel product analytics — ${purpose}`,
+    auth: options.auth ?? { type: "oauth" },
+    requireHttps: true,
+    callAdmission: MIXPANEL_ADMISSION,
+    usageGuide: usageGuide(purpose, options.instructions),
+    ...(options.maxResultBytes !== undefined
+      ? { maxResultBytes: options.maxResultBytes }
+      : {}),
+  });
+  return {
+    ...connector,
+    async listTools(ctx) {
+      return (await connector.listTools(ctx)).map(vettedSafety);
+    },
+  };
+}