@zackbart/connecta 0.28.0 → 0.29.0

package/dist/index.d.ts

@@ -1,276 +1,44 @@
-import type { CredentialVault } from "./credential-contract.js";
 import { Registry } from "./registry.js";
-import type { ConnectorGrant } from "./connector-access.js";
-import type { AccessTokensModule, ActivityModule, ArtifactsModule, OperatorSurface } from "./module-contracts.js";
-export type { AccessTokensModule, ActivityModule, ArtifactsModule, OperatorSurface, } from "./module-contracts.js";
+import { type ConnectaConfig } from "./config.js";
+import { type ConnectaConfigDescription } from "./describe-config.js";
+export { customExecutor, type CustomExecutorOptions } from "./executor-contract.js";
+export type { AccessTokensModule, ActivityModule, OperatorSurface } from "./module-contracts.js";
 export type { CredentialVault, CredentialMetadata } from "./credential-contract.js";
-import type { AuthenticatedIdentity, Connector, Executor, IdentityReference, InboundAuth, KVStorage, Logger } from "./types.js";
-/** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */
-export interface ConnectaDiscoveryConfig {
-    /**
-     * Maximum connector catalogs/status probes fetched at once by discovery
-     * operations. Default 4.
-     */
-    concurrency?: number;
-    /** Tool-list cache TTL (seconds). Default 300. */
-    catalogTtlSeconds?: number;
-    /**
-     * Persist serializable remote tool catalogs in storage so cold isolates can
-     * discover tools without a downstream handshake. Default true.
-     */
-    persistCatalog?: boolean;
-    /**
-     * How long an expired persisted catalog remains available as a fallback
-     * when a live refresh fails. Default 3600 seconds.
-     */
-    staleCatalogSeconds?: number;
-    /**
-     * Deadline (ms) for each downstream probe/catalog call fanned out by
-     * `search_tools` and by `connecta.search`/`connecta.describe` inside
-     * `execute_code`. Defaults to 30_000. A timed-out connector degrades
-     * independently; this does not apply to tool calls. Catalog walks receive the
-     * same cancellation signal, which aborts an in-flight page where supported and
-     * prevents another from starting.
-     */
-    probeTimeoutMs?: number;
-}
-/** Deployment-wide call deadlines and inline-result paging thresholds. */
-export interface ConnectaCallsConfig {
-    /**
-     * Deadline (ms) for `call_tool`/`call_destructive_tool` calls that pass no
-     * `timeoutMs`. An explicit per-call value wins. Opt-in: unset by default, so
-     * existing long-running calls gain no surprise deadline.
-     *
-     * Each call makes one attempt. `execute_code` host calls are
-     * unaffected because they already carry their own bound.
-     */
-    defaultTimeoutMs?: number;
-    /**
-     * Max inline result size (bytes) before truncation and `get_result` paging.
-     * Must be a finite whole number >= 1; invalid values warn and fall back to
-     * 24_000. Connectors may override it individually.
-     */
-    maxResultBytes?: number;
-}
-/** Runtime-wide bounds for transient direct-call result paging. */
-export interface ConnectaResultsConfig {
-    /** Stored bytes, including the paging envelope. Default 8 MiB. Zero disables stashing. */
-    maxStashBytes?: number;
-    /** Stored or in-flight entries. Default 64. Zero disables stashing. */
-    maxStashEntries?: number;
-}
-/** Budgets for execute_code programs: host calls and rich output (`connecta.emit`). */
-export interface ConnectaExecuteConfig {
-    /**
-     * Aggregate serialized bytes `connecta.emit` accepts per run. Default
-     * 4_000_000 — a transport bound, not a context bound: emitted image/audio
-     * blocks reach the model as media, not base64 text. Invalid values fall
-     * back to the default.
-     */
-    maxEmittedBytes?: number;
-    /** Content blocks `connecta.emit` accepts per run. Default 32. */
-    maxEmittedBlocks?: number;
-    /**
-     * Host calls one program may make. Default 20. Invalid values fall back to
-     * the default.
-     */
-    maxHostCalls?: number;
-    /**
-     * Deadline for each host call a program makes, in milliseconds. Default
-     * 15_000. Raise it for providers whose legitimate calls run longer, such as
-     * analytics queries; `call_tool`'s own `timeoutMs` is unaffected. Invalid
-     * values fall back to the default.
-     */
-    hostCallTimeoutMs?: number;
-    /**
-     * Hard ceiling on one execution, in milliseconds, enforced outside the
-     * sandbox. Default 120_000, above both executors' own deadlines (QuickJS
-     * 30_000, the Dynamic Worker 60_000), so it only ends a run whose executor
-     * never settled; that run fails as unresponsive and its admission slot is
-     * released. Keep it above any raised executor deadline. Invalid values
-     * fall back to the default.
-     */
-    watchdogMs?: number;
-    /**
-     * Config-exempt writes one program may send, on top of the host-call
-     * budget every call already spends. Default 10. Invalid values fall back
-     * to the default.
-     */
-    maxWrites?: number;
-    /**
-     * Which writes a program may make without asking. A program runs only
-     * explicitly read-only tools and these; every other write is refused and
-     * goes through `call_destructive_tool`, where the host asks. Keys are
-     * connector ids (all of that connector's tools) or `connector.tool`
-     * addresses (that tool); values are `"never"` (never ask) or `"ask"`. The
-     * most specific key wins, and `"ask"` switches off a connector's own
-     * default. An exempt write still spends the write budget and is recorded
-     * in activity; it is never read-only anywhere else — discovery still lists
-     * it as approval-required and `call_tool` still refuses it. An unknown
-     * connector id, or an `api()` address its tools do not include, refuses to
-     * construct; a remote connector's tool names load later, so an address
-     * naming one it never serves simply never matches.
-     */
-    approval?: Readonly<Record<string, "never" | "ask">>;
-}
-export interface AdmissionPoolConfig {
-    /** Simultaneous work admitted to this pool. */
-    concurrency?: number;
-    /** Callers allowed to wait behind active work. Set zero to fail fast. */
-    maxQueueSize?: number;
-    /** Maximum queue wait in milliseconds. */
-    queueTimeoutMs?: number;
-    /** Retry hint returned with overload failures, in milliseconds. */
-    retryAfterMs?: number;
-}
-export interface RequestAdmissionConfig extends AdmissionPoolConfig {
-    /** Hard lifetime of an admitted /mcp request. Default 300,000 ms. */
-    maxDurationMs?: number;
-}
-/**
- * Runtime-portable server-memory boundaries. `/health` and operator routes do
- * not consume these permits, so they remain responsive during MCP saturation.
- */
-export interface ConnectaAdmissionConfig {
-    /**
-     * The `/mcp` request boundary. Defaults to 16 active, 32 queued, and a
-     * 5-second maximum wait.
-     */
-    requests?: RequestAdmissionConfig;
-    /**
-     * Fallback pool for an `executor` that does not implement its own `acquire`.
-     * Defaults to 2 active, 8 queued, and a 5-second maximum wait. Bounded
-     * executors (including `quickJsExecutor`) keep their own tighter pool.
-     */
-    code?: AdmissionPoolConfig;
-}
-/** Config-owned identity rules for one deployment and tenant. */
-export type ConnectorPermission = "all" | "none" | readonly string[];
-export interface ConnectaIdentityConfig {
-    /**
-     * What this admitted identity may discover and call: `"all"`, or a list
-     * whose entries are connector ids (the whole connector) and `connector.tool`
-     * addresses (that tool only), or `{ tool: "connector.tool",
-     * requireReadOnly: true }` for an exact tool only while its loaded catalog
-     * explicitly classifies it read-only. Grants are additive: an unrestricted
-     * connector or address grant wins over the guarded form. An address naming
-     * a tool the catalog lacks is unreachable and warned once, never widened.
-     */
-    connectorAccess?(identity: Readonly<AuthenticatedIdentity>): "all" | readonly ConnectorGrant[] | Promise<"all" | readonly ConnectorGrant[]>;
-    /** Global payload-free activity reads. Defaults to interactive humans. */
-    activityAccess?(principal: Readonly<IdentityReference>): boolean | Promise<boolean>;
-    /** Shared credential and OAuth administration. Defaults to none. */
-    credentialAdministration?(identity: Readonly<AuthenticatedIdentity>): ConnectorPermission | Promise<ConnectorPermission>;
-    /** Client-token lifecycle management by interactive humans. Defaults to false. */
-    accessTokenManagement?(identity: Readonly<AuthenticatedIdentity>): boolean | Promise<boolean>;
-    /** Connecting or changing the caller's personal account. Defaults to none. */
-    personalConnection?(identity: Readonly<AuthenticatedIdentity>): ConnectorPermission | Promise<ConnectorPermission>;
-}
-/**
- * A named tool pool served at `/mcp/<name>`. The pool is the slice a client
- * pointed at that endpoint may see; the identity's own `connectorAccess`
- * remains its ceiling and the pool can only narrow it.
- */
-export interface ConnectaPoolConfig {
-    /** Connector ids and exact `connector.tool` addresses in this pool. */
-    tools: readonly string[];
-    /**
-     * Whether this admitted identity may open the pool. Denied by default:
-     * a pool with no grant serves nobody. A false return, a throw, and an
-     * undeclared pool name are the same 404.
-     */
-    grant?(identity: Readonly<AuthenticatedIdentity>): boolean | Promise<boolean>;
-}
-export interface ConnectaConfig {
-    connectors: Connector[];
-    /** Inbound auth adapters. Includes bearerToken(...); omit for open (dev). */
-    auth?: InboundAuth | InboundAuth[];
-    /** Code-derived connection visibility and independent management permissions. */
-    identity?: ConnectaIdentityConfig;
-    /** Named tool pools, each served at `/mcp/<name>` to identities its grant admits. */
-    pools?: Record<string, ConnectaPoolConfig>;
-    /** KVStorage impl. Defaults to memoryStorage(). */
-    storage?: KVStorage;
-    /**
-     * Public base URL. Defaults to the request origin per-request. Configuring an
-     * HTTPS URL also redirects matching inbound HTTP requests to HTTPS.
-     */
-    publicUrl?: string;
-    /**
-     * Exact browser MCP origins, or "*". Defaults to publicUrl's origin and
-     * HTTP(S) loopback origins at any port. Originless clients are admitted.
-     */
-    allowedOrigins?: readonly string[] | "*";
-    /** Optional recorder and reader, created by activityHistory() from /activity. */
-    activity?: ActivityModule;
-    /** Replaceable owner-partitioned credential storage. Omit for config-owned secrets. */
-    vault?: CredentialVault;
-    /** Optional connection UI, created by operatorUi() from /ui. */
-    ui?: OperatorSurface;
-    /**
-     * Optional team pages over stored data, created by artifacts() from
-     * /artifacts. Adds the built-in `artifacts` connector; needs `publicUrl`,
-     * because the links it hands out are shared.
-     */
-    artifacts?: ArtifactsModule;
-    /** Optional managed client tokens, created by accessTokens() from /auth/access-tokens. */
-    accessTokens?: AccessTokensModule;
-    /** Optional dedicated HTTPS origin that serves only artifact pages and their library. */
-    artifactOrigin?: string;
-    /** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */
-    discovery?: ConnectaDiscoveryConfig;
-    /** Deployment-wide call deadlines and result paging threshold. */
-    calls?: ConnectaCallsConfig;
-    /** Runtime-wide transient result stash limits, shared across subjects. */
-    results?: ConnectaResultsConfig;
-    /** Budgets for the `connecta.emit` rich-output channel in execute_code. */
-    execute?: ConnectaExecuteConfig;
-    /** Bounded MCP and fallback code-mode admission. */
-    admission?: ConnectaAdmissionConfig;
-    /** Diagnostic output. Use "silent" to disable all diagnostic logging. */
-    logger?: Logger | "silent";
-    serverInfo?: {
-        name?: string;
-        version?: string;
-        /** Human-readable name clients may show instead of `name`. */
-        title?: string;
-        /** Homepage clients may link from the server listing. */
-        websiteUrl?: string;
-        /** MCP icons-spec entries; clients render these instead of a scraped favicon. */
-        icons?: Array<{
-            src: string;
-            mimeType?: string;
-            sizes?: string[];
-        }>;
-    };
-    /** Deployment metadata exposed by /health (for example a Worker version). */
-    deploymentInfo?: Record<string, unknown>;
-    /**
-     * Required sandbox for `execute_code`. Workers use
-     * `new DynamicWorkerExecutor({ loader: env.LOADER })` from
-     * `@cloudflare/codemode`; Node uses `quickJsExecutor()` from
-     * `@zackbart/connecta/quickjs`.
-     */
-    executor: Executor;
-}
+export { defineConfig } from "./config.js";
+export type { AdmissionPoolConfig, ConnectaAdmissionConfig, ConnectaCallsConfig, ConnectaConfig, ConnectaDiscoveryConfig, ConnectaExecuteConfig, ConnectaIdentityConfig, ConnectaPoolConfig, ConnectaResultsConfig, ConnectorPermission, RequestAdmissionConfig, } from "./config.js";
+export type { ConfigValueSource, ConnectaConfigDescription, DescribedConnector, DescribedLimit, } from "./describe-config.js";
 export interface Connecta {
     /** Web-standard fetch handler. Usable as `export default { fetch: connecta.fetch }`. */
     fetch: (request: Request, env?: unknown, ctx?: unknown) => Promise<Response>;
     registry: Registry;
+    /**
+     * A secret-free snapshot of the configuration this deployment runs with,
+     * built once at construction: limits and where each came from, auth
+     * providers, identity rules, pools, modules, and every connector's source,
+     * endpoint, auth mode, and static tools. Header values, keys, client
+     * secrets, credentials, and functions never appear. The same object is
+     * returned on every call.
+     */
+    describeConfig: () => ConnectaConfigDescription;
     /** Drain and release configured executor resources. Idempotent. */
     close: () => Promise<void>;
 }
 export declare function createConnecta(config: ConnectaConfig): Connecta;
 export { remoteMcp } from "./connectors/remote-mcp.js";
 export { api } from "./connectors/api.js";
+export { keys, optionsOf, array, opaque, instance, strings, variants } from "./config-schema.js";
+export { defineProvider, PROVIDER_COMMON } from "./provider.js";
+export type { ProviderContext, ProviderDefinition, ProviderFactory, ProviderGuideInput, ProviderKind, ProviderOptions, ProviderSkill, } from "./provider.js";
 export { ConnectorCallError } from "./errors.js";
 export type { ConnectorCallErrorCode, CallErrorDetails } from "./errors.js";
 export { validateToolInput } from "./validate.js";
 export type { ValidateToolInputOptions } from "./validate.js";
 export { memoryStorage } from "./storage/memory.js";
 export { CONNECTA_VERSION } from "./version.js";
+export type { GuestApi, GuestResourceResult, GuestResult, GuestResultPage, GuestBlock } from "./guest-types.js";
 export type { Registry } from "./registry.js";
-export type { RemoteMcpOptions, RemoteMcpAuth, RemoteMcpRedirectPolicy, } from "./connectors/remote-mcp.js";
-export type { ApiOptions, ApiTool } from "./connectors/api.js";
-export type { CatalogDriftCounts, CatalogDriftReport, ConnectaBranding, ConnectaTheme, Connector, ConnectorCallAdmissionInput, ConnectorCallAdmissionPolicy, ConnectorCallAdmissionRule, ConnectorRollingWindowBudget, ConnectorCredentialAccess, ConnectorCredentialConfig, ConnectorCredentialFieldConfig, ConnectorCredentialValues, ConnectorContext, ConnectorUsageGuide, ConnectorStatus, CredentialTestResult, AdmittingExecutor, AdmissionSnapshot, ExecuteResult, Executor, ExecutorLease, ExecutorProvider, InboundAuth, InboundAuthRuntimeContext, UiAuthConfig, AuthResult, AuthenticatedIdentity, IdentityReference, JsonSchema, KVStorage, Logger, ToolDef, ToolAnnotations, } from "./types.js";
-export type { ActivityActor, ActivityCallSource, ActivityOutcome, ActivityPage, ActivityReadActor, ActivityReadEvent, ActivityReader, ActivityReadGate, ActivityReadPage, ActivitySink, ActivityStore, AgentFriction, CatalogDriftActivityEvent, ToolCallActivityEvent, } from "./activity.js";
+export type { RemoteMcpOptions, RemoteMcpAuth, RemoteMcpRedirectPolicy } from "./connectors/remote-mcp.js";
+export type { ApiHandlerContext, ApiOAuthAccess, ApiOAuthClientAuthentication, ApiOAuthConfig, ApiOptions, ApiTool, } from "./connectors/api.js";
+export type { CatalogDriftCounts, CatalogDriftReport, ConnectaBranding, ConnectaTheme, Connector, ConnectorCallAdmissionInput, ConnectorCallAdmissionPolicy, ConnectorCallAdmissionRule, ConnectorRollingWindowBudget, ConnectorCredentialAccess, ConnectorCredentialConfig, ConnectorCredentialFieldConfig, ConnectorCredentialValues, ConnectorContext, ConnectorAuthDescription, ConnectorDescription, ConnectorToolDescription, ConnectorUsageGuide, ConnectorSkill, ConnectorSkillResourceContents, DescribedEndpoint, ConnectorStatus, CredentialTestResult, AdmittingExecutor, AdmissionSnapshot, ExecuteResult, Executor, ExecutorLease, ExecutorProvider, InboundAuth, InboundAuthRuntimeContext, UiAuthConfig, AuthResult, AuthenticatedIdentity, IdentityReference, JsonSchema, KVStorage, Logger, ReviewedTool, ToolClassification, ToolDef, ToolAnnotations, ToolVerdict, } from "./types.js";
+export type { ActivityActor, ActivityCatalogChange, ActivityCallSource, ActivityOutcome, ActivityPage, ActivityReadActor, ActivityReadEvent, ActivityReader, ActivityReadGate, ActivityReadPage, ActivitySink, ActivityStore, AgentFriction, ToolCallActivityEvent, } from "./activity.js";
+export { META_TOOL_NAMES } from "./meta-tool-names.js";