@zackbart/connecta 0.4.1 → 0.6.0

package/dist/meta-tools.js

@@ -3,7 +3,10 @@ import { compactSchema, rankTools, summarizeDescription } from "./catalog.js";
 import { recordToolActivity, } from "./activity.js";
 import { unwrapMcpResult } from "./mcp-result.js";
 import { classifyCallError, ConnectorCallError, messageLooksRetryable, } from "./errors.js";
-import { AVAILABLE_SKILLS } from "./skills.js";
+import { isValidMaxResultBytes, MIN_MAX_RESULT_BYTES, resolveMaxResultBytes, } 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";
 const RESULT_TTL_SECONDS = 900;
 export function jsonResult(obj) {
     return {
@@ -32,40 +35,6 @@ const dec = new TextDecoder();
  * decides when to re-issue.
  */
 export const MAX_RETRY_BACKOFF_MS = 10_000;
-/** A finite, positive integer number of milliseconds, or undefined. */
-function normalizeTimeoutMs(value) {
-    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(promise, ms, label) {
-    return new Promise((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".
  *
@@ -94,6 +63,43 @@ function errorDetails(code, message) {
 function isContinuationByte(b) {
     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) {
+    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, offset) {
+    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
@@ -102,16 +108,25 @@ function isContinuationByte(b) {
  * 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(bytes, offset, end, total) {
+export function alignEndToCharBoundary(bytes, offset, end, total) {
     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++;
     }
@@ -164,58 +179,128 @@ function applyFieldsToContent(content, fields) {
     });
 }
 // --- result-size guard + get_result (feature 1) ---------------------------
-function contentBytes(content) {
-    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) {
+    const serialized = JSON.stringify(value, null, 2);
+    return serialized === undefined ? String(value) : serialized;
 }
 /**
- * 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.
+ * Stash `text` under `result:<uuid>` (ttl 900s) and describe it as the
+ * truncation notice every over-cap path hands back.
  */
-async function guardText(text, results, cap) {
-    const bytes = enc.encode(text);
-    if (bytes.length <= cap) {
-        return { content: [{ type: "text", text }] };
-    }
+async function stashResult(text, results, totalBytes) {
     const id = crypto.randomUUID();
     await results.set(`result:${id}`, text, { ttlSeconds: RESULT_TTL_SECONDS });
-    const head = dec.decode(bytes.slice(0, alignEndToCharBoundary(bytes, 0, cap, bytes.length)));
-    const notice = JSON.stringify({
+    return {
         truncated: true,
         resultId: id,
-        totalBytes: bytes.length,
+        totalBytes,
         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 `text` as a single content block; if it exceeds `cap` bytes, stash the
+ * 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 guardEncoded(text, bytes, results, cap) {
+    if (bytes.length <= cap) {
+        return { content: [{ type: "text", text }] };
+    }
+    const notice = await stashResult(text, results, bytes.length);
+    const head = dec.decode(bytes.slice(0, alignEndToCharBoundary(bytes, 0, cap, bytes.length)));
+    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, results, cap) {
+    // `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 = 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. */
 async function guardValue(value, results, cap) {
-    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, results, cap) {
+    let text;
+    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) }] };
 }
 /**
  * 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, baseUrl, opts = {}) {
-    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;
     // createMetaTools() is called once per inbound MCP request. Sharing this
@@ -276,6 +361,13 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             return failed(errorDetails("unknown_address", `Unknown address "${call.address}"`));
         }
         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.
@@ -288,6 +380,20 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         }
         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"));
@@ -388,13 +494,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 let content = mr?.content ?? [];
                 if (fields)
                     content = applyFieldsToContent(content, fields);
-                let 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 {
@@ -405,7 +505,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 };
             }
             const value = fields ? applyFields(result, fields) : result;
-            const toolResult = await guardText(JSON.stringify(value, null, 2), results, cap);
+            const toolResult = await guardText(serializeResultText(value), results, cap);
             resultProcessingMs += Date.now() - processingStarted;
             record("success");
             return {
@@ -423,29 +523,31 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
     }
     return {
         async skills(args = {}) {
+            const connectors = registry.listConnectors();
             if (!args.name) {
                 return {
                     content: [
                         {
                             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 }] };
         },
         async listConnectors(args = {}) {
             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;
                 if (probe) {
                     try {
@@ -458,17 +560,73 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                         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"
+                        : registry.hasObservedSuccess(c.id) || c.kind === "api"
+                            ? "ok"
+                            : "unknown";
                     status = {
-                        state: observed?.consecutiveFailures &&
-                            observed.consecutiveFailures > 0
-                            ? "error"
-                            : observed?.lastSuccessAt || c.kind === "api"
-                                ? "ok"
-                                : "unknown",
+                        // 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: derived === "unknown" && verdict?.state === "ok"
+                            ? "ok"
+                            : 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
@@ -485,6 +643,9 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                 }
                 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 } : {}),
@@ -495,6 +656,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     latencyMs,
                     probe,
                     ...(latestObserved ?? observed ?? {}),
+                    ...(credentialCheck ? { credentialCheck } : {}),
                     ...("authorizationUrl" in status && status.authorizationUrl
                         ? { authorizationUrl: status.authorizationUrl }
                         : {}),
@@ -521,6 +683,9 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                             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,
@@ -540,6 +705,9 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                         id: match.connectorId,
                         ...(match.connectorTitle ? { title: match.connectorTitle } : {}),
                         description: match.connectorDescription,
+                        ...(match.connectorGuideSkill
+                            ? { guide: match.connectorGuideSkill }
+                            : {}),
                         tools: [],
                     };
                     byConnector.set(match.connectorId, group);
@@ -621,6 +789,9 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     address,
                     name: tool.name,
                     description: summarizeDescription(tool.description, args.fullDescriptions === true),
+                    ...(connectorGuide(resolved.connector)
+                        ? { guide: connectorSkillName(resolved.connector.id) }
+                        : {}),
                     inputSchema: format === "json" ? schema : compactSchema(schema),
                     ...(tool.outputSchema
                         ? {
@@ -641,6 +812,20 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             return (await runCall(args, "call_destructive_tool", { allowDestructive: true })).toolResult;
         },
         async getResult(args) {
+            // 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) {
@@ -648,8 +833,17 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             }
             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
@@ -736,6 +930,17 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
             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(`Connector "${connector.id}": authorization required but no URL is available — retry authorize_connector.`);
@@ -768,10 +973,32 @@ const SEARCH_DESC = 'Start here when a tool address is unknown. Exact/name match
 const DESCRIBE_DESC = 'Inspect known tool addresses when search_tools did not include a sufficient schema. Returns descriptions, input/output schemas, and behavior annotations; format "compact" is the default.';
 const CALL_DESC = 'Use for one tool explicitly annotated readOnlyHint: true. For 2–10 independent read-only calls use batch_call; for dependent steps or data reduction use execute_code when available. Unannotated, write-capable, and destructive tools are refused and require call_destructive_tool. fields selects JSON dot-paths, resultMode "value" unwraps results, timeoutMs sets a deadline, safe maxRetries are annotation-gated, diagnostics adds timing, and large results page through get_result.';
 const CALL_DESTRUCTIVE_DESC = "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.";
+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. 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 = "Use after a connector reports auth_required. Starts downstream OAuth and returns an authorizationUrl for the operator to open. force=true wipes stored credentials first and restarts consent.";
 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> }).",
+};
+/** `base`, plus its guide note when any VISIBLE connector carries a guide. */
+function describedFor(registry, base, note) {
+    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
@@ -793,13 +1020,12 @@ const READ_ONLY_LOCAL = {
 /** Register the nine meta-tools onto an McpServer instance. */
 export function registerMetaTools(server, registry, ctx) {
     const mt = createMetaTools(registry, ctx.baseUrl, {
-        maxResultBytes: ctx.maxResultBytes,
         defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
         probeTimeoutMs: ctx.probeTimeoutMs,
         activity: ctx.activity,
     });
     server.registerTool("skills", {
-        description: SKILLS_DESC,
+        description: describedFor(registry, SKILLS_DESC, "skills"),
         inputSchema: { name: z.string().optional() },
         annotations: {
             readOnlyHint: true,
@@ -814,7 +1040,7 @@ export function registerMetaTools(server, registry, ctx) {
         annotations: READ_ONLY_REMOTE,
     }, async (args) => mt.listConnectors(args));
     server.registerTool("search_tools", {
-        description: SEARCH_DESC,
+        description: describedFor(registry, SEARCH_DESC, "search"),
         inputSchema: {
             query: z.string().optional(),
             connector: z.string().optional(),
@@ -826,7 +1052,7 @@ export function registerMetaTools(server, registry, ctx) {
         annotations: READ_ONLY_REMOTE,
     }, async (args) => mt.searchTools(args));
     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(),
@@ -884,8 +1110,12 @@ export function registerMetaTools(server, registry, ctx) {
         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,
     }, async (args) => mt.getResult(args));