@zackbart/connecta 0.24.3 → 0.25.0

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

@@ -1,151 +0,0 @@
-import type { CatalogDriftReport } from "../types.js";
-import type { CredentialManagementCapability, UiData } from "./model.js";
-/**
- * Everything the operator app knows, and every rule for changing it, with no
- * DOM in sight. The components render this and nothing else, so the questions
- * that matter — what a page shows while it loads, what an identity change
- * erases, whether a value may become an href — are answered by functions a test
- * can call directly rather than by reading rendered markup back out of a
- * browser.
- */
-export type OperatorPage = "connections" | "activity";
-export declare const OPERATOR_PAGES: readonly OperatorPage[];
-export declare const PAGE_META: Readonly<Record<OperatorPage, {
-    path: string;
-    label: string;
-}>>;
-export declare function pageForPath(path: string): OperatorPage;
-export interface UiActivityActor {
-    kind?: string;
-    id?: string;
-    namespace?: string;
-    label?: string;
-}
-export interface UiActivityEvent {
-    occurredAt: string;
-    actor?: UiActivityActor;
-    connectorId: string;
-    toolName: string;
-    address: string;
-    source: string;
-    outcome: string;
-    durationMs: number;
-    attempts: number;
-    errorCode?: string;
-    friction?: string;
-}
-/** A message with the tone that decides its live region: status or alert. */
-export interface Notice {
-    message: string;
-    tone: "info" | "error";
-}
-export declare function info(message: string): Notice;
-export declare function failure(message: string): Notice;
-/**
- * A remote collection's four states, named once so every page spells them the
- * same way. `idle` is "nobody has asked yet" and is what makes a re-entered
- * page fetch again after an identity change.
- */
-type LoadPhase = "idle" | "loading" | "ready" | "error";
-export interface OperatorState {
-    page: OperatorPage;
-    /**
-     * Bumped by every identity change. Async work captures it before awaiting and
-     * throws its result away if the operator is no longer the one who asked —
-     * the fence that keeps one identity's data off another identity's screen.
-     */
-    generation: number;
-    /** `loading` until the first /ui/data answer decides gated or ready. */
-    session: "loading" | "gated" | "ready";
-    gate: Notice | null;
-    /** True while a signed-in operator's /ui/data is in flight. */
-    refreshing: boolean;
-    /**
-     * Element id the next render should focus. A rebuilt page has no stable node
-     * to hand focus to from an event handler, so the request travels through
-     * state and the shell spends it once the new markup exists.
-     */
-    pendingFocus: string | null;
-    data: UiData | null;
-    connectorFilter: string;
-    oauthNotice: Notice | null;
-    /** Connector id whose OAuth mutation is in flight. */
-    oauthBusy: string | null;
-    credentialNotice: Notice | null;
-    /** Connector id whose credential form is open. */
-    credentialEditing: string | null;
-    /** Connector id whose credential mutation is in flight. */
-    credentialBusy: string | null;
-    activityPhase: LoadPhase;
-    activityNotice: Notice | null;
-    activityEvents: UiActivityEvent[];
-    activityCursor: string | null;
-    activitySearch: string;
-}
-export declare function initialState(page: OperatorPage): OperatorState;
-/**
- * Drop to the gate and forget the previous operator. Bumping the generation is
- * what makes the drop stick: work already in flight for the old identity
- * resolves into a state that no longer accepts it.
- */
-export declare function resetIdentity(state: OperatorState, gate?: Notice | null): OperatorState;
-/**
- * Leaving a page closes what should not survive it: a one-time secret, a half
- * typed credential, and the notices that answered the page just left.
- */
-export declare function withPage(state: OperatorState, page: OperatorPage): OperatorState;
-export declare function credentialUnavailableCopy(capability?: CredentialManagementCapability): string;
-export declare function connectorStatusLabel(status: string): string;
-export declare function toolCountLabel(count: number): string;
-/**
- * Hosted-provider catalog drift, as an operator reads it
- * ([#343](https://github.com/zackbart/connecta/issues/343)).
- *
- * - `unavailable` — no refresh has been observed in this runtime, so there is
- *   nothing to report. Deliberately not `clean`: "we have not looked" and "we
- *   looked and it matches" are different answers, and only one of them is a
- *   reason to stop worrying.
- * - `clean` — a refresh happened and every category counted zero.
- * - `warning` — a refresh happened and at least one category did not.
- */
-export type DriftState = "clean" | "warning" | "unavailable";
-export declare function driftTotal(drift?: CatalogDriftReport): number;
-export declare function driftState(drift?: CatalogDriftReport): DriftState;
-/** Every category with its count, so a clean report still shows its zeros. */
-export declare function driftCounts(drift?: CatalogDriftReport): Array<{
-    key: string;
-    label: string;
-    count: number;
-}>;
-/** One line naming the state and when it was observed. Never what drifted. */
-export declare function driftSummary(drift?: CatalogDriftReport): string;
-/**
- * Only http/https may become a clickable href — the browser half of the gate
- * `src/ui.ts` applies before an authorizationUrl is ever serialized. A hostile
- * downstream that gets a `javascript:` URL past one of them still meets the
- * other, and the caller renders inert text instead of a link.
- */
-export declare function safeHttpHref(url: string | undefined): string | null;
-/** Locale timestamp, or "" for anything that is not a readable date. */
-export declare function formatDate(value?: string): string;
-export declare function actorLabel(actor?: UiActivityActor): string;
-/**
- * The stable id behind a friendly label, shown only when a label or namespace
- * could otherwise make two different people look like one.
- */
-export declare function actorStableId(actor?: UiActivityActor): string | null;
-export declare function filterActivity(events: UiActivityEvent[], query: string): UiActivityEvent[];
-/** Counts only. What the deployment ran, never what it sent or received. */
-export declare function activitySummary(events: UiActivityEvent[]): string;
-export declare function activityOutcomeClass(outcome: string): string;
-/** The one-line detail under an address: source, retries, and friction. */
-export declare function activityDetail(event: UiActivityEvent): string;
-export declare function credentialStateLabel(credential: {
-    configured: boolean;
-    fields?: unknown[];
-    lastFour?: string;
-    updatedAt?: string;
-}): string;
-/** Gate copy for each browser-auth shape, so the sign-in state is never a blank page. */
-export declare function gateCopy(kind: string, signedIn: boolean): string;
-export {};

package/dist/result-shapes.d.ts

@@ -1,13 +0,0 @@
-import type { JsonSchema, ToolDef } from "./types.js";
-/**
- * Passive, process-local output-shape learning. Provider declarations always
- * win; observations are an open, optional-field routing aid and never a
- * replacement contract.
- */
-export declare class ObservedOutputSchemas {
-    private readonly entries;
-    private cacheKey;
-    private set;
-    get(connectorId: string, definition: ToolDef): JsonSchema | undefined;
-    observe(connectorId: string, definition: ToolDef, value: unknown): void;
-}

package/dist/retired-toolkits.d.ts

@@ -1,2 +0,0 @@
-/** Fail loudly when JavaScript callers pass the retired audience-scoping keys. */
-export declare function assertNoRetiredToolkitOptions(source: string, options: object): void;

package/dist/routes/activity.d.ts

@@ -1,2 +0,0 @@
-import { type RouteContext } from "./shared.js";
-export declare function routeActivity(context: RouteContext): Promise<Response | null>;

package/dist/routes/credentials.d.ts

@@ -1,2 +0,0 @@
-import { type RouteContext } from "./shared.js";
-export declare function routeCredentials(context: RouteContext): Promise<Response | null>;

package/dist/routes/mcp.d.ts

@@ -1,10 +0,0 @@
-import { type RouteContext, type ServerOptions } from "./shared.js";
-export declare const MCP_CORS_HEADERS: {
-    "Access-Control-Allow-Origin": string;
-    "Access-Control-Allow-Methods": string;
-    "Access-Control-Allow-Headers": string;
-};
-export declare function createMcpRoute(opts: ServerOptions): {
-    handle(context: RouteContext): Promise<Response | null>;
-    rejectOrigin(request: Request): Response | null;
-};

package/dist/routes/oauth-management.d.ts

@@ -1,2 +0,0 @@
-import { type RouteContext } from "./shared.js";
-export declare function routeOAuthManagement(context: RouteContext): Promise<Response | null>;

package/dist/routes/oauth.d.ts

@@ -1,2 +0,0 @@
-import { type RouteContext } from "./shared.js";
-export declare function routeOAuthCallback(context: RouteContext): Promise<Response | null>;

package/dist/routes/ui.d.ts

@@ -1,2 +0,0 @@
-import { type RouteContext } from "./shared.js";
-export declare function routeUi(context: RouteContext): Promise<Response | null>;

package/dist/server.d.ts

@@ -1,9 +0,0 @@
-import { type RuntimeExecutionContext, type ServerOptions } from "./routes/shared.js";
-export type { ServerOptions } from "./routes/shared.js";
-/**
- * Build the Web-standard fetch handler.
- *
- * Route ordering is the contract: private mutation routes precede wildcard
- * OPTIONS, and the security wrapper is applied to every response, including 404s.
- */
-export declare function createFetchHandler(opts: ServerOptions): (request: Request, runtimeContext?: RuntimeExecutionContext) => Promise<Response>;

package/dist/skills.d.ts

@@ -1,44 +0,0 @@
-import type { Connector } from "./types.js";
-export declare const CONNECTA_INSTRUCTIONS = "Choose a route before discovery. A known-address read needs only call_tool. Unknown-address read-only work starts with execute_code to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Inspect unfamiliar result shapes with a small sample before proceeding. Only readOnlyHint: true tools run there. Keep catalog inspection and unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool when a call is needed. After auth_required use authorize_connector. After a truncated direct result use get_result. Guidance is on demand: fetch skills({ name: \"usage\" }) only when these instructions and the tool description are insufficient or a run needs repair.";
-/** Shared Connecta routing guidance, byte-identical across deployments. */
-export declare const USAGE_SKILL: string;
-/** The always-loaded MCP `instructions` string. */
-export declare function instructionsFor(): string;
-/** True when at least one of `connectors` carries a usage guide. */
-export declare function hasConnectorGuides(connectors: readonly Connector[]): boolean;
-/** The skill name that fetches `connector`'s guide. */
-export declare function connectorSkillName(connectorId: string): string;
-/** The connector's guide, or undefined when it declares none (or a blank one). */
-export declare function connectorGuide(connector: Connector): string | undefined;
-/** Discovery budget for one connector-guide summary, including an ellipsis. */
-export declare const GUIDE_SUMMARY_LENGTH = 120;
-/** Normalize authored and derived summaries under one construction contract. */
-export declare function normalizeGuideSummary(summary: string): string | undefined;
-/** Bounded, decision-useful discovery summary for a connector guide. */
-export declare function connectorGuideSummary(connector: Connector): string | undefined;
-/** Whether correct use always depends on conventions outside the tool schema. */
-export declare function connectorGuideRequired(connector: Connector): boolean;
-export interface SkillListing {
-    name: string;
-    description: string;
-}
-/**
- * Every fetchable skill: the built-in guides plus one entry per connector that
- * carries a usage guide. Derived from the connector list passed in — the single
- * place guide visibility is decided.
- */
-export declare function listSkills(connectors: readonly Connector[]): SkillListing[];
-export type SkillLookup = {
-    found: true;
-    content: string;
-} | {
-    found: false;
-    message: string;
-};
-/**
- * Resolve one skill name. Built-in names match exactly; connector guides are
- * reachable only through the `connector:` prefix. Every miss — unknown name,
- * unknown connector, connector without a guide — is an explicit error, never a
- * silent fallback to the generic guide.
- */
-export declare function resolveSkill(name: string, connectors: readonly Connector[]): SkillLookup;

package/dist/timeout.d.ts

@@ -1,21 +0,0 @@
-/**
- * Generous default bound for a single downstream probe/catalog call. High enough
- * to trip only on a pathological hang, not a realistically slow probe.
- */
-export declare const DEFAULT_PROBE_TIMEOUT_MS = 30000;
-/** A finite, positive integer number of milliseconds, or undefined. */
-export declare function normalizeTimeoutMs(value: number | undefined): number | undefined;
-/** Resolve after `ms`, or false when the caller aborts first. */
-export declare function sleep(ms: number, signal?: AbortSignal): Promise<boolean>;
-export interface DeadlineOptions {
-    timeoutMs?: number;
-    signal?: AbortSignal;
-    timeoutError: Error;
-}
-export declare function withDeadline<T>(operation: (signal: AbortSignal) => Promise<T>, options: DeadlineOptions): Promise<T>;
-/**
- * Give one operation a caller-facing deadline and the matching cancellation
- * signal. The timeout rejects with the stable, labelled error while aborting
- * any in-flight work that honors the signal.
- */
-export declare function withAbortableTimeout<T>(operation: (signal: AbortSignal) => Promise<T>, ms: number, label: string): Promise<T>;

package/dist/tool-safety.d.ts

@@ -1,9 +0,0 @@
-import type { ToolDef } from "./types.js";
-/**
- * The one fail-closed classification shared by discovery and invocation.
- *
- * A tool is read-only only when it says so without also saying it is
- * destructive. Missing, false, and contradictory annotations all require the
- * approval-visible call path.
- */
-export declare function isExplicitlyReadOnly(definition: ToolDef): boolean;

package/documentation/call-admission.md

@@ -1,158 +0,0 @@
-# Downstream call admission
-
-One admitted MCP request can fan out into many downstream calls. A program
-calls tools from loops, from parallel `connecta.call` calls, and from branches the caller
-never saw. The deployment-wide request pool
-([request admission](./request-admission.md)) bounds the envelope; it cannot
-see anything inside it. A provider that publishes "60 requests per minute"
-needs a bound that counts calls, not requests.
-
-So a connector may declare `callAdmission`: an optional per-runtime policy
-around its own `Connector.callTool` attempts.
-
-```ts
-const projects = api("projects", {
-  description: "Projects — issues and reports",
-  callAdmission: {
-    // Plural-ready public shape; this release requires exactly one rule.
-    rules: [{
-      maxConcurrency: 5,
-      maxQueueSize: 10,       // default 32
-      queueTimeoutMs: 2_000,  // default 5_000
-      retryAfterMs: 1_000,    // concurrency-overload hint
-      budget: { kind: "rolling-window", maxCalls: 60, windowMs: 60 * 60_000 },
-      partitionKey({ toolName, args }) {
-        return projectIdFor(toolName, args);
-      },
-    }],
-    maxPartitions: 1_024,     // default
-  },
-  tools: [/* … */],
-});
-```
-
-`api()`, `remoteMcp()`, and a hand-written `Connector` all accept it. Maintained
-prebuilt connections set it themselves — but only when the provider documents a
-number, which is convention
-[P12](./provider-conventions.md#p12--declare-an-admission-budget-only-when-the-provider-documents-a-number).
-An invented budget is a throttle with no source.
-
-## Policy contract
-
-`maxConcurrency` and `budget` are independently optional, but a rule must
-declare at least one — a rule that bounds nothing is a typo, not a policy.
-Queue settings require `maxConcurrency`, because there is nothing to queue
-behind without it, and `maxQueueSize: 0` is the fail-fast shape. Numeric bounds
-are finite whole numbers: concurrency, timeouts, budget values, and
-`maxPartitions` are positive; queue size and `retryAfterMs` may be zero.
-`budget.kind` must be `"rolling-window"`. Everything invalid throws during
-registry construction.
-
-The container is an array so a later release can add atomic rules over
-different partition dimensions, but **exactly one rule** is accepted today.
-Zero or several throw rather than imply semantics the runtime does not have.
-Multiple rules cannot be faked as sequential leases: consuming one rolling
-token before a later rule refuses would charge a call that never reached the
-provider — the exact accounting error a budget exists to prevent.
-
-Omitting `partitionKey` gives one connector-wide partition. A callback runs
-synchronously on model-supplied arguments and must return a non-secret string
-of at most 128 UTF-8 bytes. A throw or an invalid return is a typed local
-`connector_call_failed`; neither the callback text nor the arguments are
-surfaced. The callback is operator code and may abort the caller synchronously,
-so cancellation is rechecked after it returns — otherwise a cancelled call
-could still consume a budget entry.
-
-State retains the returned key, bounded timestamps, counters, signals, and
-promise continuations. Nothing copies arguments into the limiter; the queued
-waiter closure deliberately captures the `AbortSignal` rather than the input
-object, because closing over the input would retain its `args`. At most
-`maxPartitions` states are live, and an idle state is evicted only once its
-active calls, queue, and rolling-window history are all empty — eviction must
-not be a way to reset a live budget. Exhausted partition capacity is
-`rate_limited` with the configured retry hint, not a silent unbounded map.
-
-## Attempt semantics
-
-The registry owns the limiter, and `InvocationService.invoke` acquires a permit
-immediately before `Connector.callTool` and releases it in `finally`. Both call
-paths, top-level `call_tool` and program calls through `connecta.call`,
-reach that same seam, so a program cannot buy itself a
-second limit by taking the other route.
-
-- **A caller retry is another call.** It reacquires and can consume another
-  budget entry. Connecta returns retry hints without waiting or retrying.
-- **A proactive short-window `rate_limited` refusal** returns its retry hint
-  without waiting or dispatching. Activity records one failed admission attempt;
-  a caller may reissue after the window.
-- **A queued cancellation consumes nothing.** It is removed from the queue with
-  no rolling-window entry charged.
-- **Caller cancellation is terminal.** It is non-retryable, releases its
-  permit, records a `cancelled` activity outcome, and is not connector-health
-  evidence.
-- **Budget exhaustion fails immediately** as `rate_limited`, `retryable: true`,
-  with the exact `retryAfterMs` to the next free slot. Concurrency overflow
-  uses the configured hint instead, because there is no exact answer.
-- **Local refusals are not connector health failures.** They are activity
-  errors, but no provider call happened, so poisoning the connector's health
-  with them would report the limiter's success as the downstream's failure.
-  `isCallAdmissionError` is what keeps `recordFailure` out of that path.
-
-Only tool execution is covered. Catalog `listTools`, status probes, credential
-checks, and authorization operations stay outside the budget: they are not the
-calls a provider is rate-limiting, and charging discovery for them would make
-a program's first search cost it capacity to act.
-
-`queueTimeoutMs` bounds only the wait for a permit. The per-call `timeoutMs`
-is one deadline over catalog resolution, the permit wait, and the connector
-call together, so a saturated call can never take longer than `timeoutMs`;
-the queue timeout may only end it sooner. With
-`diagnostics: true`, `admissionMs` reports the permit wait and `connectorMs`
-the admitted attempt — which is the only way to tell "the provider is slow"
-from "we are throttling ourselves".
-
-## Enforcement scope
-
-Shared connectors use the root registry's controller. Personal connectors use
-the owning principal's registry, so two accounts each receive their own budget;
-all requests and call paths for one principal still share it. `close()` rejects
-queued and future admissions on both kinds of controller, including a personal
-registry constructed after shutdown.
-
-The principal cache is bounded at 1,024 registries. Eviction closes an idle
-registry so an older request view cannot use an orphaned controller. A registry
-with active calls, queued calls, or unexpired rolling entries is never evicted.
-If all 1,024 are occupied, a new principal view fails closed with HTTP 403 until
-one drains. Cache churn cannot reset a live account's quota.
-
-This is deliberately **per-runtime**. It completely contains fan-out inside one
-request, including parallel `connecta.call` calls in one Worker isolate. A rolling
-budget is exact inside one Node process or Worker isolate, and best-effort
-across isolates, replicas, and restarts.
-
-KV cannot coordinate the invariant without atomic operations, and this release
-adds no Durable Object or other distributed coordinator. The async typed permit
-is the seam a coordinator would slot into later; until then the guide says what
-the bound actually is rather than implying a global one.
-
-## Observations
-
-`/health` exposes one payload-free aggregate at
-`admission.downstreamCalls.aggregate`, summed across root and retained personal
-controllers: rule and retained partition counts, current
-active and queued gauges, cumulative admitted/queued/rejected/rate-limited/
-cancelled counts, and queue-wait count, total, and maximum. The open endpoint
-never exposes connector ids, principal ids, partition keys, tool arguments, or results — a partition key can
-be a customer identifier, which is precisely why it stays out of an unauthenticated
-payload. Queue-wait maxima take the maximum, other counters sum, and `closed`
-means every included controller is closed. Evicted idle controllers no longer
-contribute to these runtime snapshots. Ordinary payload-free activity records the final call outcome and its
-typed error code.
-
-## Tests that enforce this
-
-| Invariant | Suite |
-| --- | --- |
-| Independent partitions, exact rolling-window reset and retry, queued cancellation charging no budget, synchronous cancel during partition derivation, validated values snapshotted rather than read from mutable config, bounded partition state and contained `partitionKey` failures, empty and multi-rule policies refused | `test/call-admission.test.ts` (controller) |
-| Shared and personal limiters shared by direct and program calls, independent principal budgets, shutdown covering both, eviction preserving live budgets, promise concurrency with input order preserved, cancellation threading, no dispatch or retry or health poisoning after cancellation, retry hints returned without waiting or poisoning health, payload-free `/health` aggregates | `test/call-admission.test.ts` (integration, Node + Workers) |
-| Where provider budgets are allowed to come from at all | [provider conventions P12](./provider-conventions.md#p12--declare-an-admission-budget-only-when-the-provider-documents-a-number), [provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md) |