@zackbart/connecta 0.41.0 → 0.42.0

package/dist/sent-secrets.d.ts

@@ -2,6 +2,9 @@ import type { ConnectorContext, JsonSchema, Logger } from "./types.js";
 /** One payload-free warning per configured connector, regardless of requests. */
 export declare function shortSecretWarning(): (value: string | undefined, logger: Logger) => void;
 export declare class SentSecrets {
+    /** Rises whenever this set could match more. Text checked at one revision has not been
+     * checked against a later one. */
+    revision: number;
     /** Normalized form to its strongest kind. */
     private readonly forms;
     /** A form's leading units that encode only public auth framing; absent is none. */
@@ -44,6 +47,10 @@ export declare class SentSecrets {
     contains(value: string, ignoreCase?: boolean): boolean;
     containsUrl(value: string): boolean;
     header(value: string): void;
+    /** A header maintained provider code declares a public identifier: matched whole only. A name
+     * alone never establishes this. Whitespace means an auth scheme or other framing, so that value
+     * is a credential whatever its header, and the answer is false. */
+    publicIdentifierHeader(value: string): boolean;
     request(input: RequestInfo | URL, init?: RequestInit): void;
     /** Serialized wire text about to be returned, stored, or paged, under payload rules. */
     text(value: string): string;
@@ -95,6 +102,13 @@ export declare class SentSecrets {
     /** Credentials alone: later calls keep the private arguments they submit, and cached
      * catalogs never depend on one request's arguments. */
     redactCredentials<T>(value: T): T;
+    /** A program's outbound arguments, with what the {@link outbound} check matched replaced,
+     * and whether it matched anything: a write that did is refused rather than sent altered.
+     * Output keeps the stricter matching; a program never holds what output withheld. */
+    filterCredentials<T>(value: T): {
+        value: T;
+        changed: boolean;
+    };
     private idle;
     private scan;
     private matcher;
@@ -104,6 +118,12 @@ export declare class SentSecrets {
     private wholeMatcher;
     private fragments;
     private credentials;
+    /** Credentials as an outbound argument can hold them: a whole form, or eight units of what
+     * follows its public framing and label. Identifiers and submitted private values are not
+     * here. Telling a secret from a label by shape has a limit: fewer than eight units past a
+     * label pass, and a public value sharing eight units of the rest, such as a publishable key
+     * beside its secret key, still matches. */
+    private outbound;
     /** Every form lowercased, for fields such as hosts that reach output lowercased. */
     private folded;
     /** The shortest text that might hold something this set cannot check, which is withheld: a

package/dist/sent-secrets.js

@@ -24,6 +24,11 @@ const MIN_SECRET_LENGTH = 8;
 // units is fragment-indexed. Eight units keeps ordinary words, dates, counts and auth framing out
 // of the index: a public run must repeat eight consecutive units of a secret's form to match.
 const FRAGMENT_LENGTH = MIN_SECRET_LENGTH;
+// A credential's public label, for the outbound argument check alone: a vendor prefix of up to
+// three short segments (`sk_test_`, `github_pat_`, `xoxb-`) or a JWT's header segment. Documents
+// name these and every credential of a kind shares them. Reading a secret's opening as a label
+// only stops runs starting inside it from matching; the rest of the value still matches.
+const PUBLIC_LABEL = /^(?:[Ee]yJ[\w-]*\.|(?:[A-Za-z][A-Za-z0-9]{1,6}[-_]){1,3})/;
 // A private value shorter than this is matched only as a whole field value: a leaf, key, number,
 // boolean or decoded view equal to one of its forms. One to three units recur inside ordinary
 // words, counts and ids, so a substring match would rewrite them everywhere.
@@ -115,7 +120,7 @@ const TAGS = new Set(("type:text type:image type:audio type:resource type:resour
     "resultType:input_required mode:form mode:url method:elicitation/create jsonrpc:2.0 writeOutcome:unknown").split(" "));
 // Outcome flags: a boolean under these names is kept, since a boolean carries one bit whatever
 // produced it. A number or string under them is matched like any other.
-const FACTS = new Set(["isError", "ok", "retryable", "truncated", "hasMore"]);
+const FACTS = new Set(["isError", "ok", "retryable", "truncated", "hasMore", "toolAnswered"]);
 // An error's diagnostics. Its own accessors under these names, such as V8's stack, are read once
 // into its copy, as is whatever its chain answers for them; any other own accessor is never
 // invoked. Accessors its class chain defines are read once too.
@@ -1096,6 +1101,9 @@ function windows(layer, reach) {
     return ranges;
 }
 export class SentSecrets {
+    /** Rises whenever this set could match more. Text checked at one revision has not been
+     * checked against a later one. */
+    revision = 0;
     /** Normalized form to its strongest kind. */
     forms = new Map();
     /** A form's leading units that encode only public auth framing; absent is none. */
@@ -1132,6 +1140,7 @@ export class SentSecrets {
         this.widestForm = Math.max(this.widestForm, form.length);
         this.smallForms ||= kind < PRIVATE;
         this.unicodeForms ||= /[\u0080-\uffff]/.test(form);
+        this.revision++;
         this.views = {};
         this.memo = new Map();
         for (const recipient of this.recipients)
@@ -1141,6 +1150,7 @@ export class SentSecrets {
         if (length >= this.unmatched)
             return;
         this.unmatched = length;
+        this.revision++;
         this.views = {};
         this.memo = new Map();
         for (const recipient of this.recipients)
@@ -1278,6 +1288,17 @@ export class SentSecrets {
         else
             this.secret(framed[1]);
     }
+    /** A header maintained provider code declares a public identifier: matched whole only. A name
+     * alone never establishes this. Whitespace means an auth scheme or other framing, so that value
+     * is a credential whatever its header, and the answer is false. */
+    publicIdentifierHeader(value) {
+        if (/\s/.test(value)) {
+            this.header(value);
+            return false;
+        }
+        this.identifier(value);
+        return true;
+    }
     request(input, init) {
         const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
         for (const [name, value] of headers) {
@@ -1412,6 +1433,16 @@ export class SentSecrets {
     redactCredentials(value) {
         return this.credentials().redact(value, "envelope");
     }
+    /** A program's outbound arguments, with what the {@link outbound} check matched replaced,
+     * and whether it matched anything: a write that did is refused rather than sent altered.
+     * Output keeps the stricter matching; a program never holds what output withheld. */
+    filterCredentials(value) {
+        const outbound = this.outbound();
+        if (outbound.idle())
+            return { value, changed: false };
+        const filtered = outbound.project(value, outbound.scan(false));
+        return { value: filtered.value, changed: filtered.changed };
+    }
     idle() {
         return !this.forms.size && this.unmatched === Infinity;
     }
@@ -1453,6 +1484,23 @@ export class SentSecrets {
         }
         return this.views.credentials;
     }
+    /** Credentials as an outbound argument can hold them: a whole form, or eight units of what
+     * follows its public framing and label. Identifiers and submitted private values are not
+     * here. Telling a secret from a label by shape has a limit: fewer than eight units past a
+     * label pass, and a public value sharing eight units of the rest, such as a publishable key
+     * beside its secret key, still matches. */
+    outbound() {
+        if (!this.views.outbound) {
+            const view = new SentSecrets();
+            for (const [form, kind] of this.forms) {
+                const frame = this.frames.get(form) ?? 0;
+                if (kind === CREDENTIAL && frame !== Infinity)
+                    view.store(form, kind, frame + (PUBLIC_LABEL.exec(form.slice(frame))?.[0].length ?? 0));
+            }
+            this.views.outbound = view;
+        }
+        return this.views.outbound;
+    }
     /** Every form lowercased, for fields such as hosts that reach output lowercased. */
     folded() {
         if (!this.views.folded) {

package/dist/skills.js

@@ -1,4 +1,5 @@
 import { META_ROUTES, routeNames } from "./agent-routes.js";
+import { READ_PROGRAM_SOURCE } from "./tool-safety.js";
 import { bytesToHex, utf8Length } from "./bytes.js";
 import { duringViewEffect } from "./runtime/call.js";
 import { RequestScope, requestOwner } from "./runtime/request-scope.js";
@@ -16,44 +17,92 @@ export class SkillLookupError extends ConnectorCallError {
 }
 // The meta instructions and built-in guides use the meta names: built-in guides
 // are byte-identical across deployments, and the eval code arm replaces usage.
-const ROUTE = `Choose a route before discovery. One known-address read uses ${META_ROUTES.read}; one known-address write uses ${META_ROUTES.write}. Unknown-address read-only work starts with ${META_ROUTES.program} to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Sample unfamiliar reads.`;
-const RECOVERY = `When an auth error includes a handoff, give it to the user or operator. Use ${META_ROUTES.authorize} for a fresh link. Page resultId notices and format:"paged" handles with connecta.result(handleOrId, { page? }). Missing guidance/repair only: skills tool "usage" or connecta.skill("usage").`;
-/**
- * The always-loaded MCP `instructions` string. An endpoint is writable or
- * read-only: a writable one lets programs and call_destructive_tool write,
- * and the client owns approval; a read-only one omits write tools from search
- * and describe and refuses every write call. Guides may still name them.
- */
-function writePolicy(readOnly, routes) {
-    return readOnly
-        ? "This endpoint can't perform writes; guide steps that change data will be refused. No write route exists on this endpoint."
-        : `This endpoint permits writes through ${routes.write}${routes.program === META_ROUTES.program ? ` and ${routes.program}` : ""}, subject to connector restrictions; the host owns approval.`;
+const WRITE_POLICY = "This endpoint permits writes, subject to connector restrictions; the host owns approval. Never resend a write to see its output.";
+const READ_ONLY_POLICY = "This endpoint can't perform writes; no write route exists here.";
+const RECOVERY = "On errors and truncated results, follow nextAction; give auth links to the user or operator.";
+/** A guide can name a write step, so its notice says what happens to one. */
+const READ_ONLY_GUIDE_NOTICE = "This endpoint can't perform writes; guide steps that change data will be refused. No write route exists on this endpoint.";
+const policy = (readOnly) => (readOnly ? READ_ONLY_POLICY : WRITE_POLICY);
+/** Connector ids in instructions; execute_code's inventory carries the rest. */
+const INSTRUCTION_CONNECTORS_MAX_BYTES = 120;
+/** Ids in roster order, then an exact count once they pass the byte cap. Ids are ASCII. */
+function connectorList(ids) {
+    if (ids.length === 0)
+        return "none";
+    const all = ids.join(", ");
+    if (all.length <= INSTRUCTION_CONNECTORS_MAX_BYTES)
+        return all;
+    for (let shown = ids.length - 1; shown > 0; shown--) {
+        const line = [...ids.slice(0, shown), `+${ids.length - shown} more`].join(", ");
+        if (line.length <= INSTRUCTION_CONNECTORS_MAX_BYTES)
+            return line;
+    }
+    return `+${ids.length} more`;
 }
-export const CONNECTA_INSTRUCTIONS = `${ROUTE} ${writePolicy(false, META_ROUTES)} Never repeat a write to recover its output. ${RECOVERY}`;
 /**
- * The instructions one endpoint serves: pool scope and guide pointer first,
- * then stable routing rules. Plain `/mcp` and a
- * pool without a description serve the constant unchanged. The description
- * comes from deployment config for the pool the request was admitted through;
- * nothing a request sends reaches it.
+ * The instructions one endpoint serves: pool scope, what the endpoint reaches,
+ * routing, write policy, recovery. The description comes from deployment config
+ * for the pool the request was admitted through. `connectorIds` is that
+ * request's admitted roster, the same one execute_code's inventory discloses:
+ * configured ids only, in registry order, with no catalog, call or auth state.
+ * A native pool omits them because its tool names already show them.
  */
-export function endpointInstructions(description, native, readOnly = false) {
+export function endpointInstructions(description, native, readOnly, connectorIds, readRoute = false) {
+    const gateway = `Gateway to connected services: ${connectorList(connectorIds)}. One known read: ${META_ROUTES.read}. ${readOnly ? "" : `One known write: ${META_ROUTES.write}. `}`;
     const instructions = native
         ? nativeInstructions(native.executeCode, readOnly)
-        : readOnly
-            ? `Choose a route before discovery. One known read uses ${META_ROUTES.read}; other read work uses ${META_ROUTES.program} to discover, call and return the answer. ${writePolicy(true, META_ROUTES)} Never repeat a write for output. ${RECOVERY}`
-            : CONNECTA_INSTRUCTIONS;
-    if (description === undefined)
-        return instructions;
-    const routing = native
-        ? instructions
-        : `Known read: ${META_ROUTES.read}${readOnly ? "" : `; known write: ${META_ROUTES.write}`}. Other work: ${META_ROUTES.program}; discover and call together, return answers, sample unfamiliar reads. ${writePolicy(readOnly, META_ROUTES)} Never repeat writes for output. Give auth handoffs to user/operator; ${META_ROUTES.authorize} refreshes links. Page resultId/format:"paged" with connecta.result(handleOrId,{page?}).`;
-    return `Use skills. ${description} ${routing}`;
+        : readRoute
+            ? `${gateway}Other read work: one ${READ_PROGRAM_SOURCE} program that searches, calls and returns the answer, with no write approval. ${readOnly ? "" : `Programs that write: ${META_ROUTES.program}. ${META_ROUTES.search} finds a write's address. `}${policy(readOnly)} ${RECOVERY}`
+            : `${gateway}Everything else: one ${META_ROUTES.program} program that searches, calls and returns the answer. ${policy(readOnly)} ${RECOVERY}`;
+    return description === undefined ? instructions : `${description} ${instructions}`;
 }
 /** Instructions for pools whose host searches the listed native tools. */
 export function nativeInstructions(executeCode, readOnly = false) {
     const routes = routeNames(executeCode ? "native-code" : "native");
-    return `Annotations classify reads/writes. Call known tools directly; ${executeCode ? `combine work in ${routes.program} using tool descriptions’ program addresses.` : "find tools with your host's search."} ${writePolicy(readOnly, routes)} Never repeat a write for output. Give auth handoffs to the user/operator. Tools missing? Ask the operator to repair, then reconnect. Follow nextAction to page with ${executeCode ? `connecta.result in ${routes.program}` : "read_result"}. ${routes.skills} lists guidance.`;
+    return `Call known tools directly; ${executeCode ? `combine several in ${routes.program} using each tool's Program address.` : "find others with your host's search."} ${policy(readOnly)} ${RECOVERY} Tools missing: ask the operator to repair, then reconnect.`;
+}
+/** The `capabilities.extensions` key carrying {@link endpointExtension}. */
+export const ENDPOINT_EXTENSION = "dev.connecta/endpoint";
+const inventoryWords = (text) => text
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter(Boolean);
+/** Text that only respells what its entry already shows ("Google Calendar" for google_calendar) adds nothing. */
+export function addsInformation(shown, text) {
+    const words = inventoryWords(text);
+    const shownWords = inventoryWords(shown);
+    return words.join("") !== shownWords.join("") && words.some((word) => !shownWords.includes(word));
+}
+/** Clips on a whole token, so text with no token that fits leaves nothing to show. */
+export const inventoryNote = (text, maxBytes) => {
+    const clipped = boundedEchoText(text, maxBytes);
+    return clipped === "…" ? undefined : clipped;
+};
+/** A connector's bounded title for inventories, or undefined when it adds nothing to the id or cannot fit. */
+export function connectorInventoryTitle(connector) {
+    const title = connector.title?.replace(/\s+/g, " ").trim();
+    return title && addsInformation(connector.id, title) ? inventoryNote(title, 45) : undefined;
+}
+/**
+ * Facts about the endpoint this request reached, for a client composing its own
+ * host-specific guidance. Built only from the admitted scope and configuration:
+ * `connectors` is the caller's registry view, the roster `execute_code` and
+ * `authorize_connector` already describe, and nothing here loads a catalog.
+ */
+export function endpointExtension(connectors, native, executeCode, readOnly) {
+    return {
+        surface: native ? "native" : "meta",
+        executeCode,
+        readOnly,
+        connectors: connectors.map((connector) => {
+            const title = connectorInventoryTitle(connector);
+            return {
+                id: connector.id,
+                ...(title ? { title } : {}),
+                ...(connectorGuideRequired(connector) ? { readFirst: connectorSkillName(connector.id) } : {}),
+            };
+        }),
+    };
 }
 /** True when at least one of `connectors` carries a usage guide. */
 export function hasConnectorGuides(connectors) {
@@ -115,11 +164,16 @@ const CONNECTOR_SKILL_PREFIX = "connector:";
 export function connectorSkillName(connectorId) {
     return `${CONNECTOR_SKILL_PREFIX}${connectorId}`;
 }
-/** The connector's guide, or undefined when it declares none (or a blank one). */
-export function connectorGuide(connector) {
+/** The guide as authored, or undefined when the connector declares none (or a blank one). */
+function authoredGuide(connector) {
     const guide = connector.usageGuide;
     const content = typeof guide === "string" ? guide : guide?.content;
-    if (!content || content.trim() === "")
+    return !content || content.trim() === "" ? undefined : content;
+}
+/** The connector's guide with its connection's read-only notice, or undefined when it has none. */
+export function connectorGuide(connector) {
+    const content = authoredGuide(connector);
+    if (content === undefined)
         return undefined;
     return connector.readOnly === true
         ? `This connection can't perform writes; guide steps that change data will be refused. No write route exists for this connection.\n\n${content}`
@@ -356,6 +410,11 @@ const PRIVATE = { resultType: "complete", ttlMs: 0, cacheScope: "private" };
 function localRecord(name, uri, description, content, aliases) {
     return { entry: { uri, frontmatter: { name, description }, resources: "dynamic" }, content, aliases };
 }
+/** A local record's text after the frontmatter block Connecta wrote ahead of it. */
+function localSkillBody(text) {
+    const close = text.indexOf("\n---\n", 3);
+    return close === -1 ? text : text.slice(close + "\n---\n".length).replace(/^\n/, "");
+}
 /** JSON frontmatter is YAML too; no runtime provider imports or filesystem reads. */
 function validSkillName(name) {
     return name.length <= 64 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name);
@@ -416,7 +475,11 @@ const localRecordsNative = /* @__PURE__ */ registerAuth(localRecords, function (
         const guides = identities.map(({ connector, name, legacy }) => {
             const description = connectorGuideSummary(connector);
             const root = `skill://connecta/connectors/${encodeURIComponent(name)}`;
-            const content = `---\n${JSON.stringify({ name, description }, null, 2)}\n---\n\n${readOnly ? `${writePolicy(true, META_ROUTES)}\n\n` : ""}${connectorGuide(connector)}`;
+            // One read-only notice: the endpoint's already covers its connections.
+            const guide = readOnly
+                ? `${READ_ONLY_GUIDE_NOTICE}\n\n${authoredGuide(connector)}`
+                : connectorGuide(connector);
+            const content = `---\n${JSON.stringify({ name, description }, null, 2)}\n---\n\n${guide}`;
             return {
                 ...localRecord(name, `${root}/SKILL.md`, description, content, [
                     connectorSkillName(connector.id),
@@ -666,6 +729,10 @@ export class SkillsRegistry {
             return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
                 const record = yield* upwardStep(authInvoke(self, "lookup", [name]));
                 const content = (yield* upwardStep(authInvoke(self, "read", [record.entry.uri]))).contents[0];
+                // Connecta prepends frontmatter to local guides for native SKILL.md; a
+                // tool reader wants only the body. Downstream files keep their bytes.
+                if (!record.files && typeof content.text === "string")
+                    return localSkillBody(content.text);
                 const origin = record.files ? `${downstreamOrigin(record.connector.id)}\n\n` : "";
                 if (typeof content.text === "string")
                     return origin + content.text;

package/dist/storage/keys.js

@@ -58,7 +58,8 @@ export const scopes = {
 export const RESULT_TTL_SECONDS = 900;
 /**
  * A stashed result: chunk 0 at `result:<id>`, chunk n at `result:<id>#<n>`.
- * The value is the paging envelope `src/meta-tools.ts` writes and reads.
+ * The value is the paging envelope `src/meta-tools.ts` writes and reads, or at
+ * chunk 0 the refusal `src/result-seal.ts` writes for a result it did not publish.
  */
 export const resultKeys = {
     family: {
@@ -191,7 +192,7 @@ export const responseCacheKeys = {
         codec: textCodec,
         ttl: {
             kind: "configured",
-            by: "bounded downstream ttlMs; generations and hash refresh baselines expire after 48 hours",
+            by: "bounded downstream ttlMs; generations, refusal fences and hash refresh baselines expire after 48 hours",
         },
         durable: false,
     },
@@ -356,19 +357,21 @@ export const oauthRefreshActiveKeys = {
     prefix: "oauth:refresh-active:",
     holder: (epoch, holder) => validateStorageKey(`oauth:refresh-active:${epoch}:${holder}`),
 };
-/** Single-use browser links (`used`/`started`/`failed`/`closed`) and MRTR rounds. */
+/** Single-use browser links and forced resets (`used`/`started`/`failed`), and MRTR rounds. */
 export const oauthConnectKeys = {
     family: {
         name: "oauth-connect",
         scope: "connector",
-        prefixes: ["oauth:connect-used:", "oauth:request-used:"],
+        prefixes: ["oauth:connect-used:", "oauth:connect-reset:", "oauth:request-used:"],
         version: { number: 1, in: "untagged" },
         codec: textCodec,
-        // The link's remaining lifetime, or fifteen minutes when retiring it.
-        ttl: { kind: "fixed", seconds: 15 * 60 },
+        // A link's remaining lifetime, fifteen minutes for a round, or thirty for a
+        // reset, which must outlive every link its flow can issue.
+        ttl: { kind: "fixed", seconds: 30 * 60 },
         durable: false,
     },
     used: (nonce) => validateStorageKey(`oauth:connect-used:${nonce}`),
+    reset: (flow) => validateStorageKey(`oauth:connect-reset:${flow}`),
     retry: (nonce) => validateStorageKey(`oauth:request-used:${nonce}`),
 };
 /**

package/dist/storage/sql-native.js

@@ -134,7 +134,7 @@ export function nativeSqlStorage(driver) {
         },
         catalogSnapshot(keys, generationKey, prefix, suffixes) {
             return Effect.gen(function* () {
-                if (keys.length < 1 || keys.length > 4 || suffixes.length > 2)
+                if (keys.length < 1 || keys.length > 4 || suffixes.length > 3)
                     throw new RangeError("Catalog locator exceeds bounds");
                 for (const key of [...keys, generationKey, prefix, ...suffixes])
                     validateStorageKey(key);

package/dist/tool-safety.d.ts

@@ -0,0 +1,33 @@
+import type { ToolDef } from "./types.js";
+/** What deployment code may say about one tool. */
+export type ClassificationOverride = "read" | "read-repeatable" | "write" | "hidden";
+export declare function sourceClassification(tool: ToolDef): "read" | "write";
+/** The source said this tool writes, as opposed to saying nothing. */
+export declare function sourceDeclaresWrite(tool: ToolDef): boolean;
+/**
+ * Deployment override, then fail-closed annotations. `"read"` speaks only where
+ * the source is silent: a declared write stays a write, because a read annotation
+ * lets a host resend the call. `"read-repeatable"` is the deployment accepting
+ * that resend for a tool it has checked, so it serves as a read regardless. Either
+ * way a source write stays write-like, so Connecta itself never replays it.
+ */
+export declare function classifyTool(definition: ToolDef, override?: Exclude<ClassificationOverride, "hidden">): "read" | "write";
+export declare function carryToolClassification(source: ToolDef, served: ToolDef, acceptRepeat?: boolean): ToolDef;
+/** Replay and outcome policy only; admission and presentation use the served class. */
+export declare function isWriteLike(tool: ToolDef): boolean;
+/** The surface that runs a read-only program: it never dispatches a write-like call. */
+export declare const READ_PROGRAM_SOURCE: "execute_read_code";
+/**
+ * What a read program refuses: anything write-like, unless the deployment accepted
+ * repeats. A plain `"read"` over a source write stays out, because only
+ * `"read-repeatable"` says a host's resend of the program is acceptable.
+ */
+export declare function readProgramRefuses(tool: ToolDef): boolean;
+export declare function cloneTool(tool: ToolDef): ToolDef;
+/**
+ * The only permission decision for a connector call. Approval is client-owned.
+ * A read-only endpoint refuses every write on every surface; a writable one
+ * sends writes through call_destructive_tool and writing programs, never call_tool
+ * or a read program.
+ */
+export declare function writeRefusal(classification: ToolDef["classification"], surface: string, readOnly?: boolean): "read_only_endpoint" | "destructive_tool_requires_approval" | undefined;

package/dist/tool-safety.js

@@ -1,33 +1,69 @@
-/** Deployment override, then fail-closed annotations. */
+function sourceFactsOf(annotations) {
+    const readOnly = annotations?.readOnlyHint;
+    const destructive = annotations?.destructiveHint;
+    if (readOnly === true && destructive !== true)
+        return "read";
+    // Anything but a clean read or silence counts as declared, including contradictory
+    // or malformed hints: an override must not turn an unclear statement into a read.
+    return readOnly === undefined && destructive !== true ? "silent" : "declared_write";
+}
+// Source policy is fail-closed annotations, with silence kept apart from a
+// declared write. Deployment overrides never enter it. It is private metadata,
+// not catalog data. Keep it through host-owned clones without exposing it to
+// tools or storage.
+const sourceFacts = new WeakMap();
+const factsFor = (tool) => sourceFacts.get(tool) ?? sourceFactsOf(tool.annotations);
+export function sourceClassification(tool) {
+    return factsFor(tool) === "read" ? "read" : "write";
+}
+/** The source said this tool writes, as opposed to saying nothing. */
+export function sourceDeclaresWrite(tool) {
+    return factsFor(tool) === "declared_write";
+}
+/**
+ * Deployment override, then fail-closed annotations. `"read"` speaks only where
+ * the source is silent: a declared write stays a write, because a read annotation
+ * lets a host resend the call. `"read-repeatable"` is the deployment accepting
+ * that resend for a tool it has checked, so it serves as a read regardless. Either
+ * way a source write stays write-like, so Connecta itself never replays it.
+ */
 export function classifyTool(definition, override) {
-    if (override !== undefined)
+    if (override === "read-repeatable")
+        return "read";
+    if (override === "write" || (override === "read" && !sourceDeclaresWrite(definition)))
         return override;
-    return definition.annotations?.readOnlyHint === true && definition.annotations?.destructiveHint !== true
-        ? "read"
-        : "write";
-}
-// Source policy is fail-closed annotations.
-// Deployment overrides never enter it. It is private metadata, not catalog data.
-// Keep it through host-owned clones without exposing it to tools or storage.
-const sourceClassifications = new WeakMap();
-export function sourceClassification(tool) {
-    return sourceClassifications.get(tool) ?? classifyTool(tool);
+    return sourceClassification(definition);
 }
-export function carryToolClassification(source, served) {
-    sourceClassifications.set(served, sourceClassification(source));
+// Tools a deployment set to `"read-repeatable"`, private like the source facts.
+const repeatAccepted = new WeakSet();
+export function carryToolClassification(source, served, acceptRepeat = repeatAccepted.has(source)) {
+    sourceFacts.set(served, factsFor(source));
+    if (acceptRepeat)
+        repeatAccepted.add(served);
     return served;
 }
 /** Replay and outcome policy only; admission and presentation use the served class. */
 export function isWriteLike(tool) {
     return tool.classification !== "read" || sourceClassification(tool) === "write";
 }
+/** The surface that runs a read-only program: it never dispatches a write-like call. */
+export const READ_PROGRAM_SOURCE = "execute_read_code";
+/**
+ * What a read program refuses: anything write-like, unless the deployment accepted
+ * repeats. A plain `"read"` over a source write stays out, because only
+ * `"read-repeatable"` says a host's resend of the program is acceptable.
+ */
+export function readProgramRefuses(tool) {
+    return isWriteLike(tool) && !repeatAccepted.has(tool);
+}
 export function cloneTool(tool) {
     return carryToolClassification(tool, structuredClone(tool));
 }
 /**
  * The only permission decision for a connector call. Approval is client-owned.
  * A read-only endpoint refuses every write on every surface; a writable one
- * sends writes through call_destructive_tool and programs, never call_tool.
+ * sends writes through call_destructive_tool and writing programs, never call_tool
+ * or a read program.
  */
 export function writeRefusal(classification, surface, readOnly = false) {
     if (classification === "read")

package/dist/types.d.ts

@@ -335,6 +335,12 @@ export type ConnectorSkillResourceContents = {
     text?: never;
 });
 /** The whole plugin contract — the one open seam. */
+/** A complete cached catalog and the times it was fetched and expires, in epoch milliseconds. */
+export interface ConnectorCatalogPeek {
+    tools: ToolDef[];
+    fetchedAt: number;
+    expiresAt: number;
+}
 export interface Connector {
     /** Serve only read-classified tools on every endpoint. Defaults to false. */
     readOnly?: boolean;
@@ -399,6 +405,16 @@ export interface Connector {
      * fetched lazily over the network and are not known at construction time.
      */
     staticTools?: ToolDef[];
+    /**
+     * Optional: the newest complete catalog this context could be served, fresh
+     * or stale, read from storage alone. No transport, no authorization and no
+     * writes. Discovery lists its result and marks it; call resolution never
+     * reads it. `remoteMcp()` implements it. A custom connector omits it and
+     * discovery falls back to the catalog core retains for an authenticated owner.
+     * A wrapper that replaces `listTools` must replace or remove this as well, or
+     * discovery lists what the wrapper would have changed.
+     */
+    peekCatalog?(ctx: ConnectorContext): Promise<ConnectorCatalogPeek | undefined>;
     /**
      * Optional: what this connector is, for `Connecta.describeConfig()` and the
      * operator surfaces built on it — where it points, how it authenticates,
@@ -616,6 +632,21 @@ export interface Executor {
      * rewrite; set this to say the same thing minification-proof.
      */
     readonly name?: string;
+    /**
+     * The run's wall-clock deadline, in whole milliseconds, when this sandbox has
+     * one: time from `execute()` to its own timeout result. Connecta ends a
+     * program's reads just before it, so a slow read becomes a catchable
+     * `timeout` rather than the whole run's failure. Omit it if the sandbox
+     * has no fixed deadline. See documentation/code-mode.md#cancellation-and-limits.
+     */
+    readonly deadlineMs?: number;
+    /**
+     * The largest stored result, in UTF-8 bytes, that one program may read whole
+     * with `connecta.result(id, { all: true })` and still have budget left to use
+     * it. Default 1.5 MiB. Set it lower when a tighter CPU or memory limit would
+     * end the run first.
+     */
+    readonly maxReadBytes?: number;
     execute(code: string, providers: ExecutorProvider[]): Promise<ExecuteResult>;
     /** Release runtime resources. Node's built-in pool implements this. */
     close?(): void | Promise<void>;

package/dist/usage-guide.js

@@ -1,4 +1,5 @@
 import { META_ROUTES } from "./agent-routes.js";
+import { READ_PROGRAM_SOURCE } from "./tool-safety.js";
 import { UNCOUNTED_GUEST_FUNCTIONS } from "./guest-functions.js";
 /** Self-contained content for the usage skill; independent of skill registration. */
 export const USAGE_SKILL = `---
@@ -14,7 +15,7 @@ Route as the server instructions and ${META_ROUTES.program}'s first sentence say
 Read one account with ${META_ROUTES.read}: \`{ "address": "crm.get_account", "args": { "id": "acct_42" } }\`.
 On a read-only endpoint search omits writes (guides may name them) and each
 fails read_only_endpoint; tell the user. Unannotated tools fail closed to writes.
-Connecta classifies and routes a requested write; the host owns approval.
+Where listed, ${READ_PROGRAM_SOURCE} refuses writes, marked \`callable: false\`.
 
 ## The global and the envelopes
 
@@ -28,7 +29,7 @@ Parse \`format: "text"\` only when documented as JSON. Verify collection roots.
 \`connecta.read("resource://id/"+encodeURIComponent(uri))\` returns \`{ contents }\` for advertised URIs.
 
 Search/describe return \`{ tools }\`, never an array. Check search's
-\`catalogErrors\` and \`absence\` before selecting a match. Search defaults to a
+\`catalogErrors\` and \`absence\` before selecting a match; a \`stale: true\` error's tools are listed from an older catalog, and a call still checks the live one. Search defaults to a
 TypeScript \`signature\`; text schemas have \`schemaFormat: "text"\` and no .properties.
 A \`readyCalls\` entry is a complete read: \`connecta.call(entry.address, entry.args)\`. Select the exact tool and
 account/environment, inspect its schema, and supply its required keys and types.
@@ -85,14 +86,14 @@ Otherwise fetch for units, pagination, aliases, or sequences.
 
 ## Large results and recovery
 
-Large direct results and program returns carry resultId when paging is available. Follow
-nextOffset in UTF-8 bytes, reassemble and reduce inside one program. Use the
-returned id in place of result-id below; this example assumes documented JSON.
+Large results carry resultId. Follow nextOffset in UTF-8 bytes, reassemble and reduce
+inside one program. Use that id for result-id below; this example assumes documented JSON.
 
-Calls reconstruct up to 1 MiB through stash pages. Larger values return
-\`{ format: "paged", valueFormat, resultId?, totalBytes, hint }\`. Pass the handle
-to \`connecta.result\`. No resultId means no paging. IDs expire after
-15 minutes; only explicit paging spends extra host calls.
+Calls inline up to 1 MiB; larger return
+\`{ format: "paged", valueFormat, resultId?, totalBytes, hint }\`. Follow its hint:
+\`connecta.result(handle, { all: true })\` gives \`{ data, format }\` for one host call,
+or throws result_too_large; then page. IDs last 15 minutes; only explicit
+paging spends extra host calls.
 Use zero-based \`{ page: 0 }\` or UTF-8 \`{ offset }\`, never both. Keep maxBytes
 fixed across pages; connector caps and the 32 KiB bridge ceiling apply.
 
@@ -100,7 +101,7 @@ fixed across pages; connector caps and the 32 KiB bridge ceiling apply.
 async () => {
   let text = "", offset = 0, page;
   do {
-    page = await connecta.result("result-id", { offset, maxBytes: 8000 });
+    page = await connecta.result("result-id", { offset });
     text += page.text;
     offset = page.nextOffset;
   } while (page.hasMore);
@@ -108,13 +109,13 @@ async () => {
 }
 \`\`\`
 
-Oversized returns lead with nextAction. Never rerun writes for output. write_outcome_unknown or writeOutcome forbids retry, even if caught.
+Oversized returns lead with nextAction. Never rerun writes for output. write_outcome_unknown or writeOutcome forbids retry, even if caught. Give the user any approval link in the tool's words; a call after approval is new.
 Recovery args may be partial (argsRedacted) or absent (argsOmitted). Reconcile
 before retrying with the original args or repeating a program that sent writes.
 Non-retryable errors need repair.
 host_auth_required needs host connection repair; provider_permission_denied needs
-resource-owner access. Auth failures carry the handoff in error.data. When an auth
-error includes a handoff, give it to the user or operator.
+resource-owner access. Auth failures carry the handoff in error.data; give it to the
+user or operator.
 
 ## Output