@zackbart/connecta 0.28.1 → 0.29.0

package/dist/provider.d.ts

@@ -0,0 +1,142 @@
+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.
+ */
+export type ProviderKind = "mcp" | "api" | "composed";
+/** Options every provider accepts, validated before `create` runs. */
+export interface ProviderOptions {
+    /** What this connection is for and which decisions it answers. Required. */
+    purpose: string;
+    /** Display name; each provider chooses its own default. */
+    title?: string;
+    /** Deployment conventions, appended after the maintained guide. */
+    instructions?: string;
+    /** Downstream auth ownership. Defaults to one shared deployment grant. */
+    authScope?: "shared" | "personal";
+    /** Connector-specific inline result limit; omit to inherit the deployment. */
+    maxResultBytes?: number;
+    /** Optional per-runtime downstream call-admission policy. */
+    callAdmission?: ConnectorCallAdmissionPolicy;
+}
+export declare const CALL_ADMISSION: Field<unknown, unknown, true> & {
+    readonly shape: {
+        rules: Field<unknown[], readonly unknown[] | undefined, true>;
+        maxPartitions: Field<unknown, unknown, true>;
+    };
+};
+/** Options every maintained provider shares. */
+export declare const PROVIDER_COMMON: {
+    callAdmission: Field<unknown, unknown, true> & {
+        readonly shape: {
+            rules: Field<unknown[], readonly unknown[] | undefined, true>;
+            maxPartitions: 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 {
+    /**
+     * Markdown rendered after the heading and the connection context. It states
+     * conventions the vendor's schemas cannot carry, and never varies by
+     * deployment.
+     */
+    content: string;
+    /** Heading for deployment instructions, such as `"Workspace instructions"`. */
+    instructionsHeading: string;
+    /** Exact generated guide fragments used by existing renderers. */
+    fragments?: Readonly<Record<string, string>>;
+}
+/** Connection facts a provider renders around its maintained guide. */
+export interface ProviderGuideInput {
+    /**
+     * Paragraphs that lead the guide: access mode, purpose, region, account
+     * scope. The first is what discovery summarizes when `summary` is omitted.
+     */
+    context: readonly string[];
+    /** Replaces the default `<title> usage` heading. */
+    heading?: string;
+    /** Discovery summary; see `ConnectorUsageGuide.summary`. */
+    summary?: string;
+    /** See `ConnectorUsageGuide.required`. */
+    required?: boolean;
+}
+/** What `defineProvider()` hands `create` after validating its options. */
+export interface ProviderContext {
+    /** The definition's reviewed classification, for `remoteMcp({ classify })`. */
+    readonly classify?: ToolClassification;
+    /**
+     * Common connector options the deployment set, and only those, ready to
+     * spread into `remoteMcp()` or `api()` options.
+     */
+    readonly connectorOptions: Readonly<Pick<ProviderOptions, "authScope" | "maxResultBytes" | "callAdmission">>;
+    /**
+     * Render the maintained skill with this connection's context and the
+     * deployment's instructions. Instructions are appended; they never replace
+     * the maintained text.
+     */
+    usageGuide(input: ProviderGuideInput): ConnectorUsageGuide;
+}
+export interface ProviderDefinition<O extends ProviderOptions> {
+    /**
+     * Stable lowercase name: the `providers/<name>` subpath and the default
+     * factory name in construction errors.
+     */
+    name: string;
+    /** Vendor display name, and the default guide heading. */
+    title: string;
+    kind: ProviderKind;
+    skill: ProviderSkill;
+    /** Maintained display name in the generated README inventory. */
+    readme?: string;
+    /** Reviewed build facts; generation never raises an observed cap. */
+    bundle?: {
+        baselineGzip: number;
+        maxGzip: number;
+        note?: string;
+    };
+    /** 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
+     * `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.
+     */
+    classify?: ToolClassification;
+    /**
+     * Build the connector. Runs synchronously at construction after its closed
+     * options and common values are validated. Throw here for provider-specific
+     * mistakes.
+     */
+    create(id: string, options: Readonly<O>, provider: ProviderContext): Connector;
+}
+/** A provider's factory, carrying the definition build and check tools read. */
+export interface ProviderFactory<O extends ProviderOptions> {
+    (id: string, options: O): Connector;
+    readonly definition: Readonly<ProviderDefinition<O>>;
+}
+/**
+ * Define a maintained provider: one validated description and one factory.
+ *
+ * Definition mistakes throw when the provider module loads. Closed-option
+ * and common-value mistakes throw before `create` runs,
+ * so a deployment never boots in the wrong shape (INV-11).
+ */
+export declare function defineProvider<O extends ProviderOptions>(definition: ProviderDefinition<O>): ProviderFactory<O>;
+/**
+ * Attach the same validated definition to an existing provider constructor.
+ * Its option policy stays in its builder during the mechanical folder move;
+ * adopting defineProvider's common-value policy is a separate conversion.
+ */
+export declare function asProviderFactory<O extends ProviderOptions>(definition: Omit<ProviderDefinition<O>, "create"> & {
+    create(id: string, options: Readonly<O>): Connector;
+}): ProviderFactory<O>;

package/dist/provider.js

@@ -0,0 +1,187 @@
+// The one shape every maintained provider takes. Deliberately transport-free:
+// it imports neither `remoteMcp()` nor `api()`, so an `api()` provider does not
+// acquire the MCP client, OAuth, or Effect graph by using it, and a hosted
+// provider does not acquire `api()`. Its runtime imports validate plain
+// options and reviewed classification, with no I/O.
+import { array, assertKnownOptions, keys, optionsOf } from "./config-schema.js";
+import { reviewedClassification } from "./catalog-drift.js";
+const budget = optionsOf()(keys("kind", "maxCalls", "windowMs"));
+const admissionRule = optionsOf()({
+    ...keys("maxConcurrency", "maxQueueSize", "queueTimeoutMs", "retryAfterMs", "partitionKey"),
+    budget,
+});
+export const CALL_ADMISSION = optionsOf()({
+    ...keys("maxPartitions"),
+    rules: array(admissionRule),
+});
+/** Options every maintained provider shares. */
+export const PROVIDER_COMMON = {
+    ...keys("title", "authScope", "purpose", "instructions", "maxResultBytes"),
+    callAdmission: CALL_ADMISSION,
+};
+const PROVIDER_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const KINDS = new Set(["mcp", "api", "composed"]);
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+/**
+ * Define a maintained provider: one validated description and one factory.
+ *
+ * Definition mistakes throw when the provider module loads. Closed-option
+ * and common-value mistakes throw before `create` runs,
+ * so a deployment never boots in the wrong shape (INV-11).
+ */
+export function defineProvider(definition) {
+    const label = `defineProvider("${String(definition?.name)}")`;
+    if (!nonEmpty(definition?.name) || !PROVIDER_NAME.test(definition.name)) {
+        throw new Error(`${label} name must be lowercase words joined by hyphens.`);
+    }
+    if (!nonEmpty(definition.title)) {
+        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".`);
+    }
+    if (!nonEmpty(definition.skill?.content) || !nonEmpty(definition.skill.instructionsHeading)) {
+        throw new Error(`${label} skill requires non-empty content and instructionsHeading.`);
+    }
+    if (definition.classify !== undefined && definition.kind === "api") {
+        throw new Error(`${label} is an api() provider; annotate each authored tool instead of classifying a hosted catalog.`);
+    }
+    if (!definition.options?.shape && !definition.options?.variants) {
+        throw new Error(`${label} requires a closed options shape from optionsOf().`);
+    }
+    // A validated, deep-frozen copy. The definition is what build and check
+    // tools read and what every later connector classifies with, so nothing
+    // reachable from it may change a verdict after review: neither the
+    // caller's original object nor a write through `factory.definition`.
+    const classify = definition.classify === undefined ? undefined : reviewedClassification(definition.classify, label);
+    if (typeof definition.create !== "function") {
+        throw new Error(`${label} requires a create function.`);
+    }
+    const frozen = Object.freeze({
+        ...definition,
+        skill: Object.freeze({
+            ...definition.skill,
+            ...(definition.skill.fragments ? { fragments: Object.freeze(definition.skill.fragments) } : {}),
+        }),
+        ...(definition.bundle ? { bundle: Object.freeze({ ...definition.bundle }) } : {}),
+        ...(classify !== undefined ? { classify } : {}),
+    });
+    const factoryName = `${frozen.name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())}()`;
+    const factory = (id, options) => asProvider(frozen.name, frozen.options, id, options, (id, options) => {
+        const at = `${factoryName.slice(0, -2)}(${JSON.stringify(id)})`;
+        if (typeof options !== "object" || options === null) {
+            throw new Error(`${factoryName} requires an options object.`);
+        }
+        if (!nonEmpty(options.purpose)) {
+            throw new Error(`${at} requires a non-empty purpose: what this connection is for and which decisions it answers.`);
+        }
+        if (options.title !== undefined && !nonEmpty(options.title)) {
+            throw new Error(`${at} title must be a non-empty string when set.`);
+        }
+        if (options.instructions !== undefined && typeof options.instructions !== "string") {
+            throw new Error(`${at} instructions must be a string when set.`);
+        }
+        if (options.authScope !== undefined && options.authScope !== "shared" && options.authScope !== "personal") {
+            throw new Error(`${at} authScope must be "shared" or "personal".`);
+        }
+        const resolved = { ...options, purpose: options.purpose.trim() };
+        const instructions = options.instructions?.trim();
+        const connector = frozen.create(id, resolved, {
+            ...(frozen.classify !== undefined ? { classify: frozen.classify } : {}),
+            connectorOptions: {
+                ...(options.authScope !== undefined ? { authScope: options.authScope } : {}),
+                ...(options.maxResultBytes !== undefined ? { maxResultBytes: options.maxResultBytes } : {}),
+                ...(options.callAdmission !== undefined ? { callAdmission: options.callAdmission } : {}),
+            },
+            usageGuide(input) {
+                const heading = input.heading ?? `${frozen.title} usage`;
+                const body = [...input.context, frozen.skill.content.trim()].join("\n\n");
+                return {
+                    content: `# ${heading}\n\n${body}\n` +
+                        (instructions ? `\n## ${frozen.skill.instructionsHeading}\n\n${instructions}\n` : ""),
+                    ...(input.summary !== undefined ? { summary: input.summary } : {}),
+                    ...(input.required === true ? { required: true } : {}),
+                };
+            },
+        });
+        if (connector?.id !== id) {
+            throw new Error(`${at} create() must return a connector with id "${id}".`);
+        }
+        return connector;
+    });
+    // Frozen whole: build and check tools read `definition` to learn what the
+    // factory classifies, so neither replacing nor deleting it may take effect.
+    return Object.freeze(Object.assign(factory, { definition: frozen }));
+}
+/**
+ * Attach the same validated definition to an existing provider constructor.
+ * Its option policy stays in its builder during the mechanical folder move;
+ * adopting defineProvider's common-value policy is a separate conversion.
+ */
+export function asProviderFactory(definition) {
+    const frozen = defineProvider(definition).definition;
+    const create = definition.create;
+    const factory = (id, options) => asProvider(frozen.name, frozen.options, id, options, create);
+    Object.defineProperty(factory, "name", {
+        value: frozen.name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase()),
+    });
+    return Object.freeze(Object.assign(factory, { definition: frozen }));
+}
+/**
+ * Build a maintained provider's connector: refuse unknown options and
+ * accessors by path before the builder reads any of them, then stamp the
+ * provider onto its description, so the operator surface can say "Linear"
+ * rather than "remote MCP". This is the same construction path defineProvider
+ * uses; existing constructors retain their provider-specific option policy.
+ */
+function asProvider(provider, shape, id, options, build) {
+    // The factory a deployment called: "planning-center" is planningCenter().
+    const factory = provider.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    let connector;
+    try {
+        options = assertKnownOptions(options, `${factory}(${JSON.stringify(id)})`, shape);
+        connector = build(id, options);
+    }
+    catch (error) {
+        throw providerConstructionError(factory, id, error);
+    }
+    const describe = connector.describe?.bind(connector);
+    const ownDescribe = Object.getOwnPropertyDescriptor(connector, "describe");
+    // Keep the receiver of prototype methods (including private fields). When
+    // the description cannot be replaced, inherit the whole connector instead
+    // of copying it: decorators may inherit their id, methods, and review.
+    const stamped = Object.isExtensible(connector) && (!ownDescribe || ownDescribe.configurable)
+        ? connector
+        : Object.create(connector);
+    Object.defineProperty(stamped, "describe", {
+        configurable: true,
+        enumerable: false,
+        value: () => {
+            const base = describe?.() ?? { source: { kind: "custom" } };
+            return { ...base, source: { ...base.source, provider } };
+        },
+    });
+    return stamped;
+}
+/** Keep vendor-specific refusals in one construction-error format. */
+function providerConstructionError(provider, id, error) {
+    if (!(error instanceof Error))
+        return error;
+    const at = `${provider}(${JSON.stringify(id)})`;
+    // The same helper handles legacy provider validation and shared config
+    // validation. Retain the original error class and the actionable detail.
+    const prefix = error.message.startsWith(at) ? at : error.message.startsWith(`${provider}()`) ? `${provider}()` : "";
+    const detail = error.message
+        .slice(prefix.length)
+        .trimStart()
+        .replace(/^\./, "")
+        .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 ");
+    error.message = `${at} requires ${detail}`;
+    return error;
+}

package/dist/providers/_shared/google/result-size.js

@@ -0,0 +1,57 @@
+/**
+ * How big one tool result may be, measured the way it is delivered: as UTF-8
+ * JSON. Every Workspace read must reach the agent both ways it can be called.
+ * Inside `execute_code` the QuickJS bridge refuses any single host result over
+ * 256 KiB (`MAX_HOST_RESULT_BYTES` in `src/executors/quickjs-runtime.ts`);
+ * through `call_tool` a large result is stashed and paged, up to the
+ * deployment's stash size (8 MiB by default). A result built to stay under
+ * {@link RESULT_BUDGET_BYTES} clears both, so a product never has to know which
+ * route called it. Shared by the Workspace products; never its own export.
+ *
+ * The budget leaves 64 KiB of the bridge's 256 for the envelope a tool adds
+ * around its rows — page objects, counts, ids — so a product sizes its rows
+ * against this and its envelope never needs measuring.
+ */
+/** The size one Workspace result is built to stay under, in UTF-8 JSON bytes. */
+export const RESULT_BUDGET_BYTES = 192 * 1024;
+const encoder = new TextEncoder();
+/** The UTF-8 length of a value's JSON — what both delivery routes measure. */
+export function jsonBytes(value) {
+    const json = JSON.stringify(value);
+    return json === undefined ? 0 : encoder.encode(json).length;
+}
+/**
+ * `text` cut so that its JSON string encoding — quotes and escapes included —
+ * takes at most `maxBytes` UTF-8 bytes, with `marker(dropped)` appended when
+ * anything was cut. The cut never splits a surrogate pair, and the marker is
+ * counted inside the bound, so the result always fits.
+ */
+export function clampText(text, maxBytes, marker) {
+    if (jsonBytes(text) <= maxBytes)
+        return text;
+    const fits = (length) => {
+        const cut = safePrefix(text, length);
+        return jsonBytes(cut + marker(text.length - cut.length)) <= maxBytes;
+    };
+    // The largest prefix that fits, by binary search over its length.
+    let low = 0;
+    let high = text.length;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (fits(middle))
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    const cut = safePrefix(text, low);
+    const clamped = cut + marker(text.length - cut.length);
+    // A marker longer than the bound itself leaves nothing honest to return
+    // but the cut alone, which is empty here.
+    return jsonBytes(clamped) <= maxBytes ? clamped : "";
+}
+/** The first `length` UTF-16 units, minus a dangling high surrogate. */
+function safePrefix(text, length) {
+    const cut = text.slice(0, length);
+    const last = cut.charCodeAt(cut.length - 1);
+    return last >= 0xd800 && last <= 0xdbff ? cut.slice(0, -1) : cut;
+}

package/dist/providers/_shared/google/service-account.d.ts

@@ -0,0 +1,58 @@
+import type { ConnectorContext } from "../../../types.js";
+/**
+ * The two fields of a Google service-account JSON key that delegation needs.
+ * Copy them from the downloaded key file, or pass the file's whole JSON text
+ * instead and let the provider read it.
+ */
+export interface GoogleServiceAccount {
+    /** The key's `client_email`, `name@project.iam.gserviceaccount.com`. */
+    clientEmail: string;
+    /**
+     * The key's `private_key`: a PKCS#8 PEM, `-----BEGIN PRIVATE KEY-----`. An
+     * environment variable that kept the JSON's `\n` escapes literally is
+     * accepted as written.
+     */
+    privateKey: string;
+    /**
+     * The key's `client_id`, the number the Admin console's domain-wide
+     * delegation page asks for. Optional; when known, a refused grant names it.
+     */
+    clientId?: string;
+}
+/** A parsed, construction-checked key. Its fields never reach a message. */
+export interface ServiceAccountKey {
+    readonly clientEmail: string;
+    readonly clientId: string | undefined;
+    /** PKCS#8 DER of an RSA key, decoded and checked once at construction. */
+    readonly der: Uint8Array<ArrayBuffer>;
+}
+/**
+ * Check a service account at construction: the object form, or the JSON key
+ * file's text. Structural mistakes throw here, so a deployment never boots into
+ * a connector whose every call would fail.
+ */
+export declare function parseServiceAccount(owner: string, input: unknown): ServiceAccountKey;
+/** One delegated token request: whose account, acting as whom, for what. */
+export interface DelegatedTokenRequest {
+    account: ServiceAccountKey;
+    subject: string;
+    scopes: readonly string[];
+}
+/**
+ * An access token for this subject and scope set: the cached one while it has
+ * more than a minute left, otherwise one fresh mint shared by every concurrent
+ * caller asking for the same key.
+ *
+ * Followers share only a scalar outcome and a deadline. The owner records
+ * what happened inside its own request — a token, Google's refusal, or
+ * `abandoned` for anything else — and a follower that hears `abandoned`, or
+ * reaches the deadline first, mints for itself. A refusal is rebuilt for each
+ * follower from its code and message, never handed over as the owner's object.
+ */
+export declare function delegatedToken(request: DelegatedTokenRequest, ctx: ConnectorContext): Promise<string>;
+/**
+ * Drop a token the API has just rejected, so the next request mints anew —
+ * but only that token. A 401 that arrives after a newer token replaced it
+ * leaves the newer one alone.
+ */
+export declare function forgetDelegatedToken(request: DelegatedTokenRequest, rejected: string): Promise<void>;