@zackbart/connecta 0.29.0 → 0.31.0

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

@@ -3,6 +3,15 @@ import type { CatalogDriftReport } from "../types.js";
 import type { CredentialManagementCapability, UiConnector, UiData, UiProblem } from "./model.js";
 import type { FixPromptKind } from "./fix-prompts.js";
 export declare function registrationPathLabel(path: NonNullable<UiConnector["registrationPath"]>): string;
+/**
+ * A connector's source column: the maintained provider with the
+ * implementation it uses, since a dual provider's `auth` selects either the
+ * vendor's hosted MCP server or Connecta's REST connector.
+ */
+export declare function connectorSourceLabel(source: {
+    kind: string;
+    provider?: string;
+}): string;
 export type OperatorPage = "overview" | "tools" | "access" | "config" | "connector" | "tokens" | "connections" | "activity";
 /** Pages the nav lists. */
 export declare const OPERATOR_PAGES: readonly OperatorPage[];

package/dist/operator-ui/view.js

@@ -14,6 +14,17 @@ const REGISTRATION_LABELS = {
 export function registrationPathLabel(path) {
     return REGISTRATION_LABELS[path];
 }
+/**
+ * A connector's source column: the maintained provider with the
+ * implementation it uses, since a dual provider's `auth` selects either the
+ * vendor's hosted MCP server or Connecta's REST connector.
+ */
+export function connectorSourceLabel(source) {
+    if (!source.provider)
+        return source.kind;
+    const implementation = source.kind === "remote-mcp" ? "hosted MCP" : source.kind === "api" ? "REST" : source.kind;
+    return `${source.provider} · ${implementation}`;
+}
 /** Pages the nav lists. */
 export const OPERATOR_PAGES = [
     "overview",

package/dist/program-result.js

@@ -0,0 +1,5 @@
+/** Shared transport policy, independent of any optional executor implementation. */
+export const PROGRAM_RESULT_INLINE_BYTES = 1024 * 1024;
+/** Leave room for the bridge envelope and six-character JSON escapes per byte. */
+export const PROGRAM_RESULT_PAGE_BYTES = 32 * 1024;
+export const PROGRAM_RESULT_WIRE_BYTES = 240 * 1024;

package/dist/program-writes.js

@@ -3,55 +3,10 @@
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import { Effect } from "effect";
 import { jsonResult } from "./meta-tools.js";
+import { classifyWriteOutcome } from "./write-outcome.js";
+export { classifyWriteOutcome } from "./write-outcome.js";
 /** Writes one program may send (`execute.maxWrites`), unless configured. */
 export const DEFAULT_MAX_WRITES = CONFIG_DEFAULTS.execute.maxWrites;
-/**
- * Whether a write landed, as far as anyone can know.
- *
- * `unknown` is the outcome a result must never paper over: the call left
- * connecta and no answer came back, so sending it again could do it twice and
- * not sending it could leave it undone. That is a dispatched call that timed
- * out, was cancelled, found the service unavailable, or failed any way that
- * is not a verdict. A refusal code (`REFUSALS`) or a downstream tool's own
- * `isError` is an answer, so it is `failed`. Response text does not decide
- * whether an outcome is unknown. A call that was never dispatched is
- * `failed`: nothing was sent.
- * `result_processing_failed` means the downstream call completed.
- */
-export function classifyWriteOutcome(outcome) {
-    if (outcome.ok)
-        return "ok";
-    if (!outcome.dispatched)
-        return "failed";
-    const code = outcome.error?.code;
-    if (code === "result_processing_failed")
-        return "ok";
-    if (code === "timeout" || code === "cancelled" || code === "unavailable") {
-        return "unknown";
-    }
-    if (code !== undefined && REFUSALS.has(code))
-        return "failed";
-    return outcome.answered === true ? "failed" : "unknown";
-}
-/**
- * Codes that say the other side refused the call rather than acted on it:
- * the credential, the arguments, the resource, the rate, or a base version
- * someone else already moved past (`conflict`). Anything else a
- * connector reports after dispatch — `connector_call_failed` from a response
- * too large to read, a redirect it would not follow, a body it could not
- * parse, a 5xx — may come after the write landed, so only a downstream
- * tool's own `isError` answer makes it a known failure.
- */
-const REFUSALS = new Set([
-    "auth_required",
-    "downstream_oauth_required",
-    "provider_permission_denied",
-    "invalid_args",
-    "not_found",
-    "rate_limited",
-    "input_required_unsupported",
-    "conflict",
-]);
 /** What a dispatched write's outcome says about whether it landed. */
 export function writeStateOf(outcome) {
     const state = classifyWriteOutcome(outcome.ok
@@ -104,6 +59,10 @@ export class ProgramWrites {
     get isClosed() {
         return this.closed;
     }
+    /** Whether a dispatched write completed successfully in this run. */
+    get hasSucceeded() {
+        return this.states.includes("ok");
+    }
     close() {
         this.closed = true;
     }
@@ -151,7 +110,7 @@ export class ProgramWrites {
         if (writes.unknown > 0) {
             return errorEnvelope({
                 code: "write_outcome_unknown",
-                message: "A write this program sent has no known outcome, so 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.",
+                message: "A write this program sent has no known outcome, so 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. Argument echoes may be partial or absent; use the original arguments if reconciliation requires another call.",
                 retryable: false,
                 ...(this.deadlines.length > 0 ? { details: this.deadlines[0] } : {}),
                 ...(this.deadlines.length > 1 ? { timeouts: this.deadlines } : {}),

package/dist/provider.d.ts

@@ -2,10 +2,12 @@ import { type Field } from "./config-schema.js";
 import type { Connector, ConnectorCallAdmissionPolicy, ConnectorUsageGuide, ToolClassification } from "./types.js";
 /**
  * How a provider reaches its vendor: the vendor's hosted MCP server, an
- * `api()` connector over the vendor's HTTP API, or one connector composing
- * both with an explicit operation ownership map.
+ * `api()` connector over the vendor's HTTP API, one connector composing both
+ * with an explicit operation ownership map, or `"dual"`: the configured
+ * `auth.type` selects the implementation, OAuth reaching the hosted MCP server
+ * and a key reaching Connecta's REST connector.
  */
-export type ProviderKind = "mcp" | "api" | "composed";
+export type ProviderKind = "mcp" | "api" | "composed" | "dual";
 /** Options every provider accepts, validated before `create` runs. */
 export interface ProviderOptions {
     /** What this connection is for and which decisions it answers. Required. */
@@ -35,11 +37,11 @@ export declare const PROVIDER_COMMON: {
             maxPartitions: Field<unknown, unknown, true>;
         };
     };
+    instructions: Field<unknown, unknown, true>;
     title: Field<unknown, unknown, true>;
     authScope: Field<unknown, unknown, true>;
     maxResultBytes: Field<unknown, unknown, true>;
     purpose: Field<unknown, unknown, true>;
-    instructions: Field<unknown, unknown, true>;
 };
 /** The provider's maintained, connection-independent usage guide. */
 export interface ProviderSkill {
@@ -105,8 +107,8 @@ export interface ProviderDefinition<O extends ProviderOptions> {
     /** Closed factory options, declared with `optionsOf<O>()` for key parity. */
     options: Field<unknown, unknown>;
     /**
-     * Reviewed classification of the vendor's hosted MCP catalog. Hosted and
-     * composed providers pass it to `remoteMcp({ classify })` through
+     * Reviewed classification of the vendor's hosted MCP catalog. Hosted,
+     * composed, and dual providers pass it to `remoteMcp({ classify })` through
      * `ProviderContext.classify`, so the verdicts that classify live tools and
      * the record a drift check reads cannot disagree. `api()` providers annotate
      * each tool they author and must omit it.

package/dist/provider.js

@@ -20,7 +20,7 @@ export const PROVIDER_COMMON = {
     callAdmission: CALL_ADMISSION,
 };
 const PROVIDER_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-const KINDS = new Set(["mcp", "api", "composed"]);
+const KINDS = new Set(["mcp", "api", "composed", "dual"]);
 function nonEmpty(value) {
     return typeof value === "string" && value.trim() !== "";
 }
@@ -40,7 +40,7 @@ export function defineProvider(definition) {
         throw new Error(`${label} requires a non-empty title.`);
     }
     if (!KINDS.has(definition.kind)) {
-        throw new Error(`${label} kind must be "mcp", "api", or "composed".`);
+        throw new Error(`${label} kind must be "mcp", "api", "composed", or "dual".`);
     }
     if (!nonEmpty(definition.skill?.content) || !nonEmpty(definition.skill.instructionsHeading)) {
         throw new Error(`${label} skill requires non-empty content and instructionsHeading.`);
@@ -180,8 +180,7 @@ function providerConstructionError(provider, id, error) {
         .replace(/^requires\s+/, "")
         .replace(/^must be /, "")
         .replace(/^(.+) must be /, "$1 to be ")
-        .replace(/^declares /, "a consistent declaration of ")
-        .replace(/^with headers or credential auth requires /, "headers or credential auth to declare ");
+        .replace(/^declares /, "a consistent declaration of ");
     error.message = `${at} requires ${detail}`;
     return error;
 }

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

@@ -109,12 +109,12 @@ export declare const GOOGLE_WORKSPACE_OPTIONS: import("../../../config-schema.js
                 maxPartitions: import("../../../config-schema.js").Field<unknown, unknown, true>;
             };
         };
+        instructions: import("../../../config-schema.js").Field<unknown, unknown, true>;
         title: import("../../../config-schema.js").Field<unknown, unknown, true>;
         maxResultBytes: 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>;
         purpose: import("../../../config-schema.js").Field<unknown, unknown, true>;
-        instructions: import("../../../config-schema.js").Field<unknown, unknown, true>;
     };
 };
 /** The checked, construction-time half of {@link GoogleWorkspaceOptions}. */

package/dist/providers/_shared/request-token.js

@@ -0,0 +1,83 @@
+/** In-memory tokens and credential-bound login flights shared only inside one request. */
+import { ConnectorCallError } from "../../errors.js";
+const LOGIN_TIMEOUT_MS = 15_000;
+const MAX_CACHED_TOKENS = 512;
+/** Each provider instance owns its cache, so no credential crosses an API origin. */
+export function requestTokenCache(source) {
+    const tokens = new Map();
+    const requests = new WeakMap();
+    function start(auth, ctx) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new ConnectorCallError("unavailable", "Machine identity login timed out.")), LOGIN_TIMEOUT_MS);
+        const flight = { controller, waiters: 0, settled: false, promise: Promise.resolve("") };
+        flight.promise = auth
+            .mint({ ...ctx, signal: controller.signal })
+            .then((minted) => {
+            // An abandoned login must not seed a token after cancellation.
+            controller.signal.throwIfAborted();
+            tokens.delete(auth.key);
+            tokens.set(auth.key, minted);
+            while (tokens.size > MAX_CACHED_TOKENS)
+                tokens.delete(tokens.keys().next().value);
+            return minted.accessToken;
+        })
+            .finally(() => {
+            flight.settled = true;
+            clearTimeout(timer);
+        });
+        // All waiters may cancel before the transport observes its abort.
+        void flight.promise.catch(() => { });
+        return flight;
+    }
+    async function follow(flight, signal) {
+        signal?.throwIfAborted();
+        flight.waiters++;
+        let onAbort;
+        try {
+            const aborted = new Promise((_, reject) => {
+                if (!signal)
+                    return;
+                onAbort = () => reject(signal.reason);
+                signal.addEventListener("abort", onAbort, { once: true });
+            });
+            return await Promise.race([flight.promise, aborted]);
+        }
+        finally {
+            if (onAbort)
+                signal?.removeEventListener("abort", onAbort);
+            flight.waiters--;
+            if (!flight.settled && flight.waiters === 0)
+                flight.controller.abort();
+        }
+    }
+    return {
+        async token(ctx, rejected) {
+            ctx.signal?.throwIfAborted();
+            const auth = await source(ctx);
+            ctx.signal?.throwIfAborted();
+            const cached = tokens.get(auth.key);
+            if (cached && cached.accessToken !== rejected && cached.expiresAt > Date.now())
+                return cached.accessToken;
+            const scope = ctx.requestScope ?? ctx;
+            let perCredential = requests.get(scope);
+            if (!perCredential) {
+                perCredential = new Map();
+                requests.set(scope, perCredential);
+            }
+            let request = perCredential.get(auth.key);
+            if (!request) {
+                request = {};
+                perCredential.set(auth.key, request);
+            }
+            if (rejected !== undefined) {
+                // Keep the recovery outcome for the request, including failures. Later
+                // 401s can never turn this into a fresh-login loop.
+                request.recovery ??= start(auth, ctx);
+                return await follow(request.recovery, ctx.signal);
+            }
+            if (!request.initial || request.initial.settled || request.initial.controller.signal.aborted)
+                request.initial = start(auth, ctx);
+            return await follow(request.initial, ctx.signal);
+        },
+    };
+}

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

@@ -0,0 +1,41 @@
+// Auth selects the implementation (decisions/0005): a `"dual"` provider sends
+// OAuth to the vendor's hosted MCP server and a key to Connecta's own REST
+// connector. The choice is made once, at construction, from `auth.type`; one
+// connector id is one implementation, and a failure on one is never replayed
+// against the other (INV-9).
+import { remoteMcp } from "../../../connectors/remote-mcp.js";
+/**
+ * A provider `create` that dispatches on `options.auth.type`. Pair it with
+ * `variants(["auth", "type"], …)` options, which refuse a missing or unknown
+ * type, and options the selected case does not accept, before this runs.
+ */
+export function byAuth(cases) {
+    return (id, options, provider) => {
+        const type = options.auth?.type;
+        const create = typeof type === "string" && Object.hasOwn(cases, type) ? cases[type] : undefined;
+        if (!create) {
+            throw new Error(`auth.type must be one of ${Object.keys(cases)
+                .map((name) => JSON.stringify(name))
+                .join(", ")}.`);
+        }
+        return create(id, options, provider);
+    };
+}
+/**
+ * The vendor's hosted MCP server, OAuth only: no bearer token, header, or
+ * operator credential reaches a hosted endpoint. The provider's reviewed
+ * classification classifies its catalog.
+ */
+export function hostedOAuth(id, provider, options) {
+    return remoteMcp(id, {
+        url: options.url,
+        ...provider.connectorOptions,
+        title: options.title,
+        description: options.description,
+        auth: { type: "oauth" },
+        requireHttps: true,
+        classify: provider.classify,
+        ...(options.callAdmission ? { callAdmission: options.callAdmission } : {}),
+        usageGuide: options.usageGuide,
+    });
+}

package/dist/providers/_shared/rest/operation-index.d.ts

@@ -0,0 +1,133 @@
+import type { JsonSchema } from "../../../types.js";
+export type RestMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * One request-side schema, compacted: `t` type, `e` enum, `f` format (only
+ * `binary`), `n` nullable, `d` description, `a` anyOf/oneOf, `p` properties,
+ * `r` required, `i` items, `m` additionalProperties, `x` truncated at the
+ * generation depth (unvalidated below), `$` a shared subtree.
+ */
+export interface SchemaNode {
+    readonly t?: string | readonly string[];
+    readonly e?: readonly unknown[];
+    readonly f?: string;
+    readonly n?: 1;
+    readonly d?: string;
+    readonly a?: readonly SchemaNode[];
+    readonly p?: Readonly<Record<string, SchemaNode>>;
+    readonly r?: readonly string[];
+    readonly i?: SchemaNode;
+    readonly m?: SchemaNode;
+    readonly x?: 1;
+    readonly $?: number;
+}
+/** `[method, path template, operationId, summary, tag index, server index?]` */
+type OperationRow = readonly [string, string, string, string, number, number?];
+/** What `scripts/generate-openapi.mjs` writes to `openapi.generated.ts`. */
+export interface OpenApiData {
+    /** The pinned document's URL. */
+    readonly source: string;
+    /** The pin: a tag, commit, or content hash. */
+    readonly revision: string;
+    /** `sha256:` digest of the pinned document's bytes. */
+    readonly digest: string;
+    /** The document's `info.version`; Stripe sends it as `Stripe-Version`. */
+    readonly version: string;
+    /** `[0]` is the default origin; later entries are per-operation servers. */
+    readonly servers: readonly string[];
+    readonly tags: readonly string[];
+    readonly ops: readonly OperationRow[];
+    /** JSON: `{ d: SchemaNode[], o: (0 | [params, body])[] }`, aligned with `ops`. */
+    readonly details: string;
+}
+export interface Operation {
+    readonly method: RestMethod;
+    /** The path template, e.g. `/v1/customers/{customer}`. */
+    readonly path: string;
+    readonly operationId: string;
+    readonly summary: string;
+    readonly tag: string;
+    /** A non-default origin this operation is served from, if any. */
+    readonly server: string | undefined;
+    /** Position in `OpenApiData.ops`. */
+    readonly row: number;
+}
+/** A concrete call matched to its operation. */
+export interface OperationMatch {
+    readonly op: Operation;
+    /** Path parameter values, exactly as the caller sent them. */
+    readonly params: Readonly<Record<string, string>>;
+}
+/** One operation's request contract, expanded to JSON Schema for an agent. */
+export interface OperationContract {
+    method: RestMethod;
+    path: string;
+    operationId: string;
+    summary: string;
+    server?: string;
+    parameters: {
+        name: string;
+        in: "path" | "query";
+        required: boolean;
+        description?: string;
+        schema: JsonSchema;
+    }[];
+    body?: {
+        contentType: string;
+        required?: true;
+        schema: JsonSchema;
+    };
+}
+/** The read side of one vendor's pinned index. */
+export declare class OperationIndex {
+    #private;
+    readonly version: string;
+    readonly revision: string;
+    readonly ops: readonly Operation[];
+    /** The methods any operation uses, in a stable order. */
+    readonly methods: readonly RestMethod[];
+    /**
+     * `vendor` is the tool-name prefix; `title` the display name in refusals.
+     * `slashParams` names path parameters whose values may carry an encoded
+     * "/" (`%2F`), such as an object key, and only as the path's last segment.
+     */
+    constructor(data: OpenApiData, names: {
+        vendor: string;
+        title: string;
+        slashParams?: readonly string[];
+    });
+    /** The operation with this exact method and path template, if any. */
+    operation(method: string, template: string): Operation | undefined;
+    /**
+     * Match a concrete call to its operation. Literal segments outrank
+     * parameters, as OpenAPI requires (`/v1/customers/search` before
+     * `/v1/customers/{customer}`); the most specific template that fits decides,
+     * and a method it does not define is refused rather than retried against a
+     * looser template.
+     */
+    resolve(method: string, path: string): OperationMatch;
+    /** Up to five operations whose paths most resemble a missed one. */
+    nearest(method: string, segments: readonly string[]): string[];
+    /**
+     * Rank operations for a free-text query: every query word must appear in
+     * the path, summary, operationId, or tag (plural-insensitive, prefixes of
+     * three letters count), and path matches weigh most. A query that starts
+     * with "/" also matches the templates that fit it.
+     */
+    search(query: string, options: {
+        method?: RestMethod;
+        limit: number;
+    }): Operation[];
+    /** Whether the operation takes a body, and in which framing. */
+    bodyType(op: Operation): string | undefined;
+    /** The operation's request contract as JSON Schema, optionally one parameter only. */
+    contract(op: Operation, only?: string): OperationContract;
+    /**
+     * Check query and body names, required members, enums, and object/array
+     * shapes against the operation, to the depth the index carries. Scalars are
+     * not type-policed beyond that: vendors coerce form strings, and a wrong
+     * number is the vendor's to explain. `null` and `""` pass anywhere, since
+     * they are how form APIs unset a field.
+     */
+    check(op: Operation, query: Readonly<Record<string, unknown>>, body: unknown): void;
+}
+export {};