npm - @zackbart/connecta - Versions diffs - 0.12.1 → 0.13.0 - Mend

@zackbart/connecta 0.12.1 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (58) hide show

package/CHANGELOG.md +173 -0
package/README.md +4 -1
package/dist/apps-shell.d.ts +13 -11
package/dist/apps-shell.d.ts.map +1 -1
package/dist/apps-shell.js +221 -30
package/dist/apps-shell.js.map +1 -1
package/dist/catalog-service.d.ts +41 -0
package/dist/catalog-service.d.ts.map +1 -1
package/dist/catalog-service.js +94 -5
package/dist/catalog-service.js.map +1 -1
package/dist/connectors/api.d.ts +5 -4
package/dist/connectors/api.d.ts.map +1 -1
package/dist/connectors/api.js.map +1 -1
package/dist/connectors/remote-mcp.d.ts +5 -4
package/dist/connectors/remote-mcp.d.ts.map +1 -1
package/dist/connectors/remote-mcp.js.map +1 -1
package/dist/execute.d.ts +12 -4
package/dist/execute.d.ts.map +1 -1
package/dist/execute.js +142 -20
package/dist/execute.js.map +1 -1
package/dist/index.d.ts +1 -1
package/dist/index.d.ts.map +1 -1
package/dist/index.js.map +1 -1
package/dist/meta-tools.d.ts.map +1 -1
package/dist/meta-tools.js +14 -4
package/dist/meta-tools.js.map +1 -1
package/dist/providers/mixpanel.d.ts +21 -0
package/dist/providers/mixpanel.d.ts.map +1 -0
package/dist/providers/mixpanel.js +183 -0
package/dist/providers/mixpanel.js.map +1 -0
package/dist/skills.d.ts +7 -9
package/dist/skills.d.ts.map +1 -1
package/dist/skills.js +60 -25
package/dist/skills.js.map +1 -1
package/dist/types.d.ts +26 -6
package/dist/types.d.ts.map +1 -1
package/dist/version.d.ts +1 -1
package/dist/version.js +1 -1
package/documentation/code-mode.md +32 -20
package/documentation/connectors.md +116 -4
package/documentation/mcp-ui-design.md +8 -8
package/documentation/meta-tools.md +80 -8
package/documentation/mixpanel.md +72 -0
package/documentation/program-ui-read-calls.md +213 -0
package/ethos.md +10 -4
package/package.json +5 -1
package/src/apps-shell.ts +221 -30
package/src/catalog-service.ts +139 -4
package/src/connectors/api.ts +5 -3
package/src/connectors/remote-mcp.ts +5 -3
package/src/execute.ts +215 -21
package/src/index.ts +1 -0
package/src/meta-tools.ts +19 -4
package/src/providers/mixpanel.ts +220 -0
package/src/skills.ts +66 -24
package/src/types.ts +27 -6
package/src/version.ts +1 -1
package/templates/node/package.json +1 -1

package/src/apps-shell.ts CHANGED Viewed

@@ -3,17 +3,17 @@
  *
  * A build-time string constant, not a file read at startup: the core is
  * Web-API-only so it runs unchanged on Workers, and the same bytes have to
- * serve everywhere. The shell is display-only — it renders whatever HTML a
- * program handed `connecta.ui` inside a nested `srcdoc` frame and forwards no
- * channel back from that frame to the host, so program-authored markup is
- * inert beyond its own pixels.
+ * serve everywhere. It renders whatever HTML a program handed `connecta.ui`
+ * inside a nested `srcdoc` frame. The one-argument form forwards no channel;
+ * an explicitly bound view gets only named read calls through the trusted
+ * shell, never a raw host channel.
  *
  * The address carries a version segment because hosts are permitted to
- * prefetch and cache templates by URI: change these bytes, bump `v1`.
+ * prefetch and cache templates by URI: change these bytes, bump the version.
  */
 /** The only `ui://` URI in the system. No program input reaches it. */
-export const PROGRAM_UI_RESOURCE_URI = "ui://connecta/program-ui/v1";
+export const PROGRAM_UI_RESOURCE_URI = "ui://connecta/program-ui/v2";
 /** The mimeType the Apps spec requires of an HTML template. */
 export const PROGRAM_UI_MIME_TYPE = "text/html;profile=mcp-app";
@@ -34,10 +34,12 @@ export const MCP_APPS_EXTENSION = "io.modelcontextprotocol/ui";
  * Apps postMessage dialect (`ui/initialize`, `ui/notifications/initialized`,
  * `ui/notifications/tool-result`, `ui/notifications/size-changed`,
  * `ui/resource-teardown`), lifts `_meta["connecta/ui"].html` out of the
- * delivered tool result, and puts it in a frame. It declares no CSP domains,
- * so the host applies its restrictive default and the `srcdoc` frame inherits
- * `default-src 'none'` — the payload gets scripts and local interactivity,
- * and no network.
+ * delivered tool result, and puts it in a frame. An optional read manifest
+ * installs one narrow `connecta.read(name, args)` bridge in that inner frame;
+ * the outer shell maps declared names to the existing `call_tool` meta-tool.
+ * It declares no CSP domains, so the host applies its restrictive default and
+ * the `srcdoc` frame inherits `default-src 'none'` — program markup still gets
+ * no direct network.
  */
 export const PROGRAM_UI_SHELL_HTML = `<!doctype html>
 <html lang="en">
@@ -70,17 +72,21 @@ export const PROGRAM_UI_SHELL_HTML = `<!doctype html>
     <script>
       (function () {
         "use strict";
-        // The host frame is the only peer this shell speaks to, in either
-        // direction. The payload frame below is sandboxed to scripts alone,
-        // with no same-origin escape, and is never handed a reply path:
-        // anything it posts fails the source check and is dropped. There is
-        // no bridge from program HTML to the host, by construction rather
-        // than by validation.
+        // The outer shell is the only host peer. The payload frame is
+        // sandboxed to scripts alone, with no same-origin escape. Its one
+        // optional message dialect is handled below and translated into
+        // bounded call_tool requests; raw JSON-RPC is never forwarded.
         var host = window.parent;
         var view = document.getElementById("program-view");
         var initializeId = "connecta-ui-initialize";
         var lastWidth = 0;
         var lastHeight = 0;
+        var reads = null;
+        var hostCanCallTools = false;
+        var nextHostRequestId = 0;
+        var pendingHostReads = Object.create(null);
+        var activeHostReads = 0;
+        var maxActiveHostReads = 8;
         function send(message) {
           if (!host || host === window) return;
@@ -92,8 +98,8 @@ export const PROGRAM_UI_SHELL_HTML = `<!doctype html>
         }
         // Program views are fixed-height by construction. The shell has no
-        // bridge to the payload frame — that is the security posture, not an
-        // omission — so it can never learn the payload's content height, and
+        // content-height bridge to the payload frame, so it can never learn
+        // the payload's content height, and
         // what it reports here is its own box: the min-height above, unless
         // the host has given it more. Taller content scrolls inside the inner
         // frame rather than growing the view. Raising the min-height is the
@@ -110,30 +116,213 @@ export const PROGRAM_UI_SHELL_HTML = `<!doctype html>
           });
         }
-        function payloadHtml(result) {
+        function payload(result) {
           if (!result || typeof result !== "object") return null;
           var meta = result._meta;
           if (!meta || typeof meta !== "object") return null;
-          var payload = meta["connecta/ui"];
-          if (!payload || typeof payload !== "object") return null;
-          var html = payload.html;
-          return typeof html === "string" && html.length > 0 ? html : null;
+          var value = meta["connecta/ui"];
+          if (!value || typeof value !== "object") return null;
+          return typeof value.html === "string" && value.html.length > 0
+            ? value
+            : null;
+        }
+        // This function is serialized into the opaque-origin payload frame.
+        // It knows no addresses and has no host channel of its own: one named
+        // read request goes to the trusted outer shell and one correlated
+        // result comes back.
+        function payloadReadBridge() {
+          "use strict";
+          var pending = Object.create(null);
+          var nextId = 0;
+          function read(name, args) {
+            return new Promise(function (resolve, reject) {
+              var id = String(++nextId);
+              pending[id] = { resolve: resolve, reject: reject };
+              try {
+                window.parent.postMessage({
+                  type: "connecta/read",
+                  id: id,
+                  name: name,
+                  args: args === undefined ? {} : args
+                }, "*");
+              } catch (error) {
+                delete pending[id];
+                reject(error);
+              }
+            });
+          }
+          Object.defineProperty(globalThis, "connecta", {
+            value: Object.freeze({ read: read }),
+            configurable: false,
+            enumerable: true,
+            writable: false
+          });
+          window.addEventListener("message", function (event) {
+            if (event.source !== window.parent) return;
+            var message = event.data;
+            if (!message || message.type !== "connecta/read-result") return;
+            var waiter = pending[message.id];
+            if (!waiter) return;
+            delete pending[message.id];
+            if (message.ok) waiter.resolve(message.value);
+            else waiter.reject(new Error(message.error || "Read failed"));
+          });
+        }
+        function htmlWithReadBridge(html) {
+          var script =
+            "<scr" + "ipt>(" + payloadReadBridge.toString() + ")();</scr" + "ipt>";
+          var head = /<head(?:\\s[^>]*)?>/i.exec(html);
+          if (head) {
+            var at = (head.index || 0) + head[0].length;
+            return html.slice(0, at) + script + html.slice(at);
+          }
+          var document = /<html(?:\\s[^>]*)?>/i.exec(html);
+          if (document) {
+            var afterHtml = (document.index || 0) + document[0].length;
+            return html.slice(0, afterHtml) + "<head>" + script + "</head>" + html.slice(afterHtml);
+          }
+          return script + html;
         }
         function render(params) {
-          var html =
-            payloadHtml(params) ||
-            payloadHtml(params && params.result) ||
-            payloadHtml(params && params.toolResult);
-          if (html === null) return;
-          view.srcdoc = html;
+          var value =
+            payload(params) ||
+            payload(params && params.result) ||
+            payload(params && params.toolResult);
+          if (value === null) return;
+          reads = value.reads && typeof value.reads === "object"
+            ? value.reads
+            : null;
+          view.srcdoc = reads
+            ? htmlWithReadBridge(value.html)
+            : value.html;
           reportSize();
         }
+        function readError(message, fallback) {
+          if (message && typeof message.message === "string") return message.message;
+          if (message && message.data && typeof message.data.message === "string") {
+            return message.data.message;
+          }
+          return fallback;
+        }
+        function finishInnerRead(innerId, ok, value) {
+          if (!view.contentWindow) return;
+          view.contentWindow.postMessage(ok
+            ? { type: "connecta/read-result", id: innerId, ok: true, value: value }
+            : { type: "connecta/read-result", id: innerId, ok: false, error: value }, "*");
+        }
+        function beginInnerRead(message) {
+          if (!hostCanCallTools) {
+            finishInnerRead(message && message.id, false, "This host does not support app-initiated server tool calls");
+            return;
+          }
+          if (!message || typeof message.id !== "string" || typeof message.name !== "string") return;
+          if (!reads || !Object.prototype.hasOwnProperty.call(reads, message.name)) {
+            finishInnerRead(message.id, false, "Unknown read binding");
+            return;
+          }
+          if (activeHostReads >= maxActiveHostReads) {
+            finishInnerRead(message.id, false, "Too many concurrent reads");
+            return;
+          }
+          var binding = reads[message.name];
+          if (!binding || typeof binding !== "object" || typeof binding.address !== "string") {
+            finishInnerRead(message.id, false, "Invalid read binding");
+            return;
+          }
+          var supplied = message.args;
+          if (!supplied || typeof supplied !== "object" || Array.isArray(supplied)) {
+            finishInnerRead(message.id, false, "Read arguments must be an object");
+            return;
+          }
+          var allowed = Array.isArray(binding.viewArgs) ? binding.viewArgs : [];
+          var suppliedKeys = Object.keys(supplied);
+          for (var i = 0; i < suppliedKeys.length; i++) {
+            var key = suppliedKeys[i];
+            if (allowed.indexOf(key) === -1) {
+              finishInnerRead(message.id, false, "Undeclared read argument " + JSON.stringify(key));
+              return;
+            }
+          }
+          var args = Object.create(null);
+          var fixed = binding.fixedArgs && typeof binding.fixedArgs === "object"
+            ? binding.fixedArgs
+            : {};
+          Object.keys(fixed).forEach(function (key) { args[key] = fixed[key]; });
+          suppliedKeys.forEach(function (key) { args[key] = supplied[key]; });
+          var hostId = "connecta-ui-read-" + String(++nextHostRequestId);
+          pendingHostReads[hostId] = { innerId: message.id };
+          activeHostReads++;
+          send({
+            jsonrpc: "2.0",
+            id: hostId,
+            method: "tools/call",
+            params: {
+              name: "call_tool",
+              arguments: {
+                address: binding.address,
+                args: args,
+                resultMode: "value"
+              }
+            }
+          });
+        }
+        function finishHostRead(message) {
+          var pending = pendingHostReads[message.id];
+          if (!pending) return false;
+          delete pendingHostReads[message.id];
+          activeHostReads--;
+          if (message.error) {
+            finishInnerRead(pending.innerId, false, readError(message.error, "Host rejected read"));
+            return true;
+          }
+          var toolResult = message.result;
+          if (!toolResult || typeof toolResult !== "object") {
+            finishInnerRead(pending.innerId, false, "Host returned an invalid tool result");
+            return true;
+          }
+          var structured = toolResult.structuredContent;
+          if (toolResult.isError || (structured && structured.ok === false)) {
+            var detail = structured && structured.error;
+            var content = Array.isArray(toolResult.content)
+              ? toolResult.content.find(function (block) { return block && block.type === "text"; })
+              : null;
+            finishInnerRead(
+              pending.innerId,
+              false,
+              readError(detail, content && content.text ? content.text : "Read failed")
+            );
+            return true;
+          }
+          var value = structured && structured.ok === true &&
+              Object.prototype.hasOwnProperty.call(structured, "data")
+            ? structured.data
+            : structured !== undefined
+              ? structured
+              : toolResult;
+          finishInnerRead(pending.innerId, true, value);
+          return true;
+        }
         window.addEventListener("message", function (event) {
-          if (event.source !== host) return;
           var message = event.data;
+          if (event.source === view.contentWindow) {
+            if (message && message.type === "connecta/read") beginInnerRead(message);
+            return;
+          }
+          if (event.source !== host) return;
           if (!message || message.jsonrpc !== "2.0") return;
+          if (message.id !== undefined && finishHostRead(message)) return;
           if (message.method === "ui/notifications/tool-result") {
             render(message.params);
             return;
@@ -151,6 +340,8 @@ export const PROGRAM_UI_SHELL_HTML = `<!doctype html>
           // response carries the same id, and announcing initialization on one
           // would assert a handshake that never happened.
           if (message.id === initializeId && message.result !== undefined) {
+            var capabilities = message.result.hostCapabilities;
+            hostCanCallTools = Boolean(capabilities && capabilities.serverTools);
             notify("ui/notifications/initialized", {});
           }
         });

package/src/catalog-service.ts CHANGED Viewed

@@ -25,6 +25,8 @@ import type {
 } from "./registry.js";
 import {
   connectorGuide,
+  connectorGuideRequired,
+  connectorGuideSummary,
   connectorSkillName,
 } from "./skills.js";
 import {
@@ -196,6 +198,7 @@ export interface CatalogDescribeArgs {
 interface CatalogSearchEntry {
   connector: Connector;
   guide?: string;
+  guideSummary?: string;
   tool: {
     name: string;
     address: string;
@@ -208,9 +211,34 @@ interface CatalogSearchEntry {
     requiredInputKeys?: string[];
     outputKeys?: string[];
     annotations?: ToolDef["annotations"];
+    guideRequired?: true;
+    guideRequiredReasons?: GuideRequiredReason[];
   };
 }
+type GuideRequiredReason =
+  | "connector_required"
+  | "approval_required"
+  | "schema_truncated";
+/**
+ * Reasons discovery can determine without reading arguments or guessing at a
+ * task. Summary-only conventions remain an agent decision; hard requirements
+ * are explicit and machine-readable.
+ */
+function guideRequiredReasons(
+  connector: Connector,
+  tool: ToolDef,
+  schemaTruncated: boolean,
+): GuideRequiredReason[] | undefined {
+  if (!connectorGuide(connector)) return undefined;
+  const reasons: GuideRequiredReason[] = [];
+  if (connectorGuideRequired(connector)) reasons.push("connector_required");
+  if (!isExplicitlyReadOnly(tool)) reasons.push("approval_required");
+  if (schemaTruncated) reasons.push("schema_truncated");
+  return reasons.length > 0 ? reasons : undefined;
+}
 /**
  * Code-mode key metadata for one match. Each half is omitted when its schema
  * does not resolve to an object shape, so a program reads "no metadata, use the
@@ -237,6 +265,19 @@ function schemaKeyMetadata(
   };
 }
+/**
+ * The classified-failure subset a scoped search may echo: enough to tell a
+ * transient outage from one an operator must clear, and nothing more. Kept as
+ * its own type rather than `CallErrorDetails` so widening the call-path
+ * classifier cannot widen this discovery-surface field by accident.
+ */
+interface CatalogFailureDetail {
+  code: string;
+  message: string;
+  retryable: boolean;
+  retryAfterMs?: number;
+}
 export interface CatalogSearchPage {
   entries: CatalogSearchEntry[];
   total: number;
@@ -253,6 +294,12 @@ export interface CatalogSearchPage {
     connectorScope?: string;
     unknownConnector?: true;
     unavailableConnectorCount?: number;
+    /** Bounded typed failure for an explicitly scoped unavailable catalog. */
+    catalogError?: CatalogFailureDetail;
+    guide?: string;
+    guideSummary?: string;
+    guideRequired?: true;
+    guideRequiredReasons?: GuideRequiredReason[];
     guidance?: string;
   };
 }
@@ -262,6 +309,9 @@ export interface CatalogDescription {
   name?: string;
   description?: string;
   guide?: string;
+  guideSummary?: string;
+  guideRequired?: true;
+  guideRequiredReasons?: GuideRequiredReason[];
   inputSchema?: unknown;
   outputSchema?: unknown;
   annotations?: ToolDef["annotations"];
@@ -656,10 +706,19 @@ export class CatalogService {
         match.tool.description,
         args.fullDescriptions === true,
       );
+      const requiredReasons = guideRequiredReasons(
+        match.connector,
+        match.tool,
+        renderedInput?.truncated === true || renderedOutput?.truncated === true,
+      );
+      const guideSummary = connectorGuideSummary(match.connector);
       return {
         connector: match.connector,
         ...(connectorGuide(match.connector)
-          ? { guide: connectorSkillName(match.connector.id) }
+          ? {
+              guide: connectorSkillName(match.connector.id),
+              ...(guideSummary ? { guideSummary } : {}),
+            }
           : {}),
         tool: {
           name: match.tool.name,
@@ -697,6 +756,12 @@ export class CatalogService {
           ...(match.tool.annotations
             ? { annotations: match.tool.annotations }
             : {}),
+          ...(requiredReasons
+            ? {
+                guideRequired: true as const,
+                guideRequiredReasons: requiredReasons,
+              }
+            : {}),
         },
       };
     });
@@ -732,6 +797,27 @@ export class CatalogService {
     const unavailableCatalogs = catalogs.filter(
       (catalog) => catalog.status === "rejected",
     ).length;
+    // Named field by field rather than spread: `CallErrorDetails` also carries
+    // connector, operation, recovery, and nextAction, and a discovery read is
+    // not a call — widening the classifier must not silently widen what a
+    // catalog search hands back.
+    const scopedCatalogError = ((): CatalogFailureDetail | undefined => {
+      if (!scopedConnector || catalogs[0]?.status !== "rejected") {
+        return undefined;
+      }
+      const error = classifyCallError(
+        catalogs[0].reason,
+        "catalog_lookup_failed",
+      );
+      return {
+        code: error.code,
+        message: boundedEchoText(error.message),
+        retryable: error.retryable,
+        ...(error.retryAfterMs === undefined
+          ? {}
+          : { retryAfterMs: error.retryAfterMs }),
+      };
+    })();
     const safetyLabel =
       safety === "readOnly"
         ? "read-only "
@@ -740,6 +826,14 @@ export class CatalogService {
           : "";
     const filterRecovery =
       safety === "all" ? "" : " Change safety to inspect the other tools.";
+    const scopedGuide =
+      matches.length === 0 && scopedConnector && connectorGuide(scopedConnector)
+        ? {
+            guide: connectorSkillName(scopedConnector.id),
+            guideSummary: connectorGuideSummary(scopedConnector),
+            required: connectorGuideRequired(scopedConnector),
+          }
+        : undefined;
     const guidance =
       queryTerms.length === 0
         ? undefined
@@ -748,8 +842,10 @@ export class CatalogService {
             ? `Connector "${args.connector}" is not configured in this deployment. Omit connector to search all configured tools.`
             : scopedConnector
               ? unavailableCatalogs > 0
-                ? `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Retry later.`
-                : `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Refine terms or browse it with an empty query.${filterRecovery}`
+                ? `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
+                : scopedGuide?.required
+                  ? `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Fetch queryAnalysis.guide before calling, then refine terms or browse with an empty query.${filterRecovery}`
+                  : `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Refine terms or browse it with an empty query.${filterRecovery}`
               : unavailableCatalogs === 0
                 ? `No matching ${safetyLabel}capability is configured in this deployment. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
                 : `No matching ${safetyLabel}capability was found in the catalogs that answered; ${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
@@ -789,6 +885,23 @@ export class CatalogService {
               ...(unavailableCatalogs > 0
                 ? { unavailableConnectorCount: unavailableCatalogs }
                 : {}),
+              ...(scopedCatalogError ? { catalogError: scopedCatalogError } : {}),
+              ...(scopedGuide
+                ? {
+                    guide: scopedGuide.guide,
+                    ...(scopedGuide.guideSummary
+                      ? { guideSummary: scopedGuide.guideSummary }
+                      : {}),
+                    ...(scopedGuide.required
+                      ? {
+                          guideRequired: true as const,
+                          guideRequiredReasons: [
+                            "connector_required" as const,
+                          ],
+                        }
+                      : {}),
+                  }
+                : {}),
               ...(guidance ? { guidance } : {}),
             },
           }
@@ -853,12 +966,27 @@ export class CatalogService {
         tool.description,
         args.fullDescriptions === true,
       );
+      const requiredReasons = guideRequiredReasons(
+        addressResolution.connector,
+        tool,
+        false,
+      );
+      const guideSummary = connectorGuideSummary(addressResolution.connector);
       return {
         address,
         name: tool.name,
         ...(description !== undefined ? { description } : {}),
         ...(connectorGuide(addressResolution.connector)
-          ? { guide: connectorSkillName(addressResolution.connector.id) }
+          ? {
+              guide: connectorSkillName(addressResolution.connector.id),
+              ...(guideSummary ? { guideSummary } : {}),
+            }
+          : {}),
+        ...(requiredReasons
+          ? {
+              guideRequired: true as const,
+              guideRequiredReasons: requiredReasons,
+            }
           : {}),
         inputSchema: renderSchema(input, format),
         ...(tool.outputSchema
@@ -877,6 +1005,7 @@ export function groupedSearchResult(page: CatalogSearchPage) {
     id: string;
     title?: string;
     guide?: string;
+    guideSummary?: string;
     tools: CatalogSearchEntry["tool"][];
   }> = [];
   const byConnector = new Map<string, (typeof groups)[number]>();
@@ -889,6 +1018,9 @@ export function groupedSearchResult(page: CatalogSearchPage) {
         id: entry.connector.id,
         ...(entry.connector.title ? { title: entry.connector.title } : {}),
         ...(entry.guide ? { guide: entry.guide } : {}),
+        ...(entry.guideSummary
+          ? { guideSummary: entry.guideSummary }
+          : {}),
         tools: [],
       };
       byConnector.set(entry.connector.id, group);
@@ -913,6 +1045,9 @@ export function flatSearchResult(page: CatalogSearchPage) {
     tools: page.entries.map((entry) => ({
       ...entry.tool,
       ...(entry.guide ? { guide: entry.guide } : {}),
+      ...(entry.guideSummary
+        ? { guideSummary: entry.guideSummary }
+        : {}),
     })),
     total: page.total,
     offset: page.offset,

package/src/connectors/api.ts CHANGED Viewed

@@ -5,6 +5,7 @@ import type {
   ConnectorCredentialConfig,
   ConnectorCredentialValues,
   ConnectorContext,
+  ConnectorUsageGuide,
   CredentialTestResult,
   JsonSchema,
   ToolAnnotations,
@@ -41,10 +42,11 @@ export interface ApiOptions {
   /** Optional per-runtime downstream call-admission policy. */
   callAdmission?: ConnectorCallAdmissionPolicy;
   /**
-   * Optional agent-facing usage guide (markdown) served by the `skills`
-   * meta-tool as `connector:<id>`. See `Connector.usageGuide`.
+   * Optional agent-facing usage guide served by `skills` as
+   * `connector:<id>`. A string is markdown; the structured form adds bounded
+   * discovery metadata. See `Connector.usageGuide`.
    */
-  usageGuide?: string;
+  usageGuide?: string | ConnectorUsageGuide;
   /** Optional operator-managed credential exposed through ctx.credential and /credentials. */
   credential?: ConnectorCredentialConfig;
   /** Optional validation behind /credentials' Test action. */

package/src/connectors/remote-mcp.ts CHANGED Viewed

@@ -21,6 +21,7 @@ import type {
   ConnectorCallAdmissionPolicy,
   ConnectorContext,
   ConnectorStatus,
+  ConnectorUsageGuide,
   Logger,
   ToolDef,
 } from "../types.js";
@@ -47,10 +48,11 @@ export interface RemoteMcpOptions {
   /** Optional per-runtime downstream call-admission policy. */
   callAdmission?: ConnectorCallAdmissionPolicy;
   /**
-   * Optional agent-facing usage guide (markdown) served by the `skills`
-   * meta-tool as `connector:<id>`. See `Connector.usageGuide`.
+   * Optional agent-facing usage guide served by `skills` as
+   * `connector:<id>`. A string is markdown; the structured form adds bounded
+   * discovery metadata. See `Connector.usageGuide`.
    */
-  usageGuide?: string;
+  usageGuide?: string | ConnectorUsageGuide;
   auth?: RemoteMcpAuth;
   /**
    * Downstream HTTP redirect policy. Defaults to `"none"`: every redirect is