@zackbart/connecta 0.37.1 → 0.39.0

package/dist/operator-ui/model.d.ts

@@ -20,8 +20,12 @@ export interface UiTool extends Pick<OperatorTool, "name" | "address" | "descrip
  * (`credential_required`), or a secret that lives in deployment configuration
  * (`auth_required`). Principal forwarding instead reports `caller_refused`,
  * which has no secret-repair prompt.
+ *
+ * `connector_timeout` is a downstream that did not answer before the operator
+ * page's deadline: slow or unreachable, not known to be broken. The page
+ * stops retrying it on its own until someone asks with Refresh.
  */
-export type UiProblem = "connector_unavailable" | "oauth_required" | "credential_required" | "auth_required" | "caller_refused" | "credential_mismatch" | "catalog_failed";
+export type UiProblem = "connector_unavailable" | "connector_timeout" | "oauth_required" | "credential_required" | "auth_required" | "caller_refused" | "credential_mismatch" | "catalog_failed";
 /** A stored credential that cannot be used, by cause. */
 export type UiCredentialProblem = "credential_mismatch" | "credential_unreadable";
 interface UiCredentialField {
@@ -35,6 +39,13 @@ interface UiCredentialField {
     lastFour?: string;
     updatedAt?: string;
 }
+/** Mirrors `CredentialVerification` in src/credential-verification.ts. */
+export interface UiVerification {
+    outcome: "ok" | "unverified" | UiCredentialFailure;
+    observedAt: string;
+}
+/** Why a credential test failed, as the route reports it. */
+export type UiCredentialFailure = "rejected" | "scope" | "unreachable" | "timeout" | "failed";
 interface UiCredential {
     label: string;
     description?: string;
@@ -83,11 +94,21 @@ export interface UiConnector {
     authorizationUrl?: string;
     toolCount: number;
     tools: UiTool[];
+    /** Age of the stored status observation this row shows; absent on a live read. */
+    observedAgeMs?: number;
+    /** Browser-only: the stored observation's time, fixed as the row lands. */
+    observedAt?: number;
     /** This connector exposes manageable downstream OAuth lifecycle hooks. */
     oauth?: boolean;
     /** Selected downstream client identity mechanism; never a client ID or secret. */
     registrationPath?: "cimd" | "dcr" | "static";
     credential?: UiCredential;
+    /**
+     * The stored last verification of this connector's operator-managed
+     * credential. Absent when nothing has verified the save stored now. A
+     * typed outcome and a time; never vendor text.
+     */
+    verification?: UiVerification;
     /**
      * Drift the last catalog refresh saw *in this runtime*
      * ([#343](https://github.com/zackbart/connecta/issues/343)). Four counts and

package/dist/program-writes.js

@@ -1,8 +1,8 @@
+import { toolError } from "./tool-error.js";
 // Budget and outcome accounting for writes dispatched by programs on writable endpoints.
 // Await each dispatched write once; never conceal an unknown outcome.
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import { Effect } from "effect";
-import { jsonResult } from "./meta-tools.js";
 import { classifyWriteOutcome } from "./write-outcome.js";
 /** Writes one program may send (`execute.maxWrites`), unless configured. */
 export const DEFAULT_MAX_WRITES = CONFIG_DEFAULTS.execute.maxWrites;
@@ -125,7 +125,7 @@ export class ProgramWrites {
             // the result, as a direct call reports it: its code and handoff, never
             // retryable, with the write's outcome unknown.
             const handoff = this.handoff;
-            return errorEnvelope({
+            return toolError({
                 code: handoff?.code ?? "write_outcome_unknown",
                 message: handoff
                     ? "A write this program sent failed authorization after it left, so whether it took effect is unknown, and that is the result rather than what the program returned. It will not be sent again. Check its target before doing anything that depends on it, and give nextAction to the operator to recover the connector. Argument echoes may be partial or absent; use the original arguments if reconciliation requires another call."
@@ -153,7 +153,7 @@ export class ProgramWrites {
 function withWrites(result, writes) {
     const structured = result.structuredContent;
     const error = structured?.error;
-    const annotated = errorEnvelope({
+    const annotated = toolError({
         ...(error !== null && typeof error === "object"
             ? error
             : {
@@ -171,8 +171,3 @@ function withWrites(result, writes) {
     }
     return annotated;
 }
-function errorEnvelope(error) {
-    const result = jsonResult({ error });
-    result.isError = true;
-    return result;
-}

package/dist/provider-call.js

@@ -261,11 +261,4 @@ export function providerFetch(ctx, provider, auxiliary, send) {
 export function inLogicalCall(ctx) {
     return recordedService(ctx, LogicalLedger) !== undefined;
 }
-/**
- * Every resource request dispatched under `ctx`'s logical call, from any
- * ledger, nested ones included; undefined outside one.
- */
-export function logicalCallRequests(ctx) {
-    return ctx ? recordedService(ctx, LogicalLedger)?.sent : undefined;
-}
 export { recordProviderResponse, tracksEveryRequest, tracksRequests, delegatesEachCall, providerBoundary, refusedStatus, vendorRefusal, authorizationFailure, unauthorizedAnswer, renewedAfterUnauthorized, refusalRequest, knownProviderFailure, isKnownProviderFailure, forgetProviderFailure, explainedUnauthorizedVerdict, explainsUnauthorized, settledWrite, isSettledWrite, } from "./provider-call-facts.js";

package/dist/provider.d.ts

@@ -120,7 +120,7 @@ export interface ProviderGuideBlocks<O> {
     select(options: Readonly<O>): readonly string[];
 }
 /**
- * Facts the provider kit (decision 0010) declares for `providers:generate`:
+ * Facts the provider kit declares for `providers:generate`:
  * `drift.json`'s `generated.operations` and the guide's Conventions. Plain
  * data, never read at runtime. The kit's `defineApiProvider` sets them.
  */

package/dist/providers/_shared/google/kit.js

@@ -1,3 +1,4 @@
+import { asRecord, asArray } from "../json.js";
 // Google Workspace on the provider kit (decision 0010; C.7 step 1 under 0011).
 // Shared by every Workspace product; never its own export. `workspace.ts`
 // keeps shared options, connection parsing and subject resolution;
@@ -17,12 +18,6 @@ import { delegatedToken, forgetDelegatedToken } from "./service-account.js";
 import { subjectFor, workspaceConnection } from "./workspace.js";
 import { tagWorkspaceSubject } from "../../../workspace-subject.js";
 import { googleNamedOperation, requireGoogleIndex } from "./hatch.js";
-function asRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-function asArray(value) {
-    return Array.isArray(value) ? value : [];
-}
 function reasonsOf(tokens) {
     const error = asRecord(asRecord(tokens)["error"]);
     const reasons = new Set();

package/dist/providers/_shared/google/service-account.js

@@ -1,3 +1,4 @@
+import { asRecord } from "../json.js";
 /**
  * A Google service account acting as itself or for Workspace users through
  * domain-wide delegation: the key, signed JWT-bearer assertions and short-lived
@@ -266,9 +267,6 @@ const tokenTransport = guardedFetch({
     // The assertion in the body is the authentication; there is no header.
     authenticate: () => ({}),
 });
-function asRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
 /** The token endpoint's OAuth `error` codes this module names back. */
 const TOKEN_ERROR_CODES = new Set([
     "invalid_request",

package/dist/providers/_shared/google/workspace.d.ts

@@ -92,10 +92,10 @@ export declare const GOOGLE_WORKSPACE_OPTIONS: import("../../../config-schema.js
         };
         instructions: import("../../../config-schema.js").Field<unknown, unknown, true>;
         title: import("../../../config-schema.js").Field<unknown, unknown, true>;
+        baseUrl: import("../../../config-schema.js").Field<unknown, unknown, true>;
         purpose: import("../../../config-schema.js").Field<unknown, unknown, true>;
         maxResultBytes: import("../../../config-schema.js").Field<unknown, unknown, true>;
         readOnly: import("../../../config-schema.js").Field<unknown, unknown, true>;
-        baseUrl: import("../../../config-schema.js").Field<unknown, unknown, true>;
         subject: import("../../../config-schema.js").Field<unknown, unknown, true>;
     };
 };

package/dist/providers/_shared/guide.js

@@ -0,0 +1,3 @@
+export function readOnlyNotice(readOnly) {
+    return readOnly ? ["This connection is read-only: every write is refused."] : [];
+}

package/dist/providers/_shared/json.js

@@ -0,0 +1,12 @@
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function asRecord(value) {
+    return isRecord(value) ? value : {};
+}
+export function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+export function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}

package/dist/providers/_shared/rest/compact-index.js

@@ -23,7 +23,7 @@ function rowText(packed, row) {
     return `[[${parameters.join(",")}],${body}]`;
 }
 /** Recreate the exact old JSON string, for semantic identity/cursor binding. */
-export function expandIndexDetails(packed) {
+function expandIndexDetails(packed) {
     limit(packed.length);
     let length = packed.definitions.length + 13; // {"d":defs,"o":[]}
     limit(length);

package/dist/providers/_shared/rest/kit.js

@@ -1,12 +1,10 @@
+import { isRecord } from "../json.js";
 // Shared REST call shapes, pinned-schema conversion and indexed vendor declarations.
 import { Effect, Schema } from "effect";
 import { ConnectorCallError } from "../../../errors.js";
 import { Refusal } from "../../../http/errors.js";
 import { Integer, isMinChars, isMaxChars } from "../../../http/json-schema.js";
 import { vendor as declareVendor, get, head, post, put, patch, del, } from "../../../http/vendor.js";
-function isRecord(value) {
-    return !!value && typeof value === "object" && !Array.isArray(value);
-}
 function invalid(message) {
     throw new ConnectorCallError("invalid_args", message);
 }

package/dist/providers/_shared/rest/operation-index.js

@@ -1,3 +1,4 @@
+import { isRecord } from "../json.js";
 import { canonicalJson } from "../../../canonical-json.js";
 import { parseIndexDetails } from "./compact-index.js";
 // The pinned operation index a REST connector validates against before it
@@ -10,7 +11,7 @@ import { parseIndexDetails } from "./compact-index.js";
 // are refused with the accepted names, because a guessed argument is the most
 // common way an agent wastes a call. Drift between the pin and the vendor is
 // caught by `providers:check` and refreshed by `providers:spec`.
-import { ConnectorCallError } from "../../../errors.js";
+import { ConnectorCallError, issueSummary } from "../../../errors.js";
 const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
 const MAX_ISSUES = 20;
 function words(text) {
@@ -20,14 +21,16 @@ function words(text) {
         .split(/[^a-z0-9]+/)
         .filter(Boolean);
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function invalid(message, issues, repair) {
-    throw new ConnectorCallError("invalid_args", message, {
-        ...(issues ? { validation: { issues } } : {}),
-        ...(repair ? { repair } : {}),
-    });
+/** Index findings name no example: the hatch schema cannot prove an operation's arguments safe to echo. */
+function invalid(message, issues, details) {
+    throw new ConnectorCallError("invalid_args", message, issues
+        ? {
+            validation: {
+                issues,
+                exampleUnavailable: `Examples are withheld for API operations; read ${details} for the contract.`,
+            },
+        }
+        : {});
 }
 function typesOf(node) {
     return node.t === undefined ? [] : typeof node.t === "string" ? [node.t] : node.t;
@@ -44,7 +47,7 @@ function distance(a, b) {
     }
     return previous[b.length];
 }
-/** The accepted names, bounded and led by the likeliest intended one; repair details carry the full list. */
+/** The accepted names, bounded and led by the likeliest intended one; the full list is in the tool schema. */
 function oneOf(names, given) {
     const close = given === undefined
         ? undefined
@@ -247,7 +250,7 @@ export class OperationIndex {
                 best.rows.push(row);
         });
         if (best.rows.length === 0) {
-            invalid(`${this.#title} has no ${path} operation in the pinned API index (${this.revision}). ` +
+            invalid(`${this.#title} has no operation at that path in the pinned API index (${this.revision}). ` +
                 `Nearest: ${this.nearest(method, segments).join("; ")}. Find operations with ${this.#vendorTool("search")}.`);
         }
         const templates = new Set(best.rows.map((row) => this.ops[row].path));
@@ -281,17 +284,16 @@ export class OperationIndex {
             }
         });
         const issues = [];
-        const repair = [];
         for (const [name, at, , schema] of this.#row(op)?.[0] ?? []) {
             if (at === "path" && params[name] !== undefined)
-                this.#check(schema, decodeURIComponent(params[name]), `/path/${name}`, issues, repair);
+                this.#check(schema, decodeURIComponent(params[name]), `/path/${name}`, issues);
         }
         if (issues.length) {
             const shown = issues
                 .slice(0, 5)
-                .map((issue) => `${issue.path} (${issue.code}: ${issue.expected})`)
+                .map((issue) => issueSummary([issue]))
                 .join("; ");
-            invalid(`Not sent: the path does not match ${op.method} ${op.path} in the pinned API index: ${shown}. Substitute real ids matching ${this.#vendorTool("details")}.${issues.some((issue) => issue.expected?.includes("safe integer")) ? " Integer ids use canonical ASCII decimal notation within the safe-integer range." : ""}`, issues.slice(0, MAX_ISSUES));
+            invalid(`Not sent: the path does not match ${op.method} ${op.path} in the pinned API index: ${shown}. Substitute real ids matching ${this.#vendorTool("details")}.${issues.some((issue) => issue.expected?.includes("safe integer")) ? " Integer ids use canonical ASCII decimal notation within the safe-integer range." : ""}`, issues.slice(0, MAX_ISSUES), this.#vendorTool("details"));
         }
         return { op, params };
     }
@@ -460,7 +462,7 @@ export class OperationIndex {
             }
         }
         if (only !== undefined && parameters.length === 0 && body === undefined) {
-            invalid(`${op.method} ${op.path} has no parameter named ${only}.`);
+            invalid(`${op.method} ${op.path} has no parameter by that name.`);
         }
         return {
             method: op.method,
@@ -482,7 +484,6 @@ export class OperationIndex {
     check(op, query, body) {
         const row = this.#row(op);
         const issues = [];
-        const repair = [];
         const declared = (row ? row[0] : []).filter(([, at]) => at === "query");
         const accepted = declared.map(([name]) => name);
         for (const [name, value] of Object.entries(query)) {
@@ -491,40 +492,39 @@ export class OperationIndex {
             const param = declared.find(([key]) => key === name);
             if (!param) {
                 issues.push({
-                    path: `/query/${name}`,
-                    code: "additionalProperties",
+                    path: "/query/<key>",
                     expected: accepted.length ? oneOf(accepted, name) : "no query parameters",
+                    received: valueType(value),
                 });
-                repair.push({ path: `/query/${name}`, receivedType: valueType(value), acceptedKeys: accepted });
                 continue;
             }
-            this.#check(param[3], value, `/query/${name}`, issues, repair);
+            this.#check(param[3], value, `/query/${name}`, issues);
         }
         for (const [name, , required] of declared) {
             if (required === 1 && query[name] === undefined) {
-                issues.push({ path: `/query/${name}`, code: "required", expected: "a value" });
+                issues.push({ path: `/query/${name}`, expected: "a value (required)", received: "missing" });
             }
         }
         const bodyRow = row && row[1] !== 0 ? row[1] : undefined;
         if (body !== undefined) {
             if (!bodyRow) {
-                issues.push({ path: "/body", code: "false", expected: "no body for this operation" });
+                issues.push({ path: "/body", expected: "no body for this operation" });
             }
             else {
-                this.#check(bodyRow[1], body, "/body", issues, repair);
+                this.#check(bodyRow[1], body, "/body", issues);
             }
         }
         else if (bodyRow?.[2] === 1) {
             // An optional body may be omitted whole; a required one may not.
-            issues.push({ path: "/body", code: "required", expected: `a ${bodyRow[0]} body` });
+            issues.push({ path: "/body", expected: `a ${bodyRow[0]} body (required)`, received: "missing" });
         }
         if (issues.length > 0) {
             const shown = issues
                 .slice(0, 5)
-                .map((issue) => `${issue.path} (${issue.code}: ${issue.expected})`)
+                .map((issue) => issueSummary([issue]))
                 .join("; ");
             invalid(`Not sent: the arguments do not match ${op.method} ${op.path} in the pinned API index: ${shown}` +
-                `${issues.length > 5 ? `; ${issues.length - 5} more` : ""}. Read ${this.#vendorTool("details")} for the contract.`, issues.slice(0, MAX_ISSUES), repair.length ? { issues: repair.slice(0, 5) } : undefined);
+                `${issues.length > 5 ? `; ${issues.length - 5} more` : ""}. Read ${this.#vendorTool("details")} for the contract.`, issues.slice(0, MAX_ISSUES), this.#vendorTool("details"));
         }
     }
     #vendorTool(kind) {
@@ -608,7 +608,7 @@ export class OperationIndex {
             out["truncated"] = true;
         return out;
     }
-    #check(node, value, at, issues, repair) {
+    #check(node, value, at, issues) {
         if (issues.length >= MAX_ISSUES)
             return;
         const schema = this.#deref(node);
@@ -626,7 +626,6 @@ export class OperationIndex {
                 (integer && !Number.isSafeInteger(numeric))) {
                 issues.push({
                     path: at,
-                    code: "type",
                     expected: integer ? "a canonical ASCII decimal safe integer" : "a canonical ASCII decimal number",
                 });
                 return;
@@ -637,7 +636,7 @@ export class OperationIndex {
             if (types.includes("boolean") && (value === "true" || value === "false"))
                 value = value === "true";
             else {
-                issues.push({ path: at, code: "type", expected: types.join(" or ") });
+                issues.push({ path: at, expected: types.join(" or ") });
                 return;
             }
         }
@@ -646,7 +645,7 @@ export class OperationIndex {
         // Conflicting composed constraints (disjoint enums or types) admit nothing,
         // not even the null or "" that otherwise unsets a field.
         if (schema.e?.length === 0) {
-            issues.push({ path: at, code: "enum", expected: "no value: this field's combined constraints admit none" });
+            issues.push({ path: at, expected: "no value: this field's combined constraints admit none" });
             return;
         }
         // Only newly opted-in bounded schemas enforce scalar numeric values;
@@ -663,42 +662,40 @@ export class OperationIndex {
                     ? Number(value)
                     : NaN;
             if (!Number.isFinite(numeric) || (integer && !Number.isSafeInteger(numeric))) {
-                issues.push({ path: at, code: "type", expected: integer ? "integer" : "finite number" });
+                issues.push({ path: at, expected: integer ? "integer" : "finite number" });
                 return;
             }
             if (schema.l !== undefined && numeric < schema.l)
-                issues.push({ path: at, code: "minimum", expected: `at least ${schema.l}` });
+                issues.push({ path: at, expected: `at least ${schema.l}`, received: "number" });
             if (schema.u !== undefined && numeric > schema.u)
-                issues.push({ path: at, code: "maximum", expected: `at most ${schema.u}` });
+                issues.push({ path: at, expected: `at most ${schema.u}`, received: "number" });
         }
         if (value === null || value === "")
             return;
         if (schema.a) {
             let fewest;
             for (const branch of schema.a) {
-                const attempt = { issues: [], repair: [] };
-                this.#check(branch, value, at, attempt.issues, attempt.repair);
-                if (attempt.issues.length === 0)
+                const attempt = [];
+                this.#check(branch, value, at, attempt);
+                if (attempt.length === 0)
                     return;
-                if (!fewest || attempt.issues.length < fewest.issues.length)
+                if (!fewest || attempt.length < fewest.length)
                     fewest = attempt;
             }
-            if (fewest) {
-                issues.push(...fewest.issues);
-                repair.push(...fewest.repair);
-            }
+            if (fewest)
+                issues.push(...fewest);
             return;
         }
         if (schema.e && (typeof value === "string" || typeof value === "number" || typeof value === "boolean")) {
             if (!schema.e.some((option) => option === value || String(option) === String(value))) {
-                issues.push({ path: at, code: "enum", expected: oneOf(schema.e.map(String)) });
+                issues.push({ path: at, expected: oneOf(schema.e.map(String)) });
             }
             return;
         }
         if (schema.p || types.includes("object")) {
             if (!isRecord(value)) {
                 if (types.length === 0 || types.includes("object")) {
-                    issues.push({ path: at, code: "type", expected: "object" });
+                    issues.push({ path: at, expected: "object" });
                 }
                 return;
             }
@@ -709,35 +706,34 @@ export class OperationIndex {
                     continue;
                 const child = properties[key];
                 if (child)
-                    this.#check(child, item, `${at}/${key}`, issues, repair);
+                    this.#check(child, item, `${at}/${key}`, issues);
                 else if (schema.m)
-                    this.#check(schema.m, item, `${at}/${key}`, issues, repair);
+                    this.#check(schema.m, item, `${at}/<key>`, issues);
                 else if (schema.p) {
                     issues.push({
-                        path: `${at}/${key}`,
-                        code: "additionalProperties",
+                        path: `${at}/<key>`,
                         expected: accepted.length ? oneOf(accepted, key) : "no properties",
+                        received: valueType(item),
                     });
-                    repair.push({ path: `${at}/${key}`, receivedType: valueType(item), acceptedKeys: accepted });
                 }
             }
             for (const key of schema.r ?? []) {
                 if (value[key] === undefined)
-                    issues.push({ path: `${at}/${key}`, code: "required", expected: "a value" });
+                    issues.push({ path: `${at}/${key}`, expected: "a value (required)", received: "missing" });
             }
             return;
         }
         if (schema.i || types.includes("array")) {
             if (!Array.isArray(value)) {
-                issues.push({ path: at, code: "type", expected: "array" });
+                issues.push({ path: at, expected: "array" });
                 return;
             }
             if (schema.i)
-                value.forEach((item, index) => this.#check(schema.i, item, `${at}/${index}`, issues, repair));
+                value.forEach((item, index) => this.#check(schema.i, item, `${at}/${index}`, issues));
             return;
         }
         if (types.length > 0 && (isRecord(value) || Array.isArray(value))) {
-            issues.push({ path: at, code: "type", expected: types.join(" or ") });
+            issues.push({ path: at, expected: types.join(" or ") });
         }
     }
 }