maka-agent 0.2.0-dev.3.20260830 → 0.2.0-dev.31.20260913

package/node_modules/@maka/storage/dist/runtime-policy/coordinator.js

@@ -17,17 +17,20 @@
  * under the License.
  */
 import { randomUUID } from 'node:crypto';
-import { CONNECTION_CATALOG_MAX_CONNECTIONS, decodeConnectionModelId, decodeConnectionSlug, decodeProviderType, decodeRuntimePolicyEntityId, decodeCredentialLocator, normalizeDeleteCredentialInput, normalizeRemoveCatalogConnectionInput, normalizeRequestHeaderUpdates, normalizeRequestHeaders, normalizeSetCredentialInput, parseRequestHeaders, serializeRequestHeaders, RequestCustomizationValidationError, normalizeCredentialSecret, normalizeCatalogConnectionBaseUrl, } from '@maka/core/runtime-policy';
+import { isDeepStrictEqual } from 'node:util';
+import { CONNECTION_CATALOG_MAX_CONNECTIONS, decodeConnectionModelId, connectionCredentialTarget, decodeConnectionCredentialTarget, decodeConnectionName, decodeConnectionSlug, decodeProviderType, decodeRuntimePolicyEntityId, decodeCredentialLocator, normalizeDeleteCredentialInput, normalizeRemoveCatalogConnectionInput, normalizeRequestHeaderUpdates, normalizeRequestHeaders, normalizeSetCredentialInput, parseRequestHeaders, serializeRequestHeaders, RequestCustomizationValidationError, normalizeCredentialSecret, normalizeCatalogConnectionBaseUrl, normalizeNetworkProxyUpdate, networkProxyCredentialTarget, } from '@maka/core/runtime-policy';
+import { applyConnectionModelOverrides } from '@maka/core/model-thinking';
 import { deriveProviderAuthContract } from '@maka/core/provider-auth';
 import { isRetiredProvider } from '@maka/core/provider-registry';
-import { deriveConnectionSlug, effectiveBaseUrl, PROVIDER_DEFAULTS, providerAuthSupportsApiKey, } from '@maka/core/llm-connections';
-import { deepFreeze } from './codec.js';
+import { deriveConnectionSlug, deriveInteractiveOAuthConnectionSlug, effectiveBaseUrl, PROVIDER_REGISTRY, providerFallbackModelIds, providerAuthRequiresSecret, providerAuthSupportsApiKey, } from '@maka/core/llm-connections';
+import { deepFreeze, nextRevision } from './codec.js';
 import { catalogSnapshot, connectionBasis, ConnectionCatalogDocumentOwner, connectionTestModelBasis, findConnection, sameConnectionTestModelBasis, } from './connection-catalog-document.js';
 import { credentialMaterial, credentialBasis, credentialStatus, CredentialVaultDocumentOwner, findCredential, sameCredentialBasis, vaultSnapshot, } from './credential-vault-document.js';
 import { cleanupRuntimePolicyDocumentTemps } from './document-io.js';
-import { codecError, commitOutcomeUnknown, decodeConnectionInput, decodeCredentialInput, RuntimePolicyStoreError, } from './errors.js';
+import { codecError, commitOutcomeUnknown, decodeConnectionInput, decodeCredentialInput, decodePolicyInput, RuntimePolicyStoreError, } from './errors.js';
 import { connectionCredentialLocator, connectionRequestHeadersLocator, } from './operations.js';
-import { clearConnectionOnboardingIntent, prepareConnectionOnboardingIntent, readConnectionOnboardingIntent, writeConnectionOnboardingIntent, } from './onboarding-transaction.js';
+import { clearConnectionOnboardingIntent, prepareConnectionOnboardingIntent, prepareInteractiveOAuthEnrollmentIntent, readConnectionOnboardingIntent, writeConnectionOnboardingIntent, } from './onboarding-transaction.js';
+import { findInteractiveOAuthLoginReceipt, readInteractiveOAuthLoginReceipts, sameInteractiveOAuthLoginTarget, upsertInteractiveOAuthLoginReceipt, } from './oauth-login-receipt-document.js';
 import { policySnapshot, RuntimePolicyDocumentOwner } from './policy-document.js';
 import { SerializedOperationLane } from '../serialized-operation-lane.js';
 export class RuntimePolicyCoordinator {
@@ -46,6 +49,7 @@ export class RuntimePolicyCoordinator {
         return this.lane.run(async (root) => {
             await cleanupRuntimePolicyDocumentTemps(root);
             await this.recoverConnectionOnboarding(root);
+            await readInteractiveOAuthLoginReceipts(root);
             const catalog = await this.catalog.read(root);
             const vault = await this.vault.read(root);
             await this.vault.deleteOrphanedConnectionCredentials(root, vault, new Set(catalog.connections.map((connection) => connection.connectionId)));
@@ -55,7 +59,7 @@ export class RuntimePolicyCoordinator {
         return this.inLane(async (root) => policySnapshot(await this.policy.read(root)));
     }
     getCatalogSnapshot() {
-        return this.inLane(async (root) => catalogSnapshot(await this.catalog.read(root)));
+        return this.inLane(async (root) => this.projectCatalogSnapshot(root));
     }
     getVaultSnapshot() {
         return this.inLane(async (root) => vaultSnapshot(await this.vault.read(root)));
@@ -94,11 +98,67 @@ export class RuntimePolicyCoordinator {
             }
         });
     }
+    updateNetworkProxy(rawInput) {
+        return this.inLane(async (root) => {
+            const input = decodePolicyInput(() => normalizeNetworkProxyUpdate(rawInput));
+            const policy = await this.policy.read(root);
+            const preparedPolicy = this.policy.prepareMutation(policy, {
+                expectedRevision: input.expectedPolicyRevision,
+                operation: { kind: 'set_network_proxy', value: input.networkProxy },
+            });
+            if (preparedPolicy.kind !== 'ready')
+                return preparedPolicy;
+            if (input.credential.kind === 'replace' &&
+                input.credential.expectedTarget &&
+                !isDeepStrictEqual(networkProxyCredentialTarget(policy.policy.networkProxy), input.credential.expectedTarget)) {
+                return deepFreeze({
+                    kind: 'proxy_target_mismatch',
+                    expected: input.credential.expectedTarget,
+                    actual: networkProxyCredentialTarget(policy.policy.networkProxy),
+                });
+            }
+            const vault = await this.vault.read(root);
+            const existing = findCredential(vault, networkProxyCredentialLocator());
+            if (!matchesCredentialExpectation(existing, input.expectedCredential)) {
+                return deepFreeze({
+                    kind: 'credential_stale',
+                    expected: input.expectedCredential,
+                    actual: existing ? credentialBasis(existing) : null,
+                });
+            }
+            // Preflight every document before publishing either side of the compound update.
+            if (input.credential.kind === 'replace' && existing?.secret !== input.credential.secret) {
+                const prepared = this.vault.prepareSet(vault, {
+                    locator: networkProxyCredentialLocator(),
+                    expected: existing
+                        ? { credentialId: existing.credentialId, revision: existing.revision }
+                        : null,
+                    secret: input.credential.secret,
+                });
+                if (prepared.kind !== 'ready') {
+                    if (prepared.kind === 'credential_stale')
+                        return prepared;
+                    throw codecError('invalid_credential_input', 'Network proxy credential is invalid');
+                }
+            }
+            else if (input.credential.kind === 'delete' && existing) {
+                const prepared = this.vault.prepareDelete(vault, {
+                    expected: credentialBasis(existing),
+                });
+                if (prepared.kind !== 'ready') {
+                    if (prepared.kind === 'credential_stale')
+                        return prepared;
+                    throw codecError('invalid_credential_input', 'Network proxy credential is invalid');
+                }
+            }
+            return this.applyNetworkProxyUpdate(root, input);
+        });
+    }
     createConnection(input) {
-        return this.inLane((root) => this.catalog.create(root, input));
+        return this.inLane(async (root) => this.projectCatalogMutation(root, await this.catalog.create(root, input)));
     }
     updateConnection(input) {
-        return this.inLane((root) => this.catalog.update(root, input));
+        return this.inLane(async (root) => this.projectCatalogMutation(root, await this.catalog.update(root, input)));
     }
     removeConnection(rawInput) {
         return this.inLane(async (root) => {
@@ -115,7 +175,10 @@ export class RuntimePolicyCoordinator {
             const vault = await this.vault.read(root);
             if (!connection) {
                 await this.vault.deleteConnectionCredentials(root, vault, expected.connectionId);
-                return deepFreeze({ kind: 'committed', snapshot: catalogSnapshot(catalog) });
+                return deepFreeze({
+                    kind: 'committed',
+                    snapshot: await this.projectCatalogSnapshot(root),
+                });
             }
             const result = await this.catalog.remove(root, { expected });
             if (result.kind === 'committed') {
@@ -126,11 +189,11 @@ export class RuntimePolicyCoordinator {
                     throw commitOutcomeUnknown('Connection removal committed before credential cleanup completed', error);
                 }
             }
-            return result;
+            return this.projectCatalogMutation(root, result);
         });
     }
     setDefaultTarget(input) {
-        return this.inLane((root) => this.catalog.setDefaultTarget(root, input));
+        return this.inLane(async (root) => this.projectCatalogMutation(root, await this.catalog.setDefaultTarget(root, input)));
     }
     migrateSystemSeed(input) {
         return this.inLane((root) => this.catalog.migrateSystemSeed(root, input));
@@ -155,8 +218,19 @@ export class RuntimePolicyCoordinator {
                 if (!connection) {
                     return deepFreeze({ kind: 'connection_not_found' });
                 }
+                if (input.expectedConnection &&
+                    !isDeepStrictEqual(connectionCredentialTarget(connection), input.expectedConnection)) {
+                    return deepFreeze({
+                        kind: 'connection_stale',
+                        expected: {
+                            connectionId: input.expectedConnection.connectionId,
+                            revision: input.expectedConnection.revision,
+                        },
+                        actual: connectionBasis(connection),
+                    });
+                }
                 assertConnectionIsWritable(connection);
-                const required = connectionCredentialLocator(connection.connectionId, PROVIDER_DEFAULTS[connection.providerType].authKind);
+                const required = connectionCredentialLocator(connection.connectionId, PROVIDER_REGISTRY[connection.providerType].authKind);
                 if (locator.kind !== 'request_headers' && (!required || required.kind !== locator.kind)) {
                     throw codecError('invalid_credential_input', 'Connection credential kind does not match the provider auth contract');
                 }
@@ -203,7 +277,7 @@ export class RuntimePolicyCoordinator {
             // reaches it today (execution resolution refuses first), which is
             // exactly why it would have stayed open.
             assertConnectionIsWritable(connection);
-            if (PROVIDER_DEFAULTS[connection.providerType].authKind !== 'oauth_token') {
+            if (PROVIDER_REGISTRY[connection.providerType].authKind !== 'oauth_token') {
                 throw codecError('invalid_credential_input', 'OAuth refresh credential does not match the provider auth contract');
             }
             const prepared = this.vault.prepareSet(await this.vault.read(root), input);
@@ -217,32 +291,56 @@ export class RuntimePolicyCoordinator {
             });
         });
     }
-    beginInteractiveOAuthLogin(rawConnectionId) {
+    beginInteractiveOAuthLogin(rawInput) {
         return this.inLane(async (root) => {
-            const connectionId = decodeConnectionInput(() => decodeRuntimePolicyEntityId(rawConnectionId));
+            const input = normalizeInteractiveOAuthLoginInput(rawInput);
+            const receipts = await readInteractiveOAuthLoginReceipts(root);
+            const receipt = findInteractiveOAuthLoginReceipt(receipts, input.attemptId);
+            if (receipt) {
+                return deepFreeze(sameInteractiveOAuthLoginTarget(receipt.target, input.target)
+                    ? {
+                        kind: 'authenticated',
+                        target: structuredClone(receipt.target),
+                        connection: structuredClone(receipt.connection),
+                    }
+                    : { kind: 'attempt_conflict' });
+            }
             const catalog = await this.catalog.read(root);
-            const connection = findConnection(catalog, { connectionId });
-            if (!connection)
-                return deepFreeze({ kind: 'connection_not_found' });
-            if (!connection.enabled)
-                return deepFreeze({ kind: 'connection_disabled' });
+            let connectionBefore;
+            let connectionAfter;
+            if (input.target.kind === 'create') {
+                const requestedSlug = input.target.slug;
+                if (catalog.connections.length >= CONNECTION_CATALOG_MAX_CONNECTIONS) {
+                    return deepFreeze({ kind: 'catalog_full' });
+                }
+                if (requestedSlug !== undefined &&
+                    catalog.connections.some(({ slug }) => slug === requestedSlug)) {
+                    return deepFreeze({ kind: 'slug_taken' });
+                }
+                connectionBefore = null;
+                connectionAfter = newInteractiveOAuthConnection(randomUUID(), requestedSlug ??
+                    deriveInteractiveOAuthConnectionSlug(input.target.providerType, catalog.connections.map(({ slug }) => slug)), input.target.providerType, input.target.name);
+            }
+            else {
+                const existing = findConnection(catalog, { connectionId: input.target.connectionId });
+                if (!existing)
+                    return deepFreeze({ kind: 'connection_not_found' });
+                if (!isInteractiveOAuthLoginProvider(existing.providerType)) {
+                    return deepFreeze({ kind: 'provider_action_unavailable' });
+                }
+                connectionBefore = structuredClone(existing);
+                connectionAfter = reenabledInteractiveOAuthConnection(existing);
+            }
+            const connection = connectionBefore ?? connectionAfter;
             if (!isInteractiveOAuthLoginProvider(connection.providerType)) {
-                return deepFreeze({
-                    kind: 'provider_action_unavailable',
-                    availability: 'hidden',
-                });
+                return deepFreeze({ kind: 'provider_action_unavailable' });
             }
             const contract = deriveProviderAuthContract({
                 providerType: connection.providerType,
-                enabled: true,
                 hasSecret: false,
-                lastTestStatus: connection.lastTest?.status,
             });
-            if (contract.actionAvailability.start_oauth !== 'available') {
-                return deepFreeze({
-                    kind: 'provider_action_unavailable',
-                    availability: contract.actionAvailability.start_oauth,
-                });
+            if (!contract.actionAvailability.start_oauth) {
+                return deepFreeze({ kind: 'provider_action_unavailable' });
             }
             const prepared = await this.prepareConnectionMaterial(root, connection, false);
             if (prepared.kind !== 'ready')
@@ -252,11 +350,13 @@ export class RuntimePolicyCoordinator {
                 throw codecError('invalid_document', 'OAuth login admission produced no OAuth credential locator');
             }
             const existing = findCredential(await this.vault.read(root), locator);
-            const ticket = this.issueInteractiveOAuthLoginTicket(connectionBasis(connection), connection.providerType, existing ? credentialBasis(existing) : null);
+            const ticket = this.issueInteractiveOAuthLoginTicket(input.attemptId, input.target, connectionBefore, connectionAfter, existing ? credentialBasis(existing) : null);
             return deepFreeze({
                 kind: 'ready',
                 ticket,
-                connection: structuredClone(connection),
+                target: structuredClone(input.target),
+                identity: interactiveOAuthConnectionIdentity(connectionAfter),
+                connection: structuredClone(connectionAfter),
                 secretMaterial: prepared.secretMaterial.networkProxy
                     ? { networkProxy: prepared.secretMaterial.networkProxy }
                     : {},
@@ -264,22 +364,41 @@ export class RuntimePolicyCoordinator {
             });
         });
     }
+    queryInteractiveOAuthLogin(rawAttemptId) {
+        return this.inLane(async (root) => {
+            const attemptId = decodeInteractiveOAuthAttemptId(rawAttemptId, 'invalid_connection_input');
+            const receipt = findInteractiveOAuthLoginReceipt(await readInteractiveOAuthLoginReceipts(root), attemptId);
+            return deepFreeze(receipt
+                ? {
+                    kind: 'authenticated',
+                    target: structuredClone(receipt.target),
+                    connection: structuredClone(receipt.connection),
+                }
+                : { kind: 'not_found' });
+        });
+    }
     async completeInteractiveOAuthLogin(ticket, rawSecret) {
         const claimed = this.claimInteractiveOAuthLoginTicket(ticket);
         return this.completeClaimedTicket(claimed, () => this.inLane(async (root) => {
             const secret = decodeCredentialInput(() => normalizeCredentialSecret(rawSecret));
             const catalog = await this.catalog.read(root);
-            const connection = findConnection(catalog, claimed.connectionBasis);
             const changed = [];
-            if (!connection ||
-                connection.revision !== claimed.connectionBasis.revision ||
-                connection.providerType !== claimed.providerType ||
-                !connection.enabled) {
+            const preparedCatalog = this.catalog.prepareOAuthEnrollmentUpsert(catalog, claimed.connectionBefore, claimed.connectionAfter);
+            const requestedSlug = claimed.target.kind === 'create' ? claimed.target.slug : undefined;
+            if (preparedCatalog.kind === 'connection_conflict' &&
+                requestedSlug !== undefined &&
+                catalog.connections.some(({ connectionId, slug }) => slug === requestedSlug && connectionId !== claimed.connectionAfter.connectionId)) {
+                // A caller-selected identity has one stable, actionable outcome even
+                // when another writer claims it after OAuth admission but before the
+                // token commit. No credential or Connection has been written yet.
+                return deepFreeze({ kind: 'slug_taken' });
+            }
+            if (preparedCatalog.kind !== 'ready') {
                 changed.push('connection');
             }
             const locator = {
                 scope: 'connection',
-                connectionId: claimed.connectionBasis.connectionId,
+                connectionId: claimed.connectionAfter.connectionId,
                 kind: 'oauth_token',
             };
             const vault = await this.vault.read(root);
@@ -292,37 +411,34 @@ export class RuntimePolicyCoordinator {
             if (changed.length > 0) {
                 return deepFreeze({ kind: 'superseded', changed });
             }
-            const prepared = this.vault.prepareSet(vault, {
-                locator,
-                expected: claimed.credentialBasis
-                    ? {
-                        credentialId: claimed.credentialBasis.credentialId,
-                        revision: claimed.credentialBasis.revision,
-                    }
-                    : null,
+            const intent = prepareInteractiveOAuthEnrollmentIntent({
+                attemptId: claimed.attemptId,
+                target: claimed.target,
+                connectionBefore: claimed.connectionBefore,
+                connectionAfter: claimed.connectionAfter,
+                credentialBasis: claimed.credentialBasis,
                 secret,
             });
-            if (prepared.kind !== 'ready') {
-                return deepFreeze({
-                    kind: 'superseded',
-                    changed: ['credential'],
-                });
-            }
-            const cleared = await this.catalog.clearConnectionLastTest(root, catalog, locator.connectionId);
             try {
-                await this.vault.commitSet(root, prepared);
+                await writeConnectionOnboardingIntent(root, intent);
             }
             catch (error) {
-                if (cleared) {
-                    throw commitOutcomeUnknown('Connection verification was cleared before OAuth login completed', error);
-                }
+                if (isCommitOutcomeUnknown(error))
+                    this.onboardingRecoveryRequired = true;
                 throw error;
             }
-            return deepFreeze({
-                kind: 'committed',
-                credentialId: prepared.entry.credentialId,
-                revision: prepared.entry.revision,
-            });
+            try {
+                const result = await this.applyInteractiveOAuthEnrollment(root, intent);
+                await clearConnectionOnboardingIntent(root);
+                this.onboardingRecoveryRequired = false;
+                return deepFreeze({ kind: 'committed', ...result });
+            }
+            catch (error) {
+                this.onboardingRecoveryRequired = true;
+                if (isCommitOutcomeUnknown(error))
+                    throw error;
+                throw commitOutcomeUnknown('OAuth enrollment has a durable intent and must recover before retrying', error);
+            }
         }));
     }
     deleteCredential(rawInput) {
@@ -388,33 +504,59 @@ export class RuntimePolicyCoordinator {
             if (isRetiredProvider(connection.providerType)) {
                 return deepFreeze({ kind: 'provider_retired' });
             }
-            const contract = deriveProviderAuthContract({
-                providerType: connection.providerType,
-                enabled: true,
-                hasSecret: true,
-                lastTestStatus: connection.lastTest?.status,
-            });
-            const prepared = await this.prepareConnectionMaterial(root, connection, contract.requiresSecret);
+            const prepared = await this.prepareConnectionMaterial(root, connection, providerAuthRequiresSecret(connection.providerType));
             if (prepared.kind !== 'ready')
                 return prepared;
             return deepFreeze({
                 kind: 'ready',
-                connection: structuredClone(connection),
+                connection: applyConnectionModelOverrides(structuredClone(connection)),
                 secretMaterial: prepared.secretMaterial,
                 networkProxy: structuredClone(prepared.networkProxy),
             });
         });
     }
-    exportCredentialMaterial(rawLocator) {
+    exportCredentialMaterial(rawLocator, rawExpectedConnection) {
         return this.inLane(async (root) => {
             const locator = decodeCredentialInput(() => decodeCredentialLocator(rawLocator));
+            const expectedConnection = rawExpectedConnection
+                ? decodeConnectionInput(() => decodeConnectionCredentialTarget(rawExpectedConnection))
+                : undefined;
+            if (expectedConnection && locator.scope !== 'connection') {
+                throw codecError('invalid_credential_input', 'Only connection credentials accept a connection target basis');
+            }
             if (locator.scope === 'connection') {
                 const catalog = await this.catalog.read(root);
-                if (!this.validateConnectionCredentialLocator(catalog, locator))
-                    return null;
+                const connection = findConnection(catalog, locator);
+                if (expectedConnection &&
+                    (!connection ||
+                        !isDeepStrictEqual(connectionCredentialTarget(connection), expectedConnection))) {
+                    return deepFreeze({
+                        kind: 'connection_stale',
+                        expected: {
+                            connectionId: expectedConnection.connectionId,
+                            revision: expectedConnection.revision,
+                        },
+                        actual: connection ? connectionBasis(connection) : null,
+                    });
+                }
+                if (!this.validateConnectionCredentialLocator(catalog, locator)) {
+                    return expectedConnection
+                        ? deepFreeze({ kind: 'exported', material: null })
+                        : null;
+                }
             }
             const credential = findCredential(await this.vault.read(root), locator);
-            return credential ? credentialMaterial(credential) : null;
+            const material = credential
+                ? {
+                    ...credentialMaterial(credential),
+                    ...(locator.scope === 'network_proxy'
+                        ? {
+                            proxyTarget: networkProxyCredentialTarget((await this.policy.read(root)).policy.networkProxy),
+                        }
+                        : {}),
+                }
+                : null;
+            return expectedConnection ? deepFreeze({ kind: 'exported', material }) : material;
         });
     }
     getConnectionRequestHeaders(rawConnectionId) {
@@ -594,7 +736,7 @@ export class RuntimePolicyCoordinator {
             });
         });
     }
-    resolveWebFetchExecution() {
+    resolveHostOutboundExecution() {
         return this.inLane(async (root) => {
             const policy = (await this.policy.read(root)).policy;
             if (policy.privacy.incognitoActive) {
@@ -650,7 +792,10 @@ export class RuntimePolicyCoordinator {
                 return deepFreeze({ kind: 'superseded', changed: checked.changed });
             }
             const snapshot = await this.catalog.writeModelFetchResult(root, catalog, connectionBasis(checked.connection), result);
-            return deepFreeze({ kind: 'committed', snapshot });
+            return deepFreeze({
+                kind: 'committed',
+                snapshot: await this.projectCatalogSnapshot(root),
+            });
         }));
     }
     beginConnectionOnboarding(input) {
@@ -661,13 +806,21 @@ export class RuntimePolicyCoordinator {
             const requestedTarget = input.target;
             if (requestedTarget.kind === 'create') {
                 const providerType = decodeConnectionInput(() => decodeProviderType(requestedTarget.providerType));
+                const requestedSlug = requestedTarget.slug === undefined
+                    ? null
+                    : decodeConnectionInput(() => decodeConnectionSlug(requestedTarget.slug));
                 target = {
                     kind: 'create',
                     candidate: {
                         connectionId: randomUUID(),
-                        slug: deriveConnectionSlug(providerType, catalog.connections.map((connection) => connection.slug)),
+                        slug: requestedSlug ??
+                            deriveConnectionSlug(providerType, catalog.connections.map((connection) => connection.slug)),
                         providerType,
                     },
+                    slugRequested: requestedSlug !== null,
+                    name: requestedTarget.name === undefined
+                        ? null
+                        : decodeConnectionInput(() => decodeConnectionName(requestedTarget.name)),
                 };
             }
             else if (requestedTarget.kind === 'existing') {
@@ -689,16 +842,22 @@ export class RuntimePolicyCoordinator {
                 throw codecError('invalid_connection_input', 'Unknown connection onboarding target');
             }
             const providerType = target.candidate.providerType;
-            // Onboarding guards the api_key credential slot; a provider whose auth
-            // never uses one has no business here (the Host gates on the same
-            // predicate, this keeps the storage API honest on its own).
-            if (!providerAuthSupportsApiKey(providerType)) {
+            // Onboarding may adopt either an API key or canonical serialized OAuth
+            // material. Providers without a connection credential slot have no
+            // business here (the Host applies the same gate before discovery).
+            if (!providerAuthSupportsApiKey(providerType) &&
+                PROVIDER_REGISTRY[providerType].authKind !== 'oauth_token') {
                 return deepFreeze({ kind: 'provider_unsupported' });
             }
             if (target.kind === 'create' &&
                 catalog.connections.length >= CONNECTION_CATALOG_MAX_CONNECTIONS) {
                 return deepFreeze({ kind: 'catalog_full' });
             }
+            if (target.kind === 'create' &&
+                target.slugRequested &&
+                catalog.connections.some((connection) => connection.slug === target.candidate.slug)) {
+                return deepFreeze({ kind: 'slug_taken' });
+            }
             const baseUrl = input.baseUrl === null
                 ? null
                 : (decodeConnectionInput(() => normalizeCatalogConnectionBaseUrl(input.baseUrl, providerType)) ?? null);
@@ -709,7 +868,7 @@ export class RuntimePolicyCoordinator {
             let storedSecret = null;
             let requestHeadersCredential = null;
             let requestHeadersSecret = null;
-            const locator = connectionCredentialLocator(target.candidate.connectionId, PROVIDER_DEFAULTS[providerType].authKind);
+            const locator = connectionCredentialLocator(target.candidate.connectionId, PROVIDER_REGISTRY[providerType].authKind);
             if (locator) {
                 credential = credentialStatus(vault, locator);
                 if (existing) {
@@ -777,6 +936,9 @@ export class RuntimePolicyCoordinator {
                 if (checked.kind === 'catalog_full') {
                     return deepFreeze({ kind: 'catalog_full' });
                 }
+                if (checked.kind === 'slug_taken') {
+                    return deepFreeze({ kind: 'slug_taken' });
+                }
                 return deepFreeze(checked.kind === 'target_missing'
                     ? { kind: 'target_missing' }
                     : { kind: 'superseded', changed: checked.changed });
@@ -810,6 +972,15 @@ export class RuntimePolicyCoordinator {
         }
         else if (catalog.connections.some((connection) => connection.connectionId === basis.target.candidate.connectionId ||
             connection.slug === basis.target.candidate.slug)) {
+            // A caller-chosen slug losing the race is the caller's to fix, so it
+            // reports distinctly instead of as a generic basis change. A derived
+            // slug colliding still resolves by re-running the wizard, which simply
+            // derives again.
+            if (basis.target.slugRequested &&
+                catalog.connections.some((connection) => connection.slug === basis.target.candidate.slug &&
+                    connection.connectionId !== basis.target.candidate.connectionId)) {
+                return { kind: 'slug_taken' };
+            }
             changed.push('connection');
         }
         else if (catalog.connections.length >= CONNECTION_CATALOG_MAX_CONNECTIONS) {
@@ -841,11 +1012,10 @@ export class RuntimePolicyCoordinator {
         const connectionId = candidate.connectionId;
         let invalidateLastTest = false;
         if (input.suppliedSecret !== null) {
-            const locator = {
-                scope: 'connection',
-                connectionId,
-                kind: 'api_key',
-            };
+            const locator = connectionCredentialLocator(connectionId, PROVIDER_REGISTRY[candidate.providerType].authKind);
+            if (!locator) {
+                throw codecError('invalid_document', 'Onboarding provider has no credential locator');
+            }
             const vault = await this.vault.read(root);
             const credential = findCredential(vault, locator);
             if (credential?.secret !== input.suppliedSecret) {
@@ -867,11 +1037,15 @@ export class RuntimePolicyCoordinator {
             connectionId,
             slug: candidate.slug,
             providerType: candidate.providerType,
+            name: basis.target.kind === 'create' ? basis.target.name : null,
             baseUrl: basis.baseUrl,
             invalidateLastTest,
         });
-        const catalogPreflight = this.catalog.prepareOnboardingUpsert(catalog, intent.connectionId, intent.slug, intent.providerType, intent.baseUrl, intent.enabledModelIds, intent.discovery, intent.invalidateLastTest);
+        const catalogPreflight = this.catalog.prepareOnboardingUpsert(catalog, intent.connectionId, intent.slug, intent.providerType, intent.name, intent.baseUrl, intent.enabledModelIds, intent.discovery, intent.invalidateLastTest);
         if (catalogPreflight.kind === 'slug_conflict') {
+            if (basis.target.kind === 'create' && basis.target.slugRequested) {
+                return deepFreeze({ kind: 'slug_taken' });
+            }
             return deepFreeze({ kind: 'superseded', changed: ['connection'] });
         }
         if (catalogPreflight.kind === 'catalog_full') {
@@ -904,17 +1078,18 @@ export class RuntimePolicyCoordinator {
             const prepared = await this.prepareConnectionOperation(root, connectionId, 'test_credentials');
             if (prepared.kind !== 'ready')
                 return prepared;
+            const projectedConnection = applyConnectionModelOverrides(structuredClone(prepared.connection));
             const modelId = rawModelId === null
                 ? null
                 : decodeConnectionInput(() => decodeConnectionModelId(rawModelId));
-            if (modelId !== null && !isCanonicalConnectionTestModel(prepared.connection, modelId)) {
+            if (modelId !== null && !isCanonicalConnectionTestModel(projectedConnection, modelId)) {
                 throw codecError('invalid_connection_input', 'Connection test model is not in the canonical model set');
             }
-            const ticket = this.issueTicket('connection_test', connectionTestSemanticBasis(prepared));
+            const ticket = this.issueTicket('connection_test', connectionTestSemanticBasis({ ...prepared, connection: projectedConnection }));
             return deepFreeze({
                 kind: 'ready',
                 ticket: ticket,
-                connection: structuredClone(prepared.connection),
+                connection: projectedConnection,
                 modelId,
                 secretMaterial: prepared.secretMaterial,
                 networkProxy: structuredClone(prepared.networkProxy),
@@ -924,13 +1099,19 @@ export class RuntimePolicyCoordinator {
     async completeConnectionTest(ticket, result) {
         const claimed = this.claimTicket(ticket, 'connection_test');
         return this.completeClaimedTicket(claimed, () => this.inLane(async (root) => {
+            if (claimed.basis.kind !== 'connection_test') {
+                throw new Error('Coordinator admitted a non-connection-test ticket');
+            }
             const catalog = await this.catalog.read(root);
             const checked = await this.checkSemanticConnectionBasis(root, catalog, claimed.basis);
             if (checked.changed.length > 0 || !checked.connection) {
                 return deepFreeze({ kind: 'superseded', changed: checked.changed });
             }
             const snapshot = await this.catalog.writeConnectionTestResult(root, catalog, connectionBasis(checked.connection), result);
-            return deepFreeze({ kind: 'committed', snapshot });
+            return deepFreeze({
+                kind: 'committed',
+                snapshot: await this.projectCatalogSnapshot(root),
+            });
         }));
     }
     async prepareConnectionOperation(root, connectionId, action) {
@@ -942,18 +1123,15 @@ export class RuntimePolicyCoordinator {
             return deepFreeze({ kind: 'connection_disabled' });
         const contract = deriveProviderAuthContract({
             providerType: connection.providerType,
-            enabled: true,
             hasSecret: true,
-            lastTestStatus: connection.lastTest?.status,
         });
-        const availability = contract.actionAvailability[action];
-        if (availability !== 'available') {
-            return deepFreeze({ kind: 'provider_action_unavailable', availability });
+        if (!contract.actionAvailability[action]) {
+            return deepFreeze({ kind: 'provider_action_unavailable' });
         }
         return this.prepareConnectionMaterial(root, connection, contract.requiresSecret);
     }
     async prepareConnectionMaterial(root, connection, requiresConnectionSecret) {
-        const authKind = PROVIDER_DEFAULTS[connection.providerType].authKind;
+        const authKind = PROVIDER_REGISTRY[connection.providerType].authKind;
         const locator = connectionCredentialLocator(connection.connectionId, authKind);
         const policy = await this.policy.read(root);
         const networkProxy = structuredClone(policy.policy.networkProxy);
@@ -1017,7 +1195,7 @@ export class RuntimePolicyCoordinator {
             return false;
         if (locator.kind === 'request_headers')
             return true;
-        const required = connectionCredentialLocator(connection.connectionId, PROVIDER_DEFAULTS[connection.providerType].authKind);
+        const required = connectionCredentialLocator(connection.connectionId, PROVIDER_REGISTRY[connection.providerType].authKind);
         if (!required || required.kind !== locator.kind) {
             throw codecError('invalid_credential_input', 'Connection credential kind does not match the provider auth contract');
         }
@@ -1037,14 +1215,18 @@ export class RuntimePolicyCoordinator {
     async checkSemanticConnectionBasis(root, catalog, basis) {
         const connection = findConnection(catalog, { connectionId: basis.connectionId });
         const changed = [];
-        if (!connection ||
-            connection.providerType !== basis.providerType ||
-            !connection.enabled ||
-            canonicalEffectiveEndpoint(connection) !== basis.effectiveEndpoint ||
+        const effectiveConnection = connection && basis.kind === 'connection_test'
+            ? applyConnectionModelOverrides(connection)
+            : connection;
+        if (!effectiveConnection ||
+            effectiveConnection.providerType !== basis.providerType ||
+            !effectiveConnection.enabled ||
+            canonicalEffectiveEndpoint(effectiveConnection) !== basis.effectiveEndpoint ||
             (basis.kind === 'model_fetch' &&
-                !sameStringArray(connection.enabledModelIds, basis.enabledModelIds)) ||
+                !sameStringArray(effectiveConnection.enabledModelIds, basis.enabledModelIds)) ||
             (basis.kind === 'connection_test' &&
-                JSON.stringify(connection.requestBodyOverlay ?? {}) !== basis.requestBodyOverlayJson) ||
+                JSON.stringify(effectiveConnection.requestBodyOverlay ?? {}) !==
+                    basis.requestBodyOverlayJson) ||
             (basis.kind === 'connection_test' &&
                 !sameConnectionTestModelBasis(connectionTestModelBasis(connection), basis.model))) {
             changed.push('connection');
@@ -1073,12 +1255,14 @@ export class RuntimePolicyCoordinator {
         this.tickets.set(ticket, { kind, basis, state: 'available' });
         return ticket;
     }
-    issueInteractiveOAuthLoginTicket(connectionBasisValue, providerType, credentialBasisValue) {
+    issueInteractiveOAuthLoginTicket(attemptId, target, connectionBefore, connectionAfter, credentialBasisValue) {
         const ticket = Object.freeze(Object.create(null));
         this.tickets.set(ticket, {
             kind: 'interactive_oauth_login',
-            connectionBasis: connectionBasisValue,
-            providerType,
+            attemptId,
+            target: structuredClone(target),
+            connectionBefore: connectionBefore ? structuredClone(connectionBefore) : null,
+            connectionAfter: structuredClone(connectionAfter),
             credentialBasis: credentialBasisValue,
             state: 'available',
         });
@@ -1116,7 +1300,12 @@ export class RuntimePolicyCoordinator {
         }
         this.onboardingRecoveryRequired = true;
         try {
-            await this.applyConnectionOnboarding(root, intent);
+            if (intent.schemaVersion === 3) {
+                await this.applyInteractiveOAuthEnrollment(root, intent);
+            }
+            else {
+                await this.applyConnectionOnboarding(root, intent);
+            }
             await clearConnectionOnboardingIntent(root);
             this.onboardingRecoveryRequired = false;
         }
@@ -1131,6 +1320,149 @@ export class RuntimePolicyCoordinator {
             throw commitOutcomeUnknown('Connection onboarding recovery did not converge', error);
         }
     }
+    async applyNetworkProxyUpdate(root, input) {
+        const policy = await this.policy.read(root);
+        const vault = await this.vault.read(root);
+        const locator = networkProxyCredentialLocator();
+        const existing = findCredential(vault, locator);
+        const credentialChanged = input.credential.kind === 'replace'
+            ? existing?.secret !== input.credential.secret
+            : input.credential.kind === 'delete' && existing !== undefined;
+        const proxyChanged = !isDeepStrictEqual(policy.policy.networkProxy, input.networkProxy);
+        const effectiveProxyChanged = !sameEffectiveProxyConfiguration(effectiveProxyConfigurationBasis(policy.policy.networkProxy), effectiveProxyConfigurationBasis(input.networkProxy));
+        const cleared = credentialChanged || effectiveProxyChanged
+            ? await this.catalog.clearAllConnectionLastTests(root, await this.catalog.read(root))
+            : false;
+        let durableChange = cleared;
+        let snapshot = policySnapshot(policy);
+        try {
+            const commitCredential = async () => {
+                if (input.credential.kind === 'replace' && credentialChanged) {
+                    const prepared = this.vault.prepareSet(vault, {
+                        locator,
+                        expected: existing
+                            ? { credentialId: existing.credentialId, revision: existing.revision }
+                            : null,
+                        secret: input.credential.secret,
+                    });
+                    if (prepared.kind !== 'ready') {
+                        throw codecError('invalid_document', 'Network proxy credential update became stale');
+                    }
+                    await this.vault.commitSet(root, prepared);
+                    durableChange = true;
+                }
+                else if (input.credential.kind === 'delete' && existing) {
+                    const prepared = this.vault.prepareDelete(vault, {
+                        expected: credentialBasis(existing),
+                    });
+                    if (prepared.kind !== 'ready') {
+                        throw codecError('invalid_document', 'Network proxy credential deletion became stale');
+                    }
+                    await this.vault.commitDelete(root, prepared);
+                    durableChange = true;
+                }
+            };
+            const commitPolicy = async () => {
+                if (!proxyChanged)
+                    return;
+                const prepared = this.policy.prepareMutation(policy, {
+                    expectedRevision: policy.revision,
+                    operation: { kind: 'set_network_proxy', value: input.networkProxy },
+                });
+                if (prepared.kind !== 'ready') {
+                    throw codecError('invalid_document', 'Network proxy policy update became stale');
+                }
+                snapshot = (await this.policy.commitMutation(root, prepared)).snapshot;
+                durableChange = true;
+            };
+            // Never leave an enabled policy pointing at an absent credential: publish a
+            // replacement before enabling its use, and retire credential use before deletion.
+            if (input.credential.kind === 'delete' &&
+                !requiresNetworkProxyCredential(input.networkProxy)) {
+                await commitPolicy();
+                await commitCredential();
+            }
+            else {
+                await commitCredential();
+                await commitPolicy();
+            }
+        }
+        catch (error) {
+            if (durableChange && !isCommitOutcomeUnknown(error)) {
+                throw commitOutcomeUnknown('Network proxy update committed only some effects', error);
+            }
+            throw error;
+        }
+        const finalVault = await this.vault.read(root);
+        return deepFreeze({
+            kind: 'committed',
+            snapshot,
+            credentialStatus: credentialStatus(finalVault, locator),
+        });
+    }
+    async applyInteractiveOAuthEnrollment(root, intent) {
+        const existingReceipt = findInteractiveOAuthLoginReceipt(await readInteractiveOAuthLoginReceipts(root), intent.attemptId);
+        const intendedIdentity = interactiveOAuthConnectionIdentity(intent.connectionAfter);
+        if (existingReceipt &&
+            (!sameInteractiveOAuthLoginTarget(existingReceipt.target, intent.target) ||
+                existingReceipt.connection.connectionId !== intendedIdentity.connectionId ||
+                existingReceipt.connection.slug !== intendedIdentity.slug ||
+                existingReceipt.connection.providerType !== intendedIdentity.providerType)) {
+            throw codecError('invalid_document', 'OAuth login receipt conflicts with the enrollment intent');
+        }
+        const catalog = await this.catalog.read(root);
+        // Validate the complete catalog transition before the vault-first write.
+        // A damaged intent must never rotate a real account and discover its
+        // identity collision only afterwards.
+        const catalogPrepared = this.catalog.prepareOAuthEnrollmentUpsert(catalog, intent.connectionBefore, intent.connectionAfter);
+        if (catalogPrepared.kind !== 'ready') {
+            throw codecError('invalid_document', `OAuth enrollment catalog preflight returned ${catalogPrepared.kind}`);
+        }
+        const locator = {
+            scope: 'connection',
+            connectionId: intent.connectionAfter.connectionId,
+            kind: 'oauth_token',
+        };
+        const vault = await this.vault.read(root);
+        let credential = findCredential(vault, locator);
+        if (credential?.secret !== intent.secret) {
+            if (intent.credentialBasis
+                ? !sameCredentialBasis(credential, intent.credentialBasis)
+                : credential !== undefined) {
+                throw codecError('invalid_document', 'OAuth enrollment credential basis changed');
+            }
+            const prepared = this.vault.prepareSet(vault, {
+                locator,
+                expected: intent.credentialBasis
+                    ? {
+                        credentialId: intent.credentialBasis.credentialId,
+                        revision: intent.credentialBasis.revision,
+                    }
+                    : null,
+                secret: intent.secret,
+            });
+            if (prepared.kind !== 'ready') {
+                throw codecError('invalid_document', `OAuth enrollment credential write returned ${prepared.kind}`);
+            }
+            await this.vault.commitSet(root, prepared);
+            credential = prepared.entry;
+        }
+        if (!credential) {
+            throw codecError('invalid_document', 'OAuth enrollment did not produce a credential');
+        }
+        await this.catalog.commitPreparedOnboarding(root, catalogPrepared);
+        const connection = intendedIdentity;
+        await upsertInteractiveOAuthLoginReceipt(root, {
+            attemptId: intent.attemptId,
+            target: intent.target,
+            connection,
+        });
+        return {
+            credentialId: credential.credentialId,
+            revision: credential.revision,
+            connection,
+        };
+    }
     async applyConnectionOnboarding(root, intent) {
         let changed = false;
         const catalog = await this.catalog.read(root);
@@ -1139,7 +1471,7 @@ export class RuntimePolicyCoordinator {
         // Validate the durable identity and final catalog shape before touching
         // the vault. A damaged v2 intent must not rotate a real connection's
         // credential before discovering that its ID/slug pair cannot commit.
-        const prepared = this.catalog.prepareOnboardingUpsert(catalog, intent.connectionId, slug, intent.providerType, intent.baseUrl, intent.enabledModelIds, intent.discovery, intent.invalidateLastTest);
+        const prepared = this.catalog.prepareOnboardingUpsert(catalog, intent.connectionId, slug, intent.providerType, intent.name, intent.baseUrl, intent.enabledModelIds, intent.discovery, intent.invalidateLastTest);
         if (prepared.kind === 'slug_conflict') {
             throw codecError('invalid_document', intent.schemaVersion === 1
                 ? 'Legacy onboarding intent conflicts with the connection id'
@@ -1149,11 +1481,10 @@ export class RuntimePolicyCoordinator {
             throw codecError('invalid_document', 'Onboarding intent exceeds the connection catalog');
         }
         if (intent.suppliedSecret !== null) {
-            const locator = {
-                scope: 'connection',
-                connectionId: intent.connectionId,
-                kind: 'api_key',
-            };
+            const locator = connectionCredentialLocator(intent.connectionId, PROVIDER_REGISTRY[intent.providerType].authKind);
+            if (!locator) {
+                throw codecError('invalid_document', 'Onboarding provider has no credential locator');
+            }
             const vault = await this.vault.read(root);
             const existing = findCredential(vault, locator);
             if (existing?.secret !== intent.suppliedSecret) {
@@ -1193,6 +1524,20 @@ export class RuntimePolicyCoordinator {
             return operation(root);
         });
     }
+    async projectCatalogSnapshot(root) {
+        return deepFreeze(catalogSnapshot(await this.catalog.read(root)));
+    }
+    async projectCatalogMutation(root, result) {
+        if (result.kind !== 'committed' || !('snapshot' in result))
+            return result;
+        return deepFreeze({
+            ...result,
+            snapshot: await this.projectCatalogSnapshot(root),
+        });
+    }
+}
+function matchesCredentialExpectation(actual, expected) {
+    return expected === null ? actual === undefined : sameCredentialBasis(actual, expected);
 }
 function isCommitOutcomeUnknown(error) {
     return error instanceof RuntimePolicyStoreError && error.code === 'commit_outcome_unknown';
@@ -1345,5 +1690,83 @@ function requiresNetworkProxyCredential(networkProxy) {
     return networkProxy.enabled && networkProxy.authEnabled;
 }
 function isInteractiveOAuthLoginProvider(providerType) {
-    return providerType === 'openai-codex' || providerType === 'xai-oauth';
+    return (providerType === 'openai-codex' ||
+        providerType === 'xai-oauth' ||
+        providerType === 'github-copilot');
+}
+function normalizeInteractiveOAuthLoginInput(input) {
+    const attemptId = decodeInteractiveOAuthAttemptId(input?.attemptId, 'invalid_connection_input');
+    const target = input?.target;
+    if (target?.kind === 'create') {
+        const providerType = decodeConnectionInput(() => decodeProviderType(target.providerType));
+        if (!isInteractiveOAuthLoginProvider(providerType)) {
+            throw codecError('invalid_connection_input', 'OAuth create target provider is unsupported');
+        }
+        if (providerType !== 'openai-codex' &&
+            (target.slug !== undefined || target.name !== undefined)) {
+            throw codecError('invalid_connection_input', 'Custom OAuth Connection identity is only supported for openai-codex');
+        }
+        if (providerType !== 'openai-codex') {
+            return { attemptId, target: { kind: 'create', providerType } };
+        }
+        return {
+            attemptId,
+            target: {
+                kind: 'create',
+                providerType,
+                ...(target.slug === undefined
+                    ? {}
+                    : { slug: decodeConnectionInput(() => decodeConnectionSlug(target.slug)) }),
+                ...(target.name === undefined
+                    ? {}
+                    : { name: decodeConnectionInput(() => decodeConnectionName(target.name)) }),
+            },
+        };
+    }
+    if (target?.kind === 'existing') {
+        return {
+            attemptId,
+            target: {
+                kind: 'existing',
+                connectionId: decodeConnectionInput(() => decodeRuntimePolicyEntityId(target.connectionId)),
+            },
+        };
+    }
+    throw codecError('invalid_connection_input', 'Unknown interactive OAuth login target');
+}
+function newInteractiveOAuthConnection(connectionId, slug, providerType, name) {
+    const defaults = PROVIDER_REGISTRY[providerType];
+    return {
+        connectionId,
+        revision: 1,
+        slug,
+        name: name ?? defaults.label,
+        providerType,
+        enabled: true,
+        enabledModelIds: providerFallbackModelIds(defaults),
+        models: [],
+    };
+}
+function reenabledInteractiveOAuthConnection(connection) {
+    if (connection.enabled && connection.lastTest === undefined)
+        return structuredClone(connection);
+    const { lastTest: _lastTest, ...withoutLastTest } = connection;
+    return {
+        ...withoutLastTest,
+        revision: nextRevision(connection.revision),
+        enabled: true,
+    };
+}
+function interactiveOAuthConnectionIdentity(connection) {
+    return {
+        connectionId: connection.connectionId,
+        slug: connection.slug,
+        providerType: connection.providerType,
+    };
+}
+function decodeInteractiveOAuthAttemptId(value, source) {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(value)) {
+        throw codecError(source, 'OAuth attempt id is invalid');
+    }
+    return value;
 }