@zackbart/connecta 0.5.0 → 0.6.1

package/dist/meta-tools.d.ts

@@ -38,6 +38,36 @@ export declare const MAX_RETRY_BACKOFF_MS = 10000;
  * `runCall`. Exported for direct testing.
  */
 export declare function retryBackoffMs(attempt: number, retryAfterMs: number | undefined): number | undefined;
+/** Smallest accepted `get_result` byte offset. */
+export declare 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 declare function isValidResultOffset(value: number): boolean;
+/**
+ * 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 declare function alignStartToCharBoundary(bytes: Uint8Array, offset: number): number;
 /**
  * Move a byte `end` back to the nearest UTF-8 codepoint boundary in
  * `(offset, total]`, so decoding `bytes[offset, end)` never splits a codepoint
@@ -54,6 +84,22 @@ export declare function retryBackoffMs(attempt: number, retryAfterMs: number | u
  * ever does. Exported for direct testing of that invariant.
  */
 export declare function alignEndToCharBoundary(bytes: Uint8Array, offset: number, end: number, total: number): number;
+/**
+ * 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 declare function serializeResultText(value: unknown): string;
 export interface SearchArgs {
     query?: string;
     connector?: string;
@@ -85,6 +131,10 @@ 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;
@@ -114,14 +164,16 @@ 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 (a connector's own
- * `maxResultBytes` overrides it in turn); `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 declare function createMetaTools(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. */
@@ -141,7 +193,6 @@ export declare function createMetaTools(registry: RegistryView, baseUrl: string,
 /** Register the nine meta-tools onto an McpServer instance. */
 export declare function registerMetaTools(server: McpServer, registry: RegistryView, ctx: {
     baseUrl: string;
-    maxResultBytes?: number;
     defaultToolTimeoutMs?: number;
     probeTimeoutMs?: number;
     activity?: ActivityRequestContext;

package/dist/meta-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meta-tools.d.ts","sourceRoot":"","sources":["../src/meta-tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"meta-tools.d.ts","sourceRoot":"","sources":["../src/meta-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,eAAe,CAAC;AAQvB,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAgBvB,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AACD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAID,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAOnD;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAEvD;AAYD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAKpB;AAYD,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,GACb,MAAM,CAIR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GACZ,MAAM,CAaR;AAsDD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAG1D;AA8HD,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,cAAc,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;CACrC;AACD,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AACD,MAAM,WAAW,QAAQ;IACvB,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AACD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,OAAO,CAAC;AACzC,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AACD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AACD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AACD,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AACD,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IACJ,0EAA0E;IAC1E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,yFAAyF;IACzF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,sBAAsB,CAAC;CAC9B;kBAsSe,SAAS,GAAQ,OAAO,CAAC,UAAU,CAAC;0BAqB5B,QAAQ,GAAQ,OAAO,CAAC,UAAU,CAAC;sBAwItC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;wBA2H9B,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC;mBA0EvC,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;8BAInB,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;oBAMxC,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC;oBA2DnC,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;6BAqEtB,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC;EAmDrE;AAwED,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,YAAY,EACtB,GAAG,EAAE;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,sBAAsB,CAAC;CACnC,GACA,IAAI,CA4KN"}

package/dist/meta-tools.js

@@ -5,6 +5,8 @@ import { unwrapMcpResult } from "./mcp-result.js";
 import { classifyCallError, ConnectorCallError, messageLooksRetryable, } from "./errors.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 {
@@ -33,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".
  *
@@ -95,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
@@ -174,59 +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 (a connector's own
- * `maxResultBytes` overrides it in turn); `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 globalCap = resolveMaxResultBytes(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
@@ -306,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"));
@@ -406,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 {
@@ -423,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 {
@@ -463,9 +545,9 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         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 {
@@ -478,22 +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"
-                            : registry.hasObservedSuccess(c.id) || 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
@@ -510,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 } : {}),
@@ -520,6 +656,7 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
                     latencyMs,
                     probe,
                     ...(latestObserved ?? observed ?? {}),
+                    ...(credentialCheck ? { credentialCheck } : {}),
                     ...("authorizationUrl" in status && status.authorizationUrl
                         ? { authorizationUrl: status.authorizationUrl }
                         : {}),
@@ -675,16 +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: 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
+            // 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 rule true of the handler on its own terms.
+            // 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) {
@@ -692,7 +833,12 @@ 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));
+            // 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
@@ -784,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.`);
@@ -816,7 +973,7 @@ 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. maxBytes is a whole number of bytes >= 1 (omit for the deployment default). 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.';
@@ -863,7 +1020,6 @@ 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,
@@ -954,10 +1110,11 @@ export function registerMetaTools(server, registry, ctx) {
         description: GET_RESULT_DESC,
         inputSchema: {
             id: z.string(),
-            offset: z.number().int().nonnegative().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.
+            // 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,