@zackbart/connecta 0.4.1 → 0.5.0

package/src/meta-tools.ts

@@ -13,8 +13,19 @@ import {
   messageLooksRetryable,
   type CallErrorDetails,
 } from "./errors.js";
-import type { Registry } from "./registry.js";
-import { AVAILABLE_SKILLS } from "./skills.js";
+import {
+  isValidMaxResultBytes,
+  MIN_MAX_RESULT_BYTES,
+  resolveMaxResultBytes,
+  type RegistryView,
+} from "./registry.js";
+import {
+  connectorGuide,
+  connectorSkillName,
+  hasConnectorGuides,
+  listSkills,
+  resolveSkill,
+} from "./skills.js";
 import type { ConnectorStatus, KVStorage, ToolDef } from "./types.js";
 
 interface TextContent {
@@ -150,19 +161,28 @@ function isContinuationByte(b: number): boolean {
  * forward to the end of that codepoint instead so paging always advances.
  * Assumes `offset` is itself a codepoint boundary (offsets are the prior
  * `nextOffset`, which this function guarantees, and 0 is always a boundary).
+ *
+ * The return is always `> offset` while `offset < total`, whatever `end` is
+ * asked for. That is the belt-and-braces half of issue #32: cap validation
+ * keeps an empty window from arising in the first place, and this keeps an
+ * empty window from turning into a `nextOffset === offset` paging loop if one
+ * ever does. Exported for direct testing of that invariant.
  */
-function alignEndToCharBoundary(
+export function alignEndToCharBoundary(
   bytes: Uint8Array,
   offset: number,
   end: number,
   total: number,
 ): number {
   if (end >= total) return total;
-  let e = end;
+  // A window that reaches no further than `offset` yields no bytes and no
+  // progress; widen it to one byte and let the codepoint walk below finish it.
+  const wanted = Math.max(end, offset + 1);
+  let e = wanted;
   while (e > offset && isContinuationByte(bytes[e])) e--;
   if (e === offset) {
     // Window is narrower than the codepoint at `offset`; take the whole thing.
-    e = end;
+    e = wanted;
     while (e < total && isContinuationByte(bytes[e])) e++;
   }
   return e;
@@ -310,6 +330,7 @@ export interface CallArgs {
 export interface GetResultArgs {
   id: string;
   offset?: number;
+  /** Page size in bytes; a whole number >= 1. Defaults to the deployment cap. */
   maxBytes?: number;
 }
 export interface BatchCall {
@@ -339,12 +360,13 @@ export interface SkillArgs {
 /**
  * The nine meta-tool handlers over a registry. Exported for direct testing;
  * registerMetaTools() wires them onto an McpServer. `opts.maxResultBytes`
- * overrides the registry's default result-size cap; `opts.defaultToolTimeoutMs`
+ * overrides the registry's default result-size cap (a connector's own
+ * `maxResultBytes` overrides it in turn); `opts.defaultToolTimeoutMs`
  * supplies a deadline for calls that don't carry one. (execute_code, the
  * optional tenth tool, is registered separately by registerExecuteTool.)
  */
 export function createMetaTools(
-  registry: Registry,
+  registry: RegistryView,
   baseUrl: string,
   opts: {
     maxResultBytes?: number;
@@ -355,7 +377,10 @@ export function createMetaTools(
     activity?: ActivityRequestContext;
   } = {},
 ) {
-  const cap = opts.maxResultBytes ?? registry.maxResultBytes;
+  const globalCap = resolveMaxResultBytes(
+    opts.maxResultBytes,
+    registry.maxResultBytes,
+  );
   const defaultToolTimeoutMs = normalizeTimeoutMs(opts.defaultToolTimeoutMs);
   const probeTimeoutMs =
     normalizeTimeoutMs(opts.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
@@ -442,6 +467,16 @@ export function createMetaTools(
       );
     }
     const results = registry.resultsStorage();
+    // Result-size cap for THIS call: the connector's own override wins, then
+    // the deployment-wide value, then the built-in default (already folded
+    // into `globalCap`). Resolved per call so one batch_call can mix a
+    // tight-capped connector with siblings on the global cap. An override the
+    // registry already warned about at startup is dropped here, so the
+    // connector simply inherits `globalCap`.
+    const cap = resolveMaxResultBytes(
+      resolved.connector.maxResultBytes,
+      globalCap,
+    );
     const fields = call.fields && call.fields.length > 0 ? call.fields : null;
     // An explicit per-call deadline always wins; the config default only fills
     // the gap, and stays off entirely when the deployment sets none.
@@ -632,6 +667,7 @@ export function createMetaTools(
 
   return {
     async skills(args: SkillArgs = {}): Promise<ToolResult> {
+      const connectors = registry.listConnectors();
       if (!args.name) {
         return {
           content: [
@@ -639,19 +675,15 @@ export function createMetaTools(
               type: "text",
               text:
                 'Available skills. Fetch one with skills({ name: "<name>" }).\n\n' +
-                AVAILABLE_SKILLS.map(
-                  (skill) => `- \`${skill.name}\` — ${skill.description}`,
-                ).join("\n"),
+                listSkills(connectors)
+                  .map((skill) => `- \`${skill.name}\` — ${skill.description}`)
+                  .join("\n"),
             },
           ],
         };
       }
-      const skill = AVAILABLE_SKILLS.find((item) => item.name === args.name);
-      if (!skill) {
-        return errorResult(
-          `Unknown skill "${args.name}". Available: ${AVAILABLE_SKILLS.map((item) => item.name).join(", ")}.`,
-        );
-      }
+      const skill = resolveSkill(args.name, connectors);
+      if (!skill.found) return errorResult(skill.message);
       return { content: [{ type: "text", text: skill.content }] };
     },
 
@@ -679,12 +711,17 @@ export function createMetaTools(
               status = { state: "error", message: msg(err) };
             }
           } else {
+            // "error" comes from THIS view's own observations — a sibling
+            // toolkit's failure is not this session's experience — while
+            // ok/unknown may lean on the deployment-wide success signal, since
+            // "the connector answers at all" is a fact about the connector.
+            // Unscoped, the two are the same log, so this is unchanged there.
             status = {
               state:
                 observed?.consecutiveFailures &&
                 observed.consecutiveFailures > 0
                   ? ("error" as const)
-                  : observed?.lastSuccessAt || c.kind === "api"
+                  : registry.hasObservedSuccess(c.id) || c.kind === "api"
                     ? ("ok" as const)
                     : ("unknown" as const),
               ...(observed?.lastError ? { message: observed.lastError } : {}),
@@ -742,6 +779,7 @@ export function createMetaTools(
         connectorId: string;
         connectorTitle?: string;
         connectorDescription?: string;
+        connectorGuideSkill?: string;
         tool: ToolDef;
         score: number;
         order: number;
@@ -764,6 +802,9 @@ export function createMetaTools(
               connectorId: c.id,
               connectorTitle: c.title,
               connectorDescription: c.description,
+              ...(connectorGuide(c)
+                ? { connectorGuideSkill: connectorSkillName(c.id) }
+                : {}),
               tool: ranked.tool,
               score: ranked.score,
               order: orderBase + ranked.order,
@@ -778,6 +819,8 @@ export function createMetaTools(
         id: string;
         title?: string;
         description?: string;
+        /** Skill name of this connector's usage guide, when it has one. */
+        guide?: string;
         tools: Array<{
           name: string;
           address: string;
@@ -795,6 +838,9 @@ export function createMetaTools(
             id: match.connectorId,
             ...(match.connectorTitle ? { title: match.connectorTitle } : {}),
             description: match.connectorDescription,
+            ...(match.connectorGuideSkill
+              ? { guide: match.connectorGuideSkill }
+              : {}),
             tools: [],
           };
           byConnector.set(match.connectorId, group);
@@ -899,6 +945,9 @@ export function createMetaTools(
             tool.description,
             args.fullDescriptions === true,
           ),
+          ...(connectorGuide(resolved.connector)
+            ? { guide: connectorSkillName(resolved.connector.id) }
+            : {}),
           inputSchema: format === "json" ? schema : compactSchema(schema),
           ...(tool.outputSchema
             ? {
@@ -925,6 +974,20 @@ export function createMetaTools(
     },
 
     async getResult(args: GetResultArgs): Promise<ToolResult> {
+      // Client-supplied page size: a normal input-validation error, not a
+      // clamp. Callers arriving over MCP are rejected earlier by the
+      // registered zod schema and never reach this branch, so it exists for
+      // in-process callers of createMetaTools — which have no schema in front
+      // of them — and to keep the rule true of the handler on its own terms.
+      if (
+        args.maxBytes !== undefined &&
+        !isValidMaxResultBytes(args.maxBytes)
+      ) {
+        return errorResult(
+          `Invalid maxBytes ${args.maxBytes}: must be a whole number of bytes ` +
+            `>= ${MIN_MAX_RESULT_BYTES}. Omit it to use the deployment default.`,
+        );
+      }
       const results = registry.resultsStorage();
       const stored = await results.get(`result:${args.id}`);
       if (stored === null || stored === undefined) {
@@ -933,7 +996,11 @@ export function createMetaTools(
       const bytes = enc.encode(stored);
       const total = bytes.length;
       const offset = Math.max(0, Math.trunc(args.offset ?? 0));
-      const maxBytes = args.maxBytes ?? cap;
+      // Page size only: a stashed result carries no connector identity, so
+      // get_result keeps the deployment-wide default when none is requested.
+      // Both sides are validated by now — the argument above, `globalCap` at
+      // intake — so `offset + maxBytes` always reaches past `offset`.
+      const maxBytes = args.maxBytes ?? globalCap;
       // Align the slice end to a codepoint boundary so a multi-byte char is
       // never split across pages (which would emit U+FFFD on both sides).
       // `nextOffset` is this aligned end, so it is a valid boundary for the
@@ -1076,7 +1143,7 @@ const CALL_DESC =
 const CALL_DESTRUCTIVE_DESC =
   "Invoke any tool that is not explicitly annotated readOnlyHint: true, including unannotated, write-capable, or destructive tools. The MCP destructiveHint on this meta-tool lets the host request human approval before execution. Use only after reviewing the downstream tool schema and consequences.";
 const GET_RESULT_DESC =
-  "Page a truncated result stashed by call_tool/batch_call. Input { id, offset?, maxBytes? } → { text, offset, nextOffset?, totalBytes } sliced by byte offset. Unknown/expired id is an error.";
+  "Page a truncated result stashed by call_tool/batch_call. Input { id, offset?, maxBytes? } → { text, offset, nextOffset?, totalBytes } sliced by byte offset. maxBytes is a whole number of bytes >= 1 (omit for the deployment default). Unknown/expired id is an error.";
 const BATCH_DESC =
   "Use for 2–10 independent tools explicitly annotated readOnlyHint: true. Calls run in parallel with shared request-scoped clients; use execute_code when available instead for dependencies or in-sandbox reduction. Unannotated, write-capable, and destructive tools are refused. Batch timeout, safe retry, result mode, and diagnostics defaults may be overridden per call.";
 const AUTHORIZE_DESC =
@@ -1084,6 +1151,37 @@ const AUTHORIZE_DESC =
 const SKILLS_DESC =
   'List or fetch concise guidance for choosing among Connecta meta-tools. Call skills({ name: "usage" }) once when the routing workflow is unfamiliar; do not refetch it in the same task.';
 
+/**
+ * Sentences appended to a meta-tool description only when this connection
+ * actually has connector guides. Tool descriptions are always-loaded context,
+ * so a deployment with no guides gets every base description unchanged rather
+ * than paying for text about a feature it does not use.
+ *
+ * Registration is per connection and reads the connection's own registry view,
+ * so under a toolkit these sentences reflect the SCOPED connector set: a scoped
+ * session whose connectors carry no guides sees the base descriptions, and
+ * never learns from a tool description that guides exist out of scope.
+ */
+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.',
+  search:
+    " A connector group carrying `guide` has a usage guide; fetch it with skills({ name: <guide> }).",
+  describe:
+    " An entry carrying `guide` belongs to a connector with a usage guide; fetch it with skills({ name: <guide> }).",
+} as const;
+
+/** `base`, plus its guide note when any VISIBLE connector carries a guide. */
+function describedFor(
+  registry: RegistryView,
+  base: string,
+  note: keyof typeof GUIDE_NOTES,
+): string {
+  return hasConnectorGuides(registry.listConnectors())
+    ? base + GUIDE_NOTES[note]
+    : base;
+}
+
 /**
  * Connecta refuses downstream tools that are not explicitly annotated
  * read-only, so its own meta-tools must carry the same hints — otherwise a
@@ -1107,7 +1205,7 @@ const READ_ONLY_LOCAL = {
 /** Register the nine meta-tools onto an McpServer instance. */
 export function registerMetaTools(
   server: McpServer,
-  registry: Registry,
+  registry: RegistryView,
   ctx: {
     baseUrl: string;
     maxResultBytes?: number;
@@ -1126,7 +1224,7 @@ export function registerMetaTools(
   server.registerTool(
     "skills",
     {
-      description: SKILLS_DESC,
+      description: describedFor(registry, SKILLS_DESC, "skills"),
       inputSchema: { name: z.string().optional() },
       annotations: {
         readOnlyHint: true,
@@ -1151,7 +1249,7 @@ export function registerMetaTools(
   server.registerTool(
     "search_tools",
     {
-      description: SEARCH_DESC,
+      description: describedFor(registry, SEARCH_DESC, "search"),
       inputSchema: {
         query: z.string().optional(),
         connector: z.string().optional(),
@@ -1168,7 +1266,7 @@ export function registerMetaTools(
   server.registerTool(
     "describe_tools",
     {
-      description: DESCRIBE_DESC,
+      description: describedFor(registry, DESCRIBE_DESC, "describe"),
       inputSchema: {
         addresses: z.array(z.string()),
         format: z.enum(["compact", "json"]).optional(),
@@ -1247,7 +1345,10 @@ export function registerMetaTools(
       inputSchema: {
         id: z.string(),
         offset: z.number().int().nonnegative().optional(),
-        maxBytes: z.number().int().positive().optional(),
+        // Same rule as isValidMaxResultBytes, expressed for the wire: sharing
+        // the floor constant keeps the schema from drifting away from the
+        // in-handler check if MIN_MAX_RESULT_BYTES ever moves.
+        maxBytes: z.number().int().min(MIN_MAX_RESULT_BYTES).optional(),
       },
       annotations: READ_ONLY_LOCAL,
     },