@zackbart/connecta 0.37.1 → 0.39.0

package/dist/http/hatch.js

@@ -8,6 +8,7 @@
 // entries (8 at most, 16 KiB of JSON at most, with an explicit continuation
 // cursor) and details return at most 32 KiB, cutting only optional parts and
 // listing them in `truncated`; a required parameter or body field is never cut.
+import { Routes } from "../agent-routes.js";
 import { Effect, Schema } from "effect";
 import { lexicalSearchContent } from "../catalog.js";
 import { registerOperationVocabulary } from "../operation-vocabulary.js";
@@ -18,7 +19,8 @@ import { providerFailureMessage } from "../write-outcome.js";
 import { redactionAltered } from "../redaction-marker.js";
 import { refuseWithheldValues } from "../providers/_shared/rest/value-safety.js";
 import { Refusal, toConnectorCallError } from "./errors.js";
-import { fieldsInput, fieldsProblem, selectFields } from "./fields.js";
+import { boundWarnings, fieldsDescription, fieldsInput, fieldsMisses, fieldsProblem, selectFields } from "./fields.js";
+import { RESPONSE_BUDGET, responseContract } from "./hatch-response.js";
 import { Integer, isMaxChars, isMinChars } from "./json-schema.js";
 import { boundCursor, StandardPage } from "./paging.js";
 import { Classification, Dispatches, IdempotencyKey, RequestSecrets, Signal } from "./services.js";
@@ -48,7 +50,6 @@ const Envelope = Schema.Struct({
     status: Integer.annotate({ description: "HTTP status." }),
     data: Schema.Unknown.pipe(Schema.annotateKey({ description: "Response body after value safety and the connection's privacy filtering." })),
 });
-const HATCH_FIELDS = fieldsInput("Dot paths to keep in data, applied to each item of an array, after value safety and privacy filtering.");
 function invalid(message) {
     throw new ConnectorCallError("invalid_args", message);
 }
@@ -88,7 +89,7 @@ function parameters(values) {
             if (typeof item !== "string" &&
                 typeof item !== "boolean" &&
                 !(typeof item === "number" && Number.isFinite(item))) {
-                invalid(`Parameter ${name} takes a string, finite number, boolean, or a list of them.`);
+                invalid("Each query parameter takes a string, finite number, boolean, or a list of them.");
             }
             return [name, String(item)];
         });
@@ -160,9 +161,6 @@ export function hatch(options) {
         ];
     }));
     const Headers = Object.keys(headerFields).length ? Schema.Struct(headerFields) : undefined;
-    const Fields = options.fieldsRoot
-        ? fieldsInput(`Dot paths to keep in data. Envelope fields begin with ${options.fieldsRoot}, e.g. ["${options.fieldsRoot}.id"] or ["${options.fieldsRoot}[].id"], where declared.`)
-        : HATCH_FIELDS;
     const Body = options.textBodies
         ? Schema.Union([ObjectValue, Schema.Array(Schema.Unknown), Schema.String])
         : undefined;
@@ -191,6 +189,22 @@ export function hatch(options) {
         if (!known(key) || !tool.trim())
             throw new Error(`Hatch named tool for ${key} needs an indexed operation.`);
     }
+    // Paths start at the vendor body. The example is a root some operation the
+    // tool calls declares: the envelope root, else `id`, else the first declared.
+    const fieldsFor = (writes) => {
+        const preferred = options.fieldsRoot ?? "id";
+        let first;
+        for (const [key, verdict] of verdicts) {
+            if (verdict === "refuse" || (verdict === "read") === writes)
+                continue;
+            const roots = index.responseRoots(operations.get(key));
+            if (roots?.has(preferred))
+                return fieldsInput(fieldsNote(preferred));
+            first ??= roots && [...roots][0];
+        }
+        return fieldsInput(fieldsNote(first ?? preferred));
+    };
+    const fieldsNote = (example) => fieldsDescription("data", example, `Copy declared paths from ${name}_api_details response.fields. Applied after value safety and privacy filtering.`);
     const verdictOf = (op) => verdicts.get(`${op.method} ${op.path}`) ?? "refuse";
     const refusalOf = (op) => connection.safety.refusal?.({ method: op.method, template: op.path }) ?? options.binding?.refusal?.(op);
     const discoveryRefusals = new Map();
@@ -244,13 +258,9 @@ export function hatch(options) {
                 truncated: Schema.optionalKey(Schema.Array(Schema.String).annotate({ description: "Dot paths cut for size, including the data prefix." })),
             }
             : {}),
-        ...(options.binding?.warnings
-            ? {
-                warnings: Schema.optionalKey(Schema.Array(Schema.String).annotate({
-                    description: "Reviewed warnings preserved after fields selection.",
-                })),
-            }
-            : {}),
+        warnings: Schema.optionalKey(Schema.Array(Schema.String).annotate({
+            description: `${options.binding?.warnings ? "Reviewed warnings preserved after fields selection, and " : ""}fields entries that matched nothing in this nonempty response, with the properties declared where matching stopped. At most 10 warnings of 512 characters, then an omitted count.`,
+        })),
     });
     const hasTotals = [...pages.values()].some((adapters) => adapters.some((adapter) => adapter.total !== undefined));
     const envelope = pages.size
@@ -637,6 +647,29 @@ export function hatch(options) {
     }));
     const searchTool = tool("search");
     const detailsTool = tool("details");
+    // The response contract is fixed for a connection, so each operation's is built once.
+    const responses = new Map();
+    const responseOf = (op) => {
+        if (!responses.has(op.row))
+            responses.set(op.row, responseContract(index, op, connection.safety));
+        return responses.get(op.row);
+    };
+    const Response = Schema.optionalKey(Schema.Struct({
+        anchor: Schema.Literals(["data", "data[]"]).annotate({
+            description: "Paths start at the read result's data; data[] means each item of a list body.",
+        }),
+        fields: Schema.Array(Schema.String).annotate({
+            description: "Selectable declared success-response paths, valid as fields inputs unchanged. Not a readability promise: value safety may still withhold or redact any value at read time.",
+        }),
+        withheld: Schema.optionalKey(Schema.Array(Schema.String).annotate({
+            description: "Best-effort hint: listed paths value safety always withholds or redacts. An unlisted path may still be withheld or redacted.",
+        })),
+        omitted: Schema.optionalKey(Integer.annotate({
+            description: `Declared paths not listed: deeper ones past ${RESPONSE_BUDGET.paths} paths or ${RESPONSE_BUDGET.chars} chars, or over ${RESPONSE_BUDGET.pathChars} chars.`,
+        })),
+    }).annotate({
+        description: "Where declared response values are, not whether they are readable. Absent when the operation declares no response properties or is refused.",
+    }));
     const tools = [
         read(connection, {
             name: searchTool,
@@ -756,7 +789,7 @@ export function hatch(options) {
         }),
         read(connection, {
             name: detailsTool,
-            description: `Read one ${title} API operation's request contract and refusal, including methods outside the call schemas. Reads no account data.`,
+            description: `Read one ${title} API operation's request contract, response fields and refusal, including methods outside the call schemas. Reads no account data.`,
             input: Schema.Struct({
                 method: Method.annotate({ description: "The operation's HTTP method." }),
                 path: Path.annotate({ description: "The path template from search, or a concrete path." }),
@@ -776,6 +809,7 @@ export function hatch(options) {
                 body: Schema.optionalKey(ObjectValue.annotate({
                     description: "Body content type and schema. When paged: this page's properties, the required names it delivers or chunks, and the schema's other keywords on the page that carries them.",
                 })),
+                response: Response,
                 verdict: Schema.Literals(["read", "write", "destructive", "refuse"]),
                 ...Routing,
                 revision: Schema.String,
@@ -798,8 +832,12 @@ export function hatch(options) {
                     const refusal = discoveryRefusal(op);
                     return { op, contract: { ...index.contract(op, args.param), ...(refusal ? { refusal } : {}) } };
                 });
-                const tail = { verdict: discoveryVerdictOf(op), ...route(op), revision: index.revision };
-                const whole = { ...contract, ...tail };
+                const verdict = discoveryVerdictOf(op);
+                const tail = { verdict, ...route(op), revision: index.revision };
+                // The first page of a whole-operation answer carries the response contract; param pages do not.
+                const response = args.param === undefined && args.cursor === undefined && verdict !== "refuse" ? responseOf(op) : undefined;
+                const head = response ? { response } : {};
+                const whole = { ...contract, ...head, ...tail };
                 if (args.cursor === undefined && bytes(whole) <= DETAILS_BUDGET_BYTES)
                     return whole;
                 // Bounded pages: every parameter and body property arrives whole on some page, and a
@@ -874,6 +912,7 @@ export function hatch(options) {
                                 },
                             },
                         }),
+                    ...head,
                     ...tail,
                     ...(chunk ? { chunk } : {}),
                     ...(truncated.length ? { truncated } : {}),
@@ -1105,7 +1144,7 @@ export function hatch(options) {
                 const roots = index.responseRoots(op);
                 if (!roots)
                     invalid(`${method} ${op.path} declares no response properties, so fields cannot narrow it.`);
-                const problem = fieldsProblem(args.fields, roots, "data");
+                const problem = fieldsProblem(args.fields, roots, "data", `Examples are withheld for API operations; read ${tool("details")} for the contract.`);
                 if (problem) {
                     if (options.fieldsRoot && roots.has(options.fieldsRoot))
                         invalid(`${problem.message} Use fields:["${options.fieldsRoot}.id"] or fields:["${options.fieldsRoot}[].id"] for declared record or list fields.`);
@@ -1141,6 +1180,7 @@ export function hatch(options) {
                 dispatches,
                 withholds: connection.safety.withholdsErrors,
                 signal: yield* Signal,
+                routes: yield* Routes,
             });
             const diagnostic = providerFailureMessage(error, `${error.message} ${idempotency.header}: ${key}.`);
             return yield* Effect.fail(new Refusal({
@@ -1177,16 +1217,24 @@ export function hatch(options) {
                 in: adapter.in,
             };
         }
+        const answered = answer.data === undefined ? null : answer.data;
+        // Roots were checked before dispatch; the pinned index cannot say whether a
+        // deeper level is closed, so a nested miss is reported, never refused.
+        const warnings = boundWarnings([
+            ...(options.binding?.warnings && "warnings" in answer ? (answer.warnings ?? []) : []),
+            ...fieldsMisses(answered, args.fields, index
+                .fields(op)
+                .filter((field) => field.in === "response")
+                .map((field) => field.path)),
+        ]);
         return {
             status: answer.status,
-            data: selectFields(answer.data === undefined ? null : answer.data, args.fields),
+            data: selectFields(answered, args.fields),
             ...(page ? { page } : {}),
             ...(options.binding?.truncated && "truncated" in answer && answer.truncated?.length
                 ? { truncated: answer.truncated }
                 : {}),
-            ...(options.binding?.warnings && "warnings" in answer && answer.warnings?.length
-                ? { warnings: answer.warnings }
-                : {}),
+            ...(warnings.length ? { warnings } : {}),
             ...(key ? { idempotencyKey: key } : {}),
         };
     });
@@ -1208,7 +1256,7 @@ export function hatch(options) {
     if (nonGetReads.length)
         readFields["body"] = Schema.optionalKey((Body ?? ObjectValue).annotate({ description: "Body for a reviewed read-only POST." }));
     readFields["query"] = Schema.optionalKey(Query);
-    readFields["fields"] = Schema.optionalKey(Fields);
+    readFields["fields"] = Schema.optionalKey(fieldsFor(false));
     if (Headers)
         readFields["headers"] = Schema.optionalKey(Headers);
     if (options.pageCursor === "argument")
@@ -1235,7 +1283,7 @@ export function hatch(options) {
             body: Schema.optionalKey((Body ?? Schema.Union([ObjectValue, Schema.Array(Schema.Unknown)])).annotate({
                 description: "Request body as JSON fields, named as details lists them; form operations are encoded for you.",
             })),
-            fields: Schema.optionalKey(Fields),
+            fields: Schema.optionalKey(fieldsFor(true)),
         };
         if (Headers)
             writeFields["headers"] = Schema.optionalKey(Headers);
@@ -1265,6 +1313,22 @@ export function hatch(options) {
             run: (args) => run("write", args),
         }));
     }
+    // A read search may hand back as a ready call: GET by default, no path
+    // template, no required parameter or body, and served by the read tool
+    // itself rather than a named tool. Anything an agent must choose or fill in
+    // stays behind search and details.
+    const readTool = tool("read");
+    const ready = (op) => {
+        if (op.method !== "GET" || defaultRead !== "GET" || op.path.includes("{"))
+            return undefined;
+        const routed = route(op);
+        if (routed.tool !== readTool || routed.named)
+            return undefined;
+        const contract = index.contract(op);
+        return contract.parameters.some((param) => param.required) || contract.body?.required
+            ? undefined
+            : { path: op.path, summary: op.summary.slice(0, SEARCH_BUDGET.summaryChars), operationId: op.operationId };
+    };
     registerOperationVocabulary(tools[0], function* () {
         for (const op of index.ops) {
             const verdict = discoveryVerdictOf(op);
@@ -1272,6 +1336,7 @@ export function hatch(options) {
                 text: `${op.path.slice(0, 384)} ${op.operationId.slice(0, 128)} ${op.summary.slice(0, 384)} ${op.tag.slice(0, 128)}`,
                 route: verdict === "refuse" ? searchTool : route(op).tool,
                 write: verdict !== "read",
+                ready: verdict === "read" ? ready(op) : undefined,
             };
         }
     });

package/dist/http/json-schema.js

@@ -1,4 +1,4 @@
-// Provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+// Provider kit. Unreachable from src/index.ts.
 //
 // One Schema is a tool's type, its argument decoder, and its catalog JSON
 // Schema. Effect's generator is correct but spells some things differently

package/dist/http/node-transport.js

@@ -238,4 +238,3 @@ export function createNodeGuardedTransport(proxy) {
         },
     };
 }
-export const nodeGuardedTransport = createNodeGuardedTransport();

package/dist/http/oauth.js

@@ -1,4 +1,4 @@
-// Refresh-once middleware (decision 0010, B.2). Unreachable from src/index.ts.
+// Refresh-once middleware. Unreachable from src/index.ts.
 //
 // Refresh-once for a connection that authenticates with a token it can
 // renew: a downstream OAuth grant, a service-account assertion, a machine
@@ -23,6 +23,7 @@
 //
 // The grant itself (storage, coordination across isolates, the token
 // request, the request-scope latch) stays in src/auth/.
+import { Routes } from "../agent-routes.js";
 import { Cause, Context, Effect, Option } from "effect";
 import * as HttpClient from "effect/http/HttpClient";
 import * as HttpClientResponse from "effect/http/HttpClientResponse";
@@ -70,7 +71,7 @@ export function refreshOnce(guarded, options) {
         const error = new ConnectorCallError("connector_call_failed", "The OAuth challenge exceeded its response ceiling.", { retryable: false });
         const refusal = new Refusal({
             error: !readRequest(entry ?? {}) && options?.writeUnauthorized
-                ? options.writeUnauthorized({ _tag: "Failed", failure: error })
+                ? options.writeUnauthorized({ _tag: "Failed", failure: error }, yield* Routes)
                 : error,
         });
         const dispatch = entry ? (yield* Dispatches).find((item) => item.request === entry) : undefined;
@@ -125,7 +126,7 @@ export function refreshOnce(guarded, options) {
                     };
                 // This is still the resource request's own 401. The common failure
                 // mapper attaches its provenance; settleWrite decides the outcome.
-                return yield* Effect.fail(new Refusal({ error: options.writeUnauthorized(facts) }));
+                return yield* Effect.fail(new Refusal({ error: options.writeUnauthorized(facts, yield* Routes) }));
             }
             return HttpClientResponse.fromWeb(request, new Response(reply.text ?? "", { status: reply.status, headers: reply.headers }));
         }

package/dist/http/paging.js

@@ -1,4 +1,5 @@
-// Provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+import { bytesToHex, decodeBase64url } from "../bytes.js";
+// Provider kit. Unreachable from src/index.ts.
 //
 // List tools take one page at a time. Lookahead detects an extra row; bound
 // cursors authenticate the tool, arguments, connection and credential owner.
@@ -52,7 +53,7 @@ async function signingKey(storage) {
         return cached;
     let raw = await storage.get(continuationKeys.signingKey);
     if (raw === null) {
-        const candidate = Array.from(crypto.getRandomValues(new Uint8Array(32)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+        const candidate = bytesToHex(crypto.getRandomValues(new Uint8Array(32)));
         raw = (await storage.compareAndSet(continuationKeys.signingKey, null, candidate))
             ? candidate
             : await storage.get(continuationKeys.signingKey);
@@ -92,7 +93,7 @@ export const boundCursor = {
             const expected = yield* digest(tool, args);
             let parsed;
             try {
-                parsed = JSON.parse(new TextDecoder().decode(fromBase64url(token)));
+                parsed = JSON.parse(new TextDecoder().decode(decodeBase64url(token)));
             }
             catch {
                 parsed = undefined;
@@ -108,7 +109,7 @@ export const boundCursor = {
             if (token !== base64url(JSON.stringify({ v: record.v, d: record.d, c: record.c, m: record.m })))
                 return yield* Effect.fail(new Refusal({ error: new ConnectorCallError("invalid_args", STRAY_CURSOR) }));
             const key = yield* keyForCall;
-            const mac = fromBase64url(record.m);
+            const mac = decodeBase64url(record.m);
             const binding = yield* ContinuationBinding;
             const claims = new TextEncoder().encode(canonicalJson([record.v, binding.connection, binding.principal, record.d, record.c]));
             const valid = yield* Effect.promise(() => crypto.subtle.verify("HMAC", key, mac, claims));
@@ -125,7 +126,7 @@ function digest(tool, args) {
         .sort()
         .map((key) => [key, args[key]]);
     const bytes = new TextEncoder().encode(canonicalJson([tool, shape]));
-    return Effect.promise(() => crypto.subtle.digest("SHA-256", bytes)).pipe(Effect.map((hash) => Array.from(new Uint8Array(hash).slice(0, 16), (byte) => byte.toString(16).padStart(2, "0")).join("")));
+    return Effect.promise(() => crypto.subtle.digest("SHA-256", bytes)).pipe(Effect.map((hash) => bytesToHex(new Uint8Array(hash).slice(0, 16))));
 }
 function base64url(text) {
     return base64urlBytes(new TextEncoder().encode(text));
@@ -136,7 +137,3 @@ function base64urlBytes(bytes) {
         binary += String.fromCharCode(byte);
     return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
-function fromBase64url(token) {
-    const binary = atob(token.replace(/-/g, "+").replace(/_/g, "/"));
-    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
-}

package/dist/http/provider.js

@@ -1,4 +1,6 @@
-// Internal provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+// Internal provider kit. Unreachable from src/index.ts.
+import { routePhrases, routesOf } from "../agent-routes.js";
+import { credentialFailureClass } from "../credential-verification.js";
 import { Context, Effect, Option } from "effect";
 import { api } from "../connectors/api.js";
 import { OAUTH_CHALLENGE_MAX_BYTES } from "../auth/renewable-grant.js";
@@ -12,6 +14,7 @@ import { guardedClient } from "./client.js";
 import { errorMeanings, Refusal, toConnectorCallError, withheldDefect, } from "./errors.js";
 import { hatch } from "./hatch.js";
 import { takesIdempotencyKey } from "./tools.js";
+import { registerSearchSynonyms } from "../operation-vocabulary.js";
 import { Grant, grantFromOAuth, refreshOnce } from "./oauth.js";
 import { resultSafety } from "./safety.js";
 import { Classification, Dispatches, Signal, WriteCapacity, fromConnectorContext, } from "./services.js";
@@ -43,7 +46,19 @@ const missingGrant = {
 };
 /** An ordinary Promise connector factory; Effect remains inside the kit. */
 export function defineApiProvider(definition) {
-    const { displayTitle, description, authScope, vendor, baseUrl, maxResponseBytes, timeoutMs, headers, admit, transport, defaultCallAdmission, pageSize: declaredPageSize, idempotencyKey, credential, oauth, oauthWrite401, grant, grantRenewal, authenticate, errors, safety, result, inBandRefusals, probe, guide, transformGuide, hatch: declaredHatch, tools, tagConnector, ...metadata } = definition;
+    const { displayTitle, description, authScope, vendor, baseUrl, maxResponseBytes, timeoutMs, headers, admit, transport, defaultCallAdmission, pageSize: declaredPageSize, idempotencyKey, credential, oauth, oauthWrite401, grant, grantRenewal, authenticate, errors, safety, result, inBandRefusals, probe, guide, transformGuide, hatch: declaredHatch, tools, tagConnector, searchSynonyms, ...metadata } = definition;
+    if (searchSynonyms !== undefined &&
+        !(Array.isArray(searchSynonyms) &&
+            searchSynonyms.length > 0 &&
+            searchSynonyms.length <= 32 &&
+            searchSynonyms.every((group) => Array.isArray(group) &&
+                group.length > 1 &&
+                group.length <= 8 &&
+                new Set(group).size === group.length &&
+                group.every((word) => /^[a-z][a-z0-9]{0,31}$/.test(word))))) {
+        throw new Error(`${metadata.title} searchSynonyms must be 1–32 groups of 2–8 distinct lowercase words.`);
+    }
+    const synonyms = searchSynonyms?.map((group) => [...group]);
     if (credential !== undefined && oauth !== undefined) {
         throw new Error(`${metadata.title} declares both credential and oauth; declare one authentication method.`);
     }
@@ -125,11 +140,12 @@ export function defineApiProvider(definition) {
                 ? refreshOnce(guarded, oauthWrite401
                     ? {
                         challengeMaxBytes: OAUTH_CHALLENGE_MAX_BYTES,
-                        writeUnauthorized: (renewal) => unsentAfterUnauthorized(`Connector "${id}"'s API`, renewal._tag === "Renewed"
+                        writeUnauthorized: (renewal, routes) => unsentAfterUnauthorized(`Connector "${id}"'s API`, renewal._tag === "Renewed"
                             ? undefined
                             : renewal._tag === "Failed"
                                 ? renewal.failure
-                                : new ConnectorCallError("downstream_oauth_required", `Connector "${id}" requires authorization — call authorize_connector({ connector: "${id}" }) and open the returned URL.`), "downstream_oauth_required"),
+                                : // Configured with the connection, worded during the call it refuses.
+                                    new ConnectorCallError("downstream_oauth_required", `Connector "${id}" requires authorization — ${routePhrases(routes).authorizeAndOpen(id)}.`), "downstream_oauth_required"),
                     }
                     : renewalModes)
                 : guarded, {
@@ -164,6 +180,7 @@ export function defineApiProvider(definition) {
                     dispatches: Context.get(lease.services, Dispatches),
                     withholds: connection.safety.withholdsErrors,
                     signal,
+                    routes: routesOf(ctx),
                 };
                 return runEdge(probeProgram.pipe(Effect.provideService(WriteCapacity, new Map()), Effect.flatMap((data) => Effect.try({
                     try: () => {
@@ -173,7 +190,16 @@ export function defineApiProvider(definition) {
                     catch: (error) => error,
                 }).pipe(Effect.catch((error) => error instanceof ConnectorCallError ? Effect.fail(new Refusal({ error })) : Effect.die(error)))), Effect.catch((failure) => Effect.sync(() => {
                     const error = toConnectorCallError(failure, errors, map);
-                    return probe.failure?.(error, options) ?? { ok: false, message: error.message };
+                    const described = probe.failure?.(error, options);
+                    // A provider's own verdict wins; a failure it leaves
+                    // unclassified takes the class of the typed error behind it.
+                    if (described?.ok || described?.failure)
+                        return described;
+                    return {
+                        ok: false,
+                        message: described?.message ?? error.message,
+                        failure: credentialFailureClass(error),
+                    };
                 })), Effect.catchDefect((defect) => Effect.die(withheldDefect(defect, map, !!probe.run))), Effect.provideContext(lease.services), Effect.ensuring(Effect.sync(lease.close))), { signal: ctx.signal });
             };
             const builtTools = tools({
@@ -214,6 +240,8 @@ export function defineApiProvider(definition) {
                 tools: [...builtTools, ...hatchTools],
             }));
             tagConnector?.(connector, options);
+            if (synonyms)
+                registerSearchSynonyms(connector, synonyms);
             return connector;
         },
     });

package/dist/http/safety.js

@@ -1,4 +1,4 @@
-// Provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+// Provider kit. Unreachable from src/index.ts.
 //
 // The one value-safety boundary of a kit connection. `connect` requires it,
 // and `Send` hands a provider nothing it has not passed: a named tool, a
@@ -50,6 +50,10 @@ export function resultSafety(options) {
             return dropped.size > 0 ? strip(safe) : safe;
         },
         withholdsErrors: (operation) => reviewed?.withholdsErrors(operation) === true,
+        withholds: (operation) => {
+            const reviewedHint = reviewed?.withholds?.(operation);
+            return (path) => path.some((segment) => dropped.has(segment.replace(/\[\]$/, ""))) || reviewedHint?.(path) === true;
+        },
     };
 }
 /** Bind the REST value-safety table to its pinned index; unknown operations never bypass its review. */
@@ -78,5 +82,9 @@ export function restSafety(reviewed, index) {
             const op = indexed(operation);
             return op ? reviewed.withholdsErrors(op) : true;
         },
+        withholds: (operation) => {
+            const op = indexed(operation);
+            return op ? reviewed.withholds(op.method, op.path) : () => false;
+        },
     };
 }

package/dist/http/services.js

@@ -3,7 +3,7 @@ import { Context, Effect } from "effect";
 import { dispatchProviderRequest, providerRequest } from "../provider-call.js";
 import { callClassification } from "../call-classification.js";
 import { fromSignal } from "../runtime/run.js";
-import { callFromContext, ContinuationBinding, ContinuationStorage, openCall as openCoreCall, serviceFor, Signal, } from "../runtime/call.js";
+import { callFromContext, ContinuationBinding, ContinuationStorage, serviceFor, Signal } from "../runtime/call.js";
 import { RequestRefused, ResendRefused } from "./errors.js";
 export { writeRequestKey } from "./write-request.js";
 export { Caller, Credentials, Secrets, RequestSecrets, Budget, Recovery, Signal, Classification, Ledger, } from "../runtime/call.js";
@@ -70,10 +70,3 @@ export function fromConnectorContext(ctx, fallback) {
         services: lease.services.pipe(Context.add(ContinuationStorage, serviceFor(ctx, ContinuationStorage) ?? ctx.storage), Context.add(ContinuationBinding, serviceFor(ctx, ContinuationBinding) ?? { connection: "", principal: null }), Context.add(Dispatches, []), Context.add(WriteCapacity, new Map([["write", new Map([[undefined, undefined]])]]))),
     };
 }
-export function openCall(inputs) {
-    const lease = openCoreCall(inputs);
-    return {
-        ...lease,
-        services: lease.services.pipe(Context.add(Dispatches, []), Context.add(WriteCapacity, new Map([["write", new Map([[undefined, undefined]])]]))),
-    };
-}

package/dist/http/tools.js

@@ -1,4 +1,4 @@
-// Provider kit (decision 0010, B.4). Unreachable from src/index.ts.
+// Provider kit. Unreachable from src/index.ts.
 //
 // Tool builders. A tool is a name, a description, an input Schema, an output
 // Schema, and a program; the builder renders both Schemas as catalog JSON
@@ -13,6 +13,7 @@
 // argument validation, sent-secret redaction, withheld handler text. Its
 // boundary also decides every write's outcome, from the core ledger the kit's
 // transport records into, so a kit connector declares `tracksEveryRequest`.
+import { routesOf } from "../agent-routes.js";
 import { Context, Effect, Schema } from "effect";
 import { inLogicalCall } from "../provider-call.js";
 import { registerToolEntry } from "../runtime/call-entry.js";
@@ -20,11 +21,11 @@ import { ConnectorCallError } from "../errors.js";
 import { refuseWithheldValues } from "../providers/_shared/rest/value-safety.js";
 import { causeError, runEdge } from "../runtime/run.js";
 import { recordUnauthorized, Refusal, RequestRefused, toConnectorCallError, withheldDefect, } from "./errors.js";
-import { fieldsInput, fieldsProblem, selectFields } from "./fields.js";
+import { ArgumentProblems } from "./argument-problems.js";
+import { fieldsContract, selectFields } from "./fields.js";
 import { catalogSchema, Integer } from "./json-schema.js";
 import { boundCursor, Cursor, StandardPage } from "./paging.js";
 import { Classification, Dispatches, IdempotencyKey, Recovery, ReadTool, WriteCapacity, writeRequestKey, fromConnectorContext, } from "./services.js";
-const inputs = new WeakMap();
 const keyed = new WeakSet();
 /** Whether a kit write builder declared an idempotency key for this tool. */
 export function takesIdempotencyKey(tool) {
@@ -62,26 +63,20 @@ function originalOrder(decoded, original) {
     };
     return copy(decoded, original);
 }
-/** The input Schema a kit tool decodes with, for the catalog/decoder agreement check. */
-export function kitInput(tool) {
-    return inputs.get(tool);
-}
-/** A Struct's own property names, for `fields`. */
-function propertyNames(schema, what) {
-    const fields = schema.fields;
-    if (!fields)
+/** Refuse `fields` on anything but a Schema.Struct. */
+function struct(schema, what) {
+    if (!schema.fields)
         throw new Error(`fields needs ${what} declared as a Schema.Struct.`);
-    return new Set(Object.keys(fields));
+    return schema;
 }
-/** Refuse a bad `fields` path before anything is sent. */
-function checkFields(fields, names, of) {
-    const error = fieldsProblem(fields, names, of);
-    return error ? Effect.fail(new Refusal({ error })) : Effect.void;
+/** A tool's own check plus every bad `fields` path, refused together before anything is sent. */
+function withFields(contract, check) {
+    return (args, problems) => {
+        contract.issues(problems, args.fields);
+        const { fields: _fields, ...rest } = args;
+        check?.(rest, problems);
+    };
 }
-const fieldsExample = (names) => {
-    const first = [...names][0];
-    return first === undefined ? "" : `, e.g. ["${first}"]`;
-};
 /**
  * A read: admitted to call_tool and programs. `fields: true` (decision 0011
  * S5) appends a `fields` argument that narrows the returned record; the input
@@ -93,17 +88,17 @@ export function read(connection, spec) {
         throw new Error("A read review must be nonempty.");
     if (spec.fields === undefined)
         return build(connection, spec, "read", { readOnlyHint: true }, undefined, spec.review);
-    const names = propertyNames(spec.output, "the output");
-    propertyNames(spec.input, "the input");
+    const contract = fieldsContract("result", struct(spec.output, "the output"));
+    struct(spec.input, "the input");
     const input = Schema.Struct({
         ...spec.input.fields,
-        fields: Schema.optionalKey(fieldsInput(`Dot paths to keep in the result${fieldsExample(names)}. It only narrows the result.`)),
+        fields: Schema.optionalKey(contract.input),
     });
     return build(connection, {
         ...spec,
         input,
+        check: withFields(contract, spec.check),
         run: (args) => Effect.gen(function* () {
-            yield* checkFields(args.fields, names, "the result");
             const { fields, ...rest } = args;
             return selectFields(yield* spec.run(rest), fields);
         }),
@@ -141,7 +136,7 @@ export function list(connection, spec) {
         if (name in spec.filters)
             throw new Error(`${spec.name} filters cannot declare ${name}; the kit supplies it.`);
     }
-    const names = propertyNames(spec.row, "the row");
+    const contract = fieldsContract("item", struct(spec.row, "the row"));
     const input = Schema.Struct({
         ...spec.filters,
         limit: Schema.optionalKey(allowedLimit.annotate({
@@ -149,7 +144,7 @@ export function list(connection, spec) {
             default: size,
         })),
         cursor: Schema.optionalKey(Cursor),
-        fields: Schema.optionalKey(fieldsInput(`Dot paths to keep in each item${fieldsExample(names)}. It only narrows the result.`)),
+        fields: Schema.optionalKey(contract.input),
     });
     return build(connection, {
         name: spec.name,
@@ -157,8 +152,8 @@ export function list(connection, spec) {
         input,
         // `fields` narrows each item, so items render sparse; the envelope keeps items and page required.
         output: Schema.Unknown,
+        check: withFields(contract, undefined),
         run: (args) => Effect.gen(function* () {
-            yield* checkFields(args.fields, names, "an item");
             // A cursor stays valid when only the projection changes between pages.
             const { fields, cursor: supplied, ...rest } = args;
             const scope = spec.cursorScope === undefined
@@ -314,7 +309,13 @@ rendered) {
         const lease = fromConnectorContext(ctx, verdict);
         const classification = Context.get(lease.services, Classification);
         const dispatches = Context.get(lease.services, Dispatches);
-        const map = { classification, dispatches, withholds: connection.safety.withholdsErrors, signal: ctx.signal };
+        const map = {
+            classification,
+            dispatches,
+            withholds: connection.safety.withholdsErrors,
+            signal: ctx.signal,
+            routes: routesOf(ctx),
+        };
         return Effect.try({
             try: () => {
                 if (verdict === "write" || classification === "write")
@@ -323,7 +324,22 @@ rendered) {
             catch: (error) => error,
         }).pipe(Effect.catch((error) => error instanceof ConnectorCallError ? Effect.fail(new Refusal({ error })) : Effect.die(error)), 
         // Its message can quote the argument; as a defect, api() withholds it.
-        Effect.flatMap(() => decode(args).pipe(Effect.orDie)), Effect.map((decoded) => (spec.inputOrder === "original" ? originalOrder(decoded, args) : decoded)), Effect.flatMap((decoded) => Effect.gen(function* () {
+        Effect.flatMap(() => decode(args).pipe(Effect.orDie)), Effect.map((decoded) => (spec.inputOrder === "original" ? originalOrder(decoded, args) : decoded)), Effect.flatMap((decoded) => {
+            if (!spec.check)
+                return Effect.succeed(decoded);
+            const check = spec.check;
+            return Effect.try({
+                try: () => {
+                    const problems = new ArgumentProblems();
+                    check(decoded, problems);
+                    const refusal = problems.refusal("Invalid arguments", tool.inputSchema);
+                    if (refusal)
+                        throw refusal;
+                    return decoded;
+                },
+                catch: (error) => error,
+            }).pipe(Effect.catch((error) => error instanceof ConnectorCallError ? Effect.fail(new Refusal({ error })) : Effect.die(error)));
+        }), Effect.flatMap((decoded) => Effect.gen(function* () {
             const key = idempotency?.key(decoded);
             if (key !== undefined && unsendableKey(key)) {
                 return yield* Effect.fail(new RequestRefused({
@@ -350,7 +366,6 @@ rendered) {
         })));
     });
     registerToolEntry(tool, (args, ctx) => program(args, ctx, inLogicalCall(ctx)));
-    inputs.set(tool, spec.input);
     if (idempotency)
         keyed.add(tool);
     return tool;