@zackbart/connecta 0.40.0 → 0.42.0

package/dist/providers/vercel/api.js

@@ -1,7 +1,7 @@
 import { isRecord } from "../_shared/json.js";
 // Vercel's pinned contract, authentication, failures and value-safety boundary.
 import { Effect, Schema } from "effect";
-import { ConnectorCallError } from "../../errors.js";
+import { ConnectorCallError, tokenPrefix } from "../../errors.js";
 import { Refusal, StatusFailure, UnreadableBody } from "../../http/errors.js";
 import { restSafety } from "../../http/safety.js";
 import { Credentials, RequestSecrets } from "../../http/services.js";
@@ -93,7 +93,7 @@ export const vercelErrors = {
         const code = text(error["code"]);
         const message = text(error["message"])?.trim() ?? text(root["message"])?.trim() ?? `Vercel returned HTTP ${status}.`;
         const reviewed = withheld ? facts["code"] : reviewedCode(code);
-        const detail = (code ? `Vercel ${code}: ${message}` : message).slice(0, 1_000);
+        const detail = tokenPrefix(code ? `Vercel ${code}: ${message}` : message, 1_000) || `Vercel returned HTTP ${status}.`;
         if (status >= 200 && status <= 299 && facts["envRejected"] === true)
             return `Vercel rejected the environment-variable write${reviewed ? ` (${reviewed})` : ""}; its message is withheld because this operation handles secret values.`;
         return withheld
@@ -414,6 +414,7 @@ export function usageGuide(options) {
     options = pinOptions(options);
     const team = defaultTeam(options);
     return {
+        summary: "Load for Vercel team scope, project/deployment ids, build events, runtime logs and guarded writes.",
         context: [
             `Vercel REST access token is already configured. Account purpose: ${options.purpose}`,
             options.pin

package/dist/providers/vercel/skill.generated.js

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Projects, deployments and domains\n\nResolve a team by slug, a project by name, and deployments by the observed\nproject id. Team ids start with `team_`, project ids with `prj_`, and deployment\nids with `dpl_`. A deployment hostname and a deployment id identify the same\ndeployment; an alias can later point to a different deployment.\n\nSome project paths accept a project name, but a deployment list's projectId\nfilter requires the observed `prj_` id. Resolve the name before listing its\ndeployments; an empty result for a guessed name does not prove absence.\nComplete each identifier lookup before starting the reads that depend on it.\n\n<!-- when: unpinned -->\nThe configured team is a routing default, not a restriction. Explicit teamId\nor slug selects another team the token can reach; teamId: null selects personal\nscope. Vercel token permissions determine access. Prefer an explicit team when\njoining resources across several calls.\n<!-- end -->\n\n<!-- when: pinned -->\nThe deployment confines this connection to one team. A supplied team slug must\nbelong to that team; personal scope and foreign teams are refused. Project and\ndeployment references require ownership reads. Global/account and transfer\noperations without a verifiable team boundary remain unavailable. A team list\nreturns only the pinned team.\n<!-- end -->\n\nRead deployment state before its build events. Runtime logs diagnose requests\nafter a deployment built; build logs explain a failed build. Narrow time windows\nbefore raising collection limits. Generic reads refuse live follow streams;\nuse the bounded build/runtime readers. Deployment timestamps are milliseconds.\n\nProject domains and deployment aliases are different joins: a project domain\nbelongs to the project, while an alias identifies its assigned deployment.\nRead a pending domain's verification instructions before changing DNS.\n\n## Environment changes\n\nResolve environment-variable ids using metadata, including target, branch and\ncustom environment. A key can have distinct production and preview values.\nExisting values cannot be retrieved. Supply new values only when the task asks\nfor a change; confirm the returned id and metadata.\n\nEnvironment changes apply to future deployments. A new deployment is a separate\nwrite. Promoting an existing deployment does not rebuild it or update embedded\nenvironment values. After an uncertain update, reconcile observable metadata\nsuch as id, targets and comment; reading metadata cannot verify a secret value.\n\n## Explicit files and credentials\n\nDeployment files can reference previously uploaded digests. File uploads accept\nexplicit bytes and never read a path on the agent's machine. Decrypted-value,\ncredential-minting, protection-bypass-link, signing and domain move-out operations\nare refused; use Vercel's dashboard for those workflows.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `list_teams`, `vercel_api_details`, `vercel_api_search`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `vercel_api_read`, put it in `query[page.param]` or `body[page.param]`, as `page.in` specifies. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 20, at most 100). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Hatch:** `vercel_api_search` finds this API's operations and reads no account data, `vercel_api_details` shows one operation's contract, and `vercel_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `vercel_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 29 operations are refused by design; use `vercel_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. `not_found` means the record does not exist; this API tells absence from a permission gap. It documents no conflict.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
+    "content": "## Projects, deployments and domains\n\nResolve a team by slug, a project by name, and deployments by the observed\nproject id. Team ids start with `team_`, project ids with `prj_`, and deployment\nids with `dpl_`. A deployment hostname and a deployment id identify the same\ndeployment; an alias can later point to a different deployment.\n\nSome project paths accept a project name, but a deployment list's projectId\nfilter requires the observed `prj_` id. Resolve the name before listing its\ndeployments; an empty result for a guessed name does not prove absence.\nComplete each identifier lookup before starting the reads that depend on it.\n\n<!-- when: unpinned -->\nThe configured team is a routing default, not a restriction. Explicit teamId\nor slug selects another team the token can reach; teamId: null selects personal\nscope. Vercel token permissions determine access. Prefer an explicit team when\njoining resources across several calls.\n<!-- end -->\n\n<!-- when: pinned -->\nThe deployment confines this connection to one team. A supplied team slug must\nbelong to that team; personal scope and foreign teams are refused. Project and\ndeployment references require ownership reads. Global/account and transfer\noperations without a verifiable team boundary remain unavailable. A team list\nreturns only the pinned team.\n<!-- end -->\n\nRead deployment state before its build events. Runtime logs diagnose requests\nafter a deployment built; build logs explain a failed build. Narrow time windows\nbefore raising collection limits. Generic reads refuse live follow streams;\nuse the bounded build/runtime readers. Deployment timestamps are milliseconds.\n\nProject domains and deployment aliases are different joins: a project domain\nbelongs to the project, while an alias identifies its assigned deployment.\nRead a pending domain's verification instructions before changing DNS.\n\n## Environment changes\n\nResolve environment-variable ids using metadata, including target, branch and\ncustom environment. A key can have distinct production and preview values.\nExisting values cannot be retrieved. Supply new values only when the task asks\nfor a change; confirm the returned id and metadata.\n\nEnvironment changes apply to future deployments. A new deployment is a separate\nwrite. Promoting an existing deployment does not rebuild it or update embedded\nenvironment values. After an uncertain update, reconcile observable metadata\nsuch as id, targets and comment; reading metadata cannot verify a secret value.\n\n## Explicit files and credentials\n\nDeployment files can reference previously uploaded digests. File uploads accept\nexplicit bytes and never read a path on the agent's machine. Decrypted-value,\ncredential-minting, protection-bypass-link, signing and domain move-out operations\nare refused; use Vercel's dashboard for those workflows.\n\n## Conventions\n\n- **Hatch:** `vercel_api_search` finds operations, `vercel_api_details` shows one contract, `vercel_api_read` calls a reviewed read and `vercel_api_write` a reviewed write. 29 operations are refused by design; use `vercel_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Errors:** `not_found` means the record does not exist; this API tells absence from a permission gap.",
     "instructionsHeading": "Account instructions"
 };

package/dist/registry.d.ts

@@ -2,6 +2,7 @@ import type { CatalogDriftActivityContext } from "./activity.js";
 import { type CallAdmissionPermit, type ConnectorCallAdmissionSnapshot } from "./call-admission.js";
 import { type ConnectorCaller } from "./connector-caller.js";
 import type { CredentialVault } from "./credential-contract.js";
+import { type ClassificationOverride } from "./tool-safety.js";
 import type { Connector, ConnectorContext, ConnectorStatus, KVStorage, Logger, ToolDef } from "./types.js";
 /**
  * Split `"<connectorId>.<toolName>"` on the first dot. Connector ids contain
@@ -45,7 +46,7 @@ export declare function resolveMaxResultBytes(value: number | undefined, inherit
 export interface RegistryOptions {
     publicUrl?: string | undefined;
     oauthClientName?: string | undefined;
-    classification?: Readonly<Record<string, Readonly<Record<string, "read" | "write" | "hidden">>>> | undefined;
+    classification?: Readonly<Record<string, Readonly<Record<string, ClassificationOverride>>>> | undefined;
     storage: KVStorage;
     /** Internal deployment root, preserved when a personal registry partitions storage. */
     rootStorage?: KVStorage;
@@ -99,6 +100,13 @@ export interface ProgramResultDependency {
     tool?: string;
     classification: "read" | "write";
 }
+/** A cached catalog as discovery may list it. */
+export interface CatalogPeek {
+    tools: ToolDef[];
+    fetchedAt: number;
+    /** Whether the connector's own cache would serve this now, with no failure to report. */
+    fresh: boolean;
+}
 export interface RegistryView {
     credentialUiAvailable(): boolean;
     /** Deployment-wide result-size cap threaded to the meta-tools. */
@@ -114,6 +122,12 @@ export interface RegistryView {
         toolName: string;
     } | null;
     getTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): Promise<ToolDef[]>;
+    /**
+     * The newest complete catalog this caller could be listed, classified and
+     * filtered as a listing is, from storage alone. For discovery; a call never
+     * resolves through it. Undefined for a static catalog or a miss.
+     */
+    peekCatalog(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): Promise<CatalogPeek | undefined>;
     contextFor(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): ConnectorContext;
     /** Acquire the connector's shared downstream-call permit. */
     admitCall(id: string, input: {
@@ -125,8 +139,19 @@ export interface RegistryView {
     resultIdentity(): ResultIdentity;
     /** One validation pass: admit once, then check every dependency under that scope. */
     recheckResultAccess(dependencies: readonly ProgramResultDependency[], classification: "read" | "write", signal?: AbortSignal): Promise<boolean>;
-    /** Reserve deployment-wide capacity before writing a paging envelope's chunks. */
-    stashResult(id: string, chunks: readonly string[], ttlSeconds: number): Promise<boolean>;
+    /**
+     * Reserve deployment-wide capacity before writing a paging envelope's chunks.
+     * `holdFirst` charges the whole envelope but leaves chunk 0, which makes the
+     * result readable, for the caller to write once the result is sealed.
+     */
+    stashResult(id: string, chunks: readonly string[], ttlSeconds: number, options?: {
+        readonly holdFirst?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Give back a stashed result nobody can name any more. Best effort: a failure
+     * leaves it charged until its expiry.
+     */
+    releaseResult(id: string, chunkCount: number): Promise<void>;
     /**
      * Local declared-vs-stored credential mismatch, with no downstream I/O. With
      * `requestScope`, the read joins that request's read memo.
@@ -260,7 +285,11 @@ export declare class Registry implements RegistryView {
      * unconfirmed and retain their charge. Cleanup/release and settlement each
      * stop waiting after 15 seconds. Storage TTL reclaims the rows.
      */
-    stashResult(id: string, chunks: readonly string[], ttlSeconds: number, partition?: string): Promise<boolean>;
+    stashResult(id: string, chunks: readonly string[], ttlSeconds: number, options?: {
+        readonly partition?: string;
+        readonly holdFirst?: boolean;
+    }): Promise<boolean>;
+    releaseResult(id: string, chunkCount: number, partition?: string): Promise<void>;
     /**
      * Storage namespaced to the root result partition, kept separate from any
      * connector's namespace. Backs connecta.result.
@@ -280,6 +309,8 @@ export declare class Registry implements RegistryView {
     /** Compare only the fingerprints accepted in this exact cache partition. */
     private recordCatalogDrift;
     private loadDownstreamTools;
+    /** See {@link RegistryView.peekCatalog}. Same classification and filtering as `loadTools`. */
+    private loadPeek;
     /** The served catalog excludes control-character names; raw caches stay complete. */
     private acceptToolNames;
     /**
@@ -292,6 +323,7 @@ export declare class Registry implements RegistryView {
     /** Construction-only view for the secret-free static config description. */
     describeStaticTools(id: string): ToolDef[] | undefined;
     private validateClassification;
+    peekCatalog(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions, scope?: RegistryScope): Promise<CatalogPeek | undefined>;
     getTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions, scope?: RegistryScope): Promise<ToolDef[]>;
     credentialDriftFor(id: string, requestScope?: object): Promise<string | undefined>;
     /** Age of a complete cache entry; reads never refresh it. */

package/dist/registry.js

@@ -6,21 +6,21 @@ import { authCall, authInvoke } from "./auth/native.js";
 import { Clock, Duration, Effect, Random } from "effect";
 import { activityRequest } from "./activity-request.js";
 import { aggregateCallAdmissionSnapshots, ConnectorCallAdmissionController, } from "./call-admission.js";
-import { attachCatalogCache, catalogExpiry, catalogFetchedAt, customCatalogFallback, invalidateCatalogCache, observeUncachedCatalogRefresh, retainedCatalogIdentity, storeCustomCatalogFallback, } from "./catalog-cache.js";
-import { carryCatalogFreshness, markCatalogFreshness } from "./catalog-freshness.js";
+import { attachCatalogCache, catalogExpiry, catalogFetchedAt, bindCustomCatalogListing, customCatalogFallback, customCatalogPeek, fenceCustomCatalog, invalidateCatalogCache, observeUncachedCatalogRefresh, retainedCatalogIdentity, storeCustomCatalogFallback, } from "./catalog-cache.js";
+import { carryCatalogFreshness, markCatalogFreshness, markCatalogStale } from "./catalog-freshness.js";
 import { MAX_CATALOG_TOOLS, MAX_SERIALIZED_CATALOG_BYTES } from "./catalog-limits.js";
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import { usesCallerIdentity } from "./connector-caller.js";
 import { forwardsPrincipal } from "./request-principal.js";
 import { canonicalJson } from "./canonical-json.js";
 import { storedCredentialShape } from "./credential-rules.js";
-import { ConnectorCallError } from "./errors.js";
+import { ConnectorCallError, isAccessRefusal } from "./errors.js";
 import { attachOAuthPartition, oauthPartitionIdle } from "./oauth-partition.js";
 import { attachOAuthSealer, vaultOAuthSealer } from "./oauth-sealing.js";
 import { boundedStatus, failureRecord, failureStatus, logFailure, ownStatus } from "./operator-record.js";
 import { ObservedOutputSchemas } from "./result-shapes.js";
 import { ContinuationBinding, OperationCredentials, ContinuationStorage, operationView, setViewService, duringViewEffect, } from "./runtime/call.js";
-import { hasNativeStorage, registerNativeStorage } from "./runtime/native-storage.js";
+import { getNativeStorage, hasNativeStorage, registerNativeStorage } from "./runtime/native-storage.js";
 import { observeStorageWrites } from "./runtime/request-reads.js";
 import { attachStorageDigestKey } from "./storage-digest.js";
 import { requestReads } from "./runtime/request-scope.js";
@@ -31,10 +31,10 @@ import { Storage } from "./runtime/services.js";
 import { SharedRead } from "./runtime/shared-read.js";
 import { runOnPartition, storageCompareAndSet, storageDelete, storageGet, storageGetMany, storageSet, storageList, } from "./runtime/storage.js";
 import { redactCatalog, sentSecretsFor, sentSecretsForRequest } from "./sent-secrets.js";
-import { GUIDE_SUMMARY_LENGTH, normalizeGuideSummary } from "./skills.js";
+import { GUIDE_SUMMARY_LENGTH, normalizeGuideSummary, connectorGuide, connectorGuideSummary } from "./skills.js";
 import { jsonCodec, OAUTH_HANDOFF_TTL_SECONDS, oauthHandoffKeys, resultKeys, scopes, stashExpiryKeys, stashLedgerKeys, } from "./storage/keys.js";
 import { assertStaticToolNames, hasControlCharacters } from "./tool-name.js";
-import { carryToolClassification, classifyTool } from "./tool-safety.js";
+import { carryToolClassification, classifyTool, sourceDeclaresWrite, } from "./tool-safety.js";
 import { isWorkspaceAddress } from "./workspace-address.js";
 import { workspaceSubjectOf } from "./workspace-subject.js";
 const ID_RE = /^[a-z0-9_-]+$/;
@@ -145,12 +145,18 @@ const STASH_WRITE_TIMEOUT_MS = 30_000;
 const STASH_COMPLETION_TIMEOUT_MS = 15_000;
 /** Reservation, chunk writes and completion share one finite outer budget. */
 const STASH_TIMEOUT_MS = STASH_WRITE_TIMEOUT_MS + STASH_COMPLETION_TIMEOUT_MS;
+/** Chunks one release deletes at a time; a stash holds at most 32. */
+const STASH_RELEASE_CONCURRENCY = 16;
 /** Stop waiting without starting background storage work after the deadline. */
 function completeStash(effect) {
     return effect.pipe(Effect.asVoid, Effect.timeoutOrElse({ duration: Duration.millis(STASH_COMPLETION_TIMEOUT_MS), orElse: () => Effect.void }), 
     // onError finalizers are otherwise uninterruptible, including their I/O.
     Effect.interruptible);
 }
+/** The reservation id of one result id, which is random and never reused. */
+function stashCharge(id) {
+    return Effect.tryPromise({ try: () => sha256Hex(id), catch: (error) => error });
+}
 /**
  * Live charges in a stored ledger. Anything malformed reads as empty: the
  * ledger bounds an advisory cache, and the next successful swap replaces it.
@@ -298,6 +304,13 @@ export class Registry {
                     `normalization; the discovery bound is ${GUIDE_SUMMARY_LENGTH}. ` +
                     "Shorten it or omit it to derive one.");
             }
+            // Advisory English-language heuristic: a task verb or operation noun
+            // distinguishes actionable guidance from credential/scope facts. Never
+            // log guide text, which may contain deployment-private information.
+            if (connectorGuide(c) !== undefined &&
+                !/\b(load|use|when|read|reads|write|writes|search|query|inspect|resolve|list|review|edit|create|update|deploy|paging|reconciliation|accounting)\b/i.test(connectorGuideSummary(c) ?? "")) {
+                opts.logger.warn(`Connector "${c.id}" guide needs an actionable summary; say when to load it with usageGuide.summary.`);
+            }
             this.connectors.set(c.id, c);
             if (c.callAdmission !== undefined) {
                 this.callAdmission.set(c.id, new ConnectorCallAdmissionController(c.id, c.callAdmission));
@@ -310,8 +323,8 @@ export class Registry {
         Object.freeze(this.classification);
         for (const [id, overrides] of Object.entries(this.classification)) {
             for (const [name, verdict] of Object.entries(overrides)) {
-                if (!name || (verdict !== "read" && verdict !== "write" && verdict !== "hidden")) {
-                    throw new Error(`ConnectaConfig.classification.${id}.${name}: expected "read", "write", or "hidden"`);
+                if (!name || !["read", "read-repeatable", "write", "hidden"].includes(verdict)) {
+                    throw new Error(`ConnectaConfig.classification.${id}.${name}: expected "read", "read-repeatable", "write", or "hidden"`);
                 }
             }
             const connector = this.connectors.get(id);
@@ -610,8 +623,11 @@ export class Registry {
      * unconfirmed and retain their charge. Cleanup/release and settlement each
      * stop waiting after 15 seconds. Storage TTL reclaims the rows.
      */
-    stashResult(id, chunks, ttlSeconds, partition = scopes.results) {
-        return runOnPartition(registryEdgeProgram(Registry.prototype, this, "stashResult", id, chunks, ttlSeconds, partition), this.opts);
+    stashResult(id, chunks, ttlSeconds, options = {}) {
+        return runOnPartition(registryEdgeProgram(Registry.prototype, this, "stashResult", id, chunks, ttlSeconds, options), this.opts);
+    }
+    releaseResult(id, chunkCount, partition = scopes.results) {
+        return runOnPartition(registryEdgeProgram(Registry.prototype, this, "releaseResult", id, chunkCount, partition), this.opts);
     }
     /**
      * Storage namespaced to the root result partition, kept separate from any
@@ -674,7 +690,16 @@ export class Registry {
             if (connector.staticTools)
                 return markCatalogFreshness(connector.staticTools, Infinity);
             const ctx = this.contextFor(id, baseUrl, requestScope, callOptions, scope);
-            const listed = yield* authInvoke(connector, "listTools", [ctx]).pipe(Effect.catch((error) => Effect.gen(function* () {
+            // `remoteMcp()` binds and fences its own attempts, knowing how each was made.
+            const customListing = connector.peekCatalog
+                ? undefined
+                : yield* authCall(bindCustomCatalogListing, [ctx, id]).pipe(Effect.catch((failure) => Effect.sync(() => {
+                    logFailure(this.opts.logger, "catalog read failed", failureRecord({ connector: id }, failure));
+                    return undefined;
+                })));
+            const listed = yield* authInvoke(connector, "listTools", [ctx]).pipe(Effect.catch((error) => Effect.gen({ self: this }, function* () {
+                if (customListing && isAccessRefusal(error))
+                    yield* authCall(fenceCustomCatalog, [ctx, id, customListing]).pipe(Effect.catch((failure) => Effect.sync(() => logFailure(this.opts.logger, "catalog fence failed", failureRecord({ connector: id }, failure)))));
                 const fallback = error instanceof ConnectorCallError && error.code === "unavailable"
                     ? yield* authCall(customCatalogFallback, [ctx, id]).pipe(Effect.catch(() => Effect.succeed(undefined)))
                     : undefined;
@@ -690,12 +715,18 @@ export class Registry {
             const facts = frozenFacts(structuredClone(tools));
             const accepted = this.acceptToolNames(facts);
             if (catalogFetchedAt(ctx) === undefined) {
-                for (const observe of [storeCustomCatalogFallback, observeUncachedCatalogRefresh]) {
-                    yield* authCall(observe, [ctx, id, facts]).pipe(Effect.catch((error) => Effect.sync(() => logFailure(this.opts.logger, "catalog refresh observation failed", failureRecord({ connector: id }, error)))));
+                for (const observe of [
+                    authCall(storeCustomCatalogFallback, [ctx, facts, customListing]),
+                    authCall(observeUncachedCatalogRefresh, [ctx, id, facts]),
+                ]) {
+                    yield* observe.pipe(Effect.catch((error) => Effect.sync(() => logFailure(this.opts.logger, "catalog refresh observation failed", failureRecord({ connector: id }, error)))));
                 }
             }
             const provenance = catalogExpiry(ctx);
             const freshUntil = provenance && !provenance.staleFallback ? provenance.expiresAt : 0;
+            // A transient-failure fallback answers the listing; discovery still reports its age.
+            if (provenance?.staleFallback)
+                markCatalogStale(accepted, { code: "unavailable", ageMs: Math.max(0, Date.now() - provenance.fetchedAt) });
             // Principal-forwarded listings belong to one caller, never to the shared
             // operator observation store. The actual catalog cache is identity-bound.
             if (!forwardsPrincipal(connector)) {
@@ -708,6 +739,30 @@ export class Registry {
             return markCatalogFreshness(accepted, freshUntil);
         });
     }
+    /** See {@link RegistryView.peekCatalog}. Same classification and filtering as `loadTools`. */
+    loadPeek(id, baseUrl, requestScope, callOptions = {}, scope) {
+        return Effect.gen({ self: this }, function* () {
+            const connector = this.connectors.get(id);
+            if (!connector || connector.staticTools)
+                return undefined;
+            const ctx = this.contextFor(id, baseUrl, requestScope, callOptions, scope);
+            const peek = connector.peekCatalog
+                ? yield* authInvoke(connector, "peekCatalog", [ctx])
+                : yield* authCall(customCatalogPeek, [ctx, id]);
+            if (!peek)
+                return undefined;
+            const facts = redactCatalog(ctx, peek.tools).map(({ classification: _ignored, ...fact }) => fact);
+            const overrides = this.classification[id];
+            return {
+                tools: this.acceptToolNames(frozenFacts(structuredClone(facts)))
+                    .filter((tool) => overrides?.[tool.name] !== "hidden")
+                    .map((tool) => this.publishTool(id, tool)),
+                fetchedAt: peek.fetchedAt,
+                // A custom catalog is always listed anew, so its retained copy is never current.
+                fresh: connector.peekCatalog !== undefined && peek.expiresAt > Date.now(),
+            };
+        });
+    }
     /** The served catalog excludes control-character names; raw caches stay complete. */
     acceptToolNames(tools) {
         const accepted = tools.filter((tool) => !hasControlCharacters(tool.name));
@@ -734,19 +789,20 @@ export class Registry {
     }
     publishTool(id, tool) {
         const override = this.classification[id]?.[tool.name];
+        const classification = classifyTool(tool, override === "hidden" ? undefined : override);
         return carryToolClassification(tool, {
             ...structuredClone(tool),
-            classification: classifyTool(tool, override === "hidden" ? undefined : override),
+            classification,
             ...(override !== undefined
                 ? {
                     annotations: {
                         ...structuredClone(tool.annotations),
-                        readOnlyHint: override === "read",
-                        destructiveHint: override === "write",
+                        readOnlyHint: override !== "hidden" && classification === "read",
+                        destructiveHint: override !== "hidden" && classification === "write",
                     },
                 }
                 : {}),
-        });
+        }, override === "read-repeatable" || undefined);
     }
     /** Construction-only view for the secret-free static config description. */
     describeStaticTools(id) {
@@ -764,19 +820,30 @@ export class Registry {
                 return;
             this.overrideWarningCatalogs.set(partition, catalog);
         }
-        const known = new Set(tools.map((tool) => tool.name));
-        for (const name of Object.keys(overrides ?? {})) {
-            if (known.has(name))
-                continue;
-            if (this.connectors.get(id)?.staticTools) {
+        const known = new Map(tools.map((tool) => [tool.name, tool]));
+        const staticCatalog = this.connectors.get(id)?.staticTools !== undefined;
+        for (const [name, override] of Object.entries(overrides ?? {})) {
+            const tool = known.get(name);
+            if (!tool && staticCatalog) {
                 throw new Error(`ConnectaConfig.classification: connector "${id}" has no tool "${name}"`);
             }
             // Only deployment-authored names, never downstream text. JSON quoting
             // prevents control characters from forging operator log lines.
             const quoted = JSON.stringify(`${id}.${name}`).replace(/[\u2028\u2029]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16)}`);
+            if (tool) {
+                // A static catalog cannot change, so the deployment's construction reports it once.
+                const reports = staticCatalog ? partition === undefined && this.opts.constructionChecks !== false : true;
+                if (override === "read" && reports && sourceDeclaresWrite(tool)) {
+                    this.opts.logger.warn(`classification override ${quoted} to "read" is not applied because the connector declares this tool a write; it stays a write. "read-repeatable" serves it as a read and accepts that hosts may repeat it`);
+                }
+                continue;
+            }
             this.opts.logger.warn(`classification override ${quoted} is dormant because the runtime catalog lists no such tool`);
         }
     }
+    peekCatalog(id, baseUrl, requestScope, callOptions = {}, scope) {
+        return runEdge(registryEdgeProgram(Registry.prototype, this, "peekCatalog", id, baseUrl, requestScope, callOptions, scope));
+    }
     getTools(id, baseUrl, requestScope, callOptions = {}, scope) {
         return runEdge(registryEdgeProgram(Registry.prototype, this, "getTools", id, baseUrl, requestScope, callOptions, scope));
     }
@@ -811,7 +878,8 @@ export class Registry {
     }
     static {
         provideRegistryPrograms(Registry.prototype, {
-            stashResult: (self, id, chunks, ttlSeconds, partition = scopes.results) => Effect.gen({ self }, function* () {
+            stashResult: (self, id, chunks, ttlSeconds, options = {}) => Effect.gen({ self }, function* () {
+                const partition = options.partition ?? scopes.results;
                 const maxBytes = this.opts.results?.maxStashBytes ?? CONFIG_DEFAULTS.results.maxStashBytes;
                 const maxEntries = this.opts.results?.maxStashEntries ?? CONFIG_DEFAULTS.results.maxStashEntries;
                 // The paging envelope is ASCII, so its string length is its stored byte count.
@@ -819,8 +887,9 @@ export class Registry {
                 if (bytes > maxBytes || maxEntries === 0)
                     return false;
                 const keys = chunks.map((_, index) => partition + resultKeys.chunk(id, index));
-                // IDs belong to reservations, not reusable result IDs or subjects.
-                const charge = crypto.randomUUID();
+                // A digest finds this reservation again on release without putting
+                // the result's ID in the deployment-wide ledger.
+                const charge = yield* stashCharge(id);
                 const ttlMs = ttlSeconds * 1000;
                 if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0)
                     return false;
@@ -874,16 +943,22 @@ export class Registry {
                 // ID after failure or timeout, including a late header commit.
                 const remaining = Math.max(0, writeDeadline - (yield* Clock.currentTimeMillis));
                 const written = yield* Effect.gen(function* () {
-                    for (let index = keys.length - 1; index >= 0; index--) {
+                    const multi = getNativeStorage(self.opts.storage)?.setMany;
+                    const lowest = options.holdFirst ? 1 : 0;
+                    for (let index = keys.length - 1; index >= lowest;) {
+                        const first = multi && index > 0 ? Math.max(1, index - 63) : index;
                         const before = yield* Clock.currentTimeMillis;
                         if (before >= writeDeadline || before >= chunkExpiry)
                             return false;
                         pendingWrite = true;
-                        yield* storageSet(keys[index], chunks[index], { expiresAtMs: chunkExpiry }).pipe(Effect.tap(() => Effect.sync(() => {
+                        yield* (multi && index > 0
+                            ? multi(Array.from({ length: index - first + 1 }, (_, offset) => [keys[index - offset], chunks[index - offset]]), { expiresAtMs: chunkExpiry })
+                            : storageSet(keys[index], chunks[index], { expiresAtMs: chunkExpiry })).pipe(Effect.tap(() => Effect.sync(() => {
                             pendingWrite = false;
                         })));
                         if ((yield* Clock.currentTimeMillis) >= writeDeadline)
                             return false;
+                        index = first - 1;
                     }
                     return true;
                 }).pipe(Effect.timeoutOrElse({ duration: Duration.millis(remaining), orElse: () => Effect.succeed(false) }), Effect.onError(() => release.pipe(Effect.ignore)));
@@ -893,6 +968,15 @@ export class Registry {
                     yield* completeStash(settle);
                 return written;
             }).pipe(Effect.timeoutOrElse({ duration: Duration.millis(STASH_TIMEOUT_MS), orElse: () => Effect.succeed(false) }), Effect.provideService(Storage, self.opts.storage)),
+            releaseResult: (self, id, chunkCount, partition = scopes.results) => completeStash(Effect.gen(function* () {
+                const charge = yield* stashCharge(id);
+                // Bytes first: a failed delete keeps its charge, so the ledger never
+                // undercounts what storage holds.
+                yield* Effect.forEach(Array.from({ length: chunkCount }, (_, index) => partition + resultKeys.chunk(id, index)), (key) => storageDelete(key), { concurrency: STASH_RELEASE_CONCURRENCY, discard: true });
+                yield* swapStashLedger((live) => live.some((entry) => entry[0] === charge)
+                    ? { entries: live.filter((entry) => entry[0] !== charge), result: undefined }
+                    : { result: undefined });
+            })).pipe(Effect.ignore, Effect.provideService(Storage, self.opts.storage)),
             recheckResultAccess: () => Effect.succeed(true),
             storeOAuthHandoff: (self, connectorId, state, principalKey) => Effect.gen(function* () {
                 const key = oauthHandoffKeys.handoff(connectorId, yield* Effect.tryPromise({ try: () => sha256Hex(state), catch: (error) => error }));
@@ -961,6 +1045,12 @@ export class Registry {
                     return yield* load.join(signal);
                 }));
             }),
+            peekCatalog: (self, id, baseUrl, requestScope, callOptions = {}, scope) => Effect.suspend(() => {
+                if (!self.connectors.has(id))
+                    return Effect.succeed(undefined);
+                const owner = self.contextFor(id, baseUrl, requestScope, callOptions, scope);
+                return duringViewEffect(owner, (signal) => self.loadPeek(id, baseUrl, owner.requestScope, { ...callOptions, signal }, scope));
+            }),
             credentialDriftFor: (self, id, requestScope) => Effect.gen(function* () {
                 const credential = self.connectors.get(id)?.credential;
                 const vault = self.opts.credentialVault;
@@ -1085,6 +1175,9 @@ class ScopedRegistryView {
     getTools(...args) {
         return runEdge(registryEdgeProgram(ScopedRegistryView.prototype, this, "getTools", ...args));
     }
+    peekCatalog(...args) {
+        return runEdge(registryEdgeProgram(ScopedRegistryView.prototype, this, "peekCatalog", ...args));
+    }
     contextFor(...args) {
         const registry = this.registryFor(args[0]);
         if (!registry)
@@ -1098,8 +1191,14 @@ class ScopedRegistryView {
         }
         return registry.admitCall(...args);
     }
-    stashResult(id, chunks, ttlSeconds) {
-        return this.root.stashResult(id, chunks, ttlSeconds, this.scope.subjectKey ? scopes.subject(this.scope.subjectKey) : scopes.results);
+    stashResult(id, chunks, ttlSeconds, options = {}) {
+        return this.root.stashResult(id, chunks, ttlSeconds, {
+            ...options,
+            partition: this.scope.subjectKey ? scopes.subject(this.scope.subjectKey) : scopes.results,
+        });
+    }
+    releaseResult(id, chunkCount) {
+        return this.root.releaseResult(id, chunkCount, this.scope.subjectKey ? scopes.subject(this.scope.subjectKey) : scopes.results);
     }
     resultIdentity() {
         return {
@@ -1146,7 +1245,11 @@ class ScopedRegistryView {
     }
     static {
         provideRegistryPrograms(ScopedRegistryView.prototype, {
-            stashResult: (self, id, chunks, ttlSeconds) => registryProgram(self.root, "stashResult", id, chunks, ttlSeconds, self.scope.subjectKey ? scopes.subject(self.scope.subjectKey) : scopes.results),
+            releaseResult: (self, id, chunkCount) => registryProgram(self.root, "releaseResult", id, chunkCount, self.scope.subjectKey ? scopes.subject(self.scope.subjectKey) : scopes.results),
+            stashResult: (self, id, chunks, ttlSeconds, options = {}) => registryProgram(self.root, "stashResult", id, chunks, ttlSeconds, {
+                ...options,
+                partition: self.scope.subjectKey ? scopes.subject(self.scope.subjectKey) : scopes.results,
+            }),
             recheckResultAccess: (self, dependencies, classification, signal) => Effect.tryPromise({
                 try: () => self.scope.currentResultAccess?.(dependencies, classification, signal) ?? Promise.resolve(true),
                 catch: (error) => error,
@@ -1173,6 +1276,15 @@ class ScopedRegistryView {
                 }
                 return carryCatalogFreshness(tools, visible);
             }),
+            peekCatalog: (self, ...args) => Effect.gen(function* () {
+                const registry = self.registryFor(args[0]);
+                if (!registry)
+                    return undefined;
+                const peek = yield* registryProgram(registry, "peekCatalog", args[0], args[1], args[2], args[3], self.scope);
+                const granted = self.scope.toolAccess?.get(args[0]);
+                // A pool grant binds a stale listing exactly as it binds a live one.
+                return peek && granted ? { ...peek, tools: peek.tools.filter((tool) => granted.has(tool.name)) } : peek;
+            }),
             credentialDriftFor: (self, id, requestScope) => Effect.suspend(() => {
                 const registry = self.registryFor(id);
                 return registry

package/dist/resource-read.js

@@ -1,8 +1,10 @@
+import { utilityRecovery } from "./utility-recovery.js";
 import { Effect } from "effect";
 import { classifyCallError, ConnectorCallError } from "./errors.js";
 import { InvocationFailure, timed } from "./invocation.js";
 import { withDeadlineEffect } from "./runtime/run.js";
 import { sentSecretsFor } from "./sent-secrets.js";
+import { downstreamOrigin, isSkillResource } from "./skill-origin.js";
 import { hasControlCharacters } from "./tool-name.js";
 const encoder = new TextEncoder();
 const URI_HINT = "Use resource://<connectorId>/<encodeURIComponent(downstreamUri)> with a whole-connector grant.";
@@ -26,13 +28,26 @@ function resourceTarget(registry, raw) {
     const connector = registry.getResourceConnector(match[1]);
     if (!connector?.readResource) {
         throw new InvocationFailure({
-            code: "unknown_address",
+            ...utilityRecovery(connector ? "unsupported_capability" : "unknown_address", "No resource reader is available."),
+            code: connector ? "unsupported_capability" : "unknown_address",
             message: `No resource reader is available for this address. ${URI_HINT}`,
             retryable: false,
         });
     }
     return { connector, uri };
 }
+/** Frame skill text for a program; native resources/read keeps exact bytes and never comes here. */
+function labelSkillText(contents, connectorId, uri) {
+    const items = contents?.contents;
+    if (!Array.isArray(items))
+        return contents;
+    return {
+        ...contents,
+        contents: items.map((item) => typeof item?.text === "string" && (isSkillResource(uri) || isSkillResource(String(item.uri ?? "")))
+            ? { ...item, text: `${downstreamOrigin(connectorId)}\n\n${item.text}` }
+            : item),
+    };
+}
 /** A protocol read, under the same request scope, call permit and deadline as tools. */
 export function readResource(registry, raw, options) {
     let connector;
@@ -68,7 +83,7 @@ export function readResource(registry, raw, options) {
             },
             catch: (error) => error,
         }));
-        return options.sentSecrets.redact(contents);
+        return labelSkillText(options.sentSecrets.redact(contents), target.connector.id, target.uri);
     })), {
         timeoutMs: options.timeoutMs,
         ...(options.signal ? { signal: options.signal } : {}),
@@ -98,6 +113,10 @@ export function readResource(registry, raw, options) {
                 retry: "Retry connecta.read with the same resource URI after the operator completes recovery.",
             };
         }
+        if (["unavailable", "unsupported_capability", "input_required_unsupported"].includes(details.code) &&
+            !details.nextAction) {
+            details = { ...details, nextAction: utilityRecovery(details.code, details.message).nextAction };
+        }
         return Effect.fail(new InvocationFailure(options.sentSecrets.redact(details)));
     }));
 }