@assemblyline-agents/runtime 2.0.0 → 3.0.0

package/dist/connections.js

@@ -1,16 +1,27 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
-import { ConnectionAuthorizationFailedError, ConnectionAuthorizationRequiredError, isConnectionAuthorizationFailedError, isConnectionAuthorizationRequiredError } from "@assemblyline-agents/core";
+import { ConnectionAuthorizationFailedError, ConnectionAuthorizationRequiredError, isConnectionAuthorizationFailedError, isConnectionAuthorizationRequiredError, resolveSandboxPath, shellQuote } 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 { HttpApiConnectionClient, A2AConnectionClient, CredentialConnectionClient, McpConnectionClient, OpenApiConnectionClient, RelayMcpConnectionClient, SdkApiConnectionClient, readResponseBody } from "./connection-clients.js";
 import { SandboxCliConnectionClient } from "./sandbox-cli-client.js";
+import { audienceAllowsConnectionAccess } from "./audience.js";
 import { InMemoryConnectionAuthorizationSessionStore, InMemoryConnectionGrantStore } from "./connection-stores.js";
-import { connectionToolAccess, isLiveConnection, isRecord, liveDefinitionUrl, parseQualifiedName, scoreMatch, stringValue, timestamp, tokenize } from "./connection-util.js";
+import { connectionToolAccess, connectionToolApproval, 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";
+export class ConnectionConfigurationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConnectionConfigurationError";
+    }
+}
+export function isConnectionConfigurationError(error) {
+    return error instanceof ConnectionConfigurationError;
+}
+const MATERIALIZED_CREDENTIAL_ROOT = "/workspace/.assembly-line/credentials/";
 // 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.
@@ -34,23 +45,55 @@ export async function connectionAuthorizationPrompt(store, authorizationSessionI
 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();
+    const { materialized, pending } = await registry.materializeCredentials({
+        id: run.id,
+        input: run.input
+    });
     if (materialized.length === 0 && pending.length === 0)
         return;
     for (const credential of materialized) {
         for (const file of credential.files) {
+            assertMaterializedCredentialPath(credential.connection, file.path);
             await sandbox.writeFile(file.path, file.content);
-            await sandbox.shell(`chmod ${file.mode.toString(8)} '${file.path.replaceAll("'", String.raw `'\''`)}'`);
+            const physicalPath = resolveSandboxPath(sandbox.root, file.path);
+            await sandbox.shell(`chmod ${file.mode.toString(8)} -- ${shellQuote(physicalPath)}`);
+        }
+        for (const command of credential.commands ?? []) {
+            await sandbox.shell(command);
         }
     }
     await appendEvent("connections.credentials_materialized", {
         materialized: materialized.map((credential) => ({
             connection: credential.connection,
-            files: credential.files.map((file) => file.path)
+            files: credential.files.map((file) => file.path),
+            ...(credential.audit ? { audit: credential.audit } : {})
         })),
         pending
     });
 }
+function assertMaterializedCredentialPath(connectionName, path) {
+    const normalized = path.replace(/\\/g, "/").replace(/\/+/g, "/");
+    if (normalized.split("/").includes("..") || !normalized.startsWith(MATERIALIZED_CREDENTIAL_ROOT)) {
+        throw new ConnectionConfigurationError(`Connection ${connectionName} materialize files must be under ${MATERIALIZED_CREDENTIAL_ROOT}`);
+    }
+}
+function assertRedactedAuditMetadata(connectionName, audit) {
+    const visit = (value, path) => {
+        if (Array.isArray(value)) {
+            value.forEach((item, index) => visit(item, `${path}[${index}]`));
+            return;
+        }
+        if (!value || typeof value !== "object")
+            return;
+        for (const [key, item] of Object.entries(value)) {
+            if (/(?:token|secret|password|authorization|credential)/iu.test(key)) {
+                throw new ConnectionConfigurationError(`Connection ${connectionName} audit metadata contains forbidden secret-like key ${path}.${key}.`);
+            }
+            visit(item, `${path}.${key}`);
+        }
+    };
+    visit(audit, "audit");
+}
 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
@@ -60,7 +103,7 @@ function pairingToolItem(connection) {
         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.`,
+        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. Only call this for a supplied packet; the tool's presence does not mean an existing grant is missing.`,
         inputSchema: {
             type: "object",
             additionalProperties: false,
@@ -112,6 +155,46 @@ export class RuntimeConnectionRegistry {
             .filter(isLiveConnection)
             .map((connection) => connection.name);
     }
+    /** Resolve the host-only event adapter without exposing it as a model tool. */
+    async eventBindingContext(connectionName) {
+        const compiled = this.options.connections.find((connection) => connection.name === connectionName);
+        if (!compiled || !isLiveConnection(compiled)) {
+            throw new ConnectionConfigurationError(`Connection ${connectionName} is not registered as a live connection.`);
+        }
+        const definition = (await this.resolveConnection(compiled)).definition;
+        if (!definition.events)
+            throw new ConnectionConfigurationError(`Connection ${connectionName} does not accept provider events.`);
+        const context = this.resolverContext();
+        let principal;
+        if (definition.events.scope === "connection") {
+            principal = { type: "app" };
+        }
+        else if (definition.auth) {
+            const authorization = await normalizeAuthorization(definition.auth, context);
+            principal = connectionPrincipalFor(compiled, authorization, context);
+        }
+        else if (compiled.subject === "user") {
+            const sessionPrincipal = context.session.principal;
+            if (!sessionPrincipal || sessionPrincipal.type !== "user") {
+                throw new ConnectionConfigurationError(`Connection ${connectionName} events require an authenticated user principal.`);
+            }
+            principal = sessionPrincipal;
+        }
+        else {
+            principal = { type: "app" };
+        }
+        return {
+            compiled,
+            events: definition.events,
+            principal,
+            principalKey: connectionPrincipalKey(principal),
+            getToken: async () => {
+                if (!definition.auth)
+                    throw new ConnectionConfigurationError(`Connection ${connectionName} event adapter requested a token without connection auth.`);
+                return this.resolveToken(compiled, definition.auth, context, liveDefinitionUrl(definition));
+            }
+        };
+    }
     async search(input, execution) {
         return this.authorizationIntent.run("discover", () => this.withExecutionContext(execution, () => this.searchWithContext(input)));
     }
@@ -122,15 +205,27 @@ export class RuntimeConnectionRegistry {
         const queryTokens = tokenize(keywords);
         const scored = [];
         const failures = [];
+        const privateOnly = [];
         // 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));
+            // A personal connection stays registered in a shared run, but its tool
+            // catalog, pairing, and authorization state are private-surface only.
+            if (!this.connectionAccessible(connection)) {
+                privateOnly.push({
+                    connection: connection.name,
+                    description: `${connection.name} is registered. Its personal tools, pairing, and authorization status are available only on a private surface such as a direct message; this does not mean a durable grant is missing.`,
+                    requiresPrivateAudience: true
+                });
+                continue;
+            }
             let metadata;
             try {
+                if (await this.supportsPairing(connection)) {
+                    pairable.push(pairingToolItem(connection));
+                }
                 metadata = await this.getClient(connection.name).getToolMetadata();
             }
             catch (error) {
@@ -159,23 +254,52 @@ export class RuntimeConnectionRegistry {
         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, ...matches, ...privateOnly, ...failures];
+        const privateConnectionNames = new Set(privateOnly.map((item) => item.connection));
         return [
             ...pairable,
+            ...privateOnly,
             ...target.map((connection) => ({
                 connection: connection.name,
                 description: connection.description ?? `${connection.name} connection`
-            })),
+            })).filter((item) => !privateConnectionNames.has(item.connection)),
             ...failures
         ];
     }
+    // Deliberately does not swallow load errors: a definition module that fails
+    // to resolve (for example a deployed artifact missing the connection's
+    // package) must surface the real cause instead of silently hiding the
+    // pairing tool that would otherwise be the recovery path.
     async supportsPairing(connection) {
-        try {
-            return typeof (await this.resolveConnection(connection)).definition.redeemPairingCode === "function";
-        }
-        catch {
-            return false;
-        }
+        return typeof (await this.resolveConnection(connection)).definition.redeemPairingCode === "function";
+    }
+    /**
+     * Report which live connections can redeem a pairing code right now, and
+     * which cannot because their definition failed to resolve (missing package,
+     * unset env, platform mismatch). Backs the core `pair` tool: a connection
+     * that cannot even load must still be *diagnosable* from the model — the
+     * resolve failure is the answer the user needs, not a hidden tool.
+     */
+    async pairingStatus() {
+        return this.authorizationIntent.run("discover", async () => {
+            const pairable = [];
+            const unavailable = [];
+            for (const connection of this.options.connections) {
+                if (!this.toolAllowed(connection))
+                    continue;
+                try {
+                    if (await this.supportsPairing(connection))
+                        pairable.push(connection.name);
+                }
+                catch (error) {
+                    unavailable.push({
+                        connection: connection.name,
+                        reason: error instanceof Error ? error.message : String(error)
+                    });
+                }
+            }
+            return { pairable, unavailable };
+        });
     }
     /**
      * Redeem a user-provided one-time pairing code host-side and persist the
@@ -187,6 +311,9 @@ export class RuntimeConnectionRegistry {
         if (!compiled || !isLiveConnection(compiled)) {
             throw new Error(`Connection ${connectionName} is not registered as a live connection.`);
         }
+        if (!this.connectionAccessible(compiled)) {
+            throw new Error(`Connection ${connectionName} is personal and pairs only on a private surface such as a direct message.`);
+        }
         const definition = (await this.resolveConnection(compiled)).definition;
         const redeem = definition.redeemPairingCode;
         if (!redeem)
@@ -213,6 +340,9 @@ export class RuntimeConnectionRegistry {
             const parsed = parseQualifiedName(qualifiedName);
             if (!parsed)
                 return undefined;
+            const compiled = this.options.connections.find((connection) => connection.name === parsed.connectionName);
+            if (!compiled || !this.toolAllowed(compiled))
+                return undefined;
             const metadata = await this.getClient(parsed.connectionName).getToolMetadata();
             return metadata.find((tool) => tool.name === parsed.toolName);
         });
@@ -221,11 +351,14 @@ export class RuntimeConnectionRegistry {
         const parsed = parseQualifiedName(qualifiedName);
         if (!parsed)
             throw new Error(`Invalid connection tool name: ${qualifiedName}`);
+        const compiled = this.options.connections.find((connection) => connection.name === parsed.connectionName);
+        if (!compiled || !this.toolAllowed(compiled)) {
+            throw new Error(`Connection tool ${qualifiedName} is unavailable here: personal connections work only on a private surface such as a direct message.`);
+        }
         // "<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));
@@ -237,12 +370,27 @@ export class RuntimeConnectionRegistry {
         const compiled = this.options.connections.find((connection) => connection.name === connectionName);
         if (!compiled || !isLiveConnection(compiled))
             return undefined;
+        if (!this.toolAllowed(compiled)) {
+            throw new Error(`Connection tool ${connectionName}__${toolName} is unavailable here: personal connections work only on a private surface such as a direct message.`);
+        }
+        // Pairing is a synthetic host-side bootstrap operation, not a provider
+        // tool. It must bypass the provider connection's ordinary read/write
+        // classification or discovery will advertise a tool that execution then
+        // rejects before the redeemer can run.
+        if (toolName === CONNECTION_PAIR_TOOL_NAME) {
+            if (!await this.supportsPairing(compiled)) {
+                throw new Error(`Connection ${connectionName} does not support pairing codes.`);
+            }
+            return undefined;
+        }
         const resolved = await this.resolveConnection(compiled);
+        if (!("access" in resolved.definition) || !resolved.definition.access)
+            return undefined;
         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 connectionToolApproval(toolName, resolved.definition.access);
         }
         return resolved.definition.approval;
     }
@@ -252,18 +400,24 @@ export class RuntimeConnectionRegistry {
             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.`);
+            throw new ConnectionConfigurationError(`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);
+        const client = compiled.protocol === "credential"
+            ? new CredentialConnectionClient()
+            : 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)
+                        : compiled.protocol === "sdk"
+                            ? new SdkApiConnectionClient(compiled, resolved)
+                            : compiled.protocol === "a2a"
+                                ? new A2AConnectionClient(compiled, resolved, this)
+                                : new HttpApiConnectionClient(compiled, resolved, this);
         this.clients.set(connectionName, client);
         return client;
     }
@@ -338,32 +492,38 @@ export class RuntimeConnectionRegistry {
      * 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.
+     * A normal connection that cannot resolve is reported as pending. An
+     * required or explicitly requested credential-protocol connection throws
+     * instead, so a run can never continue after a missing, revoked, or
+     * mismatched sandbox credential.
      */
-    async materializeCredentials() {
-        return this.authorizationIntent.run("discover", () => this.materializeCredentialsWithContext());
+    async materializeCredentials(run) {
+        return this.authorizationIntent.run("discover", () => this.materializeCredentialsWithContext(run));
     }
-    async materializeCredentialsWithContext() {
+    async materializeCredentialsWithContext(run) {
         const materialized = [];
         const pending = [];
         const context = this.resolverContext();
         for (const compiled of this.options.connections) {
-            if (!isLiveConnection(compiled))
+            if (!this.toolAllowed(compiled))
                 continue;
+            const failClosed = compiled.protocol === "credential"
+                && (compiled.required || sandboxCredentialWasRequested(run, compiled.name));
             let definition;
             try {
                 definition = (await this.resolveConnection(compiled)).definition;
             }
             catch (error) {
+                if (failClosed)
+                    throw 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)
+            if (!spec || ((spec.files?.length ?? 0) === 0 && !spec.resolve))
                 continue;
-            const needsToken = spec.files.some((file) => templateUsesToken(file.path) || templateUsesToken(file.content));
+            const staticFiles = spec.files ?? [];
+            const needsToken = staticFiles.some((file) => templateUsesToken(file.path) || templateUsesToken(file.content));
             let resolvedToken = { token: "" };
             if (needsToken) {
                 if (!definition.auth) {
@@ -374,6 +534,64 @@ export class RuntimeConnectionRegistry {
                     resolvedToken = await this.resolveToken(compiled, definition.auth, context, liveDefinitionUrl(definition));
                 }
                 catch (error) {
+                    if (failClosed)
+                        throw 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;
+                }
+            }
+            let files = staticFiles;
+            let commands = [];
+            let audit;
+            if (spec.resolve) {
+                if (!run) {
+                    pending.push({ connection: compiled.name, reason: "run_context_required" });
+                    continue;
+                }
+                let lazyToken;
+                try {
+                    const authorization = definition.auth
+                        ? await normalizeAuthorization(definition.auth, context)
+                        : undefined;
+                    const principal = authorization
+                        ? connectionPrincipalFor(compiled, authorization, context)
+                        : { type: "app" };
+                    const resolved = await spec.resolve({
+                        connectionName: compiled.name,
+                        agentId: this.options.agentId ?? "",
+                        run,
+                        principal,
+                        session: context.session,
+                        env: this.options.env,
+                        fetch: this.options.fetch,
+                        getToken: async () => {
+                            if (!definition.auth)
+                                throw new Error(`Connection ${compiled.name} materialization requested a token without auth.`);
+                            lazyToken ??= this.resolveToken(compiled, definition.auth, context, liveDefinitionUrl(definition));
+                            return lazyToken;
+                        }
+                    });
+                    if (!resolved)
+                        continue;
+                    files = resolved.files;
+                    commands = resolved.commands ?? [];
+                    audit = resolved.audit;
+                    if (audit)
+                        assertRedactedAuditMetadata(compiled.name, audit);
+                }
+                catch (error) {
+                    if (failClosed)
+                        throw 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 } : {}) });
@@ -400,14 +618,18 @@ export class RuntimeConnectionRegistry {
             try {
                 materialized.push({
                     connection: compiled.name,
-                    files: spec.files.map((file) => ({
+                    files: files.map((file) => ({
                         path: renderCredentialTemplate(file.path, values, compiled.name),
                         content: renderCredentialTemplate(file.content, values, compiled.name),
                         mode: file.mode ?? 0o600
-                    }))
+                    })),
+                    ...(commands.length > 0 ? { commands } : {}),
+                    ...(audit ? { audit } : {})
                 });
             }
             catch (error) {
+                if (failClosed)
+                    throw error;
                 pending.push({ connection: compiled.name, reason: error instanceof Error ? error.message : String(error) });
             }
         }
@@ -435,6 +657,11 @@ export class RuntimeConnectionRegistry {
         const session = await this.authorizationSessionStore.getSessionByState(state);
         if (!session)
             throw new ConnectionAuthorizationFailedError("unknown", { reason: "unknown_state", retryable: false });
+        // Provider callbacks are routinely retried. Once the grant was saved and
+        // the session completed, return the durable result without attempting to
+        // exchange the one-time authorization code again.
+        if (session.status === "completed")
+            return session;
         if (session.expiresAt <= Date.now()) {
             await this.authorizationSessionStore.updateSession(session.id, { status: "expired" });
             throw new ConnectionAuthorizationFailedError(session.connectionName, { reason: "authorization_expired", retryable: true });
@@ -455,7 +682,11 @@ export class RuntimeConnectionRegistry {
         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 authorization = await normalizeAuthorization(resolved.definition.auth, {
+            env: this.options.env,
+            fetch: this.options.fetch,
+            session: session.session
+        });
         const connectionContext = { url: compiled.url ?? "" };
         let token;
         if (authorization.kind === "oauth" && authorization.oauth) {
@@ -544,6 +775,15 @@ export class RuntimeConnectionRegistry {
                 throw new Error(`OpenAPI connection ${compiled.name} must export description.`);
             return { compiled, definition: raw };
         }
+        if (compiled.protocol === "a2a") {
+            if (typeof raw.agentCardUrl !== "string")
+                throw new Error(`A2A connection ${compiled.name} must export agentCardUrl.`);
+            if (typeof raw.description !== "string")
+                throw new Error(`A2A connection ${compiled.name} must export description.`);
+            if (!raw.access || typeof raw.access !== "object")
+                throw new Error(`A2A connection ${compiled.name} must export access.`);
+            return { compiled, definition: raw };
+        }
         if (compiled.protocol === "http") {
             if (typeof raw.baseUrl !== "string")
                 throw new Error(`HTTP API connection ${compiled.name} must export baseUrl.`);
@@ -553,6 +793,18 @@ export class RuntimeConnectionRegistry {
                 throw new Error(`HTTP API connection ${compiled.name} must export operations.`);
             return { compiled, definition: raw };
         }
+        if (compiled.protocol === "sdk") {
+            if (compiled.source.path.startsWith("dynamic://")) {
+                throw new Error(`Dynamic SDK API connection ${compiled.name} is not allowed.`);
+            }
+            if (typeof raw.description !== "string" || !Array.isArray(raw.operations) || typeof raw.execute !== "function") {
+                throw new Error(`SDK API connection ${compiled.name} must export description, operations, and execute.`);
+            }
+            if (!raw.access || typeof raw.access !== "object") {
+                throw new Error(`SDK API connection ${compiled.name} must export access.`);
+            }
+            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.`);
@@ -565,6 +817,12 @@ export class RuntimeConnectionRegistry {
             }
             return { compiled, definition: raw };
         }
+        if (compiled.protocol === "credential") {
+            if (typeof raw.description !== "string" || !raw.auth || !raw.materialize || typeof raw.materialize !== "object") {
+                throw new Error(`Credential connection ${compiled.name} must export description, auth, and materialize.`);
+            }
+            return { compiled, definition: raw };
+        }
         throw new Error(`Connection ${compiled.name} is declaration-only.`);
     }
     targetConnections(name) {
@@ -574,6 +832,18 @@ export class RuntimeConnectionRegistry {
             return !name || connection.name === name;
         });
     }
+    /**
+     * The single audience rule: personal (user-subject) connections exist only
+     * on private surfaces. Everything else — discovery, execution, pairing,
+     * and credential materialization — derives from this one predicate.
+     */
+    connectionAccessible(connection) {
+        const audience = this.options.audience ?? { private: true };
+        return audienceAllowsConnectionAccess(audience, connection.subject);
+    }
+    toolAllowed(connection) {
+        return isLiveConnection(connection) && this.connectionAccessible(connection);
+    }
     connectionFailure(connection, error) {
         if (isConnectionAuthorizationRequiredError(error)) {
             return {
@@ -605,14 +875,14 @@ export class RuntimeConnectionRegistry {
         if (cached && !isTokenExpired(cached.token))
             return cached.token;
         const connectionContext = { url: resolvedUrl ?? connection.url ?? "" };
-        if (authorization.kind === "oauth") {
+        if (authorization.kind === "oauth" || authorization.kind === "interactive") {
             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) {
+            if (stored?.refreshToken && authorization.kind === "oauth" && 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.
@@ -621,7 +891,9 @@ export class RuntimeConnectionRegistry {
                 this.tokenCache.set(cacheKey, { token: refreshed, authorization, principal, connection: connectionContext });
                 return refreshed;
             }
-            throw await this.createAuthorizationRequiredError(connection, authorization, principal, principalKey, context, connectionContext);
+            if (authorization.kind === "oauth") {
+                throw await this.createAuthorizationRequiredError(connection, authorization, principal, principalKey, context, connectionContext);
+            }
         }
         try {
             const token = await authorization.getToken({ principal, connection: connectionContext });
@@ -643,6 +915,7 @@ export class RuntimeConnectionRegistry {
     resolverContext() {
         return {
             env: this.options.env,
+            fetch: this.options.fetch,
             session: this.options.session
         };
     }
@@ -719,7 +992,7 @@ export class RuntimeConnectionRegistry {
             challenge = buildOAuthChallenge(authorization.oauth, oauthChallengeOptions);
         }
         else if (authorization.startAuthorization) {
-            const started = await authorization.startAuthorization({ principal, connection: connectionContext, callbackUrl });
+            const started = await authorization.startAuthorization({ principal, connection: connectionContext, callbackUrl, state });
             challenge = started.challenge;
             resume = started.resume;
             if (!challenge.url && cause?.challenge?.url)
@@ -769,7 +1042,7 @@ export class RuntimeConnectionRegistry {
         return new ConnectionAuthorizationRequiredError(connection.name, errorOptions);
     }
     callbackUrl() {
-        const base = (this.options.callbackBaseUrl ?? this.options.env.OPENEVE_PUBLIC_URL ?? "http://localhost").replace(/\/+$/u, "");
+        const base = (this.options.callbackBaseUrl ?? this.options.env.ASSEMBLY_LINE_PUBLIC_URL ?? "http://localhost").replace(/\/+$/u, "");
         return `${base}/assembly-line/connections/callback`;
     }
     async exchangeOAuthAuthorizationCode(oauth, session, callback) {
@@ -796,9 +1069,21 @@ export class RuntimeConnectionRegistry {
     }
     async requestOAuthToken(oauth, fields) {
         const body = new URLSearchParams();
-        body.set("client_id", oauth.clientId);
-        if (oauth.clientSecret)
-            body.set("client_secret", oauth.clientSecret);
+        const headers = {
+            accept: "application/json",
+            "content-type": "application/x-www-form-urlencoded"
+        };
+        if (oauth.tokenEndpointAuthMethod === "client_secret_basic") {
+            if (!oauth.clientSecret) {
+                throw new ConnectionAuthorizationFailedError("oauth", { reason: "missing_client_secret" });
+            }
+            headers.authorization = `Basic ${Buffer.from(`${oauth.clientId}:${oauth.clientSecret}`).toString("base64")}`;
+        }
+        else {
+            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)) {
@@ -807,10 +1092,7 @@ export class RuntimeConnectionRegistry {
         }
         const response = await this.request(oauth.tokenUrl, {
             method: "POST",
-            headers: {
-                accept: "application/json",
-                "content-type": "application/x-www-form-urlencoded"
-            },
+            headers,
             body
         });
         const payload = await readResponseBody(response);
@@ -879,4 +1161,11 @@ export class RuntimeConnectionRegistry {
         await this.grantStore.saveGrant(grant);
     }
 }
+function sandboxCredentialWasRequested(run, connectionName) {
+    const requests = run?.input.sandboxCredentials;
+    return Boolean(requests
+        && typeof requests === "object"
+        && !Array.isArray(requests)
+        && Object.prototype.hasOwnProperty.call(requests, connectionName));
+}
 //# sourceMappingURL=connections.js.map