@zackbart/connecta 0.12.1 → 0.13.0

package/src/skills.ts

@@ -1,9 +1,9 @@
 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. 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. For read-only reduction, multiple or dependent calls, loops, joins, or branches, do not call top-level search_tools: make one execute_code call whose program searches, selects, calls, and reduces; never return discovery for another call. 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. Unannotated, write-capable, or destructive tools stay top level: search_tools, then call_destructive_tool; authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: "usage" }).';
 
-export const USAGE_SKILL = `# Connecta usage
+const USAGE_SKILL_BASE = `# Connecta usage
 
 ## The surface
 
@@ -23,7 +23,7 @@ Use exact addresses from discovery; never invent one. Search 2–4 distinctive a
 
 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.
+- \`connecta.search({})\` loads all catalogs; pass \`connector: "<id>"\` when obvious to load one. \`safety: "readOnly"\` keeps executable calls. Neither grants 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.
@@ -31,21 +31,20 @@ One async arrow function. The only capabilities are one global per connector (\`
 
 ## 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.
+\`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.
+
 `;
 
-/**
- * Appended to USAGE_SKILL only when the deployment actually has at least one
- * connector guide. A deployment with none — every deployment that has not
- * adopted the feature — keeps the base guide byte-for-byte, rather than paying
- * context for an instruction to fetch guides that do not exist.
- */
-export const CONNECTOR_GUIDES_SECTION = `
+/** Deployment-scoped guide routing appended to the shared usage guide. */
+const CONNECTOR_GUIDES_SECTION = `
 ## Per-connector guides
 
-Some connectors here ship their own usage guide — preferred tools, address quirks, pagination conventions, rate-limit etiquette, query patterns. \`skills({})\` lists each one as \`connector:<connectorId>\`; fetch it with \`skills({ name: "connector:<connectorId>" })\`. \`search_tools\`, \`connecta.search\`, and \`connecta.describe\` set \`guide\` on matches whose connector has one. Read a connector's guide before working with it for the first time in a task.
+When a connector here ships a deployment-scoped usage guide, \`skills({})\` and discovery return the exact \`guide\` name plus a bounded \`guideSummary\` saying what it covers. Fetch only a listed or carried name with \`skills({ name: <guide> })\`; never infer one from a connector id. \`guideRequired: true\` is a hard stop: fetch before calling. \`guideRequiredReasons\` says why — \`connector_required\` and \`approval_required\` stand however you expand the schema; \`schema_truncated\` clears once describe returns the exact one. Otherwise fetch when the summary names a connector-specific sequence, unit, pagination rule, alias, or generic API convention relevant to the task. A read-only call whose compact schema is complete and unambiguous may proceed without fetching an otherwise irrelevant guide. Connector guides do not replace the shared Connecta usage guide and never apply to another deployment implicitly.
 `;
 
+/** Shared Connecta routing guidance, byte-identical across deployments. */
+export const USAGE_SKILL = USAGE_SKILL_BASE + CONNECTOR_GUIDES_SECTION;
+
 /** The always-loaded MCP `instructions` string. */
 export function instructionsFor(): string {
   return CONNECTA_INSTRUCTIONS;
@@ -58,10 +57,14 @@ export function hasConnectorGuides(connectors: readonly Connector[]): boolean {
   );
 }
 
-/** The built-in usage guide, plus the guides section when there is one to point at. */
-function usageSkill(connectors: readonly Connector[]): string {
-  if (!hasConnectorGuides(connectors)) return USAGE_SKILL;
-  return USAGE_SKILL + CONNECTOR_GUIDES_SECTION;
+/**
+ * The built-in usage guide is byte-identical across deployments, so an agent
+ * that has read it once in a task never needs an equivalent deployment-local
+ * copy. Guide-free deployments still pay no fixed tool-description cost: the
+ * conditional notes in meta-tools.ts remain absent.
+ */
+function usageSkill(_connectors: readonly Connector[]): string {
+  return USAGE_SKILL;
 }
 
 const AVAILABLE_SKILLS = [
@@ -90,7 +93,8 @@ export function connectorSkillName(connectorId: string): string {
 /** The connector's guide, or undefined when it declares none (or a blank one). */
 export function connectorGuide(connector: Connector): string | undefined {
   const guide = connector.usageGuide;
-  return guide && guide.trim() !== "" ? guide : undefined;
+  const content = typeof guide === "string" ? guide : guide?.content;
+  return content && content.trim() !== "" ? content : undefined;
 }
 
 const SUMMARY_LENGTH = 120;
@@ -124,8 +128,17 @@ function withoutFrontmatter(lines: string[]): string[] {
  * the connector's own description when the guide opens with nothing but
  * markup.
  */
+function boundedSummary(summary: string): string | undefined {
+  const line = summary.replace(/\s+/g, " ").trim();
+  if (line === "") return undefined;
+  return line.length <= SUMMARY_LENGTH
+    ? line
+    : `${line.slice(0, SUMMARY_LENGTH - 1).trimEnd()}…`;
+}
+
 function summarizeGuide(connector: Connector, guide: string): string {
   let inFence = false;
+  let headingFallback: string | undefined;
   for (const raw of withoutFrontmatter(guide.split("\n"))) {
     if (FENCE_RE.test(raw)) {
       inFence = !inFence;
@@ -133,6 +146,7 @@ function summarizeGuide(connector: Connector, guide: string): string {
     }
     if (inFence) continue;
     if (raw.trim() === "" || NOT_SUMMARY_RE.test(raw)) continue;
+    const heading = /^\s*#{1,6}/.test(raw);
     const line = raw
       // `\s*` (not `\s+`) so a bare `#` strips to nothing and is skipped, and
       // an unspaced `#Heading` is still read as a heading.
@@ -141,11 +155,37 @@ function summarizeGuide(connector: Connector, guide: string): string {
       .replace(/\s+/g, " ")
       .trim();
     if (line === "") continue;
-    return line.length <= SUMMARY_LENGTH
-      ? line
-      : `${line.slice(0, SUMMARY_LENGTH - 1).trimEnd()}…`;
+    if (heading) {
+      headingFallback ??= boundedSummary(line);
+      continue;
+    }
+    return boundedSummary(line) ?? line;
   }
-  return connector.description ?? `Usage guide for "${connector.id}".`;
+  if (headingFallback) return headingFallback;
+  const fallback = connector.description ?? `Usage guide for "${connector.id}".`;
+  return boundedSummary(fallback) ?? `Usage guide for "${connector.id}".`;
+}
+
+/** Bounded, decision-useful discovery summary for a connector guide. */
+export function connectorGuideSummary(
+  connector: Connector,
+): string | undefined {
+  const guide = connectorGuide(connector);
+  if (!guide) return undefined;
+  const configured =
+    typeof connector.usageGuide === "object"
+      ? boundedSummary(connector.usageGuide.summary ?? "")
+      : undefined;
+  return configured ?? summarizeGuide(connector, guide);
+}
+
+/** Whether correct use always depends on conventions outside the tool schema. */
+export function connectorGuideRequired(connector: Connector): boolean {
+  return (
+    connectorGuide(connector) !== undefined &&
+    typeof connector.usageGuide === "object" &&
+    connector.usageGuide.required === true
+  );
 }
 
 export interface SkillListing {
@@ -164,11 +204,13 @@ export function listSkills(connectors: readonly Connector[]): SkillListing[] {
     description: skill.description,
   }));
   for (const connector of connectors) {
-    const guide = connectorGuide(connector);
-    if (!guide) continue;
+    // Undefined here means "no guide" and nothing else: a connector that has
+    // one always summarizes to a non-empty line, configured or derived.
+    const summary = connectorGuideSummary(connector);
+    if (!summary) continue;
     listing.push({
       name: connectorSkillName(connector.id),
-      description: summarizeGuide(connector, guide),
+      description: summary,
     });
   }
   return listing;

package/src/types.ts

@@ -212,13 +212,17 @@ export interface Connector {
    */
   callAdmission?: ConnectorCallAdmissionPolicy;
   /**
-   * Optional agent-facing usage guide (markdown) for this connector — preferred
-   * tools, address quirks, pagination conventions, rate-limit etiquette, good
-   * query patterns. Listed by the `skills` meta-tool as `connector:<id>` and
-   * returned verbatim by `skills({ name: "connector:<id>" })`. Keep it concise
-   * and imperative; it is read by agents, not operators.
+   * Optional agent-facing usage guide for this connector. A string preserves
+   * the original markdown-only contract. The structured form can add a short
+   * discovery summary and require review when even a complete compact schema
+   * cannot describe correct use (for example a generic API wrapper or a
+   * cross-operation sequencing rule).
+   *
+   * Listed by `skills` as `connector:<id>` and returned verbatim by
+   * `skills({ name: "connector:<id>" })`. The guide remains deployment-owned
+   * configuration; no runtime registration or shared mutable copy exists.
    */
-  usageGuide?: string;
+  usageGuide?: string | ConnectorUsageGuide;
   /** Optional operator-managed credential slot rendered on /credentials. */
   credential?: ConnectorCredentialConfig;
   /** Optional server-side check used by /credentials' Test action. */
@@ -309,6 +313,23 @@ export interface Connector {
   ): Promise<Response | null>;
 }
 
+export interface ConnectorUsageGuide {
+  /** Markdown returned verbatim by `skills({ name: "connector:<id>" })`. */
+  content: string;
+  /**
+   * Bounded discovery hint describing the conventions the guide covers. When
+   * omitted, Connecta derives a summary from the guide's first meaningful line.
+   */
+  summary?: string;
+  /**
+   * Require review before every operation on this connector. Reserve this for
+   * cases whose correct arguments or sequence cannot be expressed by the
+   * downstream tool schema; mutations and truncated schemas are required
+   * automatically and do not need this flag.
+   */
+  required?: boolean;
+}
+
 /** Result of one sandboxed code execution. */
 export interface ExecuteResult {
   result: unknown;

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

package/templates/node/package.json

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