@zackbart/connecta 0.38.0 → 0.40.0

package/dist/guest-types.d.ts

@@ -25,7 +25,8 @@ export interface GuestApi {
         text: string;
         format: "text";
     }>;
-    emit(block: GuestNativeBlock | GuestResult): PromiseLike<void>;
+    /** Forwards an authored block, a block from result.content, or an inline result; a paged handle is refused. */
+    emit(block: GuestNativeBlock | Exclude<GuestResult, GuestResultHandle>): PromiseLike<void>;
 }
 export interface GuestResourceResult {
     contents: Array<{
@@ -114,8 +115,8 @@ interface CatalogSearchArgs {
     includeSchemaKeys?: boolean;
 }
 interface CatalogDescribeArgs {
-    address?: unknown;
-    addresses?: unknown;
+    address?: string;
+    addresses?: string[];
     format?: SchemaFormat;
     fullDescriptions?: boolean;
 }
@@ -171,8 +172,21 @@ interface CatalogSearchPage {
     };
 }
 type CatalogSearchResult = CatalogSearchPage & {
-    tools: Array<CatalogSearchTool & {
-        connectorTitle?: string;
+    tools: CatalogSearchTool[];
+    /** Complete operation reads: pass args unchanged to connecta.call(address, args). */
+    readyCalls?: Array<{
+        address: string;
+        args: {
+            path: string;
+        };
+        classification: "read";
+        summary: string;
+        guideRequired?: true;
+        guideRequiredReasons?: GuideRequiredReason[];
+    }>;
+    /** Facts shared by a connector's rows, keyed by the id before the address's first dot. */
+    connectors?: Record<string, {
+        title?: string;
         guide?: string;
         guideSummary?: string;
     }>;

package/dist/http/argument-problems.js

@@ -0,0 +1,35 @@
+// Internal provider kit (decision 0011 S5). Unreachable from src/index.ts.
+//
+// A provider's own argument checks record every problem before refusing, so
+// one invalid_args carries every finding and an agent repairs the call in one
+// turn instead of one constraint per turn.
+import { ConnectorCallError, issueSummary } from "../errors.js";
+import { schemaExample } from "../validate.js";
+/** Every argument problem one call has, then a single refusal. */
+export class ArgumentProblems {
+    #issues = [];
+    /**
+     * Record one problem. A refusal holds only what the published schema
+     * declares and fixed text: `path` names declared properties and indices
+     * (`<key>` for any other key), `expected` states the allowed shape or bound,
+     * and `received` is a JSON type. Never a submitted string or key.
+     */
+    add(path, expected, received) {
+        this.#issues.push({ path, expected, ...(received === undefined ? {} : { received }) });
+    }
+    /**
+     * The one refusal for every recorded problem, or undefined when there is
+     * none. With the tool's schema it carries the schema's synthesized example;
+     * `withheld` states why a tool offers none.
+     */
+    refusal(lead, schema, withheld) {
+        if (!this.#issues.length)
+            return undefined;
+        return new ConnectorCallError("invalid_args", `${lead}: ${issueSummary(this.#issues)}`, {
+            validation: {
+                issues: this.#issues,
+                ...(withheld ? { exampleUnavailable: withheld } : schema ? schemaExample(schema) : {}),
+            },
+        });
+    }
+}

package/dist/http/errors.js

@@ -30,6 +30,7 @@
 // ledger entries this kit forwards its matched proof and renewals to. A
 // write answered 401 stays unknown; only renewal removes its handoff, and
 // only a reviewed authentication-before-execution declaration proves refusal.
+import { routesOf } from "../agent-routes.js";
 import { Data } from "effect";
 import { ConnectorCallError, isConnectorCallErrorCode, resendAdvice, unavailableCallError, } from "../errors.js";
 import { attachFailureFacts } from "../operator-record.js";
@@ -429,7 +430,7 @@ function verdict(failure, vendor, options, dispatch = options.dispatches.find((e
                     body: undefined,
                     unreadable: true,
                     operation: dispatch.operation ?? { method: "", template: "" },
-                }), vendor, options.withholds?.(dispatch.operation ?? { method: "", template: "" }) === true, !dispatch.write);
+                }), vendor, options.withholds?.(dispatch.operation ?? { method: "", template: "" }) === true, !dispatch.write, routesOf(options));
                 return providerFailureMessage(mapped, failure.detail);
             }
             const uncertainWrite = options.classification === "write" &&
@@ -455,10 +456,10 @@ function verdict(failure, vendor, options, dispatch = options.dispatches.find((e
                 : unreadable, { retryable: false });
         }
         case "StatusFailure":
-            return statusVerdict(failure, vendor, options.withholds?.(failure.operation) === true, options.dispatches.some((dispatch) => dispatch.failure === failure && !dispatch.write));
+            return statusVerdict(failure, vendor, options.withholds?.(failure.operation) === true, options.dispatches.some((dispatch) => dispatch.failure === failure && !dispatch.write), routesOf(options));
     }
 }
-function statusVerdict(failure, vendor, withheld, read) {
+function statusVerdict(failure, vendor, withheld, read, routes) {
     const input = classificationInput(failure, vendor, withheld);
     const { headers, presence } = input;
     // Classification first, over facts and headers only.
@@ -477,7 +478,7 @@ function statusVerdict(failure, vendor, withheld, read) {
         withheld,
         ...(withheld ? {} : { body: failure.body }),
     });
-    const error = new ConnectorCallError(code, words ? words(detail) : detail, {
+    const error = new ConnectorCallError(code, words ? words(detail, routes) : detail, {
         ...(retryable === undefined ? {} : { retryable }),
         ...(wait === undefined ? {} : { retryAfterMs: wait }),
         ...(current ? { current } : {}),

package/dist/http/fields.js

@@ -3,10 +3,29 @@
 // `fields` narrows a result to the dot paths an agent names. It runs on the
 // result a tool already built (after value safety, the privacy projection and
 // any named projection), so it can only remove. A list narrows each item.
+//
+// Every `fields` argument states where its paths start, its anchor, in the
+// schema description, derived here from the same contract that validates it:
+// a named read's result, each item of a list's `items`, or a hatch's response
+// body in `data`. A path is checked against the published output schema as
+// deep as that schema is closed, so a path outside the declared contract is
+// refused before anything is sent. A declared path the response happens to
+// lack is never refused: absent optional values and empty lists are ordinary.
 import { Schema } from "effect";
-import { ConnectorCallError } from "../errors.js";
-import { isMaxChars, isMinChars } from "./json-schema.js";
+import { ArgumentProblems } from "./argument-problems.js";
+import { catalogSchema, isMaxChars, isMinChars } from "./json-schema.js";
 const MAX_FIELDS = 50;
+/** Choices listed in a refusal or a warning; more read as "a declared property". */
+const MAX_CHOICES = 40;
+const ANCHORS = {
+    result: "the result",
+    item: "each item in items",
+    data: "the response body in data, each item when the body is a list",
+};
+/** The description of a `fields` argument: its anchor, one valid example, then any tool note. */
+export function fieldsDescription(anchor, example, note = "It only narrows the result.") {
+    return `Dot paths to keep. Paths start at ${ANCHORS[anchor]}, e.g. ${JSON.stringify([example])}. ${note}`;
+}
 /** The `fields` argument: at most 50 dot paths of 1 to 200 characters. */
 export function fieldsInput(description) {
     return Schema.Array(Schema.String.check(isMinChars(1), isMaxChars(200)))
@@ -16,18 +35,97 @@ export function fieldsInput(description) {
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+/** A dot path's property names; `a[].b` and `a.b` both select `b` in each item of `a`. */
+const segments = (path) => path.replace(/\[\](?=\.|$)/g, "").split(".");
+/**
+ * Collect the properties a path segment may name at a schema position into
+ * `into`, false when the position is open (any key may appear: `{}`, a bare
+ * object or array, a record, a reference). Arrays are transparent, as
+ * selection narrows them item by item; a leaf adds nothing and stays closed.
+ * Below the first segment, JSON Schema's default applies: an object is closed
+ * only when it says `additionalProperties: false`. The first segment keeps the
+ * declared properties of the result or item as its closed set.
+ */
+function propertiesAt(node, into, root) {
+    if (!record(node))
+        return node === false;
+    const additional = node["additionalProperties"];
+    if ("$ref" in node || "allOf" in node || (additional !== undefined && additional !== false))
+        return false;
+    const branches = [node["anyOf"], node["oneOf"]].flatMap((value) => (Array.isArray(value) ? value : []));
+    if (!branches.every((branch) => propertiesAt(branch, into, root)))
+        return false;
+    if (node["items"] !== undefined && !propertiesAt(node["items"], into, root))
+        return false;
+    const properties = node["properties"];
+    if (record(properties)) {
+        for (const [name, child] of Object.entries(properties))
+            into.set(name, [...(into.get(name) ?? []), child]);
+        return root || additional === false;
+    }
+    if (branches.length || node["items"] !== undefined || "enum" in node || "const" in node)
+        return true;
+    const types = [node["type"]].flat();
+    return node["type"] !== undefined && !types.includes("object") && !types.includes("array");
+}
+const choices = (names) => names.length > 0 && names.length <= MAX_CHOICES ? `one of ${names.join(", ")}` : "a declared property";
+/**
+ * Record every `fields` path the contract cannot carry. A JSON Schema is the
+ * published shape at the anchor (a result, or a list's item), checked as deep
+ * as it is closed; a set names only the first segments, which is all a hatch's
+ * pinned index can promise. A finding names the entry's index, its segment
+ * position and the declared properties there, never the submitted text.
+ */
+function fieldsIssues(problems, fields, contract, of) {
+    const root = contract instanceof Set
+        ? { type: "object", properties: Object.fromEntries([...contract].map((n) => [n, {}])) }
+        : contract;
+    fields?.forEach((field, index) => {
+        let nodes = [root];
+        for (const [depth, name] of segments(field).entries()) {
+            const at = new Map();
+            // Selection keeps a scalar a path runs past, so below the first segment only a closed object refuses.
+            if (!nodes.every((node) => propertiesAt(node, at, depth === 0)) || (depth > 0 && at.size === 0))
+                return;
+            const next = at.get(name);
+            if (next) {
+                nodes = next;
+                continue;
+            }
+            const declared = [...at.keys()];
+            problems.add(`/fields/${index}`, depth === 0
+                ? `a path beginning with a property of ${of}: ${choices(declared)}`
+                : `a declared path of ${of}; segment ${depth + 1} names a property declared at that level: ${choices(declared)}`);
+            return;
+        }
+    });
+}
+/** The single refusal naming every bad `fields` path, if any; `withheld` says why it has no example. */
+export function fieldsProblem(fields, contract, of, withheld) {
+    const problems = new ArgumentProblems();
+    fieldsIssues(problems, fields, contract, of);
+    return problems.refusal("Invalid fields", undefined, withheld);
+}
 /**
- * The refusal for a path whose first segment is not a property the result can
- * carry, if any. Named tools pass their output Schema's property names and
- * the hatch its operation's declared response roots, so a bad path fails
- * before anything is sent.
+ * The `fields` contract for a named read's result (`"result"`) or a list's
+ * item (`"item"`). `shape` is that result or item: a Schema rendered as the
+ * catalog renders it, or the catalog JSON Schema itself. Its first declared
+ * property is the description's example, so the example is always valid.
  */
-export function fieldsProblem(fields, names, of) {
-    const bad = fields?.find((field) => !names.has(field.replace(/\[\](?=\.|$)/g, "").split(".")[0]));
-    if (bad === undefined)
-        return undefined;
-    const choices = names.size > 0 && names.size <= 40 ? `: one of ${[...names].join(", ")}` : "";
-    return new ConnectorCallError("invalid_args", `fields path ${bad} does not begin with a property of ${of}${choices}.`);
+export function fieldsContract(anchor, shape, note, of = anchor === "item" ? "an item" : "the result") {
+    const schema = "ast" in shape ? catalogSchema(shape, "output") : shape;
+    const at = new Map();
+    propertiesAt(schema, at, true);
+    const example = [...at.keys()][0];
+    if (example === undefined)
+        throw new Error("fields needs a contract that declares at least one property.");
+    const description = fieldsDescription(anchor, example, note);
+    return {
+        description,
+        input: fieldsInput(description),
+        issues: (problems, fields) => fieldsIssues(problems, fields, schema, of),
+        problem: (fields) => fieldsProblem(fields, schema, of),
+    };
 }
 /** Keep only the named dot paths; arrays are narrowed item by item. */
 export function selectFields(data, fields) {
@@ -40,10 +138,91 @@ export function selectFields(data, fields) {
             return value;
         const children = new Map();
         for (const path of paths) {
-            const [key, ...tail] = path.replace(/\[\](?=\.|$)/g, "").split(".");
+            const [key, ...tail] = segments(path);
             children.set(key, [...(children.get(key) ?? []), tail.join(".")]);
         }
         return Object.fromEntries([...children].flatMap(([key, tails]) => Object.hasOwn(value, key) ? [[key, tails.includes("") ? value[key] : pick(value[key], tails)]] : []));
     };
     return pick(data, fields);
 }
+const empty = (value) => value === null ||
+    value === undefined ||
+    (Array.isArray(value) ? value.length === 0 : record(value) && !Object.keys(value).length);
+/** Warning bounds: each warning's characters, the count kept, and every kept warning's characters together. */
+export const WARNING_BUDGET = { chars: 512, warnings: 10, totalChars: 4096 };
+/**
+ * Keep warnings within WARNING_BUDGET in order, cutting a long one with an
+ * ellipsis, then one count of what was omitted. Merged reviewed warnings and
+ * `fields` reports share the budget.
+ */
+/** At most `max` UTF-16 units, never splitting a surrogate pair. */
+function codePointSlice(text, max) {
+    const end = max > 0 && /[\uD800-\uDBFF]/.test(text[max - 1] ?? "") ? max - 1 : max;
+    return text.slice(0, end);
+}
+export function boundWarnings(warnings) {
+    const kept = [];
+    let total = 0;
+    for (const warning of warnings) {
+        const text = warning.length > WARNING_BUDGET.chars ? `${codePointSlice(warning, WARNING_BUDGET.chars - 1)}…` : warning;
+        // Leave room for the omitted count.
+        if (kept.length >= WARNING_BUDGET.warnings || total + text.length > WARNING_BUDGET.totalChars - 64)
+            break;
+        kept.push(text);
+        total += text.length;
+    }
+    const omitted = warnings.length - kept.length;
+    return omitted ? [...kept, `${omitted} more warning${omitted === 1 ? "" : "s"} omitted.`] : kept;
+}
+/** Declared names listed in one warning, within its character budget. */
+function named(names) {
+    let text = "";
+    let shown = 0;
+    for (const name of names) {
+        const next = text ? `${text}, ${name}` : name;
+        if (next.length > WARNING_BUDGET.chars - 200)
+            break;
+        text = next;
+        shown += 1;
+    }
+    return shown < names.length ? `${text}${text ? " and " : ""}${names.length - shown} more` : text;
+}
+/**
+ * One warning per `fields` entry that matched nothing in a nonempty response,
+ * for contracts that cannot refuse it in advance. It names the entry's index,
+ * the segment where matching stopped and the properties the contract declares
+ * there, from `declared` (paths in `fields` coordinates). It never lists the
+ * response's own keys, which in an open map are data, nor the submitted text.
+ * A path some item matched, a path past a scalar (kept whole), or any path of
+ * an empty response, is no warning.
+ */
+export function fieldsMisses(data, fields, declared = []) {
+    if (!fields?.length || empty(data))
+        return [];
+    const flat = (values) => values.flatMap((value) => (Array.isArray(value) ? flat(value) : [value]));
+    const contract = declared.map((path) => segments(path.replace(/^\[\]\.?/, "")));
+    return fields.flatMap((field, index) => {
+        const path = segments(field);
+        let values = flat([data]);
+        for (const [depth, name] of path.entries()) {
+            const holders = values.filter((value) => record(value) && Object.hasOwn(value, name));
+            if (holders.length) {
+                values = flat(holders.map((value) => value[name]));
+                continue;
+            }
+            // Selection keeps a scalar or null a path runs past, so only an object lacking the key is a miss.
+            if (!values.some(record))
+                return [];
+            const prefix = path.slice(0, depth);
+            const names = [
+                ...new Set(contract
+                    .filter((parts) => parts.length > depth && prefix.every((part, at) => parts[at] === part))
+                    .map((parts) => parts[depth])),
+            ];
+            return [
+                `fields/${index} matched nothing in this response after value safety and privacy filtering, at segment ${depth + 1}; ${names.length ? `declared there: ${named(names)}` : "the operation declares no properties there"}.`,
+            ];
+        }
+        return [];
+    });
+}

package/dist/http/hatch-response.js

@@ -0,0 +1,73 @@
+/**
+ * At most 100 paths and 4 KiB of path JSON, `withheld` included, an eighth of
+ * the 32 KiB details budget. That holds every path of nine in ten operations
+ * in each maintained index; larger responses keep their shallowest paths,
+ * roots first. A path over 200 characters, longer than one `fields` entry may
+ * be, is never listed.
+ */
+export const RESPONSE_BUDGET = { paths: 100, chars: 4096, pathChars: 200 };
+/** `a[].b` → `["a", "b"]`. */
+function names(path) {
+    return path.split(".").map((part) => part.replace(/\[\]$/, ""));
+}
+/**
+ * The capped response contract for one operation, or undefined when it
+ * declares no response properties (`fields` is then refused). Deterministic:
+ * paths keep the index's order within each depth.
+ */
+export function responseContract(index, op, safety) {
+    const declared = index.fields(op).filter((field) => field.in === "response");
+    if (declared.length === 0)
+        return undefined;
+    const anchor = declared.some((field) => field.path.startsWith("[]")) ? "data[]" : "data";
+    // The coordinates `fields` validates: an item path of a list body drops its leading `[].`.
+    const paths = [
+        ...new Set(declared.map((field) => field.path.replace(/^\[\]\.?/, "")).filter((path) => /^[^.[]/.test(path))),
+    ];
+    // Every root `fields` accepts is listed, including one the index names only beneath it.
+    const spelled = new Map();
+    for (const path of [...paths.map((path) => names(path)[0]), ...paths]) {
+        const key = names(path).join(".");
+        if (!spelled.has(key))
+            spelled.set(key, path);
+    }
+    let withholds;
+    try {
+        withholds = safety.withholds({ method: op.method, template: op.path });
+    }
+    catch {
+        withholds = () => false;
+    }
+    // The hint reads paths with their list markers, a list body's items included.
+    const known = new Set([...spelled]
+        .filter(([, path]) => withholds([...(anchor === "data[]" ? ["[]"] : []), ...path.split(".")]))
+        .map(([key]) => key));
+    const depth = (path) => path.split(".").length;
+    const ordered = [...spelled.values()]
+        .map((path, at) => ({ path, at }))
+        .sort((a, b) => depth(a.path) - depth(b.path) || a.at - b.at);
+    const fields = [];
+    const withheld = [];
+    let chars = 0;
+    let kept = 0;
+    for (const { path } of ordered) {
+        // A path longer than a fields input can be is counted, never listed.
+        if (path.length > RESPONSE_BUDGET.pathChars)
+            continue;
+        const hinted = known.has(names(path).join("."));
+        const cost = (JSON.stringify(path).length + 1) * (hinted ? 2 : 1);
+        if (kept >= RESPONSE_BUDGET.paths || chars + cost > RESPONSE_BUDGET.chars)
+            break;
+        fields.push(path);
+        if (hinted)
+            withheld.push(path);
+        chars += cost;
+        kept += 1;
+    }
+    return {
+        anchor,
+        fields,
+        ...(withheld.length ? { withheld } : {}),
+        ...(kept < ordered.length ? { omitted: ordered.length - kept } : {}),
+    };
+}