@zackbart/connecta 0.4.1 → 0.6.0

package/src/meta-tools.ts

@@ -13,8 +13,25 @@ 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 {
+  DEFAULT_PROBE_TIMEOUT_MS,
+  normalizeTimeoutMs,
+  withTimeout,
+} from "./timeout.js";
+import { credentialVerdictApplies } from "./credential-health.js";
 import type { ConnectorStatus, KVStorage, ToolDef } from "./types.js";
 
 interface TextContent {
@@ -64,50 +81,6 @@ type ErrorDetails = CallErrorDetails;
  */
 export const MAX_RETRY_BACKOFF_MS = 10_000;
 
-/** A finite, positive integer number of milliseconds, or undefined. */
-function normalizeTimeoutMs(value: number | undefined): number | undefined {
-  if (value === undefined || !Number.isFinite(value) || !(value > 0)) {
-    return undefined;
-  }
-  return Math.max(1, Math.trunc(value));
-}
-
-/**
- * Generous default bound for a single downstream probe/catalog call in the
- * list/search/describe fan-out. High enough to trip only on a pathological
- * hang, not a realistically slow probe.
- */
-const DEFAULT_PROBE_TIMEOUT_MS = 30_000;
-
-/**
- * Reject `promise` after `ms` if it has not settled, so one hung downstream
- * cannot stall a whole fan-out. NOTE: this bounds only the caller-facing wait —
- * the registry probe methods take no AbortSignal, so the underlying fetch is
- * NOT cancelled and keeps running in the background. Real cancellation
- * (AbortSignal plumbed through the registry) is a deferred follow-up.
- */
-function withTimeout<T>(
-  promise: Promise<T>,
-  ms: number,
-  label: string,
-): Promise<T> {
-  return new Promise<T>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      reject(new Error(`${label} timed out after ${ms}ms`));
-    }, ms);
-    promise.then(
-      (value) => {
-        clearTimeout(timer);
-        resolve(value);
-      },
-      (err) => {
-        clearTimeout(timer);
-        reject(err);
-      },
-    );
-  });
-}
-
 /**
  * How long to wait before the next attempt, or `undefined` for "don't retry".
  *
@@ -142,6 +115,48 @@ function isContinuationByte(b: number): boolean {
   return (b & 0xc0) === 0x80;
 }
 
+/** Smallest accepted `get_result` byte offset. */
+export const MIN_RESULT_OFFSET = 0;
+
+/**
+ * The one definition of a usable `get_result` offset: a whole number of bytes
+ * at or past {@link MIN_RESULT_OFFSET}. Shared by the registered zod schema and
+ * the handler's own check, the way `isValidMaxResultBytes` is shared across the
+ * cap's intake points (issue #32) — so a value valid at the wire is valid in
+ * process, and the two cannot drift.
+ *
+ * Everything else is rejected rather than coerced, because coercion is how an
+ * out-of-domain offset used to void a result silently: `Math.max(0, NaN)` is
+ * `NaN`, which slices to nothing, serializes as `"offset": null`, and reports
+ * no `nextOffset` — a caller sees a successful, empty result instead of an
+ * error. An offset past the end of the payload stays legal: it is a whole
+ * number of bytes, and it answers with an empty final page.
+ */
+export function isValidResultOffset(value: number): boolean {
+  return Number.isInteger(value) && value >= MIN_RESULT_OFFSET;
+}
+
+/**
+ * Move a byte `offset` back to the nearest UTF-8 codepoint boundary in
+ * `[0, offset]`, so decoding from it never starts mid-character (which emits
+ * U+FFFD for the severed tail).
+ *
+ * Backwards, never forwards: re-serving a few bytes the caller already has is
+ * recoverable, silently skipping the rest of a character is not. Offsets the
+ * server itself produced (`nextOffset`) are already boundaries and come back
+ * unchanged, so this only moves an offset a client computed on its own
+ * (issue #38). An offset at or past `bytes.length` is left alone — there is no
+ * character there to split.
+ */
+export function alignStartToCharBoundary(
+  bytes: Uint8Array,
+  offset: number,
+): number {
+  let o = offset;
+  while (o > 0 && isContinuationByte(bytes[o])) o--;
+  return o;
+}
+
 /**
  * Move a byte `end` back to the nearest UTF-8 codepoint boundary in
  * `(offset, total]`, so decoding `bytes[offset, end)` never splits a codepoint
@@ -150,19 +165,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;
@@ -220,39 +244,88 @@ function applyFieldsToContent(
 
 // --- result-size guard + get_result (feature 1) ---------------------------
 
-function contentBytes(content: TextContent[]): number {
-  let n = 0;
-  for (const b of content)
-    if (b.type === "text") n += enc.encode(b.text).length;
-  return n;
+/**
+ * The one serialization every result guard measures, stashes, and pages: JSON
+ * text for whatever JSON can represent, and `String(value)` for the returns
+ * JSON renders as `undefined` — a handler that returns nothing, a function, or
+ * a Symbol. `JSON.stringify` is *typed* as returning `string` while actually
+ * returning `undefined` for those, which is how a handler returning `undefined`
+ * reached clients as a `{"type":"text"}` block carrying no `text` at all: the
+ * size guard measured `enc.encode(undefined)` — the empty string, per the
+ * WebIDL default — and emitted the non-string unchanged (issue #42). `null`
+ * needs no special case; JSON renders it as `"null"`.
+ *
+ * Shared by `guardText`, `guardValue`, and execute_code's `guardResultValue` so
+ * the three give one answer to the same question. A value JSON cannot serialize
+ * at all (a BigInt) still throws, as before, and is reported as a failure.
+ */
+export function serializeResultText(value: unknown): string {
+  const serialized = JSON.stringify(value, null, 2);
+  return serialized === undefined ? String(value) : serialized;
+}
+
+/**
+ * Stash `text` under `result:<uuid>` (ttl 900s) and describe it as the
+ * truncation notice every over-cap path hands back.
+ */
+async function stashResult(
+  text: string,
+  results: KVStorage,
+  totalBytes: number,
+): Promise<{
+  truncated: true;
+  resultId: string;
+  totalBytes: number;
+  hint: string;
+}> {
+  const id = crypto.randomUUID();
+  await results.set(`result:${id}`, text, { ttlSeconds: RESULT_TTL_SECONDS });
+  return {
+    truncated: true,
+    resultId: id,
+    totalBytes,
+    hint: "use get_result {id, offset} to page, or re-call with fields to select less",
+  };
 }
 
 /**
  * Return `text` as a single content block; if it exceeds `cap` bytes, stash the
- * full text under `result:<uuid>` (ttl 900s) and return the first `cap` bytes
- * followed by a JSON truncation notice pointing at get_result.
+ * full text and return the first `cap` bytes followed by a JSON truncation
+ * notice pointing at get_result. `bytes` is `text` already encoded, so a caller
+ * that had to measure it to make this decision doesn't encode it twice.
  */
-async function guardText(
+async function guardEncoded(
   text: string,
+  bytes: Uint8Array,
   results: KVStorage,
   cap: number,
 ): Promise<ToolResult> {
-  const bytes = enc.encode(text);
   if (bytes.length <= cap) {
     return { content: [{ type: "text", text }] };
   }
-  const id = crypto.randomUUID();
-  await results.set(`result:${id}`, text, { ttlSeconds: RESULT_TTL_SECONDS });
+  const notice = await stashResult(text, results, bytes.length);
   const head = dec.decode(
     bytes.slice(0, alignEndToCharBoundary(bytes, 0, cap, bytes.length)),
   );
-  const notice = JSON.stringify({
-    truncated: true,
-    resultId: id,
-    totalBytes: bytes.length,
-    hint: "use get_result {id, offset} to page, or re-call with fields to select less",
-  });
-  return { content: [{ type: "text", text: `${head}\n${notice}` }] };
+  return {
+    content: [{ type: "text", text: `${head}\n${JSON.stringify(notice)}` }],
+  };
+}
+
+/** {@link guardEncoded} over a string that has not been measured yet. */
+async function guardText(
+  text: string,
+  results: KVStorage,
+  cap: number,
+): Promise<ToolResult> {
+  // `JSON.stringify`'s type says `string` where its behavior says `string |
+  // undefined`, so TypeScript alone does not keep a non-string out of here.
+  // Normalizing at the door means the size check below always measures exactly
+  // the text that is emitted, and no future caller can launder a non-string
+  // through it the way issue #42 describes.
+  const body: string =
+    typeof text === "string" ? text : serializeResultText(text);
+  return guardEncoded(body, enc.encode(body), results, cap);
 }
 
 /** Store an oversized JSON value and replace it with a page handle. */
@@ -261,17 +334,54 @@ async function guardValue(
   results: KVStorage,
   cap: number,
 ): Promise<unknown> {
-  const text = JSON.stringify(value, null, 2) ?? String(value);
+  const text = serializeResultText(value);
   const bytes = enc.encode(text);
   if (bytes.length <= cap) return value;
-  const id = crypto.randomUUID();
-  await results.set(`result:${id}`, text, { ttlSeconds: RESULT_TTL_SECONDS });
-  return {
-    truncated: true,
-    resultId: id,
-    totalBytes: bytes.length,
-    hint: "use get_result {id, offset} to page, or re-call with fields to select less",
-  };
+  return stashResult(text, results, bytes.length);
+}
+
+/**
+ * Bound a downstream MCP `content` array by `cap`, measuring the serialized
+ * envelope — the same string that gets stashed and paged, and the one that
+ * counts every block rather than only the text ones.
+ *
+ * Both halves matter (issue #43). Measuring only text blocks meant an oversized
+ * all-image result scored zero bytes and was returned inline unbounded, with no
+ * `resultId` to page from; and measuring one string while truncating another
+ * left `totalBytes` and the served head describing something the cap was never
+ * compared against.
+ *
+ * Over the cap, what a client gets depends on whether a prefix is usable. An
+ * all-text envelope keeps the historical head + notice — a JSON prefix is still
+ * readable. An envelope carrying non-text blocks is replaced by the notice
+ * alone: the head of a half-written base64 image is of no use to anyone, and
+ * cutting one leaves unparseable block structure behind. Either way the full
+ * envelope is stashed and pages through `get_result`.
+ */
+async function guardContent(
+  content: TextContent[],
+  results: KVStorage,
+  cap: number,
+): Promise<ToolResult> {
+  let text: string;
+  try {
+    text = JSON.stringify(content, null, 2);
+  } catch {
+    // A block carrying a BigInt or a cycle cannot be serialized, so it cannot
+    // be measured, stashed, or paged either — there is nothing this guard could
+    // do with it. Pass it through as the old text-only measure did, rather than
+    // turning a call that used to succeed into result_processing_failed.
+    return { content };
+  }
+  const bytes = enc.encode(text);
+  // Under the cap the downstream blocks pass through untouched, non-text ones
+  // included, in their original order.
+  if (bytes.length <= cap) return { content };
+  if (content.every((b) => b.type === "text")) {
+    return guardEncoded(text, bytes, results, cap);
+  }
+  const notice = await stashResult(text, results, bytes.length);
+  return { content: [{ type: "text", text: JSON.stringify(notice) }] };
 }
 
 // --- compact schema rendering (feature 3a) --------------------------------
@@ -309,7 +419,12 @@ export interface CallArgs {
 }
 export interface GetResultArgs {
   id: string;
+  /**
+   * Byte offset to page from; a whole number >= 0, aligned back to the nearest
+   * character boundary and reported as the response's `offset`. Defaults to 0.
+   */
   offset?: number;
+  /** Page size in bytes; a whole number >= 1. Defaults to the deployment cap. */
   maxBytes?: number;
 }
 export interface BatchCall {
@@ -338,16 +453,19 @@ 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`
+ * registerMetaTools() wires them onto an McpServer. `opts.defaultToolTimeoutMs`
  * supplies a deadline for calls that don't carry one. (execute_code, the
  * optional tenth tool, is registered separately by registerExecuteTool.)
+ *
+ * The deployment-wide result-size cap is read off the registry view rather than
+ * passed in: `ConnectaConfig.maxResultBytes` and the per-connector override are
+ * the only places a cap is set, so there is one answer to where a deployment
+ * sets it (issue #44).
  */
 export function createMetaTools(
-  registry: Registry,
+  registry: RegistryView,
   baseUrl: string,
   opts: {
-    maxResultBytes?: number;
     /** Deadline applied when a call passes no `timeoutMs`. Off when unset. */
     defaultToolTimeoutMs?: number;
     /** Per-connector deadline for the list/search/describe probe fan-out. Default 30_000. */
@@ -355,7 +473,8 @@ export function createMetaTools(
     activity?: ActivityRequestContext;
   } = {},
 ) {
-  const cap = opts.maxResultBytes ?? registry.maxResultBytes;
+  // Already normalized and warned about at registry construction.
+  const globalCap = registry.maxResultBytes;
   const defaultToolTimeoutMs = normalizeTimeoutMs(opts.defaultToolTimeoutMs);
   const probeTimeoutMs =
     normalizeTimeoutMs(opts.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
@@ -442,6 +561,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.
@@ -458,6 +587,20 @@ export function createMetaTools(
       ).find((tool) => tool.name === resolved.toolName);
     } catch (err) {
       catalogMs += Date.now() - catalogStarted;
+      // A connector whose catalog cannot be fetched is as unusable as one whose
+      // execution fails, so it feeds health accounting the same way the
+      // execution catch below does — otherwise a connector every call_tool
+      // fails against (a revoked downstream grant, say) still reads clean from
+      // the cheap `list_connectors({ probe: false })` signal.
+      //
+      // Recorded HERE rather than inside the registry's catalog fetch on
+      // purpose: `registry` is this connection's VIEW, so a toolkit-scoped
+      // session records into its own log as well as the deployment-wide one,
+      // which `Registry.refreshTools` could not reach. A cache hit that avoids
+      // a live listTools call therefore records nothing either way — it is not
+      // evidence of health, and success stays what it has always been: an
+      // actual downstream call that returned.
+      registry.recordFailure(resolved.connector.id, Date.now() - started, err);
       // classifyCallError so a typed auth_required thrown while listing tools
       // (e.g. a revoked downstream OAuth grant) keeps its code.
       return failed(classifyCallError(err, "catalog_lookup_failed"));
@@ -590,16 +733,7 @@ export function createMetaTools(
       if (resolved.connector.kind === "mcp") {
         let content = mr?.content ?? [];
         if (fields) content = applyFieldsToContent(content, fields);
-        let toolResult: ToolResult;
-        if (contentBytes(content) > cap) {
-          toolResult = await guardText(
-            JSON.stringify(content, null, 2),
-            results,
-            cap,
-          );
-        } else {
-          toolResult = { content };
-        }
+        const toolResult = await guardContent(content, results, cap);
         resultProcessingMs += Date.now() - processingStarted;
         record("success");
         return {
@@ -611,7 +745,7 @@ export function createMetaTools(
       }
       const value = fields ? applyFields(result, fields) : result;
       const toolResult = await guardText(
-        JSON.stringify(value, null, 2),
+        serializeResultText(value),
         results,
         cap,
       );
@@ -632,6 +766,7 @@ export function createMetaTools(
 
   return {
     async skills(args: SkillArgs = {}): Promise<ToolResult> {
+      const connectors = registry.listConnectors();
       if (!args.name) {
         return {
           content: [
@@ -639,19 +774,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 }] };
     },
 
@@ -659,9 +790,9 @@ export function createMetaTools(
       const probe = args.probe ?? true;
       const out = await Promise.all(
         registry.listConnectors().map(async (c) => {
-          const checkedAt = new Date().toISOString();
           const statusStarted = Date.now();
           const observed = registry.healthFor(c.id);
+          const verdict = await registry.credentialHealthFor(c.id);
           let status:
             | ConnectorStatus
             | { state: "ok" | "error" | "unknown"; message?: string };
@@ -678,18 +809,76 @@ export function createMetaTools(
               // hanging the whole list_connectors call.
               status = { state: "error", message: msg(err) };
             }
+          } else if (
+            verdict &&
+            // Deployment-wide, deliberately, like `hasObservedSuccess` beside
+            // it: a sibling toolkit's successful call proves the shared
+            // credential works, and a verdict retired for one view but not
+            // another would make the same connector read differently per scope
+            // for a reason that has nothing to do with scope.
+            credentialVerdictApplies(verdict, registry.observedSuccessAt(c.id))
+          ) {
+            // The proactive layer (issue #24): a liveness check already found
+            // the stored credential dead, so say so on the cheap path instead of
+            // waiting for an agent's real call to discover it. Only while it is
+            // the freshest evidence — a successful call since then retires it.
+            status = {
+              state: verdict.state,
+              ...(verdict.message ? { message: verdict.message } : {}),
+              ...(verdict.authorizationUrl
+                ? { authorizationUrl: verdict.authorizationUrl }
+                : {}),
+            };
           } 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.
+            const derived =
+              observed?.consecutiveFailures && observed.consecutiveFailures > 0
+                ? ("error" as const)
+                : registry.hasObservedSuccess(c.id) || c.kind === "api"
+                  ? ("ok" as const)
+                  : ("unknown" as const);
             status = {
+              // A successful liveness check upgrades "unknown" — nothing has
+              // been called yet, but the credential was verified, which is how
+              // re-authorization shows up here as ok rather than as an absence
+              // of evidence. It never DOWNgrades an observed failure: a real
+              // call that failed is stronger evidence than a background check.
               state:
-                observed?.consecutiveFailures &&
-                observed.consecutiveFailures > 0
-                  ? ("error" as const)
-                  : observed?.lastSuccessAt || c.kind === "api"
-                    ? ("ok" as const)
-                    : ("unknown" as const),
+                derived === "unknown" && verdict?.state === "ok"
+                  ? ("ok" as const)
+                  : derived,
               ...(observed?.lastError ? { message: observed.lastError } : {}),
             };
           }
+          // Stamped where the observation actually happened — after the status
+          // probe, not before it. A 30-second probe stamped at its start would
+          // report a verdict older than it is, and would lose the race against a
+          // real call that succeeded WHILE it ran (that success must retire the
+          // verdict, and only an honest timestamp says so).
+          const checkedAt = new Date().toISOString();
+          // A live status probe IS a liveness observation of the stored
+          // credential, so it updates the same verdict a background check
+          // writes: the cached read afterwards agrees with what the operator
+          // just saw, and they are not swept again moments later. Recorded from
+          // the STATUS phase only, and only when the connector actually answered
+          // — a catalog refresh below is not a credential check (the sweep never
+          // fetches one), it is already counted in the health log, and letting
+          // its failure land here would spend the freshness budget on it. The
+          // registry ignores this for connectors storing no credential of ours.
+          if (probe && (status.state === "ok" || status.state === "auth_required")) {
+            await registry.recordCredentialHealth(c.id, {
+              state: status.state,
+              checkedAt,
+              ...(status.message ? { message: status.message } : {}),
+              ...("authorizationUrl" in status && status.authorizationUrl
+                ? { authorizationUrl: status.authorizationUrl }
+                : {}),
+            });
+          }
           let tools = registry.peekTools(c.id);
           // An auth_required status may have just started OAuth. A second
           // listTools probe would overwrite its state/verifier while returning
@@ -709,6 +898,9 @@ export function createMetaTools(
           }
           const latencyMs = Date.now() - statusStarted;
           const latestObserved = registry.healthFor(c.id);
+          const credentialCheck = probe
+            ? await registry.credentialHealthFor(c.id)
+            : verdict;
           return {
             id: c.id,
             ...(c.title ? { title: c.title } : {}),
@@ -719,6 +911,7 @@ export function createMetaTools(
             latencyMs,
             probe,
             ...(latestObserved ?? observed ?? {}),
+            ...(credentialCheck ? { credentialCheck } : {}),
             ...("authorizationUrl" in status && status.authorizationUrl
               ? { authorizationUrl: status.authorizationUrl }
               : {}),
@@ -742,6 +935,7 @@ export function createMetaTools(
         connectorId: string;
         connectorTitle?: string;
         connectorDescription?: string;
+        connectorGuideSkill?: string;
         tool: ToolDef;
         score: number;
         order: number;
@@ -764,6 +958,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 +975,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 +994,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 +1101,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 +1130,26 @@ export function createMetaTools(
     },
 
     async getResult(args: GetResultArgs): Promise<ToolResult> {
+      // Client-supplied page size and offset: normal input-validation errors,
+      // not clamps. Callers arriving over MCP are rejected earlier by the
+      // registered zod schema and never reach these branches, so they exist for
+      // in-process callers of createMetaTools — which have no schema in front
+      // of them — and to keep the rules 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.`,
+        );
+      }
+      if (args.offset !== undefined && !isValidResultOffset(args.offset)) {
+        return errorResult(
+          `Invalid offset ${args.offset}: must be a whole number of bytes ` +
+            `>= ${MIN_RESULT_OFFSET}. Omit it to start at the beginning.`,
+        );
+      }
       const results = registry.resultsStorage();
       const stored = await results.get(`result:${args.id}`);
       if (stored === null || stored === undefined) {
@@ -932,8 +1157,17 @@ 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;
+      // Validated above, so no coercion is needed here — only alignment. A
+      // client that computes its own offsets can land inside a multi-byte
+      // character, which would decode as U+FFFD; the offset actually served is
+      // the boundary at or before it, and it is what the response reports back
+      // as `offset` (issue #38).
+      const offset = alignStartToCharBoundary(bytes, args.offset ?? 0);
+      // 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
@@ -1036,6 +1270,17 @@ export function createMetaTools(
       const ctx = registry.contextFor(connector.id, baseUrl, requestScope);
       try {
         const status = await connector.startAuth(ctx, { force: args.force });
+        // startAuth just spoke to the downstream about this exact credential, so
+        // its answer replaces any older liveness verdict — including the stale
+        // `auth_required` that sent the agent here, once it reports ok.
+        await registry.recordCredentialHealth(connector.id, {
+          state: status.state,
+          checkedAt: new Date().toISOString(),
+          ...(status.message ? { message: status.message } : {}),
+          ...(status.authorizationUrl
+            ? { authorizationUrl: status.authorizationUrl }
+            : {}),
+        });
         if (status.state === "auth_required" && !status.authorizationUrl) {
           // auth_required with nothing to open is a dead end for the operator.
           return errorResult(
@@ -1076,7 +1321,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) and offset a whole number of bytes >= 0; an offset inside a multi-byte character is moved back to that character's first byte and the offset served is returned. 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 +1329,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,17 +1383,15 @@ 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;
     defaultToolTimeoutMs?: number;
     probeTimeoutMs?: number;
     activity?: ActivityRequestContext;
   },
 ): void {
   const mt = createMetaTools(registry, ctx.baseUrl, {
-    maxResultBytes: ctx.maxResultBytes,
     defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
     probeTimeoutMs: ctx.probeTimeoutMs,
     activity: ctx.activity,
@@ -1126,7 +1400,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 +1425,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 +1442,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(),
@@ -1246,8 +1520,12 @@ export function registerMetaTools(
       description: GET_RESULT_DESC,
       inputSchema: {
         id: z.string(),
-        offset: z.number().int().nonnegative().optional(),
-        maxBytes: z.number().int().positive().optional(),
+        // Both bounds are the shared rules (isValidResultOffset,
+        // isValidMaxResultBytes) expressed for the wire: spelling them against
+        // the same constants keeps the schema from drifting away from the
+        // in-handler checks if either floor ever moves.
+        offset: z.number().int().min(MIN_RESULT_OFFSET).optional(),
+        maxBytes: z.number().int().min(MIN_MAX_RESULT_BYTES).optional(),
       },
       annotations: READ_ONLY_LOCAL,
     },