@zackbart/connecta 0.41.0 → 0.42.0

package/dist/catalog.js

@@ -1,5 +1,5 @@
-const DEFAULT_DESCRIPTION_LENGTH = 240;
 const DISCOVERY_DESCRIPTION_LENGTH = 160;
+const DISCOVERY_DESCRIPTION_MINIMUM = 40;
 export const MAX_COMPACT_DISCOVERY_SCHEMA_BYTES = 1_024;
 const MAX_COMPACT_DISCOVERY_ENUM_BYTES = MAX_COMPACT_DISCOVERY_SCHEMA_BYTES / 4;
 const MAX_COMPACT_DISCOVERY_CONSTRAINT_BYTES = MAX_COMPACT_DISCOVERY_SCHEMA_BYTES / 4;
@@ -75,21 +75,46 @@ class SchemaWork {
         }));
     }
 }
-export function summarizeDescription(text, full) {
-    return summarizeToLength(text, full, DEFAULT_DESCRIPTION_LENGTH);
-}
-export function summarizeDiscoveryDescription(text, full) {
-    return summarizeToLength(text, full, DISCOVERY_DESCRIPTION_LENGTH);
-}
-function summarizeToLength(text, full, maxLength) {
-    if (!text)
-        return undefined;
-    if (full)
-        return text;
-    const compact = text.replace(/\s+/g, " ").trim();
-    if (compact.length <= maxLength)
-        return compact;
-    return `${compact.slice(0, maxLength - 1).trimEnd()}…`;
+/** A sentence's end, or the paragraph break `discoverySummary` marks with a newline. */
+const SENTENCE_END = /[.!?]["'`)\]]*(?= |\n|$)|\n/g;
+/** A period that follows an initial or a common abbreviation ends no sentence. */
+const ABBREVIATED = /(?:^|[\s(.])(?:e\.g|i\.e|etc|vs|cf|approx|[a-z])\.$/i;
+/**
+ * What search shows of a description: the first complete sentence, joined to
+ * the next ones until it reaches 40 characters, within 160. Text with no such
+ * boundary is cut at a word. `truncated` says text was left out.
+ */
+export function discoverySummary(text) {
+    const marked = text
+        .trim()
+        .split(/\n\s*\n/)
+        .map((paragraph) => paragraph.replace(/\s+/g, " ").trim())
+        .filter(Boolean)
+        .join("\n");
+    const whole = marked.replaceAll("\n", " ");
+    let end;
+    for (const match of marked.matchAll(SENTENCE_END)) {
+        const candidate = match[0] === "\n" ? match.index : match.index + match[0].length;
+        if (candidate < DISCOVERY_DESCRIPTION_MINIMUM)
+            continue;
+        if (candidate > DISCOVERY_DESCRIPTION_LENGTH)
+            break;
+        if (ABBREVIATED.test(marked.slice(Math.max(0, candidate - 8), candidate)))
+            continue;
+        end = candidate;
+        break;
+    }
+    if (end !== undefined)
+        return { text: whole.slice(0, end), truncated: end < whole.length };
+    if (whole.length <= DISCOVERY_DESCRIPTION_LENGTH)
+        return { text: whole, truncated: false };
+    let cut = DISCOVERY_DESCRIPTION_LENGTH - 1;
+    const space = whole.lastIndexOf(" ", cut);
+    if (space >= DISCOVERY_DESCRIPTION_MINIMUM)
+        cut = space;
+    else if (/[\uD800-\uDBFF]/.test(whole.charAt(cut - 1)))
+        cut -= 1;
+    return { text: `${whole.slice(0, cut).trimEnd()}…`, truncated: true };
 }
 function lexicalTokens(text) {
     return text
@@ -163,6 +188,7 @@ export function lexicalSearchContent(query) {
     const contentTerms = terms.filter((term) => !CONVERSATIONAL_QUERY_WORDS.has(term));
     return contentTerms.join(" ");
 }
+const ZONES = ["nameTokens", "titleTokens", "summaryTokens", "tailTokens"];
 const searchIndexes = new WeakMap();
 // Only immutable token strings and numeric positions cross requests. The key
 // holds exactly what buildIndex reads, in order, so schemas cost nothing here;
@@ -170,36 +196,39 @@ const searchIndexes = new WeakMap();
 const retainedIndexes = new Map();
 const INDEX_BYTES = 8 * 1024 * 1024;
 let retainedBytes = 0;
+/** A tool's display title; MCP carries it on the tool or on its annotations. */
+function toolTitle(tool) {
+    const title = tool.title ?? tool.annotations?.title;
+    return typeof title === "string" ? title : "";
+}
 function buildIndex(tools) {
-    const nameTokenDocuments = new Map();
-    const descriptionTokenDocuments = new Map();
-    const addTokens = (target, tokens, position) => {
-        for (const token of new Set(tokens)) {
-            const documents = target.get(token) ?? [];
-            documents.push(position);
-            target.set(token, documents);
-        }
-    };
+    const postings = ZONES.map(() => new Map());
     const documents = tools.map((tool, position) => {
+        const description = tool.description ?? "";
         const nameTokens = lexicalTokens(tool.name);
-        const descriptionTokens = [...new Set(lexicalTokens(tool.description ?? ""))];
-        addTokens(nameTokenDocuments, nameTokens, position);
-        addTokens(descriptionTokenDocuments, descriptionTokens, position);
-        return Object.freeze({
+        const summary = new Set(lexicalTokens(discoverySummary(description).text));
+        const doc = {
             name: nameTokens.join(" "),
-            nameTokens: Object.freeze(nameTokens),
-            descriptionTokens: Object.freeze(descriptionTokens),
+            nameTokens,
+            titleTokens: [...new Set(lexicalTokens(toolTitle(tool)))],
+            summaryTokens: [...summary],
+            tailTokens: [...new Set(lexicalTokens(description))].filter((token) => !summary.has(token)),
+        };
+        ZONES.forEach((zone, index) => {
+            Object.freeze(doc[zone]);
+            for (const token of new Set(doc[zone])) {
+                const positions = postings[index].get(token) ?? [];
+                positions.push(position);
+                postings[index].set(token, positions);
+            }
         });
+        return Object.freeze(doc);
     });
-    for (const map of [nameTokenDocuments, descriptionTokenDocuments])
+    for (const map of postings)
         for (const positions of map.values())
             Object.freeze(positions);
     // Maps remain private to this module and are never mutated after construction.
-    return Object.freeze({
-        documents: Object.freeze(documents),
-        nameTokenDocuments,
-        descriptionTokenDocuments,
-    });
+    return Object.freeze({ documents: Object.freeze(documents), postings: Object.freeze(postings) });
 }
 function bindIndex(tools, index) {
     const view = { index, tools: new Map(tools.map((tool, position) => [position, tool])) };
@@ -210,7 +239,7 @@ function bindIndex(tools, index) {
 export function prepareLexicalCatalog(tools, partition) {
     if (searchIndexes.has(tools))
         return;
-    const key = JSON.stringify([partition, tools.map((tool) => [tool.name, tool.description ?? ""])]);
+    const key = JSON.stringify([partition, tools.map((tool) => [tool.name, tool.description ?? "", toolTitle(tool)])]);
     const retained = retainedIndexes.get(key);
     if (retained) {
         bindIndex(tools, retained.index);
@@ -221,11 +250,11 @@ export function prepareLexicalCatalog(tools, partition) {
     let bytes = key.length * 2 + 128;
     for (const doc of index.documents) {
         bytes += 128 + doc.name.length * 2;
-        for (const tokens of [doc.nameTokens, doc.descriptionTokens])
-            for (const token of tokens)
+        for (const zone of ZONES)
+            for (const token of doc[zone])
                 bytes += 32 + token.length * 2;
     }
-    for (const map of [index.nameTokenDocuments, index.descriptionTokenDocuments])
+    for (const map of index.postings)
         for (const [token, positions] of map)
             bytes += 96 + token.length * 2 + positions.length * 8;
     if (bytes > INDEX_BYTES)
@@ -267,6 +296,24 @@ function inflectionVariants(base) {
         ...(base.endsWith("y") ? [`${base.slice(0, -1)}ies`, `${base.slice(0, -1)}ied`] : []),
     ];
 }
+/**
+ * Shortenings API names use for words people write out. Only unambiguous
+ * pairs: `auth` could mean either authentication or authorization.
+ */
+const ABBREVIATIONS = new Map([
+    "config configuration",
+    "db database",
+    "doc document",
+    "env environment",
+    "org organization",
+    "repo repository",
+    "var variable",
+]
+    .map((pair) => pair.split(" "))
+    .flatMap(([short, long]) => [
+    [short, long],
+    [long, short],
+]));
 function matchingTokenCandidates(term) {
     const candidates = new Set([term, ...inflectionVariants(term)]);
     const possibleBases = [
@@ -282,6 +329,12 @@ function matchingTokenCandidates(term) {
             candidates.add(base);
         }
     }
+    for (const candidate of candidates) {
+        const other = ABBREVIATIONS.get(candidate);
+        if (other)
+            for (const variant of [other, ...inflectionVariants(other)])
+                candidates.add(variant);
+    }
     return candidates;
 }
 /**
@@ -334,30 +387,38 @@ export function lexicalCorpusStatistics(toolSets, query, synonymsFor) {
             documentFrequency: new Map(),
             nameMatches: new Map(),
             descriptionMatches: new Map(),
+            headMatches: new Map(),
         };
     }
     const nameMatches = new Map();
     const descriptionMatches = new Map();
+    const headMatches = new Map();
     for (const term of terms) {
         const termNameMatches = new Set();
         const termDescriptionMatches = new Set();
+        const termHeadMatches = new Set();
         for (const tools of toolSets) {
             const index = indexFor(tools);
             for (const candidate of synonymCandidates(term, synonymsFor?.(tools))) {
-                for (const position of index.index.nameTokenDocuments.get(candidate) ?? []) {
-                    const tool = index.tools.get(position);
-                    if (tool)
-                        termNameMatches.add(tool);
-                }
-                for (const position of index.index.descriptionTokenDocuments.get(candidate) ?? []) {
-                    const tool = index.tools.get(position);
-                    if (tool)
-                        termDescriptionMatches.add(tool);
-                }
+                // Name and title, summary and tail: only the tail is outside the head.
+                [
+                    [termNameMatches, termHeadMatches],
+                    [termDescriptionMatches, termHeadMatches],
+                    [termDescriptionMatches, termHeadMatches],
+                    [termDescriptionMatches],
+                ].forEach((targets, zone) => {
+                    for (const position of index.index.postings[zone].get(candidate) ?? []) {
+                        const tool = index.tools.get(position);
+                        if (tool)
+                            for (const target of targets)
+                                target.add(tool);
+                    }
+                });
             }
         }
         nameMatches.set(term, termNameMatches);
         descriptionMatches.set(term, termDescriptionMatches);
+        headMatches.set(term, termHeadMatches);
     }
     const documentFrequency = new Map(terms.map((term) => [
         term,
@@ -368,15 +429,20 @@ export function lexicalCorpusStatistics(toolSets, query, synonymsFor) {
         documentFrequency,
         nameMatches,
         descriptionMatches,
+        headMatches,
     };
 }
+/** A hatch's standing when one operation states every term: coverage, without a named tool's name evidence. */
+export function vocabularyScore(terms, statistics) {
+    return terms.reduce((total, term) => total + 5 * inverseDocumentFrequency(term, statistics), 0);
+}
 function inverseDocumentFrequency(term, statistics) {
     const frequency = statistics.documentFrequency.get(term) ?? 0;
     return Math.log(1 + (statistics.documentCount - frequency + 0.5) / (frequency + 0.5));
 }
 function scoreDocument(doc, phrase, terms, mode, statistics) {
     if (!phrase)
-        return { score: 0, matchedTermCount: 0 };
+        return { score: 0, matchedTermCount: 0, headTerms: [], nameTerms: [], namesDistinctiveTerm: false };
     const matchedTerms = terms.filter((term) => statistics.nameMatches.get(term)?.has(doc.tool) || statistics.descriptionMatches.get(term)?.has(doc.tool));
     if (mode === "all" && matchedTerms.length !== terms.length)
         return null;
@@ -384,8 +450,10 @@ function scoreDocument(doc, phrase, terms, mode, statistics) {
         return null;
     // Coverage remains meaningful in partial mode, but is IDF-weighted rather
     // than a raw term count: one rare domain term can beat several ubiquitous
-    // catalog verbs.
-    let score = matchedTerms.reduce((total, term) => total + 4 * inverseDocumentFrequency(term, statistics), 0);
+    // catalog verbs. A term met only in the description's tail is weak coverage,
+    // so a long description cannot outrank a tool that names what was asked.
+    const inHead = (term) => statistics.headMatches.get(term)?.has(doc.tool) === true;
+    let score = matchedTerms.reduce((total, term) => total + (inHead(term) ? 4 : 1) * inverseDocumentFrequency(term, statistics), 0);
     const phraseWeight = terms.reduce((total, term) => total + inverseDocumentFrequency(term, statistics), 0);
     if (doc.name === phrase)
         score += 40 * phraseWeight;
@@ -401,13 +469,31 @@ function scoreDocument(doc, phrase, terms, mode, statistics) {
         else if (statistics.nameMatches.get(term)?.has(doc.tool)) {
             score += 8 * weight;
         }
-        if (doc.descriptionTokens.includes(term))
+        // A term reaching a zone only through an inflection or synonym earns half.
+        if (doc.summaryTokens.includes(term))
             score += 3 * weight;
-        else if (statistics.descriptionMatches.get(term)?.has(doc.tool)) {
+        else if (doc.titleTokens.includes(term))
+            score += 2 * weight;
+        else if (doc.tailTokens.includes(term))
+            score += 0.5 * weight;
+        else if (inHead(term))
             score += 1.5 * weight;
-        }
+        else if (statistics.descriptionMatches.get(term)?.has(doc.tool))
+            score += 0.25 * weight;
     }
-    return { score, matchedTermCount: matchedTerms.length };
+    // Partial evidence earns only its squared share of the query's rarity, wherever
+    // it appears, so a common verb in a name cannot outweigh rare words in a tail.
+    const covered = matchedTerms.reduce((total, term) => total + inverseDocumentFrequency(term, statistics), 0);
+    score *= (covered / phraseWeight) ** 2;
+    const averageWeight = phraseWeight / terms.length;
+    const nameTerms = matchedTerms.filter((term) => statistics.nameMatches.get(term)?.has(doc.tool));
+    return {
+        score,
+        matchedTermCount: matchedTerms.length,
+        headTerms: matchedTerms.filter(inHead),
+        nameTerms,
+        namesDistinctiveTerm: nameTerms.some((term) => inverseDocumentFrequency(term, statistics) >= averageWeight),
+    };
 }
 function queryContainsExactName(doc, phrase) {
     if (!doc.name || !phrase)
@@ -439,6 +525,9 @@ export function rankTools(tools, query, mode = "all", statistics = lexicalCorpus
                 order: visibleOrder,
                 exactName: queryContainsExactName(doc, exactNamePhrase),
                 matchedTermCount: scored.matchedTermCount,
+                headTerms: scored.headTerms,
+                nameTerms: scored.nameTerms,
+                namesDistinctiveTerm: scored.namesDistinctiveTerm,
             });
         }
     });

package/dist/config-defaults.d.ts

@@ -18,9 +18,10 @@ export declare const CONFIG_DEFAULTS: {
         readonly maxEmittedBlocks: 32;
         readonly maxHostCalls: 20;
         readonly hostCallTimeoutMs: 15000;
-        readonly watchdogMs: 120000;
+        readonly watchdogMs: 55000;
         readonly maxWrites: 10;
         readonly maxResultChars: 24000;
+        readonly readRoute: true;
     };
     readonly admission: {
         readonly requests: {

package/dist/config-defaults.js

@@ -25,9 +25,12 @@ export const CONFIG_DEFAULTS = {
         maxEmittedBlocks: 32,
         maxHostCalls: 20,
         hostCallTimeoutMs: 15_000,
-        watchdogMs: 120_000,
+        // Below the 60 s MCP clients give one request, leaving time to send a typed
+        // result. See documentation/code-mode.md#cancellation-and-limits.
+        watchdogMs: 55_000,
         maxWrites: 10,
         maxResultChars: 24_000,
+        readRoute: true,
     },
     admission: {
         requests: {

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { ClassificationOverride } from "./tool-safety.js";
 import type { CredentialVault } from "./credential-contract.js";
 import { type ConfigInput, type ConfigOutput } from "./config-schema.js";
 import type { MemberRef } from "./membership.js";
@@ -31,7 +32,8 @@ declare const calls: {
     /**
      * Deadline (ms) for `call_tool`/`call_destructive_tool` calls that pass no
      * `timeoutMs`. An explicit per-call value wins. Unset by default, when those
-     * calls fall back to `execute.hostCallTimeoutMs`.
+     * calls fall back to `execute.hostCallTimeoutMs`. `execute.watchdogMs` caps
+     * every one of them.
      *
      * Each call makes one attempt. `connecta.call` inside `execute_code` uses
      * it too, ahead of `execute.hostCallTimeoutMs`; `connecta.result`,
@@ -67,16 +69,19 @@ declare const execute: {
      * `connecta.read`, in milliseconds. Default 15_000. Discovery uses
      * `discovery.probeTimeoutMs`. `connecta.call` and the direct call tools use it only when
      * `calls.defaultTimeoutMs` is unset, and an explicit per-call `timeoutMs`
-     * always wins. Raise it for providers whose legitimate calls run longer,
-     * such as analytics queries.
+     * wins, up to `execute.watchdogMs`. Raise it for providers whose legitimate
+     * calls run longer, such as analytics queries.
      */
     hostCallTimeoutMs: import("./config-schema.js").Field<number, number, true>;
     /**
-     * Hard ceiling on one execution, in milliseconds, enforced outside the
-     * sandbox. Default 120_000, above both executors' own deadlines (QuickJS
-     * 30_000, the Dynamic Worker 60_000), so it only ends a run whose executor
-     * never settled; that run fails as unresponsive and its admission slot is
-     * released. Keep it above any raised executor deadline.
+     * Ceiling on one `execute_code` or direct call response, in milliseconds,
+     * counted from the request's arrival and enforced outside the sandbox.
+     * Default 55_000: MCP clients commonly abandon a request at 60_000, and only
+     * a response sent before that reaches the agent as a typed result. It sits
+     * above both executors' own deadlines (QuickJS 30_000, the Dynamic Worker
+     * 50_000), so a run ends here only if its executor never settled, or if
+     * queueing spent its time. An explicit `timeoutMs` above it is cut to it. Raise it,
+     * and any executor deadline with it, only for clients whose own limit is raised.
      */
     watchdogMs: import("./config-schema.js").Field<number, number, true>;
     /**
@@ -92,6 +97,12 @@ declare const execute: {
      * model step. From 4_000 to 1_000_000.
      */
     maxResultChars: import("./config-schema.js").Field<number, number, true>;
+    /**
+     * `false` stops listing `execute_read_code` on writable human endpoints. A
+     * read program runs unprompted on hosts that auto-approve reads, so a deployment
+     * that wants a person to see every program can turn it off. Default true.
+     */
+    readRoute: import("./config-schema.js").Field<boolean, boolean, true>;
 };
 declare const codeAdmission: {
     /** Simultaneous work admitted to this pool. */
@@ -271,8 +282,11 @@ declare const connectaConfig: {
         readonly executeCode: boolean | undefined;
     }>> | undefined, true>;
     /** Exact connector id -> tool name -> verdict. Hidden tools cannot be discovered or called.
+     * `"read"` applies only where the source is silent, and asserts the call is safe to repeat; a
+     * source's declared write stays a write and is reported. `"read-repeatable"` also serves a
+     * declared write as a read: the deployment has checked it and accepts that hosts may repeat it.
      * Unknown static names fail construction; absent runtime names stay dormant and are reported. */
-    classification: import("./config-schema.js").Field<Record<string, Record<string, "read" | "write" | "hidden">>, Readonly<Record<string, Readonly<Record<string, "read" | "write" | "hidden">>>> | undefined, true>;
+    classification: import("./config-schema.js").Field<Record<string, Record<string, ClassificationOverride>>, Readonly<Record<string, Readonly<Record<string, ClassificationOverride>>>> | undefined, true>;
     /**
      * The deployment's one store: `d1Storage(env.CONNECTA_DB)` from
      * `@zackbart/connecta/d1` on Workers, `sqliteStorage(path)` from
@@ -355,7 +369,8 @@ declare const connectaConfig: {
             /**
              * Deadline (ms) for `call_tool`/`call_destructive_tool` calls that pass no
              * `timeoutMs`. An explicit per-call value wins. Unset by default, when those
-             * calls fall back to `execute.hostCallTimeoutMs`.
+             * calls fall back to `execute.hostCallTimeoutMs`. `execute.watchdogMs` caps
+             * every one of them.
              *
              * Each call makes one attempt. `connecta.call` inside `execute_code` uses
              * it too, ahead of `execute.hostCallTimeoutMs`; `connecta.result`,
@@ -394,6 +409,7 @@ declare const connectaConfig: {
         watchdogMs?: number | undefined;
         maxWrites?: number | undefined;
         maxResultChars?: number | undefined;
+        readRoute?: boolean | undefined;
     }, {
         readonly maxEmittedBytes: number;
         readonly maxEmittedBlocks: number;
@@ -402,6 +418,7 @@ declare const connectaConfig: {
         readonly watchdogMs: number;
         readonly maxWrites: number;
         readonly maxResultChars: number;
+        readonly readRoute: boolean;
     }, true> & {
         readonly shape: {
             /**
@@ -419,16 +436,19 @@ declare const connectaConfig: {
              * `connecta.read`, in milliseconds. Default 15_000. Discovery uses
              * `discovery.probeTimeoutMs`. `connecta.call` and the direct call tools use it only when
              * `calls.defaultTimeoutMs` is unset, and an explicit per-call `timeoutMs`
-             * always wins. Raise it for providers whose legitimate calls run longer,
-             * such as analytics queries.
+             * wins, up to `execute.watchdogMs`. Raise it for providers whose legitimate
+             * calls run longer, such as analytics queries.
              */
             hostCallTimeoutMs: import("./config-schema.js").Field<number, number, true>;
             /**
-             * Hard ceiling on one execution, in milliseconds, enforced outside the
-             * sandbox. Default 120_000, above both executors' own deadlines (QuickJS
-             * 30_000, the Dynamic Worker 60_000), so it only ends a run whose executor
-             * never settled; that run fails as unresponsive and its admission slot is
-             * released. Keep it above any raised executor deadline.
+             * Ceiling on one `execute_code` or direct call response, in milliseconds,
+             * counted from the request's arrival and enforced outside the sandbox.
+             * Default 55_000: MCP clients commonly abandon a request at 60_000, and only
+             * a response sent before that reaches the agent as a typed result. It sits
+             * above both executors' own deadlines (QuickJS 30_000, the Dynamic Worker
+             * 50_000), so a run ends here only if its executor never settled, or if
+             * queueing spent its time. An explicit `timeoutMs` above it is cut to it. Raise it,
+             * and any executor deadline with it, only for clients whose own limit is raised.
              */
             watchdogMs: import("./config-schema.js").Field<number, number, true>;
             /**
@@ -444,6 +464,12 @@ declare const connectaConfig: {
              * model step. From 4_000 to 1_000_000.
              */
             maxResultChars: import("./config-schema.js").Field<number, number, true>;
+            /**
+             * `false` stops listing `execute_read_code` on writable human endpoints. A
+             * read program runs unprompted on hosts that auto-approve reads, so a deployment
+             * that wants a person to see every program can turn it off. Default true.
+             */
+            readRoute: import("./config-schema.js").Field<boolean, boolean, true>;
         };
     };
     /**

package/dist/config.js

@@ -82,7 +82,8 @@ const calls = {
     /**
      * Deadline (ms) for `call_tool`/`call_destructive_tool` calls that pass no
      * `timeoutMs`. An explicit per-call value wins. Unset by default, when those
-     * calls fall back to `execute.hostCallTimeoutMs`.
+     * calls fall back to `execute.hostCallTimeoutMs`. `execute.watchdogMs` caps
+     * every one of them.
      *
      * Each call makes one attempt. `connecta.call` inside `execute_code` uses
      * it too, ahead of `execute.hostCallTimeoutMs`; `connecta.result`,
@@ -118,16 +119,19 @@ const execute = {
      * `connecta.read`, in milliseconds. Default 15_000. Discovery uses
      * `discovery.probeTimeoutMs`. `connecta.call` and the direct call tools use it only when
      * `calls.defaultTimeoutMs` is unset, and an explicit per-call `timeoutMs`
-     * always wins. Raise it for providers whose legitimate calls run longer,
-     * such as analytics queries.
+     * wins, up to `execute.watchdogMs`. Raise it for providers whose legitimate
+     * calls run longer, such as analytics queries.
      */
     hostCallTimeoutMs: whole({ min: 1, default: D.execute.hostCallTimeoutMs }),
     /**
-     * Hard ceiling on one execution, in milliseconds, enforced outside the
-     * sandbox. Default 120_000, above both executors' own deadlines (QuickJS
-     * 30_000, the Dynamic Worker 60_000), so it only ends a run whose executor
-     * never settled; that run fails as unresponsive and its admission slot is
-     * released. Keep it above any raised executor deadline.
+     * Ceiling on one `execute_code` or direct call response, in milliseconds,
+     * counted from the request's arrival and enforced outside the sandbox.
+     * Default 55_000: MCP clients commonly abandon a request at 60_000, and only
+     * a response sent before that reaches the agent as a typed result. It sits
+     * above both executors' own deadlines (QuickJS 30_000, the Dynamic Worker
+     * 50_000), so a run ends here only if its executor never settled, or if
+     * queueing spent its time. An explicit `timeoutMs` above it is cut to it. Raise it,
+     * and any executor deadline with it, only for clients whose own limit is raised.
      */
     watchdogMs: whole({ min: 1, default: D.execute.watchdogMs }),
     /**
@@ -143,6 +147,15 @@ const execute = {
      * model step. From 4_000 to 1_000_000.
      */
     maxResultChars: whole({ min: 4_000, max: 1_000_000, default: D.execute.maxResultChars }),
+    /**
+     * `false` stops listing `execute_read_code` on writable human endpoints. A
+     * read program runs unprompted on hosts that auto-approve reads, so a deployment
+     * that wants a person to see every program can turn it off. Default true.
+     */
+    readRoute: opaque({
+        check: assertFlag,
+        resolve: (value) => value ?? D.execute.readRoute,
+    }),
 };
 function admissionPool(defaults) {
     return {
@@ -359,11 +372,14 @@ const connectaConfig = {
     /** Named tool pools, each served at `/mcp/<name>` to its members only. */
     pools: record(object(pool)),
     /** Exact connector id -> tool name -> verdict. Hidden tools cannot be discovered or called.
+     * `"read"` applies only where the source is silent, and asserts the call is safe to repeat; a
+     * source's declared write stays a write and is reported. `"read-repeatable"` also serves a
+     * declared write as a read: the deployment has checked it and accepts that hosts may repeat it.
      * Unknown static names fail construction; absent runtime names stay dormant and are reported. */
     classification: record(record(opaque({
         check: (value, path) => {
-            if (value !== "read" && value !== "write" && value !== "hidden") {
-                throw new ConfigError(`${path} must be "read", "write", or "hidden".`);
+            if (value !== "read" && value !== "read-repeatable" && value !== "write" && value !== "hidden") {
+                throw new ConfigError(`${path} must be "read", "read-repeatable", "write", or "hidden".`);
             }
         },
     }))),