@zackbart/connecta 0.28.1 → 0.30.0

package/dist/types.d.ts

@@ -1,37 +1,69 @@
+import type { CallErrorDetails } from "./errors.js";
 /** A JSON Schema object describing a tool's input. */
 export type JsonSchema = Record<string, unknown>;
-/** Minimal key/value store — the only state connecta needs. */
+/**
+ * Minimal key/value store — the only state connecta needs. Keys and list
+ * prefixes must not contain U+0000 (NUL); adapters reject them with TypeError
+ * before accessing storage. SQL TEXT results truncate at NUL on Node 22.
+ */
 export interface KVStorage {
+    /**
+     * Explicit adapter opt-in: both `set` and `compareAndSet` honor
+     * `expiresAtMs`, including delayed commits. `createConnecta` rejects adapters
+     * without this capability. Declare it only after implementing that contract.
+     */
+    readonly capabilities: {
+        readonly absoluteExpiry: true;
+    };
+    /** The live value at `key`; null when absent or expired. */
     get(key: string): Promise<string | null>;
+    /**
+     * Write `value`. With `opts.ttlSeconds` the entry reads as absent once that
+     * many seconds pass; omitted or zero means no expiry. Shared stores must
+     * create and check relative expiry with a storage-owned clock. `expiresAtMs`
+     * instead sets an absolute, safe-integer epoch-millisecond expiry, including
+     * for a delayed commit. Adapters must honor it without restarting a TTL at
+     * commit time. Supply at most one of these options; a past absolute expiry
+     * writes an already-expired value.
+     */
     set(key: string, value: string, opts?: {
         ttlSeconds?: number;
+        expiresAtMs?: number;
     }): Promise<void>;
     delete(key: string): Promise<void>;
-    /**
-     * Sorted keys beginning with `prefix`. Optional for existing adapters;
-     * subsystems that need independent, enumerable records require it explicitly.
-     */
-    list?(prefix: string): Promise<string[]>;
+    /** Live keys beginning with `prefix`, sorted by UTF-16 code unit. */
+    list(prefix: string): Promise<string[]>;
     /**
      * Atomic compare-and-set: write `next` only if the key's current value is
      * exactly `expected`, and report whether the write happened. `expected:
      * null` means "absent", and an expired entry is absent. `next: null`
-     * deletes; otherwise `next` is stored with `options.ttlSeconds`, or with no
-     * expiry when that is omitted, exactly as `set` would. On `false` nothing
+     * deletes; otherwise `next` takes the relative or absolute expiry options
+     * exactly as `set` would, or no expiry when both are omitted. On `false` nothing
      * changed.
      *
      * Atomic means linearizable against every other operation on the same
      * store, `set` and `delete` included: of N concurrent `compareAndSet(key,
      * null, value)` claims on an absent key, exactly one returns true.
      *
-     * Optional, because not every backend can promise it: an eventually
-     * consistent store such as Cloudflare Workers KV must omit the method
-     * rather than emulate it with a read followed by a write. Subsystems that
-     * need an atomic claim require it explicitly.
-     */
-    compareAndSet?(key: string, expected: string | null, next: string | null, options?: {
+     * Required. Every subsystem that must claim a key exactly once relies on
+     * it, and none of them carries a read-then-write fallback. The shipped
+     * adapters are `memoryStorage()`, `d1Storage()` from
+     * `@zackbart/connecta/d1`, and `sqliteStorage()` from
+     * `@zackbart/connecta/sqlite`; an eventually consistent store such as
+     * Cloudflare Workers KV cannot implement it and is not supported.
+     */
+    compareAndSet(key: string, expected: string | null, next: string | null, options?: {
         ttlSeconds?: number;
+        expiresAtMs?: number;
     }): Promise<boolean>;
+    /**
+     * Which adapter this is, for `Connecta.describeConfig()`. The shipped
+     * adapters answer `"memory"`, `"d1"`, or `"sqlite"`; any other answer, or
+     * none, is described as `"custom"`. Never a path, binding, or value.
+     */
+    describe?(): {
+        kind: string;
+    };
 }
 export interface Logger {
     debug(...args: unknown[]): void;
@@ -40,16 +72,30 @@ export interface Logger {
     error(...args: unknown[]): void;
 }
 export interface ToolDef {
+    /** Final verdict on a request-scoped published catalog entry. Never persisted. */
+    classification?: "read" | "write";
     name: string;
     description?: string;
+    /** Downstream display metadata retained with the catalog. */
+    title?: string;
+    icons?: Array<{
+        src: string;
+        mimeType?: string;
+        sizes?: string[];
+        theme?: "light" | "dark";
+    }>;
+    /** Downstream execution requirements, enforced even on a cached catalog. */
+    execution?: {
+        taskSupport?: "required" | "optional" | "forbidden";
+    };
     inputSchema?: JsonSchema;
     /** Optional JSON Schema describing the tool's structured result. */
     outputSchema?: JsonSchema;
     /**
      * Standard MCP tool behavior hints plus provider-specific extensions.
-     * Connecta fails closed: only readOnlyHint === true (without a contradictory
-     * destructiveHint) may use call_tool or execute_code. Every other tool must
-     * cross the call_destructive_tool approval boundary.
+     * The registry classifies these after deployment overrides and provider
+     * review. Only a stored read verdict may use call_tool; program writes
+     * require a trusted pool. Approval belongs to the host.
      */
     annotations?: ToolAnnotations;
 }
@@ -82,7 +128,7 @@ export interface ConnectorRollingWindowBudget {
  * pretending multi-rule admission is already atomic.
  */
 export interface ConnectorCallAdmissionRule {
-    /** Maximum simultaneous Connector.callTool attempts in one partition. */
+    /** Maximum simultaneous tool calls and resource reads in one partition. */
     maxConcurrency?: number;
     /** Callers allowed to wait behind the concurrency bound. Default 32. */
     maxQueueSize?: number;
@@ -150,9 +196,9 @@ export interface ConnectorCredentialConfig {
 export interface CredentialTestResult {
     ok: boolean;
     /**
-     * Detail for the deployment's log. The operator page shows fixed copy for
-     * `ok` and never this text, since a downstream's reply quoted here can
-     * quote the credential it rejected.
+     * Shown and logged nowhere: a downstream's reply quoted here can quote the
+     * credential it rejected (INV-6). The operator page shows fixed copy for
+     * `ok`, and the log records only that a test failed.
      */
     message?: string;
 }
@@ -164,6 +210,10 @@ export interface ConnectorContext {
     logger: Logger;
     /** Public base URL of this deployment (origin), used for OAuth callbacks. */
     baseUrl: string;
+    /** Fixed deployment configuration, independent of the request Host. */
+    publicUrl?: string;
+    /** Deployment name used in downstream client metadata. */
+    oauthClientName?: string;
     /**
      * Read-only access to this connector's human-managed credential. Present
      * only when the connector declares `credential` and the deployment configures
@@ -182,17 +232,59 @@ export interface ConnectorContext {
     requestScope?: object;
     /** Best-effort cancellation signal for this connector operation. */
     signal?: AbortSignal;
+    /** Runtime hook keeping a dispatched OAuth refresh alive through its commit. */
+    defer?: (promise: Promise<unknown>) => void;
     /** Requested connector-operation deadline in milliseconds. */
     timeoutMs?: number;
 }
-type ConnectorStatusState = "ok" | "auth_required" | "error";
+type ConnectorStatusState = "ok" | "auth_required" | "credential_required" | "error";
+/**
+ * What a reviewed downstream tool does. `"read"` is observational. `"write"`
+ * changes state without destroying any that already exists, such as a create.
+ * `"destructive"` modifies or removes existing state, including an upsert that
+ * can overwrite. Both writes leave the read-only path; `"destructive"` also
+ * asserts `destructiveHint`, which shapes the approval copy a human reads.
+ */
+export type ToolVerdict = "read" | "write" | "destructive";
+/** One reviewed tool, with the evidence that justifies its verdict. */
+export interface ReviewedTool {
+    readonly verdict: ToolVerdict;
+    /** Why the verdict holds when the name or downstream annotations do not say. */
+    readonly reason?: string;
+    /**
+     * `sha256:<hex>` digest of the input and output schemas the review read.
+     * Omit until a review has actually read them; an invented digest reports
+     * drift that never happened. When the live schema no longer matches it, or
+     * it cannot be checked, the verdict lapses and the tool is served as a write.
+     */
+    readonly schemaDigest?: string;
+}
+/**
+ * A reviewed classification of a downstream MCP catalog, keyed by exact tool
+ * name. Plain data, validated at construction, so the same record classifies
+ * live tools and feeds the drift check. A connector carries it as
+ * `Connector.classification`, and the registry applies it on every read.
+ *
+ * It fails closed. A name it does not list keeps only an explicit downstream
+ * read annotation; silence and contradiction classify as writes. A listed read
+ * fills downstream silence but never overrules an explicit write annotation.
+ * A listed write or destructive tool stays a write whatever the downstream
+ * claims. A listed tool whose `schemaDigest` no longer matches is a write.
+ */
+export interface ToolClassification {
+    /** Hide every name absent from tools, including tools claiming to be reads. */
+    readonly unlisted?: "hide";
+    readonly tools: Readonly<Record<string, ToolVerdict | ReviewedTool>>;
+}
 /**
  * How far a downstream catalog has moved away from the manifest a release
- * reviewed. Four numbers and nothing else: names, schemas, and prose stay out
+ * reviewed. Counts and nothing else: names, schemas, and prose stay out
  * of every surface this rides on, so a drift report can never become a payload
  * ([#343](https://github.com/zackbart/connecta/issues/343)).
  */
 export interface CatalogDriftCounts {
+    /** Downstream tools dropped because their names contain C0, DEL, or C1. */
+    droppedTools?: number;
     /** Live tools no release classified. Each one fails closed at call time. */
     unclassifiedTools: number;
     /** Classified names this catalog no longer serves — plan gating included. */
@@ -213,7 +305,10 @@ export interface CatalogAccessObservation {
     state: "fresh" | "stale";
     observedAt: string;
 }
+export type ResourceTemplateRefusalCode = "resource_template_ambiguous" | "resource_match_budget_exceeded";
 export interface ConnectorStatus {
+    /** Distinct host-observed refusal codes, without URI or template text. */
+    resourceTemplateRefusals?: ResourceTemplateRefusalCode[];
     state: ConnectorStatusState;
     /** When state === "auth_required", the URL the operator should open. */
     authorizationUrl?: string;
@@ -222,6 +317,15 @@ export interface ConnectorStatus {
      * authorization URL instead of starting a new flow. Absent otherwise.
      */
     authorizationReused?: boolean;
+    /** The client registration mechanism actually selected for this grant. */
+    registrationPath?: "cimd" | "dcr" | "static";
+    /**
+     * From `startAuth()`, the message reaches the agent. From `status()`, it is
+     * never logged, and `Registry.statusFor` keeps it only when connecta wrote
+     * it: a custom connector's `status()` contributes its state alone, since
+     * its text can quote a downstream (INV-6). Connecta's connectors describe a
+     * failed status from its typed record.
+     */
     message?: string;
     /**
      * Drift observed the last time this connector served a catalog refresh *in
@@ -237,6 +341,27 @@ export interface ConnectorStatus {
      */
     catalogAccess?: CatalogAccessObservation;
 }
+/** A downstream skill's verbatim frontmatter and complete file manifest. */
+export interface ConnectorSkill {
+    uri: string;
+    frontmatter: Record<string, unknown>;
+    resources: "dynamic" | Array<{
+        uri: string;
+        digest: string;
+        size: number;
+    }>;
+}
+/** Resource bytes before the agent boundary, with exactly one encoding. */
+export type ConnectorSkillResourceContents = {
+    uri: string;
+    mimeType?: string;
+} & ({
+    text: string;
+    blob?: never;
+} | {
+    blob: string;
+    text?: never;
+});
 /** The whole plugin contract — the one open seam. */
 export interface Connector {
     id: string;
@@ -250,29 +375,17 @@ export interface Connector {
     title?: string;
     /** How call_tool wraps results. "mcp" passes the content array through; anything else is JSON-wrapped. */
     kind?: "mcp" | "api";
-    /**
-     * This connector's own default for its tools that are not explicitly
-     * read-only, inside `execute_code`: `"never"` lets a program call them
-     * without asking for approval. Reserved for connectors connecta ships
-     * whose writes are cheap to undo (the artifacts connector, whose
-     * every write is a new immutable version); a deployment's own connectors
-     * leave it unset and exempt through `execute.approval`, which overrides
-     * this either way. Never read from a downstream catalog — a server cannot
-     * exempt its own tools — and never makes a tool read-only anywhere else.
-     */
-    approval?: "never";
     description?: string;
     /**
      * Max inline result size (bytes) for this connector's tools before
-     * call_tool truncates and stashes the full text for get_result
+     * call_tool truncates and stashes the full text for connecta.result
      * paging. Overrides `ConnectaConfig.calls.maxResultBytes`;
      * omit to inherit it (which itself defaults to 24_000). Must be a whole
-     * number of bytes >= 1; anything else warns at startup and is ignored, so
-     * the connector inherits the deployment-wide cap.
+     * number of bytes >= 1; anything else refuses to construct.
      */
     maxResultBytes?: number;
     /**
-     * Optional per-runtime admission policy for downstream tool calls. It covers
+     * Optional per-runtime admission policy for downstream tool calls and resource reads. It covers
      * call_tool, call_destructive_tool, and every execute_code host call, but
      * not catalog/status/auth operations.
      */
@@ -284,11 +397,22 @@ export interface Connector {
      * cannot describe correct use (for example a generic API wrapper or a
      * cross-operation sequencing rule).
      *
-     * Listed by `skills` as `connector:<id>` and returned verbatim by
-     * `skills({ name: "connector:<id>" })`. The guide remains deployment-owned
-     * configuration; no runtime registration or shared mutable copy exists.
+     * Served as `skill://connecta/connectors/<slug>/SKILL.md`, with generated
+     * frontmatter followed by the unchanged guide body. `connector:<id>` is a
+     * one-release lookup alias. The guide remains deployment-owned configuration;
+     * no runtime registration or shared mutable copy exists.
      */
     usageGuide?: string | ConnectorUsageGuide;
+    /**
+     * Opted-in downstream Skills transport. The registry validates advertised
+     * URIs and manifest bounds before exposing these bytes to an agent. The host
+     * verifies preserved digests against the returned bytes. Neither
+     * operation registers tools or retains a catalog across requests.
+     */
+    downstreamSkills?: {
+        list(ctx: ConnectorContext): Promise<ConnectorSkill[]>;
+        read(uri: string, ctx: ConnectorContext): Promise<ConnectorSkillResourceContents[]>;
+    };
     /** Optional human-managed credential slot rendered in the connection in the operator UI. */
     credential?: ConnectorCredentialConfig;
     /** Optional server-side check used by the connection's Test action in the operator UI. */
@@ -301,21 +425,69 @@ export interface Connector {
      * fetched lazily over the network and are not known at construction time.
      */
     staticTools?: ToolDef[];
+    /**
+     * Optional reviewed classification of the tools `listTools` returns: data
+     * the registry applies, never something the connector applies itself.
+     * `remoteMcp({ classify })` and maintained providers set it to a
+     * deep-frozen record; a custom connector may set one too. It is validated
+     * when a registry first reads it (INV-11), and read once per connector
+     * object. A connector that sets it lists raw downstream tools; the
+     * registry caches and persists only that listing, and classifies it on
+     * every read with this record, so no cache layer carries a verdict.
+     * Connectors with `staticTools` cannot set it: annotate those directly.
+     *
+     * A wrapper that rebuilds a connector must forward this field to keep the
+     * review. `{ ...connector }`, `Object.assign`, and `Object.create` keep it;
+     * a forwarding class that omits it serves an unreviewed connector, whose
+     * downstream annotations are its own claims and fail closed when absent.
+     * Deployment-level classifier overrides, keyed by connector id
+     * and tool ([#706](https://github.com/zackbart/connecta/issues/706)), apply
+     * regardless of wrapping.
+     */
+    readonly classification?: ToolClassification | undefined;
     /**
      * Optional: the drift this connector saw the last time it listed tools,
-     * or undefined when it has not listed any yet. Implemented by maintained
-     * hosted-MCP proxies, which compare the live catalog with the manifest a
-     * release reviewed *while* serving a refresh the deployment already asked
-     * for. It is a getter over an observation, never a probe: calling it makes
-     * no request, touches no credential, and returns counts only.
+     * or undefined when it has not listed any yet. A getter over an
+     * observation, never a probe: calling it makes no request, touches no
+     * credential, and returns counts only. Ignored for a connector with a
+     * `classification`, whose drift the registry observes itself, against
+     * that record, while serving a refresh the deployment already asked for.
      */
     catalogDrift?(): CatalogDriftReport | undefined;
+    /**
+     * Optional: what this connector is, for `Connecta.describeConfig()` and the
+     * operator surfaces built on it — where it points, how it authenticates,
+     * and its static tools. Never a probe and never a secret: header names but
+     * no values, a credential slot's labels but never its contents, an
+     * endpoint's origin and path but no query or userinfo. `remoteMcp()`,
+     * `api()` and the maintained providers implement
+     * it; a custom connector without it is described as `{ source: { kind:
+     * "custom" } }`. Core copies only the fields named in
+     * `ConnectorDescription`, so anything else returned is dropped.
+     */
+    describe?(): ConnectorDescription;
     listTools(ctx: ConnectorContext): Promise<ToolDef[]>;
-    callTool(name: string, args: unknown, ctx: ConnectorContext): Promise<unknown>;
+    callTool(name: string, args: unknown, ctx: ConnectorContext, 
+    /** A fresh deep copy of the catalog definition for this dispatch. */
+    options?: {
+        definition?: ToolDef;
+        /** Verified direct-call continuation, never populated by a program. */
+        input?: {
+            requestState?: string;
+            inputResponses: Record<string, unknown>;
+        } | undefined;
+    }): Promise<unknown>;
+    /**
+     * Optional read-only downstream resource operation. The URI is an opaque
+     * argument to this configured connector, never a destination to fetch.
+     * Return the MCP-shaped `{ contents }` result. Programs require a grant to
+     * the whole connector; an exact-tool grant does not authorize resources.
+     */
+    readResource?(uri: string, ctx: ConnectorContext): Promise<unknown>;
     /**
      * Optional best-effort teardown for resources retained under
-     * `ctx.requestScope`. The core calls this at most once when a scope it created
-     * solely for probing ends, and never uses that scope again. Teardown gets a
+     * `ctx.requestScope`. The core calls this at most once when a probe or
+     * execute_code scope ends, and never uses that scope again. Teardown gets a
      * small, fixed best-effort completion window; a missing, rejected, or
      * never-settling hook cannot change or hold open the operation's result
      * beyond that bound.
@@ -349,12 +521,88 @@ export interface Connector {
      * pending URL could complete consent with their own account.
      */
     verifyState?(state: string | null, ctx: ConnectorContext): Promise<boolean>;
+    /** Validate a callback issuer against its verified consent, including error responses. */
+    verifyCallbackIssuer?(issuer: string | null, ctx: ConnectorContext): Promise<boolean>;
+    /**
+     * Atomically terminate the consent verified in this context, discarding its
+     * verifier. Required to accept error callbacks; must share finishAuth's
+     * single-use claim so concurrent error and code callbacks have one winner.
+     */
+    consumeAuthError?(ctx: ConnectorContext): Promise<void>;
     /**
      * Optional: complete a downstream OAuth flow (called by
      * /oauth/callback/<id>). `callbackParams` preserves the authorization
-     * server's RFC 9207 `iss` response parameter for SDK validation.
+     * server's RFC 9207 `iss` response parameter for validation. Built-in
+     * OAuth adapters require a nonempty `state` in this parameter, including
+     * programmatic calls and `api()` flows with PKCE disabled. Missing state
+     * is refused before any downstream request.
      */
-    finishAuth?(code: string, ctx: ConnectorContext, callbackParams?: URLSearchParams): Promise<void>;
+    finishAuth?(code: string, ctx: ConnectorContext, callbackParams: URLSearchParams): Promise<void>;
+}
+/** An endpoint as `describeConfig()` shows it: never a query, fragment, or userinfo. */
+export interface DescribedEndpoint {
+    origin: string;
+    path: string;
+}
+/** A connector's downstream authentication, without a single secret. */
+export interface ConnectorAuthDescription {
+    /** `none` when the connector authenticates nothing itself. */
+    mode: "none" | "headers" | "credential" | "oauth" | "request";
+    /** Names of deployment-owned static headers; their values never appear. */
+    headerNames?: string[];
+    /** Header a stored credential rides. */
+    header?: string;
+    /** Framing placed before a stored credential; null sends it verbatim. */
+    scheme?: string | null;
+    /** Requested OAuth scopes. */
+    scope?: string;
+    /** Public CIMD client metadata document. */
+    clientMetadataUrl?: string;
+    /** A declared authorization endpoint (`api()` OAuth). */
+    authorizationEndpoint?: DescribedEndpoint;
+    /** A declared token endpoint (`api()` OAuth). */
+    tokenEndpoint?: DescribedEndpoint;
+    /** Origins `ctx.oauth.fetch` sends the access token to. */
+    apiOrigins?: string[];
+    /** Token-endpoint client authentication method. */
+    tokenEndpointAuthMethod?: string;
+    /** Whether the client authenticates with a secret; the secret never appears. */
+    confidentialClient?: boolean;
+    /** Whether PKCE is used. */
+    pkce?: boolean;
+    /** Names of extra authorization-request parameters; values never appear. */
+    authorizationParamNames?: string[];
+    /** Names of extra token-request headers; values never appear. */
+    tokenRequestHeaderNames?: string[];
+}
+/** One statically known tool, with the classification core will apply. */
+export interface ConnectorToolDescription {
+    name: string;
+    description?: string;
+    annotations?: ToolAnnotations;
+    inputSchema?: JsonSchema;
+    outputSchema?: JsonSchema;
+    /** Present on registry descriptions after overrides and provider review (INV-1). */
+    classification?: "read" | "write";
+}
+/** What `Connector.describe()` reports. Every field is optional but `source`. */
+export interface ConnectorDescription {
+    /** Construction-time presence for described fields, keyed by relative dot path. Never option values. */
+    optionSources?: Readonly<Record<string, "default" | "config">>;
+    source: {
+        kind: "remote-mcp" | "api" | "custom";
+        /** The maintained provider or built-in module that built the connector. */
+        provider?: string;
+    };
+    endpoint?: DescribedEndpoint;
+    auth?: ConnectorAuthDescription;
+    transport?: {
+        versionNegotiation?: "auto" | "legacy";
+        redirects?: "none" | "same-origin";
+        requireHttps?: boolean;
+    };
+    /** Static tools; omitted for a catalog that loads from the network. */
+    tools?: ConnectorToolDescription[];
 }
 export interface ConnectorUsageGuide {
     /** Markdown returned verbatim by `skills({ name: "connector:<id>" })`. */
@@ -377,6 +625,17 @@ export interface ConnectorUsageGuide {
 export interface ExecuteResult {
     result: unknown;
     error?: string;
+    /** Host-owned sandbox facts. Never derive these from guest result values or logs. */
+    failure?: {
+        name: string;
+        /** An uncaught typed host rejection, retained by guest Error identity. */
+        call?: CallErrorDetails;
+        line?: number;
+        timeout?: {
+            elapsedMs: number;
+            deadlineMs: number;
+        };
+    };
     logs?: string[];
 }
 /** A named group of host functions exposed to sandboxed code as a global. */
@@ -385,7 +644,7 @@ export interface ExecutorProvider {
     fns: Record<string, (...args: unknown[]) => Promise<unknown>>;
     /**
      * Optional trusted sandbox-side setup run after provider globals exist.
-     * Connecta uses this to restore typed host errors. This is host-authored code, never
+     * Connecta uses this for the immutable namespace and emission acknowledgements. This is host-authored code, never
      * model input. See documentation/code-mode.md#what-an-executor-must-implement.
      */
     prelude?: string;
@@ -393,8 +652,13 @@ export interface ExecutorProvider {
 /**
  * Runs model-written JavaScript in a sandbox where the ONLY capabilities are
  * the provider functions — no network, filesystem, env, or timers. Structurally
- * compatible with `DynamicWorkerExecutor` from `@cloudflare/codemode` (Workers);
+ * compatible with the upstream `DynamicWorkerExecutor` result/provider seam;
+ * Workers must use `workerExecutor()` from "@zackbart/connecta/worker" so each
+ * run owns and releases its Worker Loader and RPC handles. Direct upstream
+ * construction is rejected by `createConnecta()`.
  * `quickJsExecutor()` from "@zackbart/connecta/quickjs" is the Node implementation.
+ * Custom implementations must explicitly opt in with
+ * `customExecutor(executor, { lifecycle: "self-managed" })` from the root entry.
  * NEVER back this with an unsandboxed eval — the code is untrusted.
  */
 export interface Executor {
@@ -436,11 +700,13 @@ export interface AdmissionSnapshot {
 /**
  * Optional admission capability used by bounded executors. The acquired lease
  * carries execution so an already-admitted caller cannot accidentally acquire
- * a second slot and deadlock a pool of one.
+ * a second slot and deadlock a pool of one. `wait: false` must refuse with
+ * executor_overloaded immediately when no slot is free; never queue it.
  */
 export interface AdmittingExecutor extends Executor {
     acquire(options?: {
         signal?: AbortSignal;
+        wait?: boolean;
     }): Promise<ExecutorLease>;
     /** Payload-free health/metrics view when the executor exposes one. */
     admissionSnapshot?(): AdmissionSnapshot;
@@ -457,6 +723,8 @@ export type AuthResult = {
     ok: true;
     userId?: string;
     subjectId?: string;
+    /** Browser session cookies refreshed by an interactive provider. */
+    sessionCookies?: readonly string[];
     /** Human owner represented by a non-interactive access credential. */
     principal?: IdentityReference;
 } | {
@@ -600,11 +868,21 @@ export interface ConnectaTheme {
      */
     colorScheme?: "system" | "light" | "dark";
 }
-/** An inbound authentication provider (bearer token, interactive identity, ...). */
+/** An inbound authentication provider (machine token or interactive identity). */
 export interface InboundAuth {
     kind: string;
     /** This provider may admit a human identity to operator mutation routes. */
     interactiveOperator?: true;
+    /**
+     * Recognize credential syntax or trusted runtime context, without verifying
+     * it or doing I/O. The first recognizing provider owns the verdict, including
+     * refusals. Human routes reject recognized machine credentials without
+     * consulting storage or another identity. A throw fails closed.
+     * Explicit Authorization headers are normalized and exclude cookies and
+     * Access context. Without recognition, the first eligible provider owns
+     * that header's verdict; a refusal never falls back to another provider.
+     */
+    recognizesCredential?(request: Request, runtimeContext?: InboundAuthRuntimeContext): boolean;
     /**
      * Stable, non-secret namespace of the identity directory behind
      * `activityActorLabel`. Stored with new activity actors so two providers with
@@ -622,11 +900,13 @@ export interface InboundAuth {
     activityActorLabel?(subjectId: string): string | undefined | Promise<string | undefined>;
     /**
      * Optional browser sign-in configuration. When present, operator pages use
-     * the provider instead of asking the operator to paste a static bearer secret.
+     * the provider's interactive sign-in flow.
      */
     uiAuth?: UiAuthConfig;
     /** Serve/short-circuit .well-known + OPTIONS. Return null when not handled. */
     handleMetadata?(request: Request, baseUrl: string): Response | null | Promise<Response | null>;
+    /** 401 challenge, selected only when this provider serves the resource metadata. */
+    challenge?(request: Request, baseUrl: string): string;
     /** Attempt to authorize a request. */
     authorize(request: Request, baseUrl: string, runtimeContext?: InboundAuthRuntimeContext): AuthResult | Promise<AuthResult>;
 }

package/dist/types.js

@@ -1,2 +1 @@
-// Core contracts for connecta. Web-API only — no node: imports here.
 export {};

package/dist/ui.d.ts

@@ -2,21 +2,15 @@ import type { OperatorSurface } from "./module-contracts.js";
 import type { CredentialVault } from "./credential-contract.js";
 import { type DeferredWork } from "./connector-scope.js";
 import { type CredentialManagementCapability, type UiData, type UiProblem, type UiToolSafety } from "./operator-ui/model.js";
-import { type ApprovalPolicy } from "./tool-safety.js";
 import type { RegistryView } from "./registry.js";
 import type { ConnectaBranding, Connector, ConnectorStatus, ToolDef, UiAuthConfig } from "./types.js";
 export { filterUiConnectors, type CredentialManagementCapability, type UiConnector, type UiData, } from "./operator-ui/model.js";
 export { CONNECTA_FAVICON_SVG, resolveBranding, isSafeHttpUrl, isSafeHttpsUrl, isSafeIconHref } from "./branding.js";
-export type OperatorPage = "tokens" | "connections" | "activity" | "artifacts" | "artifact";
+export type OperatorPage = import("./operator-ui/view.js").OperatorPage;
 export declare function operatorPageForPath(path: string): OperatorPage | undefined;
 export declare function operatorPageTitle(page: OperatorPage, configuredTitle: string): string;
-/**
- * The badge a tool earns, from the predicates core enforces with. Computed
- * here so the page reports the rule rather than restating it. `exempt` is the
- * config exemption (#566), which `isApprovalExempt` already refuses to grant
- * a read-only tool.
- */
-export declare function uiToolSafety(definition: ToolDef, exempt?: boolean): UiToolSafety;
+/** Report the verdict the registry stored, independent of pool trust. */
+export declare function uiToolSafety(definition: ToolDef): UiToolSafety;
 /**
  * The fix-prompt key for a connector that is not usable. Chosen from the
  * status state and the connector's declared auth shape — configuration, never
@@ -43,22 +37,16 @@ export declare function buildUiData(registry: RegistryView, baseUrl: string, ser
     mayManage?: (id: string) => boolean;
     timeoutMs?: number;
     signal?: AbortSignal;
-    approval?: ApprovalPolicy;
 }): Promise<UiData>;
 /**
  * Every operator page serves this same data-free shell. Connector, credential,
  * and activity data arrives only through the authenticated `/ui/*` APIs.
  */
-export declare function renderUiHtml(uiAuth?: UiAuthConfig, mcpUrl?: string, branding?: ConnectaBranding, nonce?: string, page?: OperatorPage, options?: {
-    /** Where the Connections page lives, when this shell is on another origin. */
-    homeUrl?: string;
-    /**
-     * The origin that serves `/favicon.*`, when this shell is on another one:
-     * an artifact host answers those paths with 404. See `PageLayout.iconOrigin`.
-     */
-    iconOrigin?: string | undefined;
-}): string;
+export declare function renderUiHtml(uiAuth?: UiAuthConfig, mcpUrl?: string, branding?: ConnectaBranding, 
+/** @deprecated Scripts load from same-origin assets; ignored. */
+_nonce?: string, page?: OperatorPage): string;
 /** Mount the connection UI without enabling any storage or activity module. */
 export declare function operatorUi(options?: {
     branding?: ConnectaBranding;
 }): OperatorSurface;
+export type { OperatorUiContract, OperatorConnectorOverlay, OperatorTool, OperatorViewer, OperatorGrant, OperatorPool, OperatorLastCall, } from "./operator-ui/contract.js";