@zackbart/connecta 0.30.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-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

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. */
@@ -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/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 {};