@assemblyline-agents/runtime 0.1.0

package/dist/connections.js

@@ -0,0 +1,838 @@
+import { randomUUID } from "node:crypto";
+import { ConnectionAuthorizationFailedError, ConnectionAuthorizationRequiredError, isConnectionAuthorizationFailedError, isConnectionAuthorizationRequiredError } from "@assemblyline-agents/core";
+import { OAUTH_STANDARD_TOKEN_FIELDS, buildOAuthChallenge, connectionPrincipalFor, connectionPrincipalKey, grantToTokenResult, isTokenExpired, normalizeAuthorization, randomUrlToken, resolveHeadersDefinition, storedGrantExpired, tokenCacheKey } from "./connection-auth-util.js";
+import { HttpApiConnectionClient, McpConnectionClient, OpenApiConnectionClient, RelayMcpConnectionClient, readResponseBody } from "./connection-clients.js";
+import { SandboxCliConnectionClient } from "./sandbox-cli-client.js";
+import { InMemoryConnectionAuthorizationSessionStore, InMemoryConnectionGrantStore } from "./connection-stores.js";
+import { connectionToolAccess, isLiveConnection, isRecord, liveDefinitionUrl, parseQualifiedName, scoreMatch, stringValue, timestamp, tokenize } from "./connection-util.js";
+export * from "./connection-auth-util.js";
+export * from "./connection-clients.js";
+export * from "./connection-stores.js";
+export * from "./connection-util.js";
+export * from "./computer-relay-protocol.js";
+// Compose the channel-visible response for a run parked on connection
+// authorization. The generic "authorization required" string is useless to the
+// human — the challenge URL is the thing they need to click.
+export async function connectionAuthorizationPrompt(store, authorizationSessionId, baseResponse) {
+    const session = authorizationSessionId ? await store.getSession(authorizationSessionId) : undefined;
+    const url = session && typeof session.challenge.url === "string" ? session.challenge.url : undefined;
+    if (!url)
+        return baseResponse || "Connection authorization required.";
+    const prompt = `Authorization required for ${session?.connectionName ?? "a connection"} — approve here: ${url}`;
+    return baseResponse ? `${baseResponse}\n\n${prompt}` : prompt;
+}
+/**
+ * Project declared connection credentials into a freshly acquired sandbox.
+ * Tokens resolve host-side (cached grant or refresh exchange — the grant
+ * store is updated before anything reaches the sandbox), so recycling the
+ * sandbox never loses a durable credential and never holds one. Subagent
+ * sandboxes are excluded: they receive only their engine harness credential,
+ * never the parent's connections. The emitted event carries paths only —
+ * credential contents never reach the event log.
+ */
+export async function materializeConnectionCredentialsIntoSandbox(run, registry, sandbox, appendEvent) {
+    if (run.input.channel === "subagent" || typeof run.input.parentRunId === "string")
+        return;
+    const { materialized, pending } = await registry.materializeCredentials();
+    if (materialized.length === 0 && pending.length === 0)
+        return;
+    for (const credential of materialized) {
+        for (const file of credential.files) {
+            await sandbox.writeFile(file.path, file.content);
+            await sandbox.shell(`chmod ${file.mode.toString(8)} '${file.path.replaceAll("'", String.raw `'\''`)}'`);
+        }
+    }
+    await appendEvent("connections.credentials_materialized", {
+        materialized: materialized.map((credential) => ({
+            connection: credential.connection,
+            files: credential.files.map((file) => file.path)
+        })),
+        pending
+    });
+}
+export const CONNECTION_PAIR_TOOL_NAME = "pair";
+// The synthetic host-side pairing tool advertised for connections that define
+// redeemPairingCode. The input field is named `secret` so tool-call event
+// logging redacts the pasted one-time code automatically.
+function pairingToolItem(connection) {
+    return {
+        connection: connection.name,
+        qualifiedName: `${connection.name}__${CONNECTION_PAIR_TOOL_NAME}`,
+        tool: CONNECTION_PAIR_TOOL_NAME,
+        description: `Pair ${connection.name} by redeeming a one-time pairing packet or claim code. When the user pastes binding/pairing instructions for ${connection.name}, call this with the FULL pasted text as \`secret\`; the host exchanges it and stores the credential durably. Works while the connection is not yet authorized.`,
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                secret: {
+                    type: "string",
+                    description: "The full pasted pairing packet, binding instructions, or one-time claim code."
+                }
+            },
+            required: ["secret"]
+        }
+    };
+}
+const CREDENTIAL_TEMPLATE_PATTERN = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_.]*)\s*\}\}/gu;
+function templateUsesToken(template) {
+    return [...template.matchAll(CREDENTIAL_TEMPLATE_PATTERN)].some((match) => match[1] === "token");
+}
+// An unrendered placeholder in a credentials file is a silent misconfiguration
+// (the CLI reads garbage), so unknown keys fail loudly instead of passing through.
+function renderCredentialTemplate(template, values, connectionName) {
+    return template.replace(CREDENTIAL_TEMPLATE_PATTERN, (_match, key) => {
+        const value = values[key];
+        if (value === undefined) {
+            throw new Error(`Connection ${connectionName} materialize template references unknown placeholder {{${key}}}.`);
+        }
+        return value;
+    });
+}
+export class RuntimeConnectionRegistry {
+    options;
+    resolved = new Map();
+    clients = new Map();
+    tokenCache = new Map();
+    executionContext;
+    grantStore;
+    authorizationSessionStore;
+    constructor(options) {
+        this.options = options;
+        this.grantStore = options.grantStore ?? new InMemoryConnectionGrantStore();
+        this.authorizationSessionStore = options.authorizationSessionStore ?? new InMemoryConnectionAuthorizationSessionStore();
+    }
+    hasLiveConnections() {
+        return this.options.connections.some(isLiveConnection);
+    }
+    liveConnectionNames() {
+        return this.options.connections
+            .filter(isLiveConnection)
+            .map((connection) => connection.name);
+    }
+    async search(input, execution) {
+        return this.withExecutionContext(execution, () => this.searchWithContext(input));
+    }
+    async searchWithContext(input) {
+        const keywords = input.keywords ?? "";
+        const limit = input.limit ?? 10;
+        const target = this.targetConnections(input.connection);
+        const queryTokens = tokenize(keywords);
+        const scored = [];
+        const failures = [];
+        // Pairing tools surface even when the connection cannot authenticate yet —
+        // redeeming a pasted packet is exactly how an unauthorized connection
+        // becomes authorized, so it must not hide behind the failure path.
+        const pairable = [];
+        for (const connection of target) {
+            if (await this.supportsPairing(connection))
+                pairable.push(pairingToolItem(connection));
+            let metadata;
+            try {
+                metadata = await this.getClient(connection.name).getToolMetadata();
+            }
+            catch (error) {
+                failures.push(this.connectionFailure(connection, error));
+                continue;
+            }
+            for (const tool of metadata) {
+                const score = keywords.trim() ? scoreMatch(queryTokens, tool) : 1;
+                if (score <= 0)
+                    continue;
+                const item = {
+                    connection: tool.connection,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                    qualifiedName: tool.qualifiedName,
+                    tool: tool.name
+                };
+                if (tool.outputSchema)
+                    item.outputSchema = tool.outputSchema;
+                scored.push({
+                    score,
+                    item
+                });
+            }
+        }
+        scored.sort((a, b) => b.score - a.score);
+        const matches = scored.slice(0, limit).map((entry) => entry.item);
+        if (matches.length > 0)
+            return [...pairable, ...matches, ...failures];
+        return [
+            ...pairable,
+            ...target.map((connection) => ({
+                connection: connection.name,
+                description: connection.description ?? `${connection.name} connection`
+            })),
+            ...failures
+        ];
+    }
+    async supportsPairing(connection) {
+        try {
+            return typeof (await this.resolveConnection(connection)).definition.redeemPairingCode === "function";
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Redeem a user-provided one-time pairing code host-side and persist the
+     * resulting credentials in the grant store. The durable credential never
+     * enters a sandbox; the model only relays the single-use code.
+     */
+    async redeemPairingCode(connectionName, code) {
+        const compiled = this.options.connections.find((connection) => connection.name === connectionName);
+        if (!compiled || !isLiveConnection(compiled)) {
+            throw new Error(`Connection ${connectionName} is not registered as a live connection.`);
+        }
+        const definition = (await this.resolveConnection(compiled)).definition;
+        const redeem = definition.redeemPairingCode;
+        if (!redeem)
+            throw new Error(`Connection ${connectionName} does not support pairing codes.`);
+        if (!code.trim())
+            throw new Error("A pairing code is required.");
+        const context = this.resolverContext();
+        const token = await redeem({ code }, context);
+        const authorization = definition.auth
+            ? await normalizeAuthorization(definition.auth, context)
+            : { kind: "token", principalType: "user", getToken: async () => token };
+        const principal = connectionPrincipalFor(compiled, authorization, context);
+        const principalKey = connectionPrincipalKey(principal);
+        await this.saveGrantFromToken(compiled.name, principal, principalKey, token);
+        this.tokenCache.delete(tokenCacheKey(compiled.name, principal));
+        return {
+            connected: true,
+            connection: compiled.name,
+            message: `${compiled.name} is paired. The credential is stored durably on the host; no further setup is needed.`
+        };
+    }
+    async metadataForQualifiedName(qualifiedName) {
+        const parsed = parseQualifiedName(qualifiedName);
+        if (!parsed)
+            return undefined;
+        const metadata = await this.getClient(parsed.connectionName).getToolMetadata();
+        return metadata.find((tool) => tool.name === parsed.toolName);
+    }
+    async executeQualifiedTool(qualifiedName, input, execution) {
+        const parsed = parseQualifiedName(qualifiedName);
+        if (!parsed)
+            throw new Error(`Invalid connection tool name: ${qualifiedName}`);
+        // "<connection>__pair" is the synthetic host-side pairing tool; it must
+        // run before any client/auth resolution (the whole point is that the
+        // connection is not authorized yet).
+        if (parsed.toolName === CONNECTION_PAIR_TOOL_NAME) {
+            const compiled = this.options.connections.find((connection) => connection.name === parsed.connectionName);
+            if (compiled && await this.supportsPairing(compiled)) {
+                const secret = isRecord(input) && typeof input.secret === "string" ? input.secret : "";
+                return this.withExecutionContext(execution, () => this.redeemPairingCode(parsed.connectionName, secret));
+            }
+        }
+        return this.withExecutionContext(execution, () => this.getClient(parsed.connectionName).executeTool(parsed.toolName, input));
+    }
+    async getConnectionApproval(connectionName, toolName) {
+        const compiled = this.options.connections.find((connection) => connection.name === connectionName);
+        if (!compiled || !isLiveConnection(compiled))
+            return undefined;
+        const resolved = await this.resolveConnection(compiled);
+        const access = connectionToolAccess(toolName, resolved.definition.access);
+        if (access === "none")
+            throw new Error(`Tool ${toolName} is not allowed by connection ${connectionName}.`);
+        if (access === "write" && resolved.definition.access.write !== false) {
+            return resolved.definition.access.write.approval;
+        }
+        return resolved.definition.approval;
+    }
+    getClient(connectionName) {
+        const existing = this.clients.get(connectionName);
+        if (existing)
+            return existing;
+        const compiled = this.options.connections.find((connection) => connection.name === connectionName);
+        if (!compiled || !isLiveConnection(compiled)) {
+            throw new Error(`Connection ${connectionName} is not registered as a live connection.`);
+        }
+        const resolved = () => this.resolveConnection(compiled);
+        const client = compiled.protocol === "cli"
+            ? new SandboxCliConnectionClient(compiled, resolved, this)
+            : compiled.protocol === "mcp"
+                ? compiled.transport === "relay"
+                    ? new RelayMcpConnectionClient(compiled, resolved, this)
+                    : new McpConnectionClient(compiled, resolved, this)
+                : compiled.protocol === "openapi"
+                    ? new OpenApiConnectionClient(compiled, resolved, this)
+                    : new HttpApiConnectionClient(compiled, resolved, this);
+        this.clients.set(connectionName, client);
+        return client;
+    }
+    async executeSandboxCli(invocation) {
+        if (!this.options.executeSandboxCli) {
+            throw new Error("Sandbox CLI connection execution requires an active agent run sandbox.");
+        }
+        return this.options.executeSandboxCli(invocation, this.executionContext);
+    }
+    async resolveHeaders(connection, definition) {
+        const headers = {};
+        const context = this.resolverContext();
+        if (definition.auth !== undefined) {
+            const token = await this.resolveToken(connection, definition.auth, context, liveDefinitionUrl(definition));
+            const tokenType = token.tokenType?.trim() || "Bearer";
+            headers.Authorization = `${tokenType} ${token.token}`;
+        }
+        if (definition.headers !== undefined) {
+            const resolved = await resolveHeadersDefinition(definition.headers, context);
+            for (const [key, value] of Object.entries(resolved)) {
+                if (key.toLowerCase() === "authorization" && headers.Authorization !== undefined) {
+                    throw new Error(`Connection ${connection.name} headers must not include Authorization when auth is configured.`);
+                }
+                headers[key] = value;
+            }
+        }
+        return headers;
+    }
+    /**
+     * Start (or resume) the authorization flow for a named connection and
+     * report where to send the user's browser. Backs the host's authenticated
+     * GET /openeve/connections/authorize endpoint (agent-control route class,
+     * JSON — deliberately not a public 302, so unauthenticated callers cannot
+     * trigger consent flows or enumerate connection names): the dashboard
+     * fetches the URL and opens it; the provider redirects back to the public,
+     * idempotency-claimed callback. Hitting it when a grant already exists
+     * reports "connected" instead of minting a redundant session; a pending
+     * session's challenge is reused.
+     */
+    async beginAuthorization(connectionName) {
+        const compiled = this.options.connections.find((connection) => connection.name === connectionName);
+        if (!compiled || !isLiveConnection(compiled))
+            return { status: "unavailable", reason: "unknown_connection" };
+        let definition;
+        try {
+            definition = (await this.resolveConnection(compiled)).definition;
+        }
+        catch (error) {
+            return { status: "unavailable", reason: error instanceof Error ? error.message : String(error) };
+        }
+        if (!definition.auth)
+            return { status: "unavailable", reason: "connection_has_no_auth" };
+        try {
+            await this.resolveToken(compiled, definition.auth, this.resolverContext(), liveDefinitionUrl(definition));
+            return { status: "connected" };
+        }
+        catch (error) {
+            if (isConnectionAuthorizationRequiredError(error)) {
+                const url = typeof error.challenge?.url === "string" ? error.challenge.url : undefined;
+                return url ? { status: "authorize", url } : { status: "unavailable", reason: error.reason };
+            }
+            return { status: "unavailable", reason: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    /**
+     * Resolve every connection that declares `materialize` and render its
+     * credential files for injection into the agent sandbox. Tokens resolve
+     * through the normal host-side flow — cached grant, or a refresh exchange
+     * that persists the rotated grant to the grant store BEFORE anything is
+     * rendered — so the sandbox only ever sees the short-lived access token.
+     *
+     * A connection that cannot resolve (missing grant, pending authorization,
+     * failed refresh) is reported as pending, never thrown: missing credentials
+     * are a recoverable connection-required state, not a boot crash.
+     */
+    async materializeCredentials() {
+        const materialized = [];
+        const pending = [];
+        const context = this.resolverContext();
+        for (const compiled of this.options.connections) {
+            if (!isLiveConnection(compiled))
+                continue;
+            let definition;
+            try {
+                definition = (await this.resolveConnection(compiled)).definition;
+            }
+            catch (error) {
+                pending.push({ connection: compiled.name, reason: error instanceof Error ? error.message : String(error) });
+                continue;
+            }
+            const spec = definition.materialize;
+            if (!spec || spec.files.length === 0)
+                continue;
+            const needsToken = spec.files.some((file) => templateUsesToken(file.path) || templateUsesToken(file.content));
+            let resolvedToken = { token: "" };
+            if (needsToken) {
+                if (!definition.auth) {
+                    pending.push({ connection: compiled.name, reason: "materialize templates use {{token}} but the connection has no auth" });
+                    continue;
+                }
+                try {
+                    resolvedToken = await this.resolveToken(compiled, definition.auth, context, liveDefinitionUrl(definition));
+                }
+                catch (error) {
+                    if (isConnectionAuthorizationRequiredError(error)) {
+                        const authorizeUrl = typeof error.challenge?.url === "string" ? error.challenge.url : undefined;
+                        pending.push({ connection: compiled.name, reason: `authorization_required: ${error.reason}`, ...(authorizeUrl ? { authorizeUrl } : {}) });
+                        continue;
+                    }
+                    const reason = isConnectionAuthorizationFailedError(error)
+                        ? `${error.reason}: ${error.message}`
+                        : error instanceof Error
+                            ? error.message
+                            : String(error);
+                    pending.push({ connection: compiled.name, reason });
+                    continue;
+                }
+            }
+            const values = { token: resolvedToken.token };
+            // Extra token-response fields (captured into the grant's credential bag)
+            // are addressable as {{credential.<key>}} — e.g. a provider-issued user
+            // or account id a sandbox-side CLI needs to build API paths.
+            for (const [key, value] of Object.entries(resolvedToken.credential ?? {})) {
+                if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+                    values[`credential.${key}`] = String(value);
+                }
+            }
+            try {
+                materialized.push({
+                    connection: compiled.name,
+                    files: spec.files.map((file) => ({
+                        path: renderCredentialTemplate(file.path, values, compiled.name),
+                        content: renderCredentialTemplate(file.content, values, compiled.name),
+                        mode: file.mode ?? 0o600
+                    }))
+                });
+            }
+            catch (error) {
+                pending.push({ connection: compiled.name, reason: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        return { materialized, pending };
+    }
+    async evictToken(connection, definition) {
+        if (!definition.auth)
+            return;
+        const context = this.resolverContext();
+        const authorization = await normalizeAuthorization(definition.auth, context);
+        const principal = connectionPrincipalFor(connection, authorization, context);
+        const cacheKey = tokenCacheKey(connection.name, principal);
+        const principalKey = connectionPrincipalKey(principal);
+        const cached = this.tokenCache.get(cacheKey);
+        this.tokenCache.delete(cacheKey);
+        if (cached?.authorization.kind === "oauth" || authorization.kind === "oauth") {
+            await this.grantStore.deleteGrant(connection.name, principalKey);
+        }
+        await (cached?.authorization ?? authorization).evict?.({ principal, connection: { url: connection.url ?? "" } });
+    }
+    async completeAuthorization(callback) {
+        const state = callback.params.state;
+        if (!state)
+            throw new ConnectionAuthorizationFailedError("unknown", { reason: "missing_state", retryable: false });
+        const session = await this.authorizationSessionStore.getSessionByState(state);
+        if (!session)
+            throw new ConnectionAuthorizationFailedError("unknown", { reason: "unknown_state", retryable: false });
+        if (session.expiresAt <= Date.now()) {
+            await this.authorizationSessionStore.updateSession(session.id, { status: "expired" });
+            throw new ConnectionAuthorizationFailedError(session.connectionName, { reason: "authorization_expired", retryable: true });
+        }
+        if (callback.params.error) {
+            await this.authorizationSessionStore.updateSession(session.id, { status: "denied" });
+            throw new ConnectionAuthorizationFailedError(session.connectionName, {
+                reason: callback.params.error,
+                retryable: true,
+                message: callback.params.error_description ?? `Connection ${session.connectionName} authorization was denied.`
+            });
+        }
+        const compiled = this.options.connections.find((connection) => connection.name === session.connectionName);
+        if (!compiled || !isLiveConnection(compiled)) {
+            throw new ConnectionAuthorizationFailedError(session.connectionName, { reason: "connection_not_found", retryable: false });
+        }
+        const resolved = await this.resolveConnection(compiled);
+        if (!resolved.definition.auth) {
+            throw new ConnectionAuthorizationFailedError(session.connectionName, { reason: "auth_not_configured", retryable: false });
+        }
+        const authorization = await normalizeAuthorization(resolved.definition.auth, { env: this.options.env, session: session.session });
+        const connectionContext = { url: compiled.url ?? "" };
+        let token;
+        if (authorization.kind === "oauth" && authorization.oauth) {
+            token = await this.exchangeOAuthAuthorizationCode(authorization.oauth, session, callback);
+        }
+        else if (authorization.completeAuthorization) {
+            const completeOptions = {
+                principal: session.principal,
+                connection: connectionContext,
+                callbackUrl: session.callbackUrl,
+                callback
+            };
+            if (session.resume !== undefined)
+                completeOptions.resume = session.resume;
+            token = await authorization.completeAuthorization(completeOptions);
+        }
+        else {
+            throw new ConnectionAuthorizationFailedError(session.connectionName, { reason: "callback_not_supported", retryable: false });
+        }
+        await this.saveGrantFromToken(compiled.name, session.principal, session.principalKey, token);
+        return this.authorizationSessionStore.updateSession(session.id, { status: "completed" });
+    }
+    async getAuthorizationSession(id) {
+        return this.authorizationSessionStore.getSession(id);
+    }
+    async updateAuthorizationSession(id, patch) {
+        return this.authorizationSessionStore.updateSession(id, patch);
+    }
+    async close() {
+        await Promise.allSettled([...this.clients.values()].map((client) => client.close()));
+        this.clients.clear();
+    }
+    request(input, init) {
+        return this.options.fetch(input, init);
+    }
+    environmentValue(name) {
+        return this.options.env[name];
+    }
+    async resolveConnection(compiled) {
+        const existing = this.resolved.get(compiled.name);
+        if (existing)
+            return existing;
+        const promise = this.loadResolvedConnection(compiled);
+        this.resolved.set(compiled.name, promise);
+        return promise;
+    }
+    async loadResolvedConnection(compiled) {
+        const platform = this.options.platform ?? process.platform;
+        if (compiled.hostRequirements?.platforms?.length && !compiled.hostRequirements.platforms.includes(platform)) {
+            throw new Error(`${compiled.hostRequirements.message} Current runtime platform: ${platform}.`);
+        }
+        const raw = await this.options.loadDefinition(compiled);
+        if (!isRecord(raw))
+            throw new Error(`Connection ${compiled.name} did not export an object.`);
+        if (compiled.protocol === "mcp") {
+            if (raw.transport === "stdio") {
+                if (compiled.source.path.startsWith("dynamic://")) {
+                    throw new Error(`Dynamic MCP connection ${compiled.name} cannot launch a stdio process.`);
+                }
+                if (typeof raw.command !== "string" || !raw.command.trim()) {
+                    throw new Error(`Stdio MCP connection ${compiled.name} must export command.`);
+                }
+                if (raw.args !== undefined && (!Array.isArray(raw.args) || raw.args.some((argument) => typeof argument !== "string"))) {
+                    throw new Error(`Stdio MCP connection ${compiled.name} args must contain only strings.`);
+                }
+            }
+            else if (raw.transport === "relay") {
+                if (compiled.source.path.startsWith("dynamic://")) {
+                    throw new Error(`Dynamic MCP connection ${compiled.name} cannot use a device relay.`);
+                }
+                if (typeof raw.url !== "string" || typeof raw.credentialEnv !== "string") {
+                    throw new Error(`Relay MCP connection ${compiled.name} must export url and credentialEnv.`);
+                }
+            }
+            else if (typeof raw.url !== "string") {
+                throw new Error(`HTTP MCP connection ${compiled.name} must export url.`);
+            }
+            if (typeof raw.description !== "string")
+                throw new Error(`MCP connection ${compiled.name} must export description.`);
+            return { compiled, definition: raw };
+        }
+        if (compiled.protocol === "openapi") {
+            if (raw.spec === undefined)
+                throw new Error(`OpenAPI connection ${compiled.name} must export spec.`);
+            if (typeof raw.description !== "string")
+                throw new Error(`OpenAPI connection ${compiled.name} must export description.`);
+            return { compiled, definition: raw };
+        }
+        if (compiled.protocol === "http") {
+            if (typeof raw.baseUrl !== "string")
+                throw new Error(`HTTP API connection ${compiled.name} must export baseUrl.`);
+            if (typeof raw.description !== "string")
+                throw new Error(`HTTP API connection ${compiled.name} must export description.`);
+            if (!Array.isArray(raw.operations))
+                throw new Error(`HTTP API connection ${compiled.name} must export operations.`);
+            return { compiled, definition: raw };
+        }
+        if (compiled.protocol === "cli") {
+            if (compiled.source.path.startsWith("dynamic://")) {
+                throw new Error(`Dynamic CLI connection ${compiled.name} is not allowed.`);
+            }
+            if (raw.transport !== "sandbox" || typeof raw.command !== "string" || !raw.command.trim()) {
+                throw new Error(`Sandbox CLI connection ${compiled.name} must export transport "sandbox" and command.`);
+            }
+            if (typeof raw.description !== "string" || !Array.isArray(raw.tools)) {
+                throw new Error(`Sandbox CLI connection ${compiled.name} must export description and tools.`);
+            }
+            return { compiled, definition: raw };
+        }
+        throw new Error(`Connection ${compiled.name} is declaration-only.`);
+    }
+    targetConnections(name) {
+        return this.options.connections.filter((connection) => {
+            if (!isLiveConnection(connection))
+                return false;
+            return !name || connection.name === name;
+        });
+    }
+    connectionFailure(connection, error) {
+        if (isConnectionAuthorizationRequiredError(error)) {
+            return {
+                connection: connection.name,
+                description: connection.description ?? `${connection.name} connection`,
+                needsAuthorization: true,
+                error: error.reason
+            };
+        }
+        if (isConnectionAuthorizationFailedError(error)) {
+            return {
+                connection: connection.name,
+                description: connection.description ?? `${connection.name} connection`,
+                error: `${error.reason}: ${error.message}`
+            };
+        }
+        return {
+            connection: connection.name,
+            description: connection.description ?? `${connection.name} connection`,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+    async resolveToken(connection, auth, context, resolvedUrl) {
+        const authorization = await normalizeAuthorization(auth, context);
+        const principal = connectionPrincipalFor(connection, authorization, context);
+        const principalKey = connectionPrincipalKey(principal);
+        const cacheKey = tokenCacheKey(connection.name, principal);
+        const cached = this.tokenCache.get(cacheKey);
+        if (cached && !isTokenExpired(cached.token))
+            return cached.token;
+        const connectionContext = { url: resolvedUrl ?? connection.url ?? "" };
+        if (authorization.kind === "oauth") {
+            const stored = await this.grantStore.getGrant(connection.name, principalKey);
+            if (stored && !storedGrantExpired(stored)) {
+                const token = grantToTokenResult(stored);
+                this.tokenCache.set(cacheKey, { token, authorization, principal, connection: connectionContext });
+                return token;
+            }
+            if (stored?.refreshToken && authorization.oauth) {
+                const refreshed = await this.refreshOAuthGrant(authorization.oauth, connection.name, principal, principalKey, stored.refreshToken);
+                // saveGrantFromToken preserved the credential bag on the grant; mirror
+                // that on the returned token so template rendering sees it too.
+                if (!refreshed.credential && stored.credential)
+                    refreshed.credential = stored.credential;
+                this.tokenCache.set(cacheKey, { token: refreshed, authorization, principal, connection: connectionContext });
+                return refreshed;
+            }
+            throw await this.createAuthorizationRequiredError(connection, authorization, principal, principalKey, context, connectionContext);
+        }
+        try {
+            const token = await authorization.getToken({ principal, connection: connectionContext });
+            this.tokenCache.set(cacheKey, { token, authorization, principal, connection: connectionContext });
+            return token;
+        }
+        catch (error) {
+            if (isConnectionAuthorizationRequiredError(error) && authorization.kind === "interactive") {
+                throw await this.createAuthorizationRequiredError(connection, authorization, principal, principalKey, context, connectionContext, error);
+            }
+            if (isConnectionAuthorizationRequiredError(error) || isConnectionAuthorizationFailedError(error))
+                throw error;
+            throw error;
+        }
+    }
+    resolverContext() {
+        return {
+            env: this.options.env,
+            session: this.options.session
+        };
+    }
+    async withExecutionContext(execution, fn) {
+        const previous = this.executionContext;
+        if (execution)
+            this.executionContext = execution;
+        try {
+            return await fn();
+        }
+        finally {
+            this.executionContext = previous;
+        }
+    }
+    async createAuthorizationRequiredError(connection, authorization, principal, principalKey, context, connectionContext, cause) {
+        const existing = await this.authorizationSessionStore.findPendingSession(connection.name, principalKey);
+        if (existing) {
+            const options = {
+                reason: cause?.reason ?? "authorization_required",
+                challenge: existing.challenge
+            };
+            if (cause?.message)
+                options.message = cause.message;
+            return new ConnectionAuthorizationRequiredError(connection.name, {
+                ...options
+            });
+        }
+        const callbackUrl = this.callbackUrl();
+        const id = randomUUID();
+        const state = randomUrlToken();
+        const expiresAt = Date.now() + 10 * 60_000;
+        let challenge;
+        let resume;
+        let codeVerifier;
+        if (authorization.kind === "oauth" && authorization.oauth) {
+            codeVerifier = randomUrlToken(48);
+            const oauthChallengeOptions = {
+                state,
+                callbackUrl,
+                codeVerifier
+            };
+            if (authorization.displayName)
+                oauthChallengeOptions.displayName = authorization.displayName;
+            challenge = buildOAuthChallenge(authorization.oauth, oauthChallengeOptions);
+        }
+        else if (authorization.startAuthorization) {
+            const started = await authorization.startAuthorization({ principal, connection: connectionContext, callbackUrl });
+            challenge = started.challenge;
+            resume = started.resume;
+            if (!challenge.url && cause?.challenge?.url)
+                challenge.url = cause.challenge.url;
+            if (!challenge.instructions && cause?.challenge?.instructions)
+                challenge.instructions = cause.challenge.instructions;
+        }
+        else {
+            challenge = cause?.challenge ?? { instructions: `Authorize connection ${connection.name} and retry.` };
+            if (authorization.displayName)
+                challenge.displayName = authorization.displayName;
+        }
+        challenge.sessionId = id;
+        challenge.state = state;
+        challenge.expiresAt = expiresAt;
+        const session = {
+            id,
+            state,
+            connectionName: connection.name,
+            principal,
+            principalKey,
+            session: context.session,
+            callbackUrl,
+            challenge,
+            status: "pending",
+            expiresAt,
+            createdAt: timestamp(),
+            updatedAt: timestamp()
+        };
+        if (codeVerifier)
+            session.codeVerifier = codeVerifier;
+        if (resume !== undefined)
+            session.resume = resume;
+        if (this.executionContext?.runId)
+            session.runId = this.executionContext.runId;
+        if (this.executionContext?.toolCallId)
+            session.toolCallId = this.executionContext.toolCallId;
+        if (this.executionContext?.toolName)
+            session.toolName = this.executionContext.toolName;
+        await this.authorizationSessionStore.createSession(session);
+        const errorOptions = {
+            reason: cause?.reason ?? "authorization_required",
+            challenge
+        };
+        if (cause?.message)
+            errorOptions.message = cause.message;
+        return new ConnectionAuthorizationRequiredError(connection.name, errorOptions);
+    }
+    callbackUrl() {
+        const base = (this.options.callbackBaseUrl ?? this.options.env.OPENEVE_PUBLIC_URL ?? "http://localhost").replace(/\/+$/u, "");
+        return `${base}/openeve/connections/callback`;
+    }
+    async exchangeOAuthAuthorizationCode(oauth, session, callback) {
+        const code = callback.params.code;
+        if (!code) {
+            throw new ConnectionAuthorizationFailedError(session.connectionName, { reason: "missing_code", retryable: true });
+        }
+        return this.requestOAuthToken(oauth, {
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: oauth.redirectUri ?? session.callbackUrl,
+            code_verifier: session.codeVerifier
+        });
+    }
+    async refreshOAuthGrant(oauth, connectionName, principal, principalKey, refreshToken) {
+        const token = await this.requestOAuthToken(oauth, {
+            grant_type: "refresh_token",
+            refresh_token: refreshToken
+        });
+        if (!token.refreshToken)
+            token.refreshToken = refreshToken;
+        await this.saveGrantFromToken(connectionName, principal, principalKey, token);
+        return token;
+    }
+    async requestOAuthToken(oauth, fields) {
+        const body = new URLSearchParams();
+        body.set("client_id", oauth.clientId);
+        if (oauth.clientSecret)
+            body.set("client_secret", oauth.clientSecret);
+        for (const [key, value] of Object.entries(oauth.tokenParams ?? {}))
+            body.set(key, value);
+        for (const [key, value] of Object.entries(fields)) {
+            if (value !== undefined)
+                body.set(key, value);
+        }
+        const response = await this.request(oauth.tokenUrl, {
+            method: "POST",
+            headers: {
+                accept: "application/json",
+                "content-type": "application/x-www-form-urlencoded"
+            },
+            body
+        });
+        const payload = await readResponseBody(response);
+        if (!response.ok || !isRecord(payload)) {
+            throw new ConnectionAuthorizationFailedError("oauth", {
+                reason: "token_exchange_failed",
+                message: `OAuth token exchange failed with HTTP ${response.status}.`
+            });
+        }
+        const accessToken = stringValue(payload.access_token);
+        if (!accessToken) {
+            throw new ConnectionAuthorizationFailedError("oauth", { reason: "missing_access_token" });
+        }
+        const token = { token: accessToken };
+        const refreshToken = stringValue(payload.refresh_token);
+        const tokenType = oauth.tokenType?.trim() || stringValue(payload.token_type);
+        const scope = stringValue(payload.scope);
+        const expiresIn = typeof payload.expires_in === "number" ? payload.expires_in : Number(payload.expires_in);
+        if (refreshToken)
+            token.refreshToken = refreshToken;
+        if (tokenType)
+            token.tokenType = tokenType;
+        if (scope)
+            token.scopes = scope.split(/\s+/u).filter(Boolean);
+        if (Number.isFinite(expiresIn) && expiresIn > 0)
+            token.expiresAt = Date.now() + expiresIn * 1000;
+        // Non-standard response fields (provider identity ids and the like) ride
+        // along as the grant's credential bag; RFC 6749 §5.1 permits extras.
+        const credential = {};
+        for (const [key, value] of Object.entries(payload)) {
+            if (OAUTH_STANDARD_TOKEN_FIELDS.has(key))
+                continue;
+            if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+                credential[key] = value;
+        }
+        if (Object.keys(credential).length > 0)
+            token.credential = credential;
+        return token;
+    }
+    async saveGrantFromToken(connectionName, principal, principalKey, token) {
+        const now = timestamp();
+        const existing = await this.grantStore.getGrant(connectionName, principalKey);
+        const grant = {
+            connectionName,
+            principalKey,
+            principal,
+            token: token.token,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now
+        };
+        if (token.refreshToken)
+            grant.refreshToken = token.refreshToken;
+        else if (existing?.refreshToken)
+            grant.refreshToken = existing.refreshToken;
+        if (token.tokenType)
+            grant.tokenType = token.tokenType;
+        if (token.scopes)
+            grant.scopes = token.scopes;
+        if (token.expiresAt)
+            grant.expiresAt = token.expiresAt;
+        // A response that omits extras must not erase identity captured earlier.
+        if (token.credential)
+            grant.credential = token.credential;
+        else if (existing?.credential)
+            grant.credential = existing.credential;
+        await this.grantStore.saveGrant(grant);
+    }
+}
+//# sourceMappingURL=connections.js.map