Class: AgentRuntimeMutationManager
Makaio Framework / ai-adapters-core / AgentRuntimeMutationManager
Class: AgentRuntimeMutationManager
Section titled “Class: AgentRuntimeMutationManager”Defined in: ../../../adapters/core/src/agent/agent-runtime-mutation-manager.ts:76
Handles runtime mutation requests for AIAgent (cwd/model/credential changes).
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new AgentRuntimeMutationManager(
config):AgentRuntimeMutationManager
Defined in: ../../../adapters/core/src/agent/agent-runtime-mutation-manager.ts:92
Parameters
Section titled “Parameters”config
Section titled “config”AgentRuntimeMutationManagerConfig
Returns
Section titled “Returns”AgentRuntimeMutationManager
Methods
Section titled “Methods”handleCredentialChanged()
Section titled “handleCredentialChanged()”handleCredentialChanged(
payload):Promise<{success:true;swapped:true; } | {reason:string;success:false; }>
Defined in: ../../../adapters/core/src/agent/agent-runtime-mutation-manager.ts:479
Handle a credential rotation request.
When a turn is active, returns { success: false, reason: 'turn_active' }.
Otherwise:
- Rebuilds provider context from storage (validates providerConfigId)
- Fires
credential.activateso extensions prepare native stores - Swaps the connector with updated providerContext (forces re-resolution)
Parameters
Section titled “Parameters”payload
Section titled “payload”Credential change request payload
adapterId
Section titled “adapterId”string = ...
Adapter instance identifier (required)
adapterName
Section titled “adapterName”string = ...
Adapter type name (e.g., ‘claude-code’) (required)
adapterSessionId?
Section titled “adapterSessionId?”string = ...
Provider’s native session ID is optional for persisted agents during credential fan-out.
agentId
Section titled “agentId”string = ...
Unique agent identifier (required)
changeSequence
Section titled “changeSequence”number = CredentialChangeSequenceSchema
Monotonic per-provider-config change token used to reject stale fan-out.
clientId?
Section titled “clientId?”string = ...
Client identifier for the owning application/runtime when known.
credentialRefs
Section titled “credentialRefs”Record<string, string> = ...
Updated credential references to resolve.
definitionId
Section titled “definitionId”string = ...
Provider definition ID (e.g., 'anthropic').
messageId?
Section titled “messageId?”string = ...
User message ID being processed (for correlation with user_message lifecycle events)
occurredAt?
Section titled “occurredAt?”number = ...
Event occurrence timestamp in epoch milliseconds when known.
providerConfigId
Section titled “providerConfigId”string = ...
Provider config UUID whose credentials changed.
sessionId?
Section titled “sessionId?”string = ...
Makaio session ID (NOT provider’s native session ID)
turnId?
Section titled “turnId?”string = ...
Turn ID from the session orchestrator. Optional for backward compatibility.
Returns
Section titled “Returns”Promise<{ success: true; swapped: true; } | { reason: string; success: false; }>
Success/failure result
handleCwdChange()
Section titled “handleCwdChange()”handleCwdChange(
payload):Promise<{previousCwd?:string;reason?:string;success:boolean; }>
Defined in: ../../../adapters/core/src/agent/agent-runtime-mutation-manager.ts:111
Handle agent.cwd.change request.
Parameters
Section titled “Parameters”payload
Section titled “payload”CWD change request payload
adapterId
Section titled “adapterId”string = ...
Adapter instance identifier (required)
adapterName
Section titled “adapterName”string = ...
Adapter type name (e.g., ‘claude-code’) (required)
adapterSessionId
Section titled “adapterSessionId”string = ...
Provider’s native session ID (e.g., Claude conversation ID)
agentId
Section titled “agentId”string = ...
Unique agent identifier (required)
clientId?
Section titled “clientId?”string = ...
Client identifier for the owning application/runtime when known.
messageId?
Section titled “messageId?”string = ...
User message ID being processed (for correlation with user_message lifecycle events)
newCwd
Section titled “newCwd”string = ...
New working directory path
occurredAt?
Section titled “occurredAt?”number = ...
Event occurrence timestamp in epoch milliseconds when known.
providerConfigId?
Section titled “providerConfigId?”string = ...
Resolved provider configuration identifier when known.
sessionId?
Section titled “sessionId?”string = ...
Makaio session ID (NOT provider’s native session ID)
skipWarning?
Section titled “skipWarning?”boolean = ...
Skip interactive warning dialog for trusted/programmatic callers
turnId?
Section titled “turnId?”string = ...
Turn ID from the session orchestrator. Optional for backward compatibility.
Returns
Section titled “Returns”Promise<{ previousCwd?: string; reason?: string; success: boolean; }>
CWD mutation response payload
handleModelChange()
Section titled “handleModelChange()”handleModelChange(
payload):Promise<{appliedReasoningEffort?:"none"|"low"|"medium"|"high"|"extra-high";model?:string;reason?:string;success:boolean;supportedReasoningLevels?: {extra-high?:string|number;high?:string|number;low?:string|number;medium?:string|number;none?:string|number; };swapped?:boolean; }>
Defined in: ../../../adapters/core/src/agent/agent-runtime-mutation-manager.ts:154
Handle agent.model.change request.
Implements a four-branch decision tree based on the presence of newModel
and reasoningEffort in the request payload:
- Both present → change model, then apply reasoningEffort (with fallback)
- Model only → change model, run fallback chain for reasoning
- Effort only → change reasoning in-place, no model swap logic
- Neither → no-op (return current state)
Parameters
Section titled “Parameters”payload
Section titled “payload”Model change request payload
adapterId
Section titled “adapterId”string = ...
Adapter instance identifier (required)
adapterName
Section titled “adapterName”string = ...
Adapter type name (e.g., ‘claude-code’) (required)
adapterSessionId
Section titled “adapterSessionId”string = ...
Provider’s native session ID (e.g., Claude conversation ID)
agentId
Section titled “agentId”string = ...
Unique agent identifier (required)
clientId?
Section titled “clientId?”string = ...
Client identifier for the owning application/runtime when known.
messageId?
Section titled “messageId?”string = ...
User message ID being processed (for correlation with user_message lifecycle events)
newModel?
Section titled “newModel?”string = ...
New model identifier. Optional when only changing reasoning effort without switching models.
occurredAt?
Section titled “occurredAt?”number = ...
Event occurrence timestamp in epoch milliseconds when known.
providerConfigId?
Section titled “providerConfigId?”string = ...
Resolved provider configuration identifier when known.
providerContext?
Section titled “providerContext?”{ ambientCredentialEnvVars?: string[]; credentialEnvVars?: Record<string, string>; credentialRefs: Record<string, string>; definitionId: string; endpointOverrides?: { anthropic?: string; openai?: string; }; providerConfigId: string; } = ...
Unresolved provider context (credential refs, not plaintext).
Connectors resolve credentials locally via resolveConnectorCredentials().
providerContext.ambientCredentialEnvVars?
Section titled “providerContext.ambientCredentialEnvVars?”string[] = ...
Provider credential environment variables known to the host.
Subprocess adapters remove these from ambient process.env before spawning
clients, then add back only credentials explicitly resolved from
credentialRefs.
providerContext.credentialEnvVars?
Section titled “providerContext.credentialEnvVars?”Record<string, string> = ...
Maps credential keys to environment variable names for subprocess adapters.
E.g., { apiKey: 'ANTHROPIC_API_KEY' }.
providerContext.credentialRefs
Section titled “providerContext.credentialRefs”Record<string, string> = ...
Credential references resolved at the connector layer, not on the bus.
providerContext.definitionId
Section titled “providerContext.definitionId”string = ...
Provider definition ID (e.g., 'anthropic', 'alibaba').
providerContext.endpointOverrides?
Section titled “providerContext.endpointOverrides?”{ anthropic?: string; openai?: string; } = ...
Endpoint URL overrides keyed by protocol.
providerContext.endpointOverrides.anthropic?
Section titled “providerContext.endpointOverrides.anthropic?”string = ...
providerContext.endpointOverrides.openai?
Section titled “providerContext.endpointOverrides.openai?”string = ...
providerContext.providerConfigId
Section titled “providerContext.providerConfigId”string = ...
Provider config UUID. Links back to the ProviderConfig that produced this context.
reasoningEffort?
Section titled “reasoningEffort?”"none" | "low" | "medium" | "high" | "extra-high" = ...
Reasoning effort level to apply after the model change.
sessionId?
Section titled “sessionId?”string = ...
Makaio session ID (NOT provider’s native session ID)
skipWarning?
Section titled “skipWarning?”boolean = ...
Skip interactive warning dialog for trusted/programmatic callers
turnId?
Section titled “turnId?”string = ...
Turn ID from the session orchestrator. Optional for backward compatibility.
Returns
Section titled “Returns”Promise<{ appliedReasoningEffort?: "none" | "low" | "medium" | "high" | "extra-high"; model?: string; reason?: string; success: boolean; supportedReasoningLevels?: { extra-high?: string | number; high?: string | number; low?: string | number; medium?: string | number; none?: string | number; }; swapped?: boolean; }>
Model mutation response payload