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?”{ 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.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