"""Foundational coding-agent session abstraction."""
from __future__ import annotations
import asyncio
import base64
import copy
import inspect
import logging
import os
import re
import time
import traceback
from collections.abc import Awaitable, Callable, Mapping, Sequence
from collections.abc import Set as AbstractSet
from contextlib import contextmanager
from dataclasses import dataclass, field, replace
from datetime import datetime
from typing import Any, Literal, NoReturn, TypedDict
from misaka.agent.agent import Agent
from misaka.agent.agent_loop import RunToolCallOptions, runToolCall
from misaka.agent.types import (
AgentContext,
AgentLoopTurnUpdate,
AgentMessage,
AgentRequestUpdate,
AgentState,
AgentTool,
AgentToolCallOutcome,
AgentToolResult,
AgentTurnContext,
AgentTurnDecision,
PrepareNextTurnContext,
PrepareRequestContext,
ThinkingLevel,
)
from misaka.ai.compat import resetApiProviders, streamSimple
from misaka.ai.models import (
clampThinkingLevel,
getSupportedThinkingLevels,
modelsAreEqual,
)
from misaka.ai.session_resources import cleanupSessionResources
from misaka.ai.types import (
AssistantMessage,
ImageContent,
Model,
SystemMessage,
TextContent,
ToolCall,
validate_message,
)
from misaka.ai.utils.headers import providerHeadersToRecord
from misaka.ai.utils.overflow import isContextOverflow, isRecoverableLength
from misaka.ai.utils.retry import (
RetryCallbacks,
RetryPolicy,
isRetryableAssistantError,
retryDelayMs,
)
from misaka.ai.utils.transcript import (
getCurrentSystemMessage,
getCurrentTools,
getToolStateChanges,
toToolDeclaration,
)
from misaka.core.auth_guidance import (
formatNoApiKeyFoundMessage,
formatNoModelSelectedMessage,
)
from misaka.core.bash_executor import BashResult, executeBashWithOperations
from misaka.core.cache_warmer import CacheWarmer, CacheWarmingStatus
from misaka.core.compaction import (
CompactionPreparation,
CompactionSettings,
calculateContextTokens,
compact,
estimateContextTokens,
prepareCompaction,
shouldCompact,
)
from misaka.core.compaction import (
CompactionResult as SessionCompactionResult,
)
from misaka.core.compaction.branch_summarization import (
GenerateBranchSummaryOptions,
collectEntriesForBranchSummary,
generateBranchSummary,
)
from misaka.core.compaction.compaction import (
estimateProjectedContextTokens,
estimateTokens,
)
from misaka.core.defaults import DEFAULT_THINKING_LEVEL
from misaka.core.export_html import exportSessionToHtml
from misaka.core.export_html.tool_renderer import (
ToolHtmlRendererDeps,
createToolHtmlRenderer,
)
from misaka.core.extensions.runner import (
BeforeAgentStartTrigger,
ExtensionRunner,
emitSessionShutdownEvent,
)
from misaka.core.extensions.types import (
ExecuteToolOptions,
ExtensionCommandContextActions,
ExtensionError,
ExtensionErrorListener,
ExtensionMode,
ExtensionUIContext,
RegisteredTool,
ToolDefinition,
ToolExposure,
ToolInfo,
ToolLoadout,
)
from misaka.core.extensions.wrapper import wrapRegisteredTool
from misaka.core.mcp_servers import createToolNameMatcher, isMcpToolName
from misaka.core.messages import BashExecutionMessage, convertToLlm
from misaka.core.model_registry import ModelRegistry
from misaka.core.model_runtime import ModelRuntime, is_rejected_credential_error
from misaka.core.moments import CoreCommand, Moments
from misaka.core.nested_tool_calls import NestedToolCallOptions, NestedToolCallRunner
from misaka.core.prompt_templates import PromptTemplate, expandPromptTemplate
from misaka.core.resource_loader import ResourceLoaderLike
from misaka.core.session_export import exportSessionToJsonl
from misaka.core.session_manager import (
SessionManager,
SessionProjection,
getLatestCompactionEntry,
)
from misaka.core.settings_manager import (
DEFAULT_TOOL_NAMES,
SettingsManager,
applyToolModifiers,
)
from misaka.core.slash_commands import SlashCommandInfo, _make_slash_command_info
from misaka.core.source_info import (
BUILTIN_PATH_PREFIX,
SourceInfo,
createSyntheticSourceInfo,
isSyntheticPath,
)
from misaka.core.system_prompt import (
buildSystemPrompt,
buildSystemPromptSections,
diffSystemPromptSections,
normalizeBuildSystemPromptOptions,
)
from misaka.core.tools import createAllToolDefinitions
from misaka.core.tools.bash import createLocalBashOperations
from misaka.core.tools.tool_definition_wrapper import (
createToolDefinitionFromAgentTool,
)
from misaka.core.usage_totals import addUsageToTotals, combineUsage, createUsageTotals
from misaka.core.virtual_models import (
VIRTUAL_MODEL_STATE_ENTRY,
VirtualModelDefinition,
VirtualModelStateData,
answersAsOtherModels,
findLatestResponse,
getBranchSelection,
getVirtualModelState,
isVirtualModel,
)
from misaka.modes.interactive.theme.theme import getThemeByName, theme
from misaka.utils._abort_signal import AnyAbortSignal
from misaka.utils.image_process import ProcessImageOptions, processImage
from misaka.utils.image_resize import ImageResizeOptions
from misaka.utils.js import AbortController
from misaka.utils.tool_result_images import (
NormalizeToolResultImagesOptions,
normalizeToolResultImages,
)
from misaka.utils.values import read_field
_SKILL_BLOCK_PATTERN = re.compile(
r'^\n([\s\S]*?)\n(?:\n\n([\s\S]+))?$'
)
_STALE_CONTEXT_MESSAGE = (
"This extension ctx is stale after session replacement or reload. Do not use a captured pi or command ctx "
"after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and "
"switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For "
"reload, do not use the old ctx after await ctx.reload()."
)
_THINKING_LEVELS: tuple[ThinkingLevel, ...] = (
"off", "minimal", "low", "medium", "high", "xhigh", "max",
)
# Strong references to fire-and-forget session tasks; see `_holdBackgroundTask`.
_BACKGROUND_TASKS: set[asyncio.Task[Any]] = set()
class _CompactionCancelledByExtension(RuntimeError):
"""MISAKA fork: pi's `cancelledByExtension` flag. The `session_before_compact` hook runs inside the
operation `_prepareCompactionOperation` returns, so the cancellation reaches the caller as this type."""
@dataclass(slots=True)
class ParsedSkillBlock:
name: str
location: str
content: str
userMessage: str | None = None
AgentSessionEvent = Any
AgentSessionEventListener = Callable[[AgentSessionEvent], None]
@dataclass(slots=True)
class AgentSessionConfig:
agent: Agent
sessionManager: SessionManager
settingsManager: SettingsManager
cwd: str
resourceLoader: ResourceLoaderLike
modelRuntime: ModelRuntime
scopedModels: list[dict[str, Any]] = field(default_factory=list)
customTools: list[Any] = field(default_factory=list)
cacheWarmer: CacheWarmer | None = None
# MISAKA fork: the session's own subsystems, called from core.moments ahead of extensions.
parts: list[Any] = field(default_factory=list)
initialActiveToolNames: list[str] | None = None
# Whether the initial tools come from the `defaultTools` setting. When true, a resumed session
# replaces them with the loadout its transcript records, with `defaultToolModifiers` applied, and
# reload activates tools newly added to the setting. Tools removed from it stay active.
usesDefaultTools: bool = False
# `+name`/`-name` entries applied on top of the `defaultTools` setting, from `--tools`. Reload
# applies them to the reloaded setting too, so a removed tool stays removed.
defaultToolModifiers: list[str] | None = None
# Optional allowlist of tool names or patterns (`*` matches any characters). When provided, only
# matching tools are exposed. A non-empty list without `mcp__` entries also keeps MCP tools
# registered for codemode and tool_search; only tool_search can declare them. An empty list
# exposes no tools.
allowedToolNames: list[str] | None = None
baseToolsOverride: dict[str, AgentTool] | None = None
extensionRunnerRef: dict[str, Any] | None = None
sessionStartEvent: dict[str, Any] | None = None
# Optional denylist of tool names or patterns. When provided, matching tools are not exposed.
excludedToolNames: list[str] | None = None
@dataclass(slots=True)
class ExtensionBindings:
uiContext: ExtensionUIContext | None = None
# Which run mode is driving the session (pi agent-session.ts:234,2421-2423).
mode: ExtensionMode | None = None
commandContextActions: ExtensionCommandContextActions | None = None
abortHandler: Callable[[], None] | None = None
shutdownHandler: Callable[[], None] | None = None
onError: ExtensionErrorListener | None = None
@dataclass(slots=True)
class SessionTokenStats:
input: int
output: int
cacheRead: int
cacheWrite: int
total: int
@dataclass(slots=True)
class SessionStats:
sessionFile: str | None
sessionId: str
userMessages: int
assistantMessages: int
toolCalls: int
toolResults: int
totalMessages: int
tokens: SessionTokenStats
cost: float
contextUsage: dict[str, float | int | None] | None = None
QueuedInputDisposition = Literal["handled", "queued"]
PromptDisposition = Literal["handled", "queued", "started"]
@dataclass(slots=True)
class PromptOptions:
expandPromptTemplates: bool = True
images: list[ImageContent] | None = None
streamingBehavior: str | None = None
source: str = "interactive"
# Observes how an accepted prompt was dispatched. Not called if the prompt is rejected.
preflightResult: Callable[[PromptDisposition], None] | None = None
class ModelMutationOptions(TypedDict, total=False):
# Persist the new value to global defaults. Defaults to session-only.
persist: bool
# Result from cycleModel()
@dataclass(slots=True)
class ModelCycleResult:
model: Model[Any]
thinkingLevel: ThinkingLevel
isScoped: bool
@dataclass(frozen=True, slots=True)
class RoutedModel:
"""Physical model and thinking level of the latest successful response under a virtual selection."""
model: Model[Any]
thinkingLevel: ThinkingLevel | None = None
@dataclass(slots=True)
class _ToolDefinitionEntry:
definition: Any
sourceInfo: SourceInfo
promptSnippet: str | None = None
promptGuidelines: list[str] = field(default_factory=list)
def parseSkillBlock(text: str) -> ParsedSkillBlock | None:
match = _SKILL_BLOCK_PATTERN.match(text)
if match:
return ParsedSkillBlock(
name=match.group(1),
location=match.group(2),
content=match.group(3),
userMessage=match.group(4).strip() if match.group(4) else None,
)
# MISAKA keeps Pi's historical transcript renderer, while /skill now emits
# Hermes' activation scaffold. Parse both so old and new sessions collapse.
from misaka.core.skills.wiring.skills import parse_skill_invocation_message
parsed = parse_skill_invocation_message(text)
if parsed is None:
return None
return ParsedSkillBlock(
name=parsed["name"],
location=parsed["location"],
content=parsed["content"],
userMessage=parsed["user_instruction"],
)
class AgentSession:
# MISAKA fork: a session built without __init__ (test doubles) has no parts.
moments: Moments = Moments(None, [])
# Class-level defaults for doubles built without __init__, as `moments`.
_nestedToolCalls: NestedToolCallRunner | None = None
_hiddenDeclarations: frozenset[str] = frozenset()
def __init__(self, config: AgentSessionConfig | dict[str, Any]) -> None:
resolved = config if isinstance(config, AgentSessionConfig) else AgentSessionConfig(**config)
self.agent = resolved.agent
# MISAKA fork: queued background-task notifications go in together, in one turn (R28).
self.agent.deliverTogether = _is_task_notification
self.sessionManager = resolved.sessionManager
self.settingsManager = resolved.settingsManager
self._cwd = resolved.cwd
self._resourceLoader = resolved.resourceLoader
self._modelRuntime = resolved.modelRuntime
self._modelRegistry: ModelRegistry | None = None
self._scopedModels = list(resolved.scopedModels)
self._customTools = list(resolved.customTools)
self._cacheWarmer = resolved.cacheWarmer
if self._cacheWarmer is not None:
self._cacheWarmer.onWarmed = lambda entry: self._emit({"type": "entry_appended", "entry": entry})
self.moments = Moments(self, list(resolved.parts)) # MISAKA fork
self._initialActiveToolNames = (
list(resolved.initialActiveToolNames) if resolved.initialActiveToolNames is not None else None
)
# Tools of the restored or reloaded loadout that are not registered yet, such as tools of MCP
# servers that are still connecting. They are activated when they are registered, and dropped when
# `setActiveToolsByName()` deactivates a tool or the next agent run starts.
# Insertion-ordered, like pi's `Set`: restored tools are redeclared in transcript order.
self._pendingToolNames: dict[str, None] = {}
self._usesDefaultTools = bool(resolved.usesDefaultTools)
self._defaultToolModifiers: list[str] = list(resolved.defaultToolModifiers or [])
# Matches the `--tools` entries: tool names or patterns.
self._allowedTools: Callable[[str], bool] | None = None
# Whether the allowlist filters MCP tools: it is empty (`--no-tools`) or names an MCP tool
# (`mcp__*`). Otherwise it keeps MCP tools registered for codemode and tool_search.
self._allowlistFiltersMcp = False
if resolved.allowedToolNames is not None:
self._allowedTools = createToolNameMatcher(resolved.allowedToolNames)
self._allowlistFiltersMcp = len(resolved.allowedToolNames) == 0 or any(
entry.startswith("mcp__") for entry in resolved.allowedToolNames
)
self._excludedTools: Callable[[str], bool] | None = (
createToolNameMatcher(resolved.excludedToolNames) if resolved.excludedToolNames is not None else None
)
self._disallowedToolNames: set[str] = set()
self._toolAdmission: Callable[[str], bool] | None = None
self._alwaysAllowedToolNames: set[str] = set()
self._baseToolsOverride = (
dict(resolved.baseToolsOverride) if resolved.baseToolsOverride is not None else None
)
self._extensionRunnerRef = resolved.extensionRunnerRef
self._sessionStartEvent = resolved.sessionStartEvent or {"type": "session_start", "reason": "startup"}
self._eventListeners: list[AgentSessionEventListener] = []
self._unsubscribeAgent = self.agent.subscribe(self._handleAgentEvent)
self._extensionErrorUnsubscriber: Callable[[], None] | None = None
self._extensionAbortHandler: Callable[[], None] | None = None
self._extensionShutdownHandler: Callable[[], None] | None = None
self._extensionBindings: ExtensionBindings | None = None
self._extensionUIContext: ExtensionUIContext | None = None
self._extensionMode: ExtensionMode = "print"
self._extensionCommandContextActions: ExtensionCommandContextActions | None = None
self._extensionErrorListener: ExtensionErrorListener | None = None
self._steeringMessages: list[str] = []
self._followUpMessages: list[str] = []
self._pendingNextTurnMessages: list[dict[str, Any]] = []
self._pendingBashMessages: list[BashExecutionMessage] = []
self._pendingCustomMessages: list[dict[str, Any]] = []
self._customMessageReceipts: dict[str, dict[str, Any]] = {}
self._bashAbortControllers: set[AbortController] = set()
self._auto_compaction_abort_controller: AbortController | None = None
self._compactionAbortController: AbortController | None = None
self._branchSummaryAbortController: AbortController | None = None
self._overflow_recovery_attempted = False
# True for the whole run driven by _startRun, not just the inner agent loop:
# retries, auto-compaction and every continue_() between them are still "busy"
# (pi agent-session.ts _isAgentRunActive).
self._isAgentRunActive = False
self._agentRunAbortRequested = False
self._idleWaiters: list[asyncio.Future[None]] = []
self._retryAbortController: AbortController | None = None
self._retryAttempt = 0
# Failed response that the next request repeats, set by auto-retry and overflow recovery. The
# retry is routed with it as `failed`, since the context no longer contains it.
self._failedResponse: AssistantMessage | None = None
# MISAKA fork: the model the current request goes to, routed or not. A context engine sizes
# itself from it at the provider boundary; under a virtual selection `self.model` has no
# window of its own.
self._requestModel: Model[Any] | None = None
self._turnIndex = 0
# pi keys these by message object in a WeakMap; pydantic messages are neither
# hashable nor weak-referenceable, so they are keyed by `id()` and the map is rebuilt
# from the projection on every refresh, which is where pi's entries would be collected.
self._entryIdsByMessage: dict[int, tuple[Any, str]] = {}
self._boundaryDispatchedMessages: set[int] = set()
self._lastAssistantMessage: AssistantMessage | None = None
self._lastAssistantToolResults: list[Any] = []
self._lastActivityOutcome = "completed"
self._isBeforeSettle = False
self._abortDuringBeforeSettle = False
self._isEmittingAgentSettled = False
self._deferredSettledActions: list[Callable[[], Awaitable[None]]] = []
self._stopHookContinuationPending = False
self._baseToolDefinitions: dict[str, Any] = {}
self._toolRegistry: dict[str, AgentTool] = {}
self._toolDefinitions: dict[str, _ToolDefinitionEntry] = {}
# Runs the calls tools make through ctx.executeTool(); created on the first one.
self._nestedToolCalls = None
# Declared tools whose declarations prepareLoadout hooks hide from requests.
self._hiddenDeclarations = frozenset()
self._baseSystemPromptOptions: dict[str, Any] = normalizeBuildSystemPromptOptions({"cwd": self._cwd})
# Prompt options after before_agent_start mutations for the active run.
self._runSystemPromptOptions: dict[str, Any] | None = None
self._toolScopes: list[dict[str, Any]] = []
self._unscopedToolNames: list[str] = []
# MISAKA fork: the last tool scope ended while a run was working; see `toolScope`.
self._recordLoadoutAfterRun = False
self._installAgentToolHooks()
self._installAgentNextTurnRefresh()
self._installAgentRequestProjection()
self._installAgentBoundaryHooks()
self._installHiddenDeclarationsProjection()
self._installAgentForcedPromptProjection()
self._buildRuntime(
{
"activeToolNames": self._initialActiveToolNames,
"includeAllExtensionTools": True,
}
)
if self._usesDefaultTools:
self._restoreToolsFromTranscript(self._defaultToolModifiers)
@property
def extensionRunner(self) -> ExtensionRunner:
return self._extensionRunner
@property
def modelRuntime(self) -> ModelRuntime:
return self._modelRuntime
@property
def modelRegistry(self) -> ModelRegistry:
"""MISAKA fork: the extension-facing facade over ``modelRuntime``, one per session and
shared with the ExtensionRunner, for code that reads the registry (subagents)."""
if self._modelRegistry is None:
self._modelRegistry = ModelRegistry(self._modelRuntime)
return self._modelRegistry
@property
def resourceLoader(self) -> ResourceLoaderLike:
return self._resourceLoader
@property
def state(self) -> AgentState:
return self.agent.state
@property
def model(self) -> Model[Any] | None:
return self.agent.state.model
@property
def thinkingLevel(self) -> ThinkingLevel:
return self.agent.state.thinkingLevel
@property
def routedModel(self) -> RoutedModel | None:
"""Under a virtual selection, the physical model and thinking level of the latest successful response."""
# MISAKA fork: an MoA preset reports its aggregator the same way.
if self.model is None or not answersAsOtherModels(self.model):
return None
latest = findLatestResponse(self.agent.state.messages)
model = (
self._modelRuntime.getPhysicalModel(read_field(latest, "provider"), read_field(latest, "model"))
if latest is not None
else None
)
return RoutedModel(model=model, thinkingLevel=read_field(latest, "thinkingLevel")) if model is not None else None
@property
def isStreaming(self) -> bool:
"""Whether the session is processing an agent run or a post-run continuation.
This is the run-level flag, not ``agent.state.isStreaming``: the inner loop goes
idle between two ``continue_()`` calls, during retry backoff and during
auto-compaction, and pi reports busy for all of those (agent-session.ts:900-908).
"""
return self._isAgentRunActive
@property
def isIdle(self) -> bool:
"""No active agent run, retry, auto-compaction or queued continuation."""
return not self._isAgentRunActive
async def waitForIdle(self) -> None:
if self.isIdle:
return
waiter: asyncio.Future[None] = asyncio.get_running_loop().create_future()
self._idleWaiters.append(waiter)
await waiter
def _modelResizeOptions(self) -> ImageResizeOptions | None:
"""The limits model's `inputLimits.images.resize`, as the resizer's own options."""
# `model.inputLimits?.images?.resize`, whether the limits are models or plain mappings.
resize = read_field(read_field(read_field(self._limitsModel(), "inputLimits"), "images"), "resize")
if resize is None:
return None
return ImageResizeOptions(
maxWidth=read_field(resize, "maxWidth"),
maxHeight=read_field(resize, "maxHeight"),
maxBytes=read_field(resize, "maxBytes"),
jpegQuality=read_field(resize, "jpegQuality"),
)
async def _normalizePromptImages(self, images: Sequence[ImageContent] | None) -> tuple[list[ImageContent], list[str]]:
"""Resize prompt attachments to the model's cache-safe profile; a failed image becomes a hint."""
if not images:
return [], []
normalized_images: list[ImageContent] = []
hints: list[str] = []
for image in images:
# Images arrive as models from the TUI and as plain mappings from RPC/skill callers.
data = read_field(image, "data")
mime_type = read_field(image, "mimeType")
processed = await processImage(
base64.b64decode(data),
mime_type,
ProcessImageOptions(
autoResizeImages=self.settingsManager.getImageAutoResize(),
resizeOptions=self._modelResizeOptions(),
),
)
if not processed.ok:
hints.append(processed.message)
continue
normalized_images.append(ImageContent(data=processed.data, mimeType=processed.mimeType))
hints.extend(processed.hints)
return normalized_images, hints
def refreshContext(self) -> None:
"""Refresh the public finalized transcript from the canonical session projection."""
self._refreshFinalizedContext()
@property
def cacheWarmingStatus(self) -> CacheWarmingStatus | None:
"""Current cache-warming state and the policy inputs that produced it."""
return self._cacheWarmer.status if self._cacheWarmer is not None else None
def setCacheWarmingMode(self, mode: str) -> None:
"""Persist the cache-warming mode and immediately reconcile active warming."""
self.settingsManager.setCacheWarmingMode(mode)
if self._cacheWarmer is not None:
self._cacheWarmer.onModeChanged()
@property
def systemPrompt(self) -> str:
"""Current effective system prompt, including changes not yet sent to the model."""
return buildSystemPrompt(
self._runSystemPromptOptions if self._runSystemPromptOptions is not None else self._baseSystemPromptOptions
)
@property
def isCompacting(self) -> bool:
return any(
controller is not None
for controller in (
self._auto_compaction_abort_controller,
self._compactionAbortController,
self._branchSummaryAbortController,
)
)
@property
def messages(self) -> list[AgentMessage]:
return self.agent.state.messages
@property
def steeringMode(self) -> str:
return self.agent.steeringMode
@property
def followUpMode(self) -> str:
return self.agent.followUpMode
@property
def sessionFile(self) -> str | None:
return self.sessionManager.getSessionFile()
@property
def sessionId(self) -> str:
return self.sessionManager.getSessionId()
@property
def sessionName(self) -> str | None:
return self.sessionManager.getSessionName()
@property
def scopedModels(self) -> list[dict[str, Any]]:
return list(self._scopedModels)
@property
def promptTemplates(self) -> list[PromptTemplate]:
return list(self._resourceLoader.getPrompts()["prompts"])
@property
def autoCompactionEnabled(self) -> bool:
return self.settingsManager.getCompactionEnabled()
@property
def autoRetryEnabled(self) -> bool:
return self.settingsManager.getRetryEnabled()
@property
def isRetrying(self) -> bool:
return self._retryAbortController is not None
@property
def retryAttempt(self) -> int:
return self._retryAttempt
@property
def pendingMessageCount(self) -> int:
return len(self._steeringMessages) + len(self._followUpMessages)
@property
def isBashRunning(self) -> bool:
return len(self._bashAbortControllers) > 0
@property
def hasPendingBashMessages(self) -> bool:
return len(self._pendingBashMessages) > 0
def setScopedModels(self, scopedModels: list[dict[str, Any]]) -> None:
self._scopedModels = list(scopedModels)
def subscribe(self, listener: AgentSessionEventListener) -> Callable[[], None]:
self._eventListeners.append(listener)
def unsubscribe() -> None:
if listener in self._eventListeners:
self._eventListeners.remove(listener)
return unsubscribe
def dispose(self) -> None:
try:
self.abortRetry()
self.abortCompaction()
self.abortBranchSummary()
self.abortBash()
self.agent.abort()
except Exception: # noqa: BLE001,S110 - Pi disposal ignores abort-hook failures
pass
for delivery_id in list(self._customMessageReceipts):
self._failCustomReceipt(delivery_id, RuntimeError("session closed before persistence"))
self._extensionRunner.invalidate(_STALE_CONTEXT_MESSAGE)
self._disconnectFromAgent()
self._eventListeners = []
if self._cacheWarmer is not None:
self._cacheWarmer.onWarmed = None
self._cacheWarmer.cancel()
cleanupSessionResources(self.sessionId)
def _disconnectFromAgent(self) -> None:
if self._unsubscribeAgent is not None:
self._unsubscribeAgent()
self._unsubscribeAgent = None
async def abort(self) -> None:
"""Abort current operation and wait for agent to become idle."""
if self._isAgentRunActive:
self._agentRunAbortRequested = True
self.abortRetry()
self.abortCompaction()
self.abortBranchSummary()
if self._isBeforeSettle:
self._abortDuringBeforeSettle = True
self.agent.abort()
# Wait for the whole run to settle, not just the inner agent loop: pi
# (agent-session.ts:1599-1603) returns only once the post-run continuation,
# retry and auto-compaction windows are done too.
await self.waitForIdle()
async def _getRequiredRequestAuth(self, model: Model[Any], signal: Any | None = None) -> dict[str, Any]:
try:
result = await self._modelRuntime.getAuth(model, _auth_overrides(signal))
except Exception as error:
cause = error.__cause__
if isinstance(cause, Exception) and str(cause) == "authHeader requires a resolved API key":
raise RuntimeError(
formatNoApiKeyFoundMessage(model.provider)
) from error
raise
if result and (result.auth.apiKey or result.auth.headers is not None):
request_model = (
model.model_copy(update={"baseUrl": result.auth.baseUrl})
if result.auth.baseUrl
else model
)
return {
"model": request_model,
"apiKey": result.auth.apiKey,
"headers": providerHeadersToRecord(result.auth.headers),
"env": result.env,
}
if self._modelRuntime.isUsingOAuth(model.provider):
raise RuntimeError(
f'Authentication failed for "{model.provider}". '
"Credentials may have expired or network is unavailable. "
f"Run '/login {model.provider}' to re-authenticate."
)
raise RuntimeError(formatNoApiKeyFoundMessage(model.provider))
async def _getSummarizationRequestAuth(
self, selected_model: Model[Any], signal: Any | None = None
) -> dict[str, Any]:
# Route a virtual model first: summaries size their input and output from the model they get.
if isVirtualModel(selected_model):
route = await self._modelRuntime.resolveModel(selected_model, convertToLlm(self.messages), {"reason": "direct", "thinkingLevel": self.thinkingLevel, "signal": signal})
model, thinking_level = route.model, route.thinkingLevel
else:
model, thinking_level = selected_model, self.thinkingLevel
if self.agent.streamFunction == streamSimple:
return {**await self._getRequiredRequestAuth(model, signal), "thinkingLevel": thinking_level}
try:
result = await self._modelRuntime.getAuth(model, _auth_overrides(signal))
if result is None:
return {"model": model, "thinkingLevel": thinking_level}
request_model = (
model.model_copy(update={"baseUrl": result.auth.baseUrl})
if result.auth.baseUrl
else model
)
return {
"model": request_model,
"apiKey": result.auth.apiKey,
"headers": providerHeadersToRecord(result.auth.headers),
"env": result.env,
"thinkingLevel": thinking_level,
}
except Exception: # custom streams may own credentials outside the registry
if signal is not None and signal.aborted:
raise
return {"model": model, "thinkingLevel": thinking_level}
def _modelForMessage(self, message: AssistantMessage) -> Model[Any] | None:
"""The model whose limits apply to `message`, or None when the message came from another
model. Under a virtual selection, that is the physical model that produced it."""
model = self.model
# MISAKA fork: under an MoA preset the aggregator produced the message.
if model is not None and answersAsOtherModels(model):
return self._modelRuntime.getPhysicalModel(message.provider, message.model)
return model if model is not None and model.provider == message.provider and model.id == message.model else None
def _recordSelection(self) -> None:
"""Record the selection on the current branch when the branch implies another one, so a resume
restores it. Tree navigation can leave the latest `model_change` on another branch; responses
cannot record a virtual selection because they name physical models. Responses do record a
physical selection unless the branch holds a virtual one; checking a physical selection against
responses would record it on every prompt while `prepareRequest` redirects to another model."""
model = self.model
if model is None:
return
get_model = self._modelRuntime.getModel
recorded = getBranchSelection(self.sessionManager.getBranch(), get_model)
if recorded is None or (recorded["provider"] == model.provider and recorded["modelId"] == model.id):
return
recorded_model = get_model(recorded["provider"], recorded["modelId"])
# MISAKA fork: MoA presets are recorded like virtual models while they are in the catalog. One
# that left it still answers through an aggregator, so recording it would repeat every prompt.
holds = isVirtualModel(model) or (answersAsOtherModels(model) and get_model(model.provider, model.id) is not None)
if not holds and not (recorded_model is not None and answersAsOtherModels(recorded_model)):
return
self.sessionManager.appendModelChange(model.provider, model.id)
def _limitsModel(self) -> Model[Any] | None:
"""The model whose limits apply to the conversation."""
routed = self.routedModel
return routed.model if routed is not None else self.model
async def prompt(
self,
text: str,
options: PromptOptions | dict[str, Any] | None = None,
) -> None:
if self._isEmittingAgentSettled:
async def deferred_prompt() -> None:
await self.prompt(text, options)
self._deferredSettledActions.append(deferred_prompt)
return
resolved = options if isinstance(options, PromptOptions) else PromptOptions(**dict(options or {}))
def report_preflight(disposition: PromptDisposition) -> None:
if resolved.preflightResult is not None:
resolved.preflightResult(disposition)
def assert_not_compacting() -> None:
if self._compactionAbortController is not None:
raise RuntimeError(
"Cannot submit a prompt while compaction is in progress. "
"Wait for compaction to finish and retry."
)
# MISAKA fork: skill commands prepare text for this same submission.
# Keep its images, delivery mode, preflight and cancellation ownership.
prompt_command = self.getCorePromptCommand(text) if resolved.expandPromptTemplates else None
if (
resolved.expandPromptTemplates
and prompt_command is None
and text.startswith("/")
and (
await self._tryExecuteCoreCommand(text) # MISAKA fork: a part's command first
or await self._tryExecuteExtensionCommand(text)
)
):
# Extension command executed, no prompt to send
report_preflight("handled")
return
# Compaction replaces agent.state.messages wholesale, so a prompt accepted while
# it runs would append into a list that is about to be thrown away. pi refuses
# instead of racing (agent-session.ts:1155-1159). The extension-command branch
# above stays reachable, exactly as in pi.
assert_not_compacting()
current_text = await self._expandCorePromptCommand(prompt_command, text) if prompt_command else text
if current_text is None:
report_preflight("handled")
return
if prompt_command is not None:
assert_not_compacting()
# Generated command messages retain sendUserMessage's input origin:
# /research's pending-question capture must not consume a skill scaffold.
input_source = "extension" if prompt_command else resolved.source
current_images = None if resolved.images is None else list(resolved.images)
processed_input = await self._runInputHandlers(
current_text,
current_images,
input_source,
resolved.streamingBehavior if self.isStreaming else None,
)
if processed_input is None:
report_preflight("handled")
return
current_text, current_images = processed_input
if resolved.expandPromptTemplates and prompt_command is None:
current_text = expandPromptTemplate(current_text, self.promptTemplates)
if self.isStreaming:
if resolved.streamingBehavior == "followUp":
await self._queueFollowUp(current_text, current_images)
report_preflight("queued")
return
if resolved.streamingBehavior == "steer":
await self._queueSteer(current_text, current_images)
report_preflight("queued")
return
raise RuntimeError(
"Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the "
"message."
)
if self.model is None:
raise RuntimeError(formatNoModelSelectedMessage())
has_configured_auth = (
self._modelRuntime.hasConfiguredAuth(self.model.provider)
or await self._modelRuntime.checkAuth(self.model.provider) is not None
)
if not has_configured_auth:
if self._modelRuntime.isUsingOAuth(self.model.provider):
raise RuntimeError(
f'Authentication failed for "{self.model.provider}". '
"Credentials may have expired or network is unavailable. "
f"Run '/login {self.model.provider}' to re-authenticate."
)
raise RuntimeError(formatNoApiKeyFoundMessage(self.model.provider))
await self._startRun(
{"messageType": "user", "prompt": current_text, "images": current_images},
lambda: report_preflight("started"),
# MISAKA fork: a core prompt command's text must not land in a conversation that a
# compaction started during the hooks is about to replace.
admit=assert_not_compacting if prompt_command is not None else None,
)
async def _emitBeforeAgentStart(self, trigger: BeforeAgentStartTrigger):
"""The before_agent_start hooks: the messages they contribute and the run's prompt options."""
selected_tools_before = list(self._baseSystemPromptOptions["selectedTools"])
# MISAKA fork: the session's own parts run first; an extension sees the prompt
# options and the messages as core left them.
core = await self.moments.before_agent_start(trigger, self._baseSystemPromptOptions)
if core.block:
_raiseRunBlocked(trigger, core.reason or "a core part blocked the turn")
contributed: list[Any] = list(core.messages)
options = core.system_prompt_options
if self._extensionRunner.hasHandlers("before_agent_start"):
before_result = await self._extensionRunner.emitBeforeAgentStart(trigger, options)
if before_result and _event_field(before_result, "block", False):
_raiseRunBlocked(
trigger,
str(_event_field(before_result, "reason", "before_agent_start hook blocked the turn")),
)
contributed.extend(_event_field(before_result, "messages") or [])
options = _event_field(before_result, "systemPromptOptions", options)
# Handlers may edit event.systemPromptOptions.selectedTools or call setActiveTools(),
# which updates the live loadout instead. An explicit edit wins; otherwise the live
# loadout is authoritative, so a setActiveTools() call is not undone here.
handler_edited_tools = list(options["selectedTools"]) != selected_tools_before
if not handler_edited_tools:
options["selectedTools"] = self.getActiveToolNames()
return contributed, options
async def _runInputHandlers(
self,
text: str,
images: list[ImageContent] | None,
source: Any,
streaming_behavior: Any,
) -> tuple[str, list[ImageContent] | None] | None:
"""Parts first, then extensions (MISAKA fork: pi has only the runner). None when a
handler took the input."""
input_result = await self.moments.input(text, images, source, streaming_behavior)
action = _event_field(input_result, "action", "continue")
if action == "handled":
return None
if action == "transform":
text = _event_field(input_result, "text", text)
transformed_images = _event_field(input_result, "images", None)
if transformed_images is not None:
images = list(transformed_images)
if not self._extensionRunner.hasHandlers("input"):
return text, images
input_result = await self._extensionRunner.emitInput(text, images, source, streaming_behavior)
action = _event_field(input_result, "action", "continue")
if action == "handled":
return None
if action == "transform":
text = _event_field(input_result, "text", text)
transformed_images = _event_field(input_result, "images", None)
if transformed_images is not None:
images = list(transformed_images)
return text, images
async def _queueUserInput(
self, text: str, images: Sequence[ImageContent] | None, behavior: str, source: Any
) -> QueuedInputDisposition:
command = self.getCorePromptCommand(text) # MISAKA fork: a part's prompt command first
if command is not None:
expanded = await self._expandCorePromptCommand(command, text)
if expanded is None:
return "handled"
text = expanded
elif text.startswith("/"):
self._throwIfExtensionCommand(text)
processed_input = await self._runInputHandlers(
text, None if images is None else list(images), source, behavior if self.isStreaming else None
)
if processed_input is None:
return "handled"
expanded_text, processed_images = processed_input
if command is None:
expanded_text = expandPromptTemplate(expanded_text, self.promptTemplates)
if behavior == "steer":
await self._queueSteer(expanded_text, processed_images)
else:
await self._queueFollowUp(expanded_text, processed_images)
return "queued"
async def steer(
self, text: str, images: Sequence[ImageContent] | None = None, options: dict[str, Any] | None = None
) -> QueuedInputDisposition:
"""Queue a steering message while the agent is running. Delivered after the current
assistant turn finishes executing its tool calls, before the next LLM call. Runs the
`input` handlers, expands skill commands and prompt templates; errors on extension commands."""
return await self._queueUserInput(text, images, "steer", (options or {}).get("source", "interactive"))
async def followUp(
self, text: str, images: Sequence[ImageContent] | None = None, options: dict[str, Any] | None = None
) -> QueuedInputDisposition:
"""Queue a follow-up message to be processed after the agent finishes. Delivered only
when agent has no more tool calls or steering messages. Runs the `input` handlers,
expands skill commands and prompt templates; errors on extension commands."""
return await self._queueUserInput(text, images, "followUp", (options or {}).get("source", "interactive"))
def _emitQueueUpdate(self) -> None:
self._emit(
{
"type": "queue_update",
"steering": list(self._steeringMessages),
"followUp": list(self._followUpMessages),
}
)
async def _queueSteer(self, text: str, images: Sequence[ImageContent] | None = None) -> None:
self._steeringMessages.append(text)
self._emitQueueUpdate()
self.agent.steer(self._buildUserMessage(text, images))
async def _queueFollowUp(self, text: str, images: Sequence[ImageContent] | None = None) -> None:
self._followUpMessages.append(text)
self._emitQueueUpdate()
self.agent.followUp(self._buildUserMessage(text, images))
def _throwIfExtensionCommand(self, text: str) -> None:
command_text = text.removeprefix("/")
command_name = command_text.split(" ", 1)[0]
if self._extensionRunner.getCommand(command_name) is not None:
raise RuntimeError(
f'Extension command "/{command_name}" cannot be queued. '
"Use prompt() or execute the command when not streaming."
)
def setSessionName(self, name: str, *, is_user: bool = True) -> None:
self.sessionManager.appendSessionInfo(name, is_user=is_user)
event = {"type": "session_info_changed", "name": self.sessionManager.getSessionName()}
self._emit(event)
# pi agent-session.ts:3063-3068 sends the same event to the extension runner as well;
# only the UI half was ported, so `session_info_changed` handlers never ran.
self._spawnBackground(self._extensionRunner.emit(event), "session_info_changed")
def clearQueue(self) -> dict[str, list[str]]:
steering = list(self._steeringMessages)
follow_up = list(self._followUpMessages)
self._steeringMessages = []
self._followUpMessages = []
self.agent.clearAllQueues()
retained = {(message.get("details") or {}).get("delivery_id")
for message in [*self._pendingCustomMessages, *self._pendingNextTurnMessages]
if isinstance(message.get("details"), dict)}
for delivery_id in set(self._customMessageReceipts) - retained:
self._failCustomReceipt(delivery_id, RuntimeError("message queue cleared before persistence"))
self._emitQueueUpdate()
return {"steering": steering, "followUp": follow_up}
def getSteeringMessages(self) -> list[str]:
return list(self._steeringMessages)
def getFollowUpMessages(self) -> list[str]:
return list(self._followUpMessages)
async def _emitModelSelect(
self,
nextModel: Model[Any],
previousModel: Model[Any] | None,
source: Literal["set", "cycle", "restore"],
) -> None:
if modelsAreEqual(previousModel, nextModel):
return
await self._extensionRunner.emit(
{
"type": "model_select",
"model": nextModel,
"previousModel": previousModel,
"source": source,
}
)
async def setModel(self, model: Model[Any], options: ModelMutationOptions | None = None) -> None:
"""Set model directly.
Validates that auth is configured and saves to the session transcript.
Persists to global defaults only when options.persist is true.
MISAKA fork: SettingsManager saves to this session's role when bound, otherwise to the global default.
@throws Error if no auth is configured for the model
"""
options = options or {}
if not await self._modelRuntime.checkAuth(model.provider):
raise RuntimeError(f"No API key for {model.provider}/{model.id}")
previousModel = self.model
thinkingLevel = self._getThinkingLevelForModelSwitch(model)
# MISAKA fork: the settings write goes first; a role whose default cannot be saved here refuses it and the
# session keeps its model.
if options.get("persist"):
self.settingsManager.setDefaultModelAndProvider(model.provider, model.id)
self.agent.state.model = model
self.sessionManager.appendModelChange(model.provider, model.id)
if options.get("persist"):
self._addPersistedDefaultToNonEmptyScope(model)
# Apply thinking level for the new model.
# Per-model thinking level overrides take priority over the global default.
# Model persistence does not implicitly rewrite the global thinking default.
self.setThinkingLevel(thinkingLevel)
await self._emitModelSelect(model, previousModel, "set")
def _addPersistedDefaultToNonEmptyScope(self, model: Model[Any]) -> None:
if not self._scopedModels:
return
if any(modelsAreEqual(item["model"], model) for item in self._scopedModels):
return
self._scopedModels = [*self._scopedModels, {"model": model}]
if getattr(self.settingsManager, "getModelProfile", lambda: None)():
return
enabled_models = self.settingsManager.getEnabledModels()
if not enabled_models:
return
model_reference = f"{model.provider}/{model.id}"
if any(pattern.lower() == model_reference.lower() for pattern in enabled_models):
return
self.settingsManager.setEnabledModels([*enabled_models, model_reference])
def setThinkingLevel(self, level: ThinkingLevel, options: ModelMutationOptions | None = None) -> None:
"""Set thinking level.
Clamps to model capabilities based on available thinking levels.
Saves the clamped level to the session transcript only if the level actually changes.
Persists the requested level to global defaults only when options.persist is true.
"""
options = options or {}
model = self.model
clamped = level if model is None else clampThinkingLevel(model, level)
previous_level = self.agent.state.thinkingLevel
self.agent.state.thinkingLevel = clamped
if options.get("persist"):
self.settingsManager.setDefaultThinkingLevel(level)
if clamped == previous_level:
return
self.sessionManager.appendThinkingLevelChange(clamped)
self._emit({"type": "thinking_level_changed", "level": clamped})
if self._extensionRunner.hasHandlers("thinking_level_select"):
async def emit_change() -> None:
await self._extensionRunner.emit(
{
"type": "thinking_level_select",
"level": clamped,
"previousLevel": previous_level,
}
)
try:
loop = asyncio.get_running_loop()
except RuntimeError:
pass # no loop to deliver on; the UI half of the event already went out
else:
self._holdBackgroundTask(loop.create_task(emit_change()), "thinking_level_select")
def getAvailableThinkingLevels(self) -> list[ThinkingLevel]:
if self.model is None:
return list(_THINKING_LEVELS)
return list(getSupportedThinkingLevels(self.model))
def supportsThinking(self) -> bool:
return bool(self.model and self.model.reasoning)
def cycleThinkingLevel(self, options: ModelMutationOptions | None = None) -> ThinkingLevel | None:
"""Cycle to next thinking level.
@returns New level, or undefined if model doesn't support thinking
"""
if not self.supportsThinking():
return None
levels = self.getAvailableThinkingLevels()
# `indexOf` gives -1 for a level the model lacks, so the cycle starts at the first level.
currentIndex = levels.index(self.thinkingLevel) if self.thinkingLevel in levels else -1
nextIndex = (currentIndex + 1) % len(levels)
nextLevel = levels[nextIndex]
self.setThinkingLevel(nextLevel, options)
return nextLevel
async def cycleModel(
self, direction: Literal["forward", "backward"] = "forward", options: ModelMutationOptions | None = None
) -> ModelCycleResult | None:
"""Cycle to next/previous model.
Uses scoped models (from --models flag) if available, otherwise all available models.
@param direction - "forward" (default) or "backward"
@returns The new model info, or undefined if only one model available
"""
options = options or {}
if self._scopedModels:
return await self._cycleScopedModel(direction, options)
return await self._cycleAvailableModel(direction, options)
async def _cycleScopedModel(
self, direction: Literal["forward", "backward"], options: ModelMutationOptions
) -> ModelCycleResult | None:
available_ids = {(model.provider, model.id) for model in self._modelRuntime.getAvailableSnapshot()}
scoped_models = [
item for item in self._scopedModels if (item["model"].provider, item["model"].id) in available_ids
]
if len(scoped_models) <= 1:
return None
current_model = self.model
current_index = next(
(index for index, item in enumerate(scoped_models) if modelsAreEqual(item["model"], current_model)),
-1,
)
current_index = max(current_index, 0)
next_index = (current_index + (1 if direction == "forward" else -1)) % len(scoped_models)
next_model = scoped_models[next_index]["model"]
thinking_level = self._getThinkingLevelForModelSwitch(
next_model,
scoped_models[next_index].get("thinkingLevel"),
)
# MISAKA fork: the settings write goes first; a role whose default cannot be saved here refuses it and the
# session keeps its model.
if options.get("persist"):
self.settingsManager.setDefaultModelAndProvider(next_model.provider, next_model.id)
# Apply model
self.agent.state.model = next_model
self.sessionManager.appendModelChange(next_model.provider, next_model.id)
if options.get("persist"):
self._addPersistedDefaultToNonEmptyScope(next_model)
# Apply thinking level for the new model.
# - Explicit scoped model thinking level overrides defaults
# - Per-model thinking level overrides take priority over the global default
# setThinkingLevel clamps to model capabilities.
# Model persistence does not implicitly rewrite the global thinking default.
self.setThinkingLevel(thinking_level)
await self._emitModelSelect(next_model, current_model, "cycle")
return ModelCycleResult(model=next_model, thinkingLevel=self.thinkingLevel, isScoped=True)
async def _cycleAvailableModel(
self, direction: Literal["forward", "backward"], options: ModelMutationOptions
) -> ModelCycleResult | None:
available_models = self._modelRuntime.getAvailableSnapshot()
if len(available_models) <= 1:
return None
current_model = self.model
current_index = next(
(index for index, model in enumerate(available_models) if modelsAreEqual(model, current_model)),
-1,
)
current_index = max(current_index, 0)
next_index = (current_index + (1 if direction == "forward" else -1)) % len(available_models)
next_model = available_models[next_index]
thinking_level = self._getThinkingLevelForModelSwitch(next_model)
# MISAKA fork: the settings write goes first; a role whose default cannot be saved here refuses it and the
# session keeps its model.
if options.get("persist"):
self.settingsManager.setDefaultModelAndProvider(next_model.provider, next_model.id)
self.agent.state.model = next_model
self.sessionManager.appendModelChange(next_model.provider, next_model.id)
if options.get("persist"):
self._addPersistedDefaultToNonEmptyScope(next_model)
# Apply thinking level for the new model.
# Model persistence does not implicitly rewrite the global thinking default.
self.setThinkingLevel(thinking_level)
await self._emitModelSelect(next_model, current_model, "cycle")
return ModelCycleResult(model=next_model, thinkingLevel=self.thinkingLevel, isScoped=False)
def _getThinkingLevelForModelSwitch(
self,
targetModel: Model[Any] | None = None,
explicitLevel: ThinkingLevel | None = None,
) -> ThinkingLevel:
if explicitLevel is not None:
return explicitLevel
# MISAKA fork: the agent's own default comes before the shared per-model table.
own = self.settingsManager.getRoleThinkingLevel()
if own is not None:
return own
if targetModel is not None:
per_model = self.settingsManager.getModelThinkingLevel(targetModel.provider, targetModel.id)
if per_model is not None:
return per_model
return self.settingsManager.getDefaultThinkingLevel() or self.thinkingLevel or DEFAULT_THINKING_LEVEL
def setSteeringMode(self, mode: str) -> None:
self.agent.steeringMode = mode
self.settingsManager.setSteeringMode(mode)
def setFollowUpMode(self, mode: str) -> None:
self.agent.followUpMode = mode
self.settingsManager.setFollowUpMode(mode)
def getPermissionMode(self) -> str | None:
for part in self.moments.parts:
getter = getattr(part, "get_permission_mode", None)
if callable(getter):
return getter()
return None
def setPermissionMode(self, mode: str) -> None:
for part in self.moments.parts:
setter = getattr(part, "set_permission_mode", None)
if callable(setter):
setter(mode)
return
raise ValueError("This session has no agent permission policy part")
def registerCustomTools(self, definitions: list[Any]) -> None:
# MISAKA fork: a part adding tools after startup (an MCP server that answered late)
# takes the door ``customTools`` took, then the refresh an extension's registerTool gets.
self._customTools.extend(definitions)
self.refreshTools()
def unregisterCustomTools(self, definitions: list[Any]) -> None:
"""Remove precisely the temporary definitions the caller installed, not namesakes."""
identities = {id(definition) for definition in definitions}
self._customTools = [tool for tool in self._customTools if id(tool) not in identities]
self.refreshTools()
def refreshTools(self) -> None:
# MISAKA fork: the runtime action of the same name, callable by a part that changed a
# definition it already registered (a description that depends on the session).
self._refreshToolRegistry()
def getActiveToolNames(self) -> list[str]:
"""Get the names of currently active tools, which are the tools declared to the model.
Tools with ``codemode`` or ``deferred`` exposure are callable from other tools without
being active."""
return [tool.name for tool in self.agent.state.tools]
def getCallableToolNames(self) -> list[str]:
"""Get the names of the tools that tools can call through ``ctx.executeTool()``."""
return [tool.name for tool in self._getCallableTools()]
def getAllTools(self) -> list[ToolInfo]:
"""Get all configured tools with name, description, parameter schema, prompt guidelines,
and source metadata."""
tools: list[ToolInfo] = []
for entry in self._toolDefinitions.values():
definition = entry.definition
namespace = _definition_attr(definition, "namespace")
annotations = _definition_attr(definition, "annotations")
reaches_tools = _definition_attr(definition, "reachesTools")
tools.append(
ToolInfo(
name=definition.name,
description=definition.description,
parameters=definition.parameters,
promptGuidelines=list(getattr(definition, "promptGuidelines", None) or []),
exposure=self._getToolExposure(definition.name),
namespace=namespace if namespace else None,
annotations=dict(annotations) if annotations else None,
reachesTools=reaches_tools if reaches_tools else None,
sourceInfo=entry.sourceInfo,
)
)
return tools
def getToolDefinition(self, name: str) -> Any | None:
entry = self._toolDefinitions.get(name)
return entry.definition if entry is not None else None
def getSlashCommands(self) -> list[SlashCommandInfo]:
commands: list[SlashCommandInfo] = []
for command in self._extensionRunner.getRegisteredCommands():
invocation_name = str(read_field(command, "invocationName", read_field(command, "name", ""))).strip()
if not invocation_name:
continue
commands.append(
_make_slash_command_info(
invocation_name,
"extension",
read_field(command, "sourceInfo")
or createSyntheticSourceInfo(
f"",
{"source": "inline", "scope": "temporary", "origin": "extension"},
),
read_field(command, "description"),
)
)
for core_command in self.moments.commands(): # MISAKA fork: the parts' commands
commands.append(
_make_slash_command_info(
core_command.name,
"core",
createSyntheticSourceInfo(f"", {"source": "sdk"}),
core_command.description,
)
)
for template in self.promptTemplates:
commands.append(
_make_slash_command_info(
str(template.name),
"prompt",
template.sourceInfo
or createSyntheticSourceInfo(
f"",
{"source": "auto", "scope": "project", "origin": "prompt"},
),
template.description,
)
)
return commands
def setActiveToolsByName(self, toolNames: list[str]) -> None:
"""Set active tools by name.
Only tools in the registry can be enabled. Unknown and hidden tool names are ignored.
Also rebuilds the system prompt to reflect the new tool set. Changes take effect on the
next agent turn.
"""
previous = self.getActiveToolNames()
if self._toolScopes:
# MISAKA fork: a caller inside a scope sees only the scoped loadout (`[...active, x]`).
# Selected tools the scope hides from it stay selected underneath, in place; tools the
# scope itself granted (visible before the call) do not outlive it.
names = list(dict.fromkeys(toolNames))
visible, chosen = set(previous), set(names)
self._unscopedToolNames = [
*(name for name in self._unscopedToolNames if name in chosen or name not in visible),
*(name for name in names if name not in self._unscopedToolNames and name not in visible),
]
self._toolScopes[-1]["active"] = list(toolNames)
self._setActiveTools(toolNames)
# A loadout that deactivates a tool replaces the restored one, whose pending tools are dropped.
# One that only adds tools, like activating tool_search, keeps them.
active = set(self.getActiveToolNames())
if any(name not in active for name in previous):
self._pendingToolNames.clear()
@contextmanager
def toolScope(self, toolNames: Sequence[str], callable: Sequence[str] = ()):
"""Temporary selection AND ceiling, independent of registry refresh.
Keep the normal selection live underneath: late registrations, removals,
reloads and explicit user changes survive leaving the scope. Nested scopes
intersect; they never change the session's persistent permission settings.
``callable`` names tools the scope lets other tools call (codemode scripts
calling MCP tools) without declaring them to the model; its entries may be ``*``
patterns, so tools registered after the scope starts can be admitted too.
"""
scope = {"allowed": createToolNameMatcher([*toolNames, *callable]), "active": list(toolNames)}
if not self._toolScopes:
self._unscopedToolNames = self.getActiveToolNames()
self._toolScopes.append(scope)
try:
self._setActiveTools(scope["active"])
yield
finally:
self._toolScopes = [item for item in self._toolScopes if item is not scope]
names = self._toolScopes[-1]["active"] if self._toolScopes else self._unscopedToolNames
self._setActiveTools(names)
if not self._toolScopes:
# MISAKA fork: a run inside the scope declared the scope's tools in the transcript,
# which a resume or `/tree` restores as the lasting loadout.
self.recordLoadout()
def recordLoadout(self) -> bool:
"""MISAKA fork: declare the loadout now, for a change a resume must not lose to the transcript;
return whether it is declared. A run still working could declare the old tools after it, so
it waits for that run."""
if self._isAgentRunActive:
self._recordLoadoutAfterRun = True
return False
self._recordUnscopedLoadout()
return True
def _recordUnscopedLoadout(self) -> None:
"""MISAKA fork: declare the live loadout in the transcript when it differs from the loadout
the transcript declares, as the tool patch the next run would write. Used when the last
tool scope ends: pi's invariant that the transcript's declarations are the lasting loadout
(restored on resume and `/tree`) then holds for the scope's runs too. A transcript that
declares no loadout is left alone: restoring it keeps the default tools."""
if self._toolScopes:
return
messages = self.sessionManager.buildSessionContext().messages
if getCurrentSystemMessage(messages) is None:
return
changes = getToolStateChanges(
getCurrentTools(messages), [toToolDeclaration(tool) for tool in self.agent.state.tools]
)
if len(changes.toolsAdded) == 0 and len(changes.toolsRemoved) == 0:
return
update = SystemMessage(
content="",
toolsAdded=changes.toolsAdded or None,
toolsRemoved=changes.toolsRemoved or None,
timestamp=int(time.time() * 1000),
)
# Recorded as a run records its messages (`message_end`): appended to the conversation and the transcript.
entry_id = self.sessionManager.appendMessage(_message_dict(update))
self.agent.state.messages = [*self.agent.state.messages, update]
self._entryIdsByMessage[id(update)] = (update, entry_id)
def _setActiveTools(self, toolNames: Sequence[str]) -> None:
tools = self._applyToolLoadout(list(toolNames))
for tool in tools:
self._pendingToolNames.pop(tool.name, None)
self._rebuildSystemPrompt([tool.name for tool in tools])
def _getToolExposure(self, name: str) -> ToolExposure:
entry = self._toolDefinitions.get(name)
exposure = _definition_attr(entry.definition, "exposure") if entry is not None else None
return exposure or "direct"
def _getCallableTools(self, active: AbstractSet[str] | None = None) -> list[AgentTool]:
"""Tools callable through ``ctx.executeTool()``: the active ``direct`` tools and every
registered ``codemode`` or ``deferred`` tool."""
if active is None:
active = set(self.getActiveToolNames())
tools = [
tool
for tool in self._toolRegistry.values()
if (exposure := self._getToolExposure(tool.name)) in ("codemode", "deferred")
or (exposure == "direct" and tool.name in active)
]
# MISAKA fork: a nested call answers to the same boundaries as a model-issued one. The
# registry is already inside the admission, allow and deny lists; a tool scope (a
# research window) and the parts' projections (driver-owned tools) narrow it further.
for scope in self._toolScopes:
tools = [tool for tool in tools if scope["allowed"](tool.name)]
return self.moments.project_tools(tools)
def _applyToolLoadout(self, toolNames: list[str]) -> list[AgentTool]:
"""Set the agent's tools for the given active tool names and return them. The active
tools are the registered, non-hidden ones; they are declared to the model. Active tools
with a ``prepareLoadout`` hook can change the declared descriptions and hide declarations
from requests (see ``_installHiddenDeclarationsProjection``).
The active tools are a set: tools that stay active keep their current order and newly active
ones are appended, so reordering the same names does not change the prompt (#11495)."""
# MISAKA fork: the tool scopes, the browser_exec/bash pairing and the parts' projections
# apply to every loadout, so every path that sets the agent's tools honours them.
for scope in self._toolScopes:
toolNames = [name for name in toolNames if scope["allowed"](name)]
requested = dict.fromkeys(toolNames)
kept = [name for name in self.getActiveToolNames() if name in requested]
tools = [
self._toolRegistry[name]
for name in dict.fromkeys([*kept, *requested])
if name in self._toolRegistry and self._getToolExposure(name) != "hidden" and self._isActivatable(name)
]
if not any(tool.name == "bash" for tool in tools):
tools = [tool for tool in tools if tool.name != "browser_exec"]
elif any(tool.name == "browser_exec" for tool in tools):
from misaka.core.web.browser.settings import BASE_TOOLS
tools = [tool for tool in tools if tool.name not in BASE_TOOLS]
tools = self.moments.project_tools(tools)
hooks = [
entry
for tool in tools
if (entry := self._toolDefinitions.get(tool.name)) is not None
and _definition_attr(entry.definition, "prepareLoadout")
]
hidden: set[str] = set()
declared = tools
if hooks:
def get_namespace(name: str) -> Any:
entry = self._toolDefinitions.get(name)
return _definition_attr(entry.definition, "namespace") if entry is not None else None
def get_prompt_guidelines(name: str) -> list[str]:
entry = self._toolDefinitions.get(name)
return list(entry.promptGuidelines) if entry is not None else []
loadout = ToolLoadout(
declared=tuple(tools),
callable=tuple(self._getCallableTools({tool.name for tool in tools})),
registered=tuple(self._toolRegistry.values()),
getExposure=self._getToolExposure,
getNamespace=get_namespace,
getPromptGuidelines=get_prompt_guidelines,
)
descriptions: dict[str, str] = {}
for entry in hooks:
try:
changes = _definition_attr(entry.definition, "prepareLoadout")(loadout)
descriptions.update(read_field(changes, "descriptions") or {})
hidden.update(read_field(changes, "hiddenDeclarations") or [])
except Exception as error: # noqa: BLE001 - extension code: reported through the runner
self._extensionRunner.emitError(
ExtensionError(
extensionPath=entry.sourceInfo.path,
event="prepare_loadout",
error=str(error),
stack="".join(traceback.format_exception(error)),
)
)
declared = [
tool if (description := descriptions.get(tool.name)) is None
else tool.model_copy(update={"description": description})
for tool in tools
]
self._hiddenDeclarations = frozenset(hidden)
self.agent.state.tools = declared
return declared
def setDisallowedToolsByName(
self,
toolNames: list[str],
alwaysAllowed: list[str] | None = None,
*,
admission: Callable[[str], bool] | None = None,
) -> None:
"""Apply a case-insensitive deny-list to current and future tools."""
self._disallowedToolNames = {
name.casefold() for name in toolNames if isinstance(name, str) and name
}
self._toolAdmission = admission
self._alwaysAllowedToolNames = {
name
for name in (alwaysAllowed or [])
if isinstance(name, str) and name
}
# The selection stays; tools the change lets through join as new registrations do.
self._refreshToolRegistry()
async def bindExtensions(self, bindings: ExtensionBindings | dict[str, Any] | None = None) -> None:
resolved = bindings if isinstance(bindings, ExtensionBindings) else ExtensionBindings(**(bindings or {}))
self._extensionBindings = resolved
if resolved.uiContext is not None:
self._extensionUIContext = resolved.uiContext
if resolved.mode is not None:
self._extensionMode = resolved.mode
if resolved.commandContextActions is not None:
self._extensionCommandContextActions = resolved.commandContextActions
if resolved.abortHandler is not None:
self._extensionAbortHandler = resolved.abortHandler
if resolved.shutdownHandler is not None:
self._extensionShutdownHandler = resolved.shutdownHandler
if resolved.onError is not None:
self._extensionErrorListener = resolved.onError
self._applyExtensionBindings(self._extensionRunner)
await self.moments.session_start(dict(self._sessionStartEvent)) # MISAKA fork
await self._extensionRunner.emit(dict(self._sessionStartEvent))
self._extensionRunner.reportUnhandledMcpServers()
await self.extendResourcesFromExtensions(
"reload" if _event_field(self._sessionStartEvent, "reason") == "reload" else "startup"
)
await self.moments.resources_ready({"type": "resources_ready"})
async def reload(self, options: dict[str, Any] | None = None) -> None:
previous_flag_values = self._extensionRunner.getFlagValues()
await self.moments.session_shutdown({"type": "session_shutdown", "reason": "reload"}) # MISAKA fork
await emitSessionShutdownEvent(self._extensionRunner, {"type": "session_shutdown", "reason": "reload"})
# The old runner must unsubscribe from the shared event bus, or every
# /reload leaks one more layer of handlers (pi #7656/6ca423447).
self._extensionRunner.invalidate(_STALE_CONTEXT_MESSAGE)
def getDefaultTools() -> list[str]:
if not self._usesDefaultTools:
return []
configured = self.settingsManager.getDefaultTools()
return applyToolModifiers(DEFAULT_TOOL_NAMES if configured is None else configured, self._defaultToolModifiers)
previous_default_tools = set(getDefaultTools())
await self.settingsManager.reload()
self.agent.steeringMode = self.settingsManager.getSteeringMode()
self.agent.followUpMode = self.settingsManager.getFollowUpMode()
resetApiProviders()
await self._resourceLoader.reload()
# Activate tools newly added to defaultTools. Removed ones stay active, and tools disabled
# during the session stay disabled unless the setting newly adds them.
added_default_tools = [name for name in getDefaultTools() if name not in previous_default_tools]
# Tools the new extensions register later, such as MCP tools, are pending until then.
# MISAKA fork: the user's selection, not the loadout a tool scope shows.
selected_tool_names = self._unscopedToolNames if self._toolScopes else self.getActiveToolNames()
for name in selected_tool_names:
self._pendingToolNames[name] = None
self._buildRuntime(
{
"activeToolNames": [*selected_tool_names, *added_default_tools],
"flagValues": previous_flag_values,
"includeAllExtensionTools": True,
}
)
has_bindings = any(
value is not None
for value in (
self._extensionUIContext,
self._extensionCommandContextActions,
self._extensionShutdownHandler,
self._extensionErrorListener,
)
)
if has_bindings:
before_session_start = read_field(options, "beforeSessionStart")
if before_session_start is not None:
result = before_session_start()
if inspect.isawaitable(result):
await result
# Native parts were shut down above even for a bound headless session.
# Their lifecycle does not depend on UI/error/command bindings.
if has_bindings or self._extensionBindings is not None:
await self.moments.session_start({"type": "session_start", "reason": "reload"})
if has_bindings:
await self._extensionRunner.emit({"type": "session_start", "reason": "reload"})
self._extensionRunner.reportUnhandledMcpServers()
# A started headless session can have no UI/command/error bindings. Refresh
# its resources too, but do not start discovery on a never-bound session.
if self._extensionBindings is not None:
await self.extendResourcesFromExtensions("reload")
await self.moments.resources_ready({"type": "resources_ready", "reason": "reload"})
def createReplacedSessionContext(self) -> Any:
context = self._extensionRunner.createCommandContext()
replaced_context = object.__new__(type(context))
replaced_context.__dict__.update(context.__dict__)
replaced_context.sendMessage = self.sendMessage
replaced_context.sendUserMessage = self.sendUserMessage
return replaced_context
def hasExtensionHandlers(self, eventType: str) -> bool:
return self._extensionRunner.hasHandlers(eventType)
async def sendCustomMessage(
self,
message: Any,
options: dict[str, Any] | None = None,
) -> None:
resolved_options = dict(options or {})
normalized = _message_dict(message)
app_message = _normalize_nullish_message_content(
{
"role": "custom",
"customType": read_field(normalized, "customType"),
"content": _message_content(normalized),
"display": bool(read_field(normalized, "display")),
"details": read_field(normalized, "details"),
"timestamp": int(time.time() * 1000),
}
)
delivery_id = resolved_options.get("_deliveryId")
if delivery_id:
app_message["details"] = {**(app_message["details"] or {}), "delivery_id": delivery_id}
if self._customMessageRecorded(delivery_id):
self._customReceiptCallback(resolved_options, "_onPersist")
return
already_queued = delivery_id in self._customMessageReceipts
self._customMessageReceipts[delivery_id] = resolved_options
if already_queued:
return
await self._routeCustomMessage(app_message, resolved_options)
async def _routeCustomMessage(self, app_message: dict[str, Any], resolved_options: dict[str, Any]) -> None:
"""Deliver a custom message whose receipt `sendCustomMessage` has taken: queue it, start a
run with it, or append it.
MISAKA fork: pi's `sendCustomMessage` is one method. Here the receipt bookkeeping for
`_deliveryId` stays there, so a run deferred past `agent_settled` re-runs this routing
alone: re-calling `sendCustomMessage` with the same delivery id would meet its own receipt
and return without delivering the message."""
try:
deliver_as = resolved_options.get("deliverAs")
if deliver_as == "nextTurn":
self._pendingNextTurnMessages.append(app_message)
elif self.isStreaming and resolved_options.get("triggerTurn") is False:
# triggerTurn=False: record the message without interrupting the running turn
# (pi #8022/47b5119d0). It cannot go into agent.state.messages from here: a
# turn in flight has already appended the assistant message carrying its
# toolCalls, so a custom message landing now sits between the calls and their
# results -- and convertToLlm turns it into a user message, which the
# Messages API rejects on every later request. Hold it out of the conversation
# and let the flush put it in at the next turn boundary, where the toolCalls
# are answered. The UI is told there too, not here: the TUI answers a custom
# message_end by rebuilding the chat from the transcript, so announcing a
# message that has not been written yet only draws it long enough for the next
# toolResult to erase it.
self._pendingCustomMessages.append(app_message)
elif self.isStreaming:
if deliver_as == "followUp":
self.agent.followUp(app_message)
else:
self.agent.steer(app_message)
elif resolved_options.get("triggerTurn"):
if self._isEmittingAgentSettled:
# Re-evaluated when it runs: by then another deferred action may have started a
# run, which this message then joins as a queued message.
async def deferred_route() -> None:
await self._routeCustomMessage(app_message, resolved_options)
# MISAKA fork: a route a cancellation keeps from running is handed back (`_emitAgentSettled`).
deferred_route.handBack = lambda error: self._keepOrFailCustomMessage( # type: ignore[attr-defined]
app_message, resolved_options, error, keepWithoutReceipt=True
)
self._deferredSettledActions.append(deferred_route)
return
await self._startRun({"messageType": "custom", "message": app_message})
else:
self._appendCustomMessage(app_message)
self._refreshFinalizedContext()
self._emit({"type": "message_start", "message": app_message})
self._emit({"type": "message_end", "message": app_message})
except BaseException as error:
self._keepOrFailCustomMessage(app_message, resolved_options, error)
raise
def _keepOrFailCustomMessage(
self, app_message: dict[str, Any], resolved_options: dict[str, Any], error: BaseException,
*, keepWithoutReceipt: bool = False,
) -> None:
"""MISAKA fork: a custom message that could not be delivered now (the run it started failed to start, or a
cancellation kept its deferred route from running). One whose sender redelivers it (a receipt with
`_onError`: the Sister outbox, mail) is failed back to that sender. One nobody redelivers (a sub-agent's or
a background shell's completion notice, `_onPersist` only) keeps its receipt and waits in the follow-up
queue for the next run, as `_handBackQueuedReceipts` leaves queued ones: failing it would lose it for
good. A message with no receipt at all fails with its caller, as upstream, unless `keepWithoutReceipt`
(a deferred route has no caller left to tell)."""
delivery_id = resolved_options.get("_deliveryId")
receipt = self._customMessageReceipts.get(delivery_id) if delivery_id else None
if receipt is not None and receipt.get("_onError") is not None:
self._failCustomReceipt(delivery_id, error)
elif receipt is not None or (keepWithoutReceipt and not delivery_id):
self.agent.followUp(app_message)
def _customMessageRecorded(self, delivery_id):
return bool(self.sessionManager.flushed and any(
entry.get("type") == "custom_message" and isinstance(entry.get("details"), dict)
and entry["details"].get("delivery_id") == delivery_id
for entry in self.sessionManager.getEntries()))
@staticmethod
def _customReceiptCallback(receipt, name, *args):
callback = receipt.get(name)
if callback is None:
return
try:
callback(*args)
except Exception: # a failed outbox ACK stays retryable
logging.getLogger(__name__).warning("custom message receipt failed", exc_info=True)
def _failCustomReceipt(self, delivery_id, error):
receipt = self._customMessageReceipts.pop(delivery_id, None)
if receipt and receipt.get("_onError"):
if not isinstance(error, Exception):
# MISAKA fork: a sender never gets the `CancelledError` (or another exit) of the task that was
# delivering its message: it would take it for its own cancellation (the mail inbox's pump ended
# with it, and the session read no more mail). It gets an ordinary failure and redelivers.
logging.getLogger(__name__).warning(
"delivery %s was interrupted (%s); handed back to its sender", delivery_id, type(error).__name__)
error = RuntimeError(f"The delivery was interrupted ({type(error).__name__}); it is to be redelivered")
self._customReceiptCallback(receipt, "_onError", error)
def _appendCustomMessage(self, message) -> str | None:
details = read_field(message, "details")
delivery_id = details.get("delivery_id") if isinstance(details, dict) else None
entry_id: str | None = None
try:
if not delivery_id or not self._customMessageRecorded(delivery_id):
entry_id = self.sessionManager.appendCustomMessageEntry(
str(read_field(message, "customType")), _message_content(message),
bool(read_field(message, "display")), details)
except BaseException as error:
self._failCustomReceipt(delivery_id, error)
raise
if delivery_id and self.sessionManager.flushed:
receipt = self._customMessageReceipts.pop(delivery_id, None)
if receipt:
# The file has landed. A failed ACK is retried via the delivery id,
# never by appending a second copy of the notification.
self._customReceiptCallback(receipt, "_onPersist")
return entry_id
async def sendMessage(self, message: Any, options: dict[str, Any] | None = None) -> None:
await self.sendCustomMessage(message, options)
async def _sendUserMessage(
self,
content: str | list[TextContent | ImageContent | dict[str, Any]],
options: dict[str, Any] | None = None,
) -> None:
resolved_options = dict(options or {})
if isinstance(content, str):
text = content
images: list[ImageContent] | None = None
else:
text_parts: list[str] = []
images = []
for item in content:
if _content_type(item) == "text":
text_parts.append(str(read_field(item, "text", "")))
else:
images.append(item if isinstance(item, ImageContent) else ImageContent.model_validate(item))
text = "\n".join(text_parts)
if not images:
images = None
await self.prompt(
text,
{
# Extensions may opt in to command dispatch and skill/template expansion (pi #7857/b987ead35); default stays False
"expandPromptTemplates": bool(resolved_options.get("expandPromptTemplates", False)),
"streamingBehavior": resolved_options.get("deliverAs"),
"images": images,
"source": "extension",
},
)
async def sendUserMessage(
self,
content: str | list[TextContent | ImageContent | dict[str, Any]],
options: dict[str, Any] | None = None,
) -> None:
await self._sendUserMessage(content, options)
def getUserMessagesForForking(self) -> list[dict[str, str]]:
result: list[dict[str, str]] = []
for entry in self.sessionManager.getEntries():
if entry.get("type") != "message":
continue
message = entry.get("message")
if _message_role(message) != "user":
continue
text = self._extractUserMessageText(_message_content(message))
if text:
result.append({"entryId": str(entry["id"]), "text": text})
return result
async def executeBash(
self,
command: str,
onChunk: Callable[[str], None] | None = None,
options: dict[str, Any] | None = None,
) -> BashResult:
resolved_options = dict(options or {})
abort_controller = AbortController()
self._bashAbortControllers.add(abort_controller)
prefix = self.settingsManager.getShellCommandPrefix()
shell_path = self.settingsManager.getShellPath()
resolved_command = f"{prefix}\n{command}" if prefix else command
def handle_chunk(delta: str) -> None:
if onChunk is not None:
onChunk(delta)
event: dict[str, Any] = {"type": "bash_execution_update", "delta": delta}
bash_id = resolved_options.get("id")
if bash_id is not None:
event["id"] = bash_id
self._emit(event)
try:
result = await executeBashWithOperations(
resolved_command,
self.sessionManager.getCwd(),
resolved_options.get("operations") or createLocalBashOperations({"shellPath": shell_path}),
{
"onChunk": handle_chunk,
"signal": abort_controller.signal,
},
)
self.recordBashResult(command, result, resolved_options)
return result
finally:
self._bashAbortControllers.discard(abort_controller)
def recordBashResult(self, command: str, result: BashResult, options: dict[str, Any] | None = None) -> None:
resolved_options = dict(options or {})
bash_message = BashExecutionMessage(
command=command,
output=result.output,
exitCode=result.exitCode,
cancelled=result.cancelled,
truncated=result.truncated,
fullOutputPath=result.fullOutputPath,
timestamp=int(time.time() * 1000),
excludeFromContext=resolved_options.get("excludeFromContext"),
)
if self.isStreaming:
self._pendingBashMessages.append(bash_message)
return
self.sessionManager.appendMessage(bash_message)
self._refreshFinalizedContext()
def abortBash(self) -> None:
for abort_controller in tuple(self._bashAbortControllers):
abort_controller.abort()
def abortBranchSummary(self) -> None:
if self._branchSummaryAbortController is not None:
self._branchSummaryAbortController.abort()
def _compactionSource(self) -> tuple[Any, ...]:
"""Owner and immutable branch identity captured before awaiting a summarizer."""
manager = self.sessionManager
return (manager, manager.getSessionId(), manager.getSessionFile(),
tuple(entry.get("id") for entry in manager.getBranch()),
len(manager.getEntries()), (self.model.model_dump(mode="json")
if isinstance(self.model, Model) else copy.deepcopy(self.model)),
copy.deepcopy(self.settingsManager.getCompactionSettings()))
def _checkCompactionSource(self, source: tuple[Any, ...]) -> None:
current = self._compactionSource()
fields = ("owner", "session", "session file", "branch", "entries", "model", "settings")
changed = [name for name, before, after in zip(fields, source, current, strict=True)
if before != after]
appended = self.sessionManager.getEntries()[source[4]:]
# Bookkeeping may arrive while a context engine or summarizer is awaiting.
# Only accept a contiguous append to the original leaf, not a new branch,
# message (including custom_message), model/thinking change or compaction.
# ``usage`` is pi 1.3.0's cache warmer: a slow summary outlasts its interval
# (Last Order's 500k-token compaction, 2026-10-26; R10).
if (current[4] == source[4] + len(appended)
and current[3] == (*source[3], *(entry.get("id") for entry in appended))
and all(entry.get("type") in {"custom", "label", "session_info", "usage"} for entry in appended)):
changed = [name for name in changed if name not in {"branch", "entries"}]
if changed:
raise RuntimeError("Session, branch, model or settings changed during compaction "
f"({', '.join(changed)})")
def _publishCompaction(self, result: SessionCompactionResult, from_hook: bool,
source: tuple[Any, ...]) -> Any:
self._checkCompactionSource(source)
entry_id = self.sessionManager.appendCompaction(
result.summary, result.firstKeptEntryId, result.tokensBefore,
result.details, from_hook, result.usage,
contextMessages=result.contextMessages, contextSummaries=result.contextSummaries,
)
# appendCompaction commits before changing either view. A failed write leaves
# the previous archive, leaf and provider context intact.
self._refreshFinalizedContext()
result.estimatedTokensAfter = sum(
estimateTokens(message) for message in self.sessionManager.buildSessionProjection().messages
)
return next((entry for entry in self.sessionManager.getEntries()
if entry.get("id") == entry_id), None)
async def _prepareCompactionOperation(self, reason, signal, custom_instructions=None,
*, preflight=False, current_tokens=None, will_retry=False,
context_window=None):
"""Ask an installed context engine before native auth, threshold or cut points.
A returned operation owns the whole replay; an explicit empty operation owns
the no-op too. Only an absent engine goes through Pi's existing summary hook.
"""
event = {"type": "session_context_prepare", "reason": reason, "signal": signal,
"preflight": preflight, "currentTokens": current_tokens,
"customInstructions": custom_instructions, "messages": list(self.messages),
"systemPrompt": self.systemPrompt,
"tools": [{"name": tool.name, "description": tool.description, "parameters": tool.parameters}
for tool in self.agent.state.tools],
"allowCompression": reason == "manual" or bool(self.settingsManager.getCompactionSettings(self.model).get("enabled")),
# MISAKA fork: the model whose window applies, routed under a virtual selection.
"model": self._compactionLimitsModel(preflight)}
decision = await self.moments.session_context_prepare(event)
if decision is None and self._extensionRunner.hasHandlers("session_context_prepare"):
decision = await self._extensionRunner.emit(event)
if decision is not None:
operation = _event_field(decision, "execute")
if operation is None:
return None
if not callable(operation):
raise TypeError("Context engine execute must be callable or None")
async def engine_operation():
result = await operation()
if result is not None and _event_field(result, "contextMessages") is None:
raise ValueError("Context engine must return its complete contextMessages")
return result, True
return engine_operation
if self.model is None:
if reason == "manual":
raise RuntimeError(formatNoModelSelectedMessage())
return None
settings = CompactionSettings(**self.settingsManager.getCompactionSettings(self.model))
if reason == "threshold" and (preflight or current_tokens is not None):
tokens = (
estimateProjectedContextTokens(
self.sessionManager.buildSessionProjection(), self.sessionManager.getBranch()
).tokens
if current_tokens is None
else current_tokens
)
# MISAKA fork: the caller passes the window of the model that produced the checked
# response (upstream checks in `_checkCompaction` itself); the preflight uses the model
# the request goes to, and an unknown window never compacts (`_exceedsCompactionThreshold`).
limits_model = self._compactionLimitsModel(preflight)
window = limits_model.contextWindow if context_window is None else context_window
if (preflight and window <= 0) or not shouldCompact(tokens, window, settings):
return None
if signal is not None and signal.aborted:
raise RuntimeError("Compaction cancelled")
branch_entries = self.sessionManager.getBranch()
preparation = prepareCompaction(branch_entries, settings)
if preparation is None or _is_noop_compaction(preparation):
if reason == "manual":
if branch_entries and branch_entries[-1].get("type") == "compaction":
raise RuntimeError("Already compacted")
raise RuntimeError("Nothing to compact (session too small)")
return None
async def native_operation():
event = {"type": "session_before_compact", "preparation": preparation,
"branchEntries": branch_entries, "customInstructions": custom_instructions,
"reason": reason, "willRetry": will_retry,
"signal": signal}
provided = await self.moments.session_before_compact(event)
if provided is None and self._extensionRunner.hasHandlers("session_before_compact"):
provided = await self._extensionRunner.emit(event)
if _result_flag(provided, "cancel", False):
raise _CompactionCancelledByExtension("Compaction cancelled")
provided = _result_flag(provided, "compaction")
if provided is not None:
return SessionCompactionResult(
summary=_event_field(provided, "summary"),
firstKeptEntryId=_event_field(provided, "firstKeptEntryId"),
tokensBefore=int(_event_field(provided, "tokensBefore", 0)),
details=_event_field(provided, "details"), usage=_event_field(provided, "usage"),
contextMessages=_event_field(provided, "contextMessages"),
contextSummaries=_event_field(provided, "contextSummaries")), True
# Upstream `_runAutoCompaction`: `abortController.signal.throwIfAborted()` after the hooks.
if reason != "manual" and signal is not None and signal.aborted:
raise RuntimeError("Compaction cancelled")
return await self._runDefaultCompaction(
preparation, self.model, custom_instructions, signal, reason), False
return native_operation
def _compactionLimitsModel(self, preflight: bool) -> Model[Any] | None:
"""MISAKA fork: the model whose window a compaction check uses. At the provider boundary
that is the model the request goes to; otherwise the model the conversation's limits
come from."""
return (self._requestModel if preflight else None) or self._limitsModel()
async def _runDefaultCompaction(self, preparation, model, custom_instructions, signal, reason):
"""Generate Pi's built-in compaction summary for manual and automatic compaction."""
# Resolve the request only when Pi summarizes itself: routing may call models or fail.
request = await self._getSummarizationRequestAuth(model, signal)
return await compact(
preparation, request["model"], request.get("apiKey"), request.get("headers"),
custom_instructions, signal, request["thinkingLevel"], self.agent.streamFunction,
retry=self._summarizationRetryPolicy(), env=request.get("env"),
callbacks=self._summarizationRetryCallbacks({"source": "compaction", "reason": reason}),
sessionId=None)
async def compact(self, customInstructions: str | None = None) -> SessionCompactionResult:
# Keep the agent subscription live across compaction (pi #7370/e56893f4c):
# unsubscribing here would drop the aborted partial message's
# message_end/agent_end, so it would never be persisted or applied to state.
await self.abort()
self._compactionAbortController = AbortController()
compaction_abort_controller = self._compactionAbortController
self._emit({"type": "compaction_start", "reason": "manual"})
published_result = None
from_hook = False
try:
source = self._compactionSource()
operation = await self._prepareCompactionOperation(
"manual", self._compactionAbortController.signal, customInstructions)
if operation is None:
raise RuntimeError("Nothing to compact")
self._checkCompactionSource(source)
result, from_hook = await operation()
if result is None:
raise RuntimeError("Nothing to compact")
if self._compactionAbortController.signal.aborted:
raise RuntimeError("Compaction cancelled")
saved_entry = self._publishCompaction(result, from_hook, source)
published_result = result
if saved_entry is not None:
await self.moments.session_compact({ # MISAKA fork
"type": "session_compact", "compactionEntry": saved_entry, "fromExtension": from_hook,
"reason": "manual", "willRetry": False,
})
await self._extensionRunner.emit(
{
"type": "session_compact",
"compactionEntry": saved_entry,
"fromExtension": from_hook,
"reason": "manual",
"willRetry": False,
}
)
# compaction_end listeners may submit queued prompts, so expose idle state
# before notifying them. (pi 3852cb2)
self._compactionAbortController = None
self._emit(
{
"type": "compaction_end",
"reason": "manual",
"result": result,
"aborted": False,
"willRetry": False,
}
)
return result
except asyncio.CancelledError:
self._compactionAbortController = None
self._emit({"type": "compaction_end", "reason": "manual",
"result": published_result, "aborted": published_result is None,
"willRetry": False})
if published_result is None:
await self._emitSessionCompactFailed(
reason="manual", aborted=True, will_retry=False, from_extension=from_hook)
raise
except Exception as error:
message = str(error)
aborted = compaction_abort_controller.signal.aborted or isinstance(error, _CompactionCancelledByExtension)
self._compactionAbortController = None
self._emit(
{
"type": "compaction_end",
"reason": "manual",
"result": published_result,
"aborted": aborted and published_result is None,
"willRetry": False,
"errorMessage": (f"Compaction notification failed: {message}" if published_result is not None
else None if aborted else f"Compaction failed: {message}"),
}
)
if published_result is None:
await self._emitSessionCompactFailed(
reason="manual", aborted=aborted, will_retry=False,
error_message=None if aborted else f"Compaction failed: {message}",
from_extension=from_hook)
raise
finally:
self._compactionAbortController = None
async def _emitSessionCompactFailed(self, *, reason: str, aborted: bool,
will_retry: bool,
error_message: str | None = None,
from_extension: bool = False) -> None:
"""Emit the terminal event for a failed or aborted compaction (pi #8175/a6b1dbceb).
Lets extensions such as telemetry or LCM pair a session_before_compact
attempt with its outcome; previously failures only reached the UI.
"""
failed_event = {
"type": "session_compact_failed",
"reason": reason,
"errorMessage": error_message,
"aborted": aborted,
"willRetry": will_retry,
"fromExtension": from_extension,
}
# MISAKA fork: core parts hear it whether or not an extension is listening.
await self.moments.session_compact_failed(failed_event)
if not self._extensionRunner.hasHandlers("session_compact_failed"):
return
await self._extensionRunner.emit(failed_event)
def abortCompaction(self) -> None:
if self._compactionAbortController is not None:
self._compactionAbortController.abort()
if self._auto_compaction_abort_controller is not None:
self._auto_compaction_abort_controller.abort()
async def navigateTree(
self,
targetId: str,
options: dict[str, Any] | None = None,
) -> dict[str, Any]:
if self.isStreaming:
raise RuntimeError(
"Wait for the current response to finish before navigating the session tree."
)
if self.isCompacting:
raise RuntimeError(
"Wait for the current compaction or tree navigation to finish before navigating the session tree."
)
resolved_options = dict(options or {})
old_leaf_id = self.sessionManager.getLeafId()
if targetId == old_leaf_id:
return {"cancelled": False}
wants_summary = bool(resolved_options.get("summarize"))
if wants_summary and self.model is None:
raise RuntimeError("No model available for summarization")
target_entry = self.sessionManager.getEntry(targetId)
if target_entry is None:
raise RuntimeError(f"Entry {targetId} not found")
collected = collectEntriesForBranchSummary(self.sessionManager, old_leaf_id, targetId)
custom_instructions = resolved_options.get("customInstructions")
replace_instructions = resolved_options.get("replaceInstructions")
label = resolved_options.get("label")
preparation = {
"targetId": targetId,
"oldLeafId": old_leaf_id,
"commonAncestorId": collected.commonAncestorId,
"entriesToSummarize": collected.entries,
"userWantsSummary": wants_summary,
"customInstructions": custom_instructions,
"replaceInstructions": replace_instructions,
"label": label,
}
self._branchSummaryAbortController = AbortController()
try:
extension_summary: dict[str, Any] | None = None
from_extension = False
if self._extensionRunner.hasHandlers("session_before_tree"):
hook_result = await self._extensionRunner.emit(
{
"type": "session_before_tree",
"preparation": preparation,
"signal": self._branchSummaryAbortController.signal,
}
)
if _result_flag(hook_result, "cancel", False):
return {"cancelled": True}
if wants_summary:
provided_summary = _result_flag(hook_result, "summary")
if provided_summary is not None:
extension_summary = _message_dict(provided_summary)
from_extension = True
if _event_field(hook_result, "customInstructions") is not None:
custom_instructions = _event_field(hook_result, "customInstructions")
if _event_field(hook_result, "replaceInstructions") is not None:
replace_instructions = _event_field(hook_result, "replaceInstructions")
if _event_field(hook_result, "label") is not None:
label = _event_field(hook_result, "label")
summary_text: str | None = None
summary_details: dict[str, Any] | None = None
summary_usage: Any | None = None
if wants_summary and collected.entries and extension_summary is None:
auth = await self._getSummarizationRequestAuth(self.model, self._branchSummaryAbortController.signal)
branch_summary_settings = self.settingsManager.getBranchSummarySettings()
summary_result = await generateBranchSummary(
collected.entries,
GenerateBranchSummaryOptions(
model=auth.get("model", self.model),
apiKey=auth.get("apiKey"),
headers=auth.get("headers"),
env=auth.get("env"),
signal=self._branchSummaryAbortController.signal,
customInstructions=custom_instructions,
replaceInstructions=replace_instructions,
reserveTokens=int(branch_summary_settings.get("reserveTokens", 16384)),
streamFn=self.agent.streamFunction,
retry=self._summarizationRetryPolicy(),
callbacks=self._summarizationRetryCallbacks({"source": "branchSummary"}),
),
)
if summary_result.aborted:
return {"cancelled": True, "aborted": True}
if summary_result.error:
raise RuntimeError(summary_result.error)
summary_text = summary_result.summary
summary_usage = summary_result.usage
summary_details = {
"readFiles": list(summary_result.readFiles or []),
"modifiedFiles": list(summary_result.modifiedFiles or []),
}
elif extension_summary is not None:
summary_text = _event_field(extension_summary, "summary")
details = _event_field(extension_summary, "details")
summary_details = _message_dict(details) if details is not None else None
summary_usage = _event_field(extension_summary, "usage")
new_leaf_id: str | None
editor_text: str | None = None
entry_type = target_entry.get("type")
if entry_type == "message" and _message_role(target_entry.get("message")) == "user":
parent_id = target_entry.get("parentId")
new_leaf_id = parent_id if isinstance(parent_id, str) else None
editor_text = self._extractUserMessageText(_message_content(target_entry.get("message")))
elif entry_type == "custom_message":
parent_id = target_entry.get("parentId")
new_leaf_id = parent_id if isinstance(parent_id, str) else None
custom_content = target_entry.get("content")
if isinstance(custom_content, str):
editor_text = custom_content
elif isinstance(custom_content, list):
editor_text = "".join(
str(read_field(block, "text", ""))
for block in custom_content
if _content_type(block) == "text"
)
else:
new_leaf_id = targetId
summary_entry = None
if summary_text:
summary_id = self.sessionManager.branchWithSummary(
new_leaf_id,
summary_text,
summary_details,
from_extension,
summary_usage,
)
summary_entry = self.sessionManager.getEntry(summary_id)
if label:
self.sessionManager.appendLabelChange(summary_id, str(label))
elif new_leaf_id is None:
self.sessionManager.resetLeaf()
else:
self.sessionManager.branch(new_leaf_id)
if label and not summary_text:
self.sessionManager.appendLabelChange(targetId, str(label))
# Update finalized context from the canonical session projection.
self._refreshFinalizedContext()
self._restoreToolsFromTranscript()
await self.moments.session_tree({"type": "session_tree"}) # MISAKA fork
await self._extensionRunner.emit(
{
"type": "session_tree",
"newLeafId": self.sessionManager.getLeafId(),
"oldLeafId": old_leaf_id,
"summaryEntry": summary_entry,
"fromExtension": from_extension if summary_text else None,
}
)
result: dict[str, Any] = {"cancelled": False}
if editor_text is not None:
result["editorText"] = editor_text
if summary_entry is not None:
result["summaryEntry"] = summary_entry
return result
finally:
self._branchSummaryAbortController = None
def setAutoCompactionEnabled(self, enabled: bool) -> None:
self.settingsManager.setCompactionEnabled(enabled)
def setAutoRetryEnabled(self, enabled: bool) -> None:
self.settingsManager.setRetryEnabled(enabled)
def abortRetry(self) -> None:
if self._retryAbortController is not None:
self._retryAbortController.abort()
def getSessionStats(self) -> SessionStats:
user_messages = 0
assistant_messages = 0
tool_results = 0
total_messages = 0
tool_calls = 0
usage_totals = createUsageTotals()
for entry in self.sessionManager.getEntries():
entry_type = read_field(entry, "type")
if entry_type == "usage":
addUsageToTotals(usage_totals, read_field(entry, "usage"))
elif entry_type in ("branch_summary", "compaction"):
usage = read_field(entry, "usage")
if usage:
addUsageToTotals(usage_totals, usage)
if entry_type != "message":
continue
total_messages += 1
message = read_field(entry, "message")
role = _message_role(message)
if role == "user":
user_messages += 1
elif role == "toolResult":
tool_results += 1
usage = read_field(message, "usage")
if usage:
addUsageToTotals(usage_totals, usage)
elif role == "assistant":
assistant_messages += 1
content = _message_content(message)
if isinstance(content, list):
tool_calls += sum(1 for block in content if _content_type(block) == "toolCall")
addUsageToTotals(usage_totals, read_field(message, "usage") or {})
return SessionStats(
sessionFile=self.sessionFile,
sessionId=self.sessionId,
userMessages=user_messages,
assistantMessages=assistant_messages,
toolCalls=tool_calls,
toolResults=tool_results,
totalMessages=total_messages,
tokens=SessionTokenStats(
input=usage_totals.input,
output=usage_totals.output,
cacheRead=usage_totals.cacheRead,
cacheWrite=usage_totals.cacheWrite,
total=(
usage_totals.input
+ usage_totals.output
+ usage_totals.cacheRead
+ usage_totals.cacheWrite
),
),
cost=usage_totals.cost,
contextUsage=self.getContextUsage(),
)
async def exportToHtml(
self,
outputPath: str | None = None,
options: dict[str, str | None] | None = None,
) -> str:
requested_theme = (options or {}).get("themeName")
theme_name = next(
(
candidate
for candidate in (requested_theme, self.settingsManager.getTheme())
if isinstance(candidate, str)
and candidate
and getThemeByName(candidate) is not None
),
None,
)
return await exportSessionToHtml(
self.sessionManager,
self.state,
{
"outputPath": outputPath,
"themeName": theme_name,
"toolRenderer": createToolHtmlRenderer(
ToolHtmlRendererDeps(
getToolRenderers=lambda name: self._extensionRunner.resolveToolRenderers(
name, lambda: self.getToolDefinition(name)
),
theme=theme,
cwd=self.sessionManager.getCwd(),
)
),
},
)
def exportToJsonl(self, outputPath: str | None = None) -> str:
return exportSessionToJsonl(self.sessionManager, outputPath)
def getLastAssistantText(self) -> str | None:
for message in reversed(self.messages):
if _message_role(message) != "assistant":
continue
if read_field(message, "stopReason") == "aborted" and not _message_content(message):
continue
content = _message_content(message)
if not isinstance(content, list):
continue
text = "".join(
str(read_field(block, "text", ""))
for block in content
if _content_type(block) == "text"
)
if text:
return text.strip() or None
return None
def getContextUsage(self) -> dict[str, float | int | None] | None:
model = self._limitsModel()
if model is None or model.contextWindow <= 0:
return None
# After compaction, the last assistant usage reflects pre-compaction context size.
# We can only trust usage from an assistant that responded after the latest compaction.
# If no such assistant exists, context token count is unknown until the next LLM response.
projection = self.sessionManager.buildSessionProjection()
branch = self.sessionManager.getBranch()
latest_compaction = getLatestCompactionEntry(branch)
if latest_compaction is not None:
projected_assistants = {
str(entry.sourceEntry.get("id"))
for entry in projection.entries
if any(
_message_role(message) == "assistant"
and read_field(message, "stopReason") not in {"aborted", "error"}
and calculateContextTokens(read_field(message, "usage") or {}) > 0
for message in entry.messages
)
}
compaction_index = next(
(index for index, entry in enumerate(branch) if entry.get("id") == latest_compaction.get("id")), -1
)
has_post_compaction_usage = any(
str(entry.get("id")) in projected_assistants for entry in branch[compaction_index + 1 :]
)
if not has_post_compaction_usage:
return {"tokens": None, "contextWindow": model.contextWindow, "percent": None}
estimate = estimateProjectedContextTokens(projection, branch)
percent = (estimate.tokens / model.contextWindow) * 100 if model.contextWindow else None
return {"tokens": estimate.tokens, "contextWindow": model.contextWindow, "percent": percent}
async def _setModelIfConfigured(self, model: Model[Any]) -> bool:
if not self._modelRuntime.hasConfiguredAuth(model.provider):
return False
await self.setModel(model)
return True
async def _handleAgentEvent(self, event: Any, _signal: Any | None = None) -> None:
event_type = _event_type(event)
message = _event_field(event, "message")
# An abort requested while the run was starting, e.g. during before_agent_start, stops it
# here. agent_start is awaited before the first request.
if event_type == "agent_start" and self._agentRunAbortRequested:
self.agent.abort()
# Record the calls a tool made through ctx.executeTool() and their usage on its result message.
if self._nestedToolCalls is not None:
if event_type == "message_start" and _message_role(message) == "toolResult":
summary = self._nestedToolCalls.takeRecord(read_field(message, "toolCallId"))
if summary is not None and summary.calls is not None:
message.nestedCalls = summary.calls
if summary is not None and summary.usage is not None:
message.usage = (
combineUsage(message.usage, summary.usage) if message.usage is not None else summary.usage
)
elif event_type == "agent_end":
self._nestedToolCalls.clear()
if event_type == "message_start" and _message_role(message) == "user":
self._overflow_recovery_attempted = False
message_text = self._extractUserMessageText(_message_content(message))
if message_text:
if message_text in self._steeringMessages:
self._steeringMessages.remove(message_text)
self._emitQueueUpdate()
elif message_text in self._followUpMessages:
self._followUpMessages.remove(message_text)
self._emitQueueUpdate()
# Emit to extensions first, then notify public listeners.
await self._emitExtensionEvent(event)
if event_type == "agent_end":
self._emit(_decorate_agent_end_event(event, self._willRetryAfterAgentEnd(event)))
else:
self._emit(event)
if event_type == "message_end" and message is not None:
entry_id = self._persistMessage(message)
if entry_id:
self._entryIdsByMessage[id(message)] = (message, entry_id)
assistant_message = _as_assistant_message(message)
if assistant_message is not None:
self._lastAssistantMessage = assistant_message
# "length" is also a mid-recovery failure state: resetting here would
# zero the truncation retry counter and loop forever (#7540)
if assistant_message.stopReason not in ("error", "length"):
self._overflow_recovery_attempted = False
if assistant_message.stopReason != "error" and self._retryAttempt > 0:
self._emit(
{
"type": "auto_retry_end",
"success": True,
"attempt": self._retryAttempt,
}
)
self._retryAttempt = 0
if event_type == "turn_end":
self._lastAssistantToolResults = list(_event_field(event, "toolResults") or [])
# MISAKA fork: a turn boundary is the first place a message queued mid-turn can
# land safely: every toolCall the turn made has its result by now. Waiting for
# the end of the run instead would keep a research run's progress off disk and
# off screen for hours. A turn that errored, aborted or was cut at the output
# cap is skipped -- its tail is still being rewritten, by _prepareRetry, by
# the abort itself, or by the truncated-response recovery in _checkCompaction
# /_runAutoCompaction. A custom message flushed on top of it would hide the
# tail and leave it in the conversation for the retry to re-send.
turn_message = _as_assistant_message(_event_field(event, "message"))
if turn_message is not None and turn_message.stopReason not in ("error", "aborted", "length"):
self._flushPendingCustomMessages()
def _emit(self, event: Any) -> None:
# MISAKA fork: iterate a snapshot so listeners that unsubscribe during dispatch do not
# cause later listeners to miss this event (pi applies this to its RPC client's listeners).
for listener in list(self._eventListeners):
listener(event)
def getCorePromptCommand(self, text: str) -> CoreCommand | None:
if not text.startswith("/"):
return None
command = self.moments.command(text[1:].partition(" ")[0])
return command if command is not None and command.is_prompt else None
async def _expandCorePromptCommand(self, command: CoreCommand, text: str) -> str | None:
result = command.handler(text[1:].partition(" ")[2], self._extensionRunner.createCommandContext())
if inspect.isawaitable(result):
result = await result
if result is not None and not isinstance(result, str):
raise TypeError(f"Prompt command /{command.name} must return text or None")
return result
async def _tryExecuteCoreCommand(self, text: str) -> bool:
# MISAKA fork: a part's command runs like an extension command, without the runner.
if not text.startswith("/"):
return False
command_name, _, raw_args = text[1:].partition(" ")
resolved = self.moments.command(command_name)
if resolved is None or resolved.is_prompt:
return False
try:
result = resolved.handler(raw_args, self._extensionRunner.createCommandContext())
if inspect.isawaitable(result):
await result
except Exception as error: # noqa: BLE001 - reported through the same channel as an extension command
self._extensionRunner.emitError(
ExtensionError(
extensionPath=f"command:{command_name}",
event="command",
error=str(error),
)
)
return True
async def _tryExecuteExtensionCommand(self, text: str) -> bool:
if not text.startswith("/"):
return False
command_text = text[1:]
command_name, _, raw_args = command_text.partition(" ")
resolved = self._extensionRunner.getCommand(command_name)
if resolved is None or resolved.handler is None:
return False
try:
result = resolved.handler(raw_args, self._extensionRunner.createCommandContext())
if inspect.isawaitable(result):
await result
except Exception as error: # noqa: BLE001 - extension code: any failure is reported as an extension error
self._extensionRunner.emitError(
ExtensionError(
extensionPath=f"command:{command_name}",
event="command",
error=str(error),
)
)
return True
def _persistMessage(self, message: Any) -> str | None:
role = _message_role(message)
if role == "custom":
return self._appendCustomMessage(message)
if role in {"system", "user", "assistant", "toolResult"}:
return self.sessionManager.appendMessage(_message_dict(message))
return None
def _applyExtensionBindings(self, runner: ExtensionRunner) -> None:
runner.setUIContext(self._extensionUIContext, self._extensionMode)
runner.bindCommandContext(self._extensionCommandContextActions)
if self._extensionErrorUnsubscriber is not None:
self._extensionErrorUnsubscriber()
self._extensionErrorUnsubscriber = None
self._extensionErrorUnsubscriber = (
runner.onError(self._extensionErrorListener) if self._extensionErrorListener is not None else None
)
async def extendResourcesFromExtensions(self, reason: str) -> None:
if not self._extensionRunner.hasHandlers("resources_discover"):
return
discovered = await self._extensionRunner.emitResourcesDiscover(self._cwd, reason)
if not discovered["promptPaths"] and not discovered["themePaths"] and not discovered.get("skillPaths"):
return
self._resourceLoader.extendResources(
{
"promptPaths": self.buildExtensionResourcePaths(discovered["promptPaths"]),
"themePaths": self.buildExtensionResourcePaths(discovered["themePaths"]),
"skillPaths": self.buildExtensionResourcePaths(discovered.get("skillPaths", [])),
}
)
self._rebuildSystemPrompt(self.getActiveToolNames())
def buildExtensionResourcePaths(self, entries: list[dict[str, str]]) -> list[dict[str, Any]]:
result: list[dict[str, Any]] = []
for entry in entries:
extension_path = entry["extensionPath"]
base_dir = None if isSyntheticPath(extension_path) else os.path.dirname(extension_path)
result.append(
{
"path": entry["path"],
"metadata": {
"source": self.getExtensionSourceLabel(extension_path),
"scope": "temporary",
"origin": "top-level",
"baseDir": base_dir,
},
}
)
return result
def getExtensionSourceLabel(self, extension_path: str) -> str:
if isSyntheticPath(extension_path):
return f"extension:{extension_path.replace('<', '').replace('>', '')}"
base = os.path.basename(extension_path)
return f"extension:{re.sub(r'[.](ts|js)$', '', base)}"
async def _emitExtensionEvent(self, event: Any) -> None:
event_type = _event_type(event)
if event_type == "agent_start":
self._turnIndex = 0
await self.moments.agent_start({"type": "agent_start"}) # MISAKA fork
await self._extensionRunner.emit({"type": "agent_start"})
elif event_type == "agent_end":
agent_end_event = {
"type": "agent_end",
"messages": list(_event_field(event, "messages", []) or []),
}
# MISAKA fork: a core part may block first; extensions are asked only if none did.
hook_result = await self.moments.agent_end(agent_end_event)
if not _event_field(hook_result, "block", False):
hook_result = await self._extensionRunner.emitAgentEnd(agent_end_event)
if _event_field(hook_result, "block", False):
reason = str(
_event_field(
hook_result,
"reason",
"Stop hook blocked completion",
)
)
self._stopHookContinuationPending = True
await self._queueFollowUp(f"Stop hook feedback:\n{reason}")
elif event_type == "turn_start":
await self._extensionRunner.emit(
{
"type": "turn_start",
"turnIndex": self._turnIndex,
"timestamp": int(time.time() * 1000),
}
)
elif event_type == "turn_end":
turn_message = _event_field(event, "message")
dispatched = id(turn_message) in self._boundaryDispatchedMessages
self._boundaryDispatchedMessages.discard(id(turn_message))
if _message_role(turn_message) == "assistant" and not dispatched:
await self._dispatchTurnEndBoundary(turn_message, list(_event_field(event, "toolResults") or []))
self._turnIndex += 1
elif event_type == "message_start":
await self._extensionRunner.emit({"type": "message_start", "message": _event_field(event, "message")})
elif event_type == "message_update":
await self._extensionRunner.emit(
{
"type": "message_update",
"message": _event_field(event, "message"),
"assistantMessageEvent": _event_field(event, "assistantMessageEvent"),
}
)
elif event_type == "message_end":
message = _event_field(event, "message")
# The Agent reducer stores an isolated copy before awaiting listeners. Capture
# that exact copy before the extension can re-enter and append more state.
state_message = self.agent.state.messages[-1] if self.agent.state.messages else None
replacement = await self._extensionRunner.emitMessageEnd({"type": "message_end", "message": message})
if replacement is not None and message is not None:
normalized_replacement = _normalize_nullish_message_content(replacement)
self._replaceMessageInPlace(message, normalized_replacement)
if state_message is not None:
self._replaceMessageInPlace(state_message, message)
elif event_type in ("tool_execution_start", "tool_execution_update", "tool_execution_end"):
await self._extensionRunner.emit(_tool_execution_extension_event(event))
def _replaceMessageInPlace(self, target: Any, replacement: Any) -> None:
if target is replacement:
return
replacement_dict = _message_dict(replacement)
if isinstance(target, dict):
target.clear()
target.update(replacement_dict)
return
target_dict = getattr(target, "__dict__", None)
if isinstance(target_dict, dict):
# The caller keeps using `target` right after this - agent_loop reads
# block.type on every content block of the message it just ended - so the
# target has to stay a usable model. Copying model_dump()'s plain dicts
# into __dict__ would leave .content full of dicts and kill the turn with
# unanswered toolCalls, so re-validate into the target's own type first.
validated = _validate_as(type(target), replacement_dict)
source = replacement_dict if validated is None else validated.__dict__
target_dict.clear()
target_dict.update(source)
fields_set = getattr(target, "__pydantic_fields_set__", None)
if isinstance(fields_set, set):
fields_set.clear()
fields_set.update(
replacement_dict.keys()
if validated is None
else getattr(validated, "__pydantic_fields_set__", replacement_dict.keys())
)
return
for key, value in replacement_dict.items():
setattr(target, key, value)
def _bindExtensionCore(self, runner: ExtensionRunner) -> None:
def _emit_runtime_error(event: str, error: Exception) -> None:
runner.emitError(
ExtensionError(
extensionPath="",
event=event,
error=str(error),
)
)
def _send_message_from_runtime(message: Any, options: dict[str, Any] | None = None) -> None:
async def _run() -> None:
try:
await self.sendCustomMessage(message, options)
except Exception as error: # noqa: BLE001
_emit_runtime_error(
"send_message",
error if isinstance(error, Exception) else RuntimeError(str(error)),
)
self._spawnExtensionMessage(_run())
def _send_user_message_from_runtime(
content: str | list[TextContent | ImageContent | dict[str, Any]],
options: dict[str, Any] | None = None,
) -> None:
async def _run() -> None:
try:
await self._sendUserMessage(content, options)
except Exception as error: # noqa: BLE001
_emit_runtime_error(
"send_user_message",
error if isinstance(error, Exception) else RuntimeError(str(error)),
)
self._spawnExtensionMessage(_run(), "send_user_message")
def _append_entry_from_runtime(custom_type: str, *data: Any) -> None:
entry_id = self.sessionManager.appendCustomEntry(custom_type, *data)
entry = self.sessionManager.getEntry(entry_id)
if entry is not None:
self._emit({"type": "entry_appended", "entry": entry})
def _compact_from_extension(options: dict[str, Any] | None = None) -> None:
async def _run() -> None:
try:
result = await self.compact(_event_field(options, "customInstructions"))
on_complete = _event_field(options, "onComplete")
if callable(on_complete):
on_complete(result)
except Exception as error: # noqa: BLE001
on_error = _event_field(options, "onError")
if callable(on_error):
on_error(error if isinstance(error, Exception) else RuntimeError(str(error)))
self._spawnBackground(_run(), "compact")
runner.bindCore(
{
"sendMessage": _send_message_from_runtime,
"sendUserMessage": _send_user_message_from_runtime,
"appendEntry": _append_entry_from_runtime,
# An extension's name is an automatic title, as Hermes' auto-titler is (``is_user=False``).
"setSessionName": lambda name: self.setSessionName(name, is_user=False),
"getSessionName": self.sessionManager.getSessionName,
"setLabel": lambda entryId, label: self.sessionManager.appendLabelChange(entryId, label),
"getActiveTools": self.getActiveToolNames,
"getAllTools": self.getAllTools,
"getSettings": self.settingsManager.getSettings,
"setActiveTools": self.setActiveToolsByName,
"refreshTools": lambda: self._refreshToolRegistry(),
"getCommands": self.getSlashCommands,
"setModel": self._setModelIfConfigured,
"getThinkingLevel": lambda: self.thinkingLevel,
"setThinkingLevel": self.setThinkingLevel,
},
{
"getModel": lambda: self.model,
"getScopedModels": lambda: self.scopedModels,
"isIdle": lambda: self.isIdle,
"isProjectTrusted": lambda: self.settingsManager.isProjectTrusted(),
"getSignal": lambda: self.agent.signal,
"abort": lambda: self._extensionAbortHandler() if self._extensionAbortHandler else self._spawnBackground(self.abort(), "abort"),
"hasPendingMessages": lambda: self.pendingMessageCount > 0,
"shutdown": lambda: self._extensionShutdownHandler() if self._extensionShutdownHandler else None,
"getContextUsage": self.getContextUsage,
"compact": _compact_from_extension,
"getSystemPrompt": lambda: self.systemPrompt,
"getSystemPromptOptions": lambda: self._baseSystemPromptOptions,
"executeTool": self._executeNestedToolCall,
"getCallableTools": lambda: self._getCallableTools(),
},
{
"registerProvider": self._registerProvider,
"registerNativeProvider": self._registerNativeProvider,
"unregisterProvider": self._unregisterProvider,
"registerVirtualModel": self._registerVirtualModel,
"unregisterVirtualModel": self._unregisterVirtualModel,
},
)
def _createExtensionRunner(self, flag_values: dict[str, bool | str] | None = None) -> ExtensionRunner:
extensions_result = self._resourceLoader.getExtensions()
if flag_values:
for name, value in flag_values.items():
extensions_result.runtime.flagValues[name] = value
runner = ExtensionRunner(
extensions=list(extensions_result.extensions),
runtime=extensions_result.runtime,
cwd=self._cwd,
sessionManager=self.sessionManager,
modelRegistry=self.modelRegistry,
)
self._bindExtensionCore(runner)
if self._extensionRunnerRef is not None:
self._extensionRunnerRef["current"] = runner
self._extensionRunnerRef["session"] = self # MISAKA fork: sdk.transform_context reaches the parts
runner.moments = self.moments # MISAKA fork: the runner's own ui_prompt events reach the parts
return runner
def _registerProvider(self, name: str, config: dict[str, Any]) -> None:
self._modelRuntime.registerProvider(name, config)
self._refreshCurrentModelFromRegistry()
def _registerNativeProvider(self, provider: Any) -> None:
self._modelRuntime.registerNativeProvider(provider)
self._refreshCurrentModelFromRegistry()
def _unregisterProvider(self, name: str) -> None:
self._modelRuntime.unregisterProvider(name)
self._refreshCurrentModelFromRegistry()
def _registerVirtualModel(self, definition: VirtualModelDefinition) -> None:
self._modelRuntime.registerVirtualModel(definition)
self._refreshCurrentModelFromRegistry()
def _unregisterVirtualModel(self, provider: str, id: str) -> None:
self._modelRuntime.unregisterVirtualModel(provider, id)
self._refreshCurrentModelFromRegistry()
def _refreshCurrentModelFromRegistry(self) -> None:
current_model = self.model
if current_model is None:
return
refreshed_model = self._modelRuntime.getModel(current_model.provider, current_model.id)
if refreshed_model is None or refreshed_model == current_model:
return
self.agent.state.model = refreshed_model
def _refreshToolRegistry(self, options: dict[str, Any] | None = None) -> None:
resolved_options = dict(options or {})
if self.moments.parts:
self._customTools = self.moments.configure_tools(
self._customTools, self._resourceLoader.getExtensions().extensions
)
# Tools that were already activated on registration. A tool whose exposure changes to
# `direct` or `model-only` (for example from `hidden`) is activated like a new tool.
previous_activated_on_registration = {
name for name in self._toolRegistry if self._isActivatedOnRegistration(name)
}
# MISAKA fork: the user's selection, not the loadout a tool scope shows.
previous_active_tool_names = list(self._unscopedToolNames) if self._toolScopes else self.getActiveToolNames()
registered_tools = self._extensionRunner.getAllRegisteredTools()
all_custom_tools: list[tuple[Any, SourceInfo]] = [
*( (tool.definition, tool.sourceInfo) for tool in registered_tools ),
*(
(
definition
if isinstance(definition, ToolDefinition)
else createToolDefinitionFromAgentTool(definition),
createSyntheticSourceInfo(f"", {"source": "sdk"}),
)
for definition in self._customTools
),
]
all_custom_tools = [
(definition, source_info)
for definition, source_info in all_custom_tools
if self._isAllowedTool(definition.name)
]
definition_registry: dict[str, _ToolDefinitionEntry] = {}
for name, definition in self._baseToolDefinitions.items():
if not self._isAllowedTool(name):
continue
definition_registry[name] = _ToolDefinitionEntry(
definition=definition,
sourceInfo=createSyntheticSourceInfo(f"{BUILTIN_PATH_PREFIX}{name}", {"source": "builtin"}),
promptSnippet=self._normalizePromptSnippet(_definition_attr(definition, "promptSnippet")),
promptGuidelines=self._normalizePromptGuidelines(_definition_attr(definition, "promptGuidelines")),
)
for definition, source_info in all_custom_tools:
definition_registry[definition.name] = _ToolDefinitionEntry(
definition=definition,
sourceInfo=source_info,
promptSnippet=self._normalizePromptSnippet(_definition_attr(definition, "promptSnippet")),
promptGuidelines=self._normalizePromptGuidelines(_definition_attr(definition, "promptGuidelines")),
)
self._toolDefinitions = definition_registry
# pi agent-session.ts:2694-2703 sends built-in and extension tools through the same
# wrapper, so a tool of either kind that turns on more tools while it runs tags its
# own result with the names that became available (A-15 addedToolNames).
tool_registry: dict[str, AgentTool] = {}
for name, definition in self._baseToolDefinitions.items():
if self._isAllowedTool(name):
tool_registry[name] = wrapRegisteredTool(
RegisteredTool(
definition=definition,
sourceInfo=createSyntheticSourceInfo(f"{BUILTIN_PATH_PREFIX}{name}", {"source": "builtin"}),
),
self._extensionRunner,
)
for definition, source_info in all_custom_tools:
tool_registry[definition.name] = wrapRegisteredTool(
RegisteredTool(definition=definition, sourceInfo=source_info),
self._extensionRunner,
)
self._toolRegistry = tool_registry
if "activeToolNames" in resolved_options:
next_active_tool_names = list(resolved_options["activeToolNames"] or [])
else:
next_active_tool_names = list(previous_active_tool_names)
next_active_tool_names = [name for name in next_active_tool_names if self._isAllowedTool(name)]
if self._toolScopes:
# A scope is not permission to revive tools the underlying user
# selection had turned off. Only genuinely new registrations join it.
next_active_tool_names.extend(
name
for name in self._toolRegistry
if name not in previous_activated_on_registration and self._isActivatedOnRegistration(name)
)
elif self._allowedTools is not None:
for tool_name in self._toolRegistry:
# Naming or matching a tool activates it even when it is not active by default. MCP tools
# kept registered without being named stay inactive.
if self._allowedTools(tool_name) and self._isDeclarable(tool_name):
next_active_tool_names.append(tool_name)
elif resolved_options.get("includeAllExtensionTools"):
for definition, _source_info in all_custom_tools:
if self._isActivatedOnRegistration(definition.name):
next_active_tool_names.append(definition.name)
elif "activeToolNames" not in resolved_options:
for tool_name in self._toolRegistry:
if tool_name not in previous_activated_on_registration and self._isActivatedOnRegistration(
tool_name
):
next_active_tool_names.append(tool_name)
# Pending tools that are registered now become active.
next_active_tool_names.extend(self._pendingToolNames)
# MISAKA fork: inside a tool scope the scoped loadout stays active; the selection changes underneath it.
if self._toolScopes:
self._unscopedToolNames = [name for name in dict.fromkeys(next_active_tool_names) if name in self._toolRegistry]
self._setActiveTools(self._toolScopes[-1]["active"])
else:
self._setActiveTools(list(dict.fromkeys(next_active_tool_names)))
def _isAllowedTool(self, name: str) -> bool:
"""Whether `--tools` and `--exclude-tools` keep the tool registered. MCP tools stay registered
unless the allowlist filters them (see `_allowlistFiltersMcp`)."""
# MISAKA fork: misaka also asks the tool admission hook, keeps browser_exec behind bash, and
# honours the disallowed and always-allowed sets.
if self._toolAdmission is not None and not self._toolAdmission(name):
return False
if name == "browser_exec" and ("bash" not in self._baseToolDefinitions or not self._isAllowedTool("bash")):
return False
if self._excludedTools is not None and self._excludedTools(name):
return False
normalized = name.casefold()
if name in self._alwaysAllowedToolNames:
return True
if "*" in self._disallowedToolNames or normalized in self._disallowedToolNames:
return False
if self._allowedTools is None or self._allowedTools(name):
return True
return not self._allowlistFiltersMcp and isMcpToolName(name)
def _isActivatable(self, name: str) -> bool:
"""Whether the tool may be active, which declares it to the model. MCP tools the allowlist keeps
without matching them are only for codemode and tool_search: they may be declared only when
tool_search can load them (non-`direct` exposure and tool_search registered). This also applies
to tools restored from the transcript or set by extensions."""
if self._allowedTools is None or self._allowedTools(name) or not isMcpToolName(name):
return True
return self._getToolExposure(name) != "direct" and "tool_search" in self._toolRegistry
def _isDeclarable(self, name: str) -> bool:
"""Whether activating the tool declares it to the model."""
return self._getToolExposure(name) in ("direct", "model-only")
def _isActivatedOnRegistration(self, name: str) -> bool:
"""Whether registering the tool activates it, which declares it to the model."""
entry = self._toolDefinitions.get(name)
return self._isDeclarable(name) and (
entry is None or _definition_attr(entry.definition, "defaultActive") is not False
)
def _buildRuntime(self, options: dict[str, Any] | None = None) -> None:
resolved_options = dict(options or {})
auto_resize_images = self.settingsManager.getImageAutoResize()
shell_command_prefix = self.settingsManager.getShellCommandPrefix()
shell_path = self.settingsManager.getShellPath()
if self._baseToolsOverride is not None:
base_tool_definitions = {
name: createToolDefinitionFromAgentTool(tool)
for name, tool in self._baseToolsOverride.items()
}
else:
tool_options = {
"read": {"autoResizeImages": auto_resize_images},
"bash": {"commandPrefix": shell_command_prefix, "shellPath": shell_path},
}
self.moments.configure_tool_options(tool_options)
base_tool_definitions = createAllToolDefinitions(self._cwd, tool_options)
self._baseToolDefinitions = dict(base_tool_definitions)
self._extensionRunner = self._createExtensionRunner(resolved_options.get("flagValues"))
self._applyExtensionBindings(self._extensionRunner)
# MISAKA fork: MISAKA's default tools (`DEFAULT_TOOL_NAMES`), where pi lists read/bash/edit/write here.
default_active_tool_names = (
list(self._baseToolsOverride)
if self._baseToolsOverride is not None
else list(DEFAULT_TOOL_NAMES)
)
base_active_tool_names = (
list(resolved_options["activeToolNames"])
if "activeToolNames" in resolved_options and resolved_options["activeToolNames"] is not None
else default_active_tool_names
)
self._refreshToolRegistry(
{
"activeToolNames": base_active_tool_names,
"includeAllExtensionTools": resolved_options.get("includeAllExtensionTools"),
}
)
def _normalizePromptSnippet(self, text: str | None) -> str | None:
if not text:
return None
one_line = re.sub(r"\s+", " ", text.replace("\r", " ").replace("\n", " ")).strip()
return one_line or None
def _normalizePromptGuidelines(self, guidelines: Any) -> list[str]:
if not guidelines:
return []
unique: list[str] = []
for guideline in list(guidelines):
normalized = str(guideline).strip()
if normalized and normalized not in unique:
unique.append(normalized)
return unique
def _rebuildSystemPrompt(self, toolNames: list[str]) -> None:
valid_tool_names = [name for name in toolNames if name in self._toolRegistry]
tool_snippets: dict[str, str] = {}
tool_guidelines: dict[str, list[str]] = {}
hidden = getattr(self, "_hiddenDeclarations", frozenset()) # doubles built without __init__
for name in self._toolRegistry:
entry = self._toolDefinitions.get(name)
if entry is None:
continue
# Tools without a snippet are not listed.
if entry.promptSnippet:
tool_snippets[name] = entry.promptSnippet
if entry.promptGuidelines:
tool_guidelines[name] = list(entry.promptGuidelines)
loader_system_prompt = self._resourceLoader.getSystemPrompt()
loader_append_system_prompt = self._resourceLoader.getAppendSystemPrompt()
append_system_prompt = "\n\n".join(loader_append_system_prompt) if loader_append_system_prompt else ""
# MISAKA fork: no `skills` option -- misaka's layered skill index (misaka/core/skills) replaces pi's
# skills.ts and reaches the model through its own tools, not a prompt section.
self._baseSystemPromptOptions = normalizeBuildSystemPromptOptions(
{
"cwd": self._cwd,
"contextFiles": self._resourceLoader.getAgentsFiles()["agentsFiles"],
"customPrompt": loader_system_prompt,
"appendSystemPrompt": append_system_prompt,
"selectedTools": valid_tool_names,
"hiddenTools": list(hidden),
"toolSnippets": tool_snippets,
"toolGuidelines": tool_guidelines,
}
)
def _preparePromptAndToolLoadout(
self, options: dict[str, Any], messages: list[Any] | None = None
) -> SystemMessage | None:
"""Apply a prompt and tool loadout for the next request. Sets the executable tools and
returns a system message patching the prompt sections the model currently has (replayed
from `messages`), or None when the prompt is unchanged. Tool changes are declared by
the agent loop before the request.
A forced prompt does not affect the transcript: the structured sections are still diffed
and persisted, and the forced text is projected onto the request by
`_installAgentForcedPromptProjection`.
"""
if messages is None:
messages = self.agent.state.messages
options["selectedTools"] = [tool.name for tool in self._applyToolLoadout(list(options["selectedTools"]))]
# The tool list and rules must match the declarations the request carries.
options["hiddenTools"] = list(self._hiddenDeclarations)
current = getCurrentSystemMessage(messages)
sections = diffSystemPromptSections(
dict(current.sections or {}) if current else {}, buildSystemPromptSections(options)
)
return (
SystemMessage(content="", sections=sections, timestamp=int(time.time() * 1000)) if sections else None
)
def _installHiddenDeclarationsProjection(self) -> None:
"""Remove the declarations that ``prepareLoadout`` hooks hide from every request. The whole
transcript is filtered with the current set, so the projected declarations stay consistent
across requests and only change when the loadout does."""
previous_transform_context = self.agent.transformContext
async def transform_context(messages: list[Any], signal: Any | None = None) -> list[Any]:
transformed = (
await previous_transform_context(messages, signal) if previous_transform_context else messages
)
hidden = self._hiddenDeclarations
if not hidden:
return transformed
def project(message: Any) -> Any:
tools_added = read_field(message, "toolsAdded")
tools_removed = read_field(message, "toolsRemoved")
if _message_role(message) != "system" or (not tools_added and not tools_removed):
return message
added = [tool for tool in tools_added or [] if read_field(tool, "name") not in hidden]
removed = [tool for tool in tools_removed or [] if read_field(tool, "name") not in hidden]
if isinstance(message, dict):
projected = {key: value for key, value in message.items() if key not in ("toolsAdded", "toolsRemoved")}
if added:
projected["toolsAdded"] = added
if removed:
projected["toolsRemoved"] = removed
return projected
return message.model_copy(update={"toolsAdded": added or None, "toolsRemoved": removed or None})
return [project(message) for message in transformed]
self.agent.transformContext = transform_context
def _installAgentForcedPromptProjection(self) -> None:
"""Send a forced prompt as the provider's leading system prompt without recording it.
A `before_agent_start` handler that returns `systemPrompt` needs that exact text at the
head of the request; a mid-conversation system message would leave the original prompt
in place. The forced text is a rendering of the current prompt, so the transcript keeps
its structured sections and the request is projected instead: the system messages
collapse into one head holding the forced text and the current tools. Runs after the
`context` extension handlers.
"""
previous_transform_context = self.agent.transformContext
async def transform_context(messages: list[Any], signal: Any | None = None) -> list[Any]:
transformed = (
await previous_transform_context(messages, signal) if previous_transform_context else messages
)
forced = (
self._runSystemPromptOptions.get("forceSystemPrompt")
if self._runSystemPromptOptions is not None
else None
)
if forced is None:
return transformed
current = getCurrentSystemMessage(transformed)
head = SystemMessage(
content=forced,
toolsAdded=current.toolsAdded if current and current.toolsAdded else None,
timestamp=current.timestamp if current else int(time.time() * 1000),
)
return [head, *(message for message in transformed if _message_role(message) != "system")]
self.agent.transformContext = transform_context
def _restoreToolsFromTranscript(self, modifiers: Sequence[str] = ()) -> None:
"""Restore the active tool loadout declared by the session transcript, if it declares one.
Tools reachable only from other tools are never declared, but they do not depend on the
active set, so the transcript's declarations are the whole loadout.
`modifiers` are `+name`/`-name` entries applied to the restored loadout."""
self._pendingToolNames.clear()
# All system messages on the branch, including those before a compaction. Compaction snapshots
# are derived from these, so replaying them gives the current loadout.
system_messages = [
read_field(entry, "message")
for entry in self.sessionManager.getBranch()
if read_field(entry, "type") == "message" and read_field(read_field(entry, "message"), "role") == "system"
]
# No recorded loadout: keep the current tools.
if not system_messages:
return
recorded = [read_field(tool, "name") for tool in getCurrentTools(system_messages)]
if self._toolScopes:
# MISAKA fork: inside a tool scope (a research window) the transcript's loadout is the
# scope's own; it must not become the user's lasting selection, nor wait as pending. Tools
# new to the branch stay out of it: a scope's `callable` tools are not declared.
self._setActiveTools(applyToolModifiers(recorded, modifiers))
return
# Tools the branch ever added or removed. Removed tools stay inactive.
mentioned = {
read_field(tool, "name")
for message in system_messages
for tool in [*(read_field(message, "toolsAdded") or []), *(read_field(message, "toolsRemoved") or [])]
}
# Extension tools the branch never mentioned were registered after it recorded its loadout, so
# they are activated like newly registered tools. Built-in tools follow `defaultTools` instead.
new_tools = [
name
for name in self._toolRegistry
if name not in mentioned and name not in self._baseToolDefinitions and self._isActivatedOnRegistration(name)
]
names = applyToolModifiers([*recorded, *new_tools], modifiers)
self._pendingToolNames = dict.fromkeys(name for name in names if self._isAllowedTool(name))
self._setActiveTools(names)
def _buildUserMessage(
self,
text: str,
images: Sequence[ImageContent] | None = None,
) -> dict[str, Any]:
content: list[dict[str, Any]] = [TextContent(text=text).model_dump()]
if images:
content.extend(image.model_dump() if hasattr(image, "model_dump") else image for image in images)
return {"role": "user", "content": content, "timestamp": int(time.time() * 1000)}
def _extractUserMessageText(self, content: str | list[Any]) -> str:
# `read_field` rather than `block.get`: a user message that came through
# `Agent.prompt()` has been run through `validate_message`, so its blocks are
# pydantic `TextContent`, not dicts, and the dict-only filter returned "" for
# every one of them. Only the steer/followUp queue path (raw dicts built by
# `_buildUserMessage`) still matches by text, so this was a silent zero rather
# than a visible bug -- one normalization away from a queue that never drains.
# pi has no such split: agent-session.ts:649 shares one `contentText` helper.
if isinstance(content, str):
return content
return "".join(
str(read_field(block, "text") or "")
for block in content
if read_field(block, "type") == "text"
)
def _installAgentToolHooks(self) -> None:
"""Install tool hooks once on the agent instance.
The callbacks read ``self._extensionRunner`` at execution time, so extension reload swaps
in the new runner without reinstalling hooks.
"""
self.agent.beforeToolCall = lambda context, _signal=None: self._beforeToolCall(context)
self.agent.afterToolCall = lambda context, _signal=None: self._afterToolCall(context)
async def _beforeToolCall(self, payload: Any, parent_tool_call_id: str | None = None) -> Any:
"""``tool_call`` handlers. ``parent_tool_call_id`` is set for calls another tool made."""
name = read_field(_event_field(payload, "toolCall"), "name", "")
if self._toolAdmission is not None and not self._toolAdmission(name):
return {"block": True, "reason": f"Tool {name!r} is outside the current agent tool policy."}
if getattr(self, "_toolScopes", ()):
name = read_field(_event_field(payload, "toolCall"), "name")
# MISAKA fork: a nested call reaches callable tools, which need not be active.
reachable = self.getCallableToolNames() if parent_tool_call_id else self.getActiveToolNames()
if name not in reachable:
return {"block": True, "reason": f"Tool {name!r} is outside the current tool scope."}
runner = self._extensionRunner
# MISAKA fork: the parts are asked first; a block from them is final.
if not self.moments.parts and not runner.hasHandlers("tool_call"):
return None
tool_call = _event_field(payload, "toolCall")
args = _event_field(payload, "args")
event = {
"type": "tool_call",
"toolName": read_field(tool_call, "name"),
"toolCallId": read_field(tool_call, "id"),
**({"parentToolCallId": parent_tool_call_id} if parent_tool_call_id else {}),
"input": args,
}
result = await self.moments.tool_call(event)
if _event_field(result, "block", False) or not runner.hasHandlers("tool_call"):
return result
extension_result = await runner.emitToolCall(event) # type: ignore[attr-defined]
if extension_result and _event_field(result, "updatedInput") is not None:
return {"block": _event_field(extension_result, "block", False),
"reason": _event_field(extension_result, "reason"),
"terminate": _event_field(extension_result, "terminate"),
"updatedInput": _event_field(result, "updatedInput")}
return extension_result if extension_result else result
async def _afterToolCall(self, payload: Any, parent_tool_call_id: str | None = None) -> Any:
"""``tool_result`` handlers and image normalization. ``parent_tool_call_id`` is set for
calls another tool made."""
runner = self._extensionRunner
result = _event_field(payload, "result")
tool_call = _event_field(payload, "toolCall")
structured_content = _event_field(result, "structuredContent")
hook_result = None
if self.moments.parts or runner.hasHandlers("tool_result"):
event = {
"type": "tool_result",
"toolName": read_field(tool_call, "name"),
"toolCallId": read_field(tool_call, "id"),
**({"parentToolCallId": parent_tool_call_id} if parent_tool_call_id else {}),
"input": _event_field(payload, "args"),
"content": _event_field(result, "content"),
"details": _event_field(result, "details"),
**({"structuredContent": structured_content} if structured_content is not None else {}),
"isError": bool(_event_field(payload, "isError")),
"usage": _event_field(result, "usage"),
}
# MISAKA fork: the parts rewrite the result first; extensions see their version.
hook_result = await self.moments.tool_result(event)
if hook_result is not None:
event.update(hook_result)
if event.get("structuredContent") is None:
event.pop("structuredContent", None)
if runner.hasHandlers("tool_result"):
extension_result = await runner.emitToolResult(event) # type: ignore[attr-defined]
if extension_result is not None:
hook_result = extension_result
result_content = _event_field(result, "content")
content = (
_event_field(hook_result, "content")
if hook_result is not None
else result_content
)
if content is None:
content = result_content
if content is None:
content = []
# Runs after the extension hook so images injected or replaced by extensions are normalized too.
normalized_content = await normalizeToolResultImages(
content,
NormalizeToolResultImagesOptions(
autoResizeImages=self.settingsManager.getImageAutoResize(),
resizeOptions=self._modelResizeOptions(),
),
)
if hook_result is None and normalized_content is content:
return None
hook_is_error = (
_event_field(hook_result, "isError")
if hook_result is not None
else None
)
return {
"content": normalized_content,
"details": (
_event_field(hook_result, "details")
if hook_result is not None
else None
),
# The hook result already dropped structured content that replaced content no longer matches.
"structuredContent": (
_event_field(hook_result, "structuredContent") if hook_result is not None else structured_content
),
"isError": (
hook_is_error
if hook_is_error is not None
else _event_field(payload, "isError")
),
# None here means "hook did not set it"; the agent loop falls back to the
# executed result's usage (pi agent-session.ts:537 usage: hookResult?.usage).
"usage": (
_event_field(hook_result, "usage")
if hook_result is not None
else None
),
"terminate": _event_field(hook_result, "terminate") if hook_result is not None else None,
}
async def _executeNestedToolCall(
self, parent_tool_call_id: str, name: str, args: Any, options: ExecuteToolOptions | None = None
) -> AgentToolCallOutcome:
"""Run a call that the tool call ``parent_tool_call_id`` made through
``ctx.executeTool()``. It goes through the agent's tool pipeline with the session's hooks,
against the callable tools."""
# MISAKA fork: a tool run by another Agent built from this session's tools (a verifier
# with its own filter and hooks) would otherwise reach the session's callable tools
# through the session's hooks. Only calls the session's agent issued may nest.
caller_root = parent_tool_call_id.split("/", 1)[0]
issuing_message = self._findLastAssistantMessage()
issued_ids = {
read_field(block, "id")
for block in (issuing_message.content if issuing_message is not None else [])
if read_field(block, "type") == "toolCall"
}
if caller_root not in issued_ids:
return AgentToolCallOutcome(
toolCall=ToolCall.model_construct(
type="toolCall", id=f"{parent_tool_call_id}/0", name=name, arguments=args if args is not None else {}
),
result=AgentToolResult(
content=[TextContent(text="Nested tool calls are not available in this context")], details={}
),
isError=True,
)
if self._nestedToolCalls is None:
session = self
class _Host:
def getTools(self) -> list[AgentTool]:
return session._getCallableTools()
def isSequential(self) -> bool:
return session.agent.toolExecution == "sequential"
async def runToolCall(
self, tool_call: Any, parent_id: str, signal: Any, on_update: Any
) -> AgentToolCallOutcome:
assistant_message = session._findLastAssistantMessage()
if assistant_message is None:
return AgentToolCallOutcome(
toolCall=tool_call,
result=AgentToolResult(
content=[TextContent(text="No assistant message issued this call")], details={}
),
isError=True,
)
return await runToolCall(
tool_call,
RunToolCallOptions(
tools=session._getCallableTools(),
assistantMessage=assistant_message,
context=AgentContext(messages=session.agent.state.messages, tools=session.agent.state.tools),
beforeToolCall=lambda context, _signal=None: session._beforeToolCall(context, parent_id),
afterToolCall=lambda context, _signal=None: session._afterToolCall(context, parent_id),
signal=signal,
onUpdate=on_update,
),
)
async def emit(self, event: Any) -> None:
await session._extensionRunner.emit(_tool_execution_extension_event(event))
session._emit(event)
self._nestedToolCalls = NestedToolCallRunner(_Host())
return await self._nestedToolCalls.execute(
parent_tool_call_id,
name,
args,
NestedToolCallOptions(signal=read_field(options, "signal"), onUpdate=read_field(options, "onUpdate")),
)
def _hasContextEngine(self) -> bool:
runner = getattr(self, "_extensionRunner", None)
return bool(runner is not None and runner.hasHandlers("session_context_prepare")) or any(
callable(getattr(part, "session_context_prepare", None))
for part in getattr(getattr(self, "moments", None), "parts", ()))
async def prepareContextMessages(self, messages, signal=None):
"""Engine preflight before EVERY provider request, before transient context hooks.
prepareNextTurn runs only after a completed assistant/tool turn. It misses the
initial request and newly drained steering, so it is not the engine boundary.
Only the durable engine publication mutates the loop's source list here.
"""
if self._hasContextEngine():
before = self.agent.state.messages
await self._runAutoCompaction(
"threshold", False, preflight=True,
current_tokens=estimateContextTokens(messages).tokens,
parent_signal=signal)
if self.agent.state.messages is not before:
messages[:] = self.agent.state.messages
return messages
def _exceedsCompactionThreshold(self, model: Model[Any], projection: SessionProjection) -> bool:
"""Whether `projection`, the current session projection, exceeds the compaction threshold of `model`."""
if model.contextWindow <= 0:
return False
return shouldCompact(
estimateProjectedContextTokens(projection, self.sessionManager.getBranch()).tokens,
model.contextWindow,
CompactionSettings(**self.settingsManager.getCompactionSettings(self.model)),
)
async def _compactBeforeNextAssistantResponse(
self,
context: AgentContext,
) -> AgentContext:
projection = self.sessionManager.buildSessionProjection()
if self._hasContextEngine():
# MISAKA fork: engine preparation runs at the provider boundary.
return replace(context, messages=list(projection.messages))
# A virtual selection is checked in prepareRequest, against the model the request is routed to.
model = self.model
if model is None or isVirtualModel(model) or not self._exceedsCompactionThreshold(model, projection):
return replace(context, messages=list(projection.messages))
await self._runAutoCompaction("threshold", False)
return replace(context, messages=list(self.sessionManager.buildSessionProjection().messages))
def _installAgentRequestProjection(self) -> None:
previous_prepare_request = self.agent.prepareRequest
async def prepare_request(request: PrepareRequestContext, signal: Any | None = None) -> AgentRequestUpdate:
failed = self._failedResponse
self._failedResponse = None
async def prepare() -> tuple[Any, AgentContext, SessionProjection]:
projection = self.sessionManager.buildSessionProjection()
canonical_context = replace(
request.context,
messages=list(projection.messages),
# Messages declare the provider-visible loadout; context.tools keeps executable implementations.
tools=self.agent.state.tools[:],
)
previous: Any = None
if previous_prepare_request is not None:
previous = previous_prepare_request(
replace(
request,
context=canonical_context,
model=self.agent.state.model,
thinkingLevel=self.agent.state.thinkingLevel,
),
signal,
)
if inspect.isawaitable(previous):
previous = await previous
return previous, read_field(previous, "context") or canonical_context, projection
previous, context, projection = await prepare()
model = read_field(previous, "model") or self.agent.state.model
thinking_level = read_field(previous, "thinkingLevel") or self.agent.state.thinkingLevel
if not isVirtualModel(model):
self._requestModel = model
return AgentRequestUpdate(context=context, model=model, thinkingLevel=thinking_level)
# The selection stays in agent state; only this request uses the routed model. A routing
# failure raises, which ends the run with an error response. Only messages the user wrote
# start a turn; extension messages can follow them, e.g. from before_agent_start.
last_response = max(
(index for index, message in enumerate(context.messages) if _message_role(message) == "assistant"),
default=-1,
)
user_turn = any(_message_role(message) == "user" for message in context.messages[last_response + 1 :])
state = getVirtualModelState(self.sessionManager.getBranch(), model.provider, model.id)
route = await self._modelRuntime.resolveModel(model, convertToLlm(context.messages), {"reason": "retry" if failed is not None else "user" if user_turn else "continuation", "thinkingLevel": thinking_level, "signal": signal, "failed": failed, "state": state})
if route.state is not None and route.state is not state:
data: VirtualModelStateData = {"provider": model.provider, "modelId": model.id, "state": route.state}
entry = self.sessionManager.getEntry(
self.sessionManager.appendCustomEntry(VIRTUAL_MODEL_STATE_ENTRY, data)
)
if entry is not None:
self._emit({"type": "entry_appended", "entry": entry})
# The route stands: the router already decided this request. The state entry does not change
# the projection. MISAKA fork: a context engine prepares the context at the provider
# boundary instead, sized from the routed model (`_requestModel`).
if not self._hasContextEngine() and self._exceedsCompactionThreshold(route.model, projection):
await self._runAutoCompaction("threshold", False)
previous, context, _ = await prepare()
self._requestModel = route.model
return AgentRequestUpdate(context=context, model=route.model, thinkingLevel=route.thinkingLevel)
self.agent.prepareRequest = prepare_request
async def _dispatchTurnEndBoundary(self, message: Any, tool_results: list[Any]) -> bool:
stop_reason = read_field(message, "stopReason")
self._lastActivityOutcome = (
"aborted" if stop_reason == "aborted" else "error" if stop_reason == "error" else "completed"
)
message_entry_id = self._findPersistedMessageEntryId(message)
if not self._extensionRunner.hasHandlers("turn_end"):
return False
if not message_entry_id:
self._extensionRunner.emitError(
ExtensionError(
extensionPath="",
event="turn_end",
error="turn_end could not resolve the persisted assistant entry ID",
)
)
return False
tool_result_entry_ids = [
entry_id
for entry_id in (self._findPersistedMessageEntryId(result) for result in tool_results)
if entry_id
]
boundary = await self._extensionRunner.emitBoundary(
{
"type": "turn_end",
"turnIndex": self._turnIndex,
"message": message,
"toolResults": tool_results,
"messageEntryId": message_entry_id,
"toolResultEntryIds": tool_result_entry_ids,
"outcome": self._lastActivityOutcome,
},
lambda entries: self._buildBoundaryContext(entries, "turn_end"),
)
self._commitBoundaryDrafts(boundary["entries"])
if boundary["continue"] and not self._buildBoundaryContext([], "turn_end")["canContinue"]:
self._reportInvalidBoundaryContinuation("turn_end")
return False
return bool(boundary["continue"])
def _installAgentBoundaryHooks(self) -> None:
previous_finish_turn = self.agent.finishTurn
async def finish_turn(turn: AgentTurnContext, signal: Any | None = None) -> AgentTurnDecision | None:
self._boundaryDispatchedMessages.add(id(turn.message))
extension_continue = await self._dispatchTurnEndBoundary(turn.message, turn.toolResults)
previous_decision: Any = None
if previous_finish_turn is not None:
previous_decision = previous_finish_turn(turn, signal)
if inspect.isawaitable(previous_decision):
previous_decision = await previous_decision
if read_field(previous_decision, "action") == "end":
return previous_decision
if extension_continue or read_field(previous_decision, "action") == "continue":
return AgentTurnDecision(action="continue")
return None
self.agent.finishTurn = finish_turn
def _installAgentNextTurnRefresh(self) -> None:
"""Refresh mutable session state before each request in one agent run."""
previous_with_context = self.agent.prepareNextTurnWithContext
previous_legacy = self.agent.prepareNextTurn
async def prepare_next_turn(
turn: PrepareNextTurnContext,
signal: Any | None = None,
) -> AgentLoopTurnUpdate:
context = await self._compactBeforeNextAssistantResponse(turn.context)
previous_snapshot: Any = None
if previous_with_context is not None:
previous_snapshot = previous_with_context(replace(turn, context=context), signal)
elif previous_legacy is not None:
previous_snapshot = previous_legacy(signal)
if inspect.isawaitable(previous_snapshot):
previous_snapshot = await previous_snapshot
previous_context = read_field(previous_snapshot, "context")
next_context = previous_context if previous_context is not None else context
run_options = (
self._runSystemPromptOptions
if self._runSystemPromptOptions is not None
else self._baseSystemPromptOptions
)
options = normalizeBuildSystemPromptOptions(
{
**run_options,
"selectedTools": self.getActiveToolNames(),
"toolSnippets": {**self._baseSystemPromptOptions["toolSnippets"], **run_options["toolSnippets"]},
"toolGuidelines": {
**self._baseSystemPromptOptions["toolGuidelines"],
**run_options["toolGuidelines"],
},
}
)
next_messages = list(read_field(next_context, "messages", []) or [])
update_message = self._preparePromptAndToolLoadout(options, next_messages)
# Keep session.systemPrompt and ctx.getSystemPrompt() in step with what the provider sees.
self._runSystemPromptOptions = options
previous_messages = list(read_field(previous_snapshot, "messages", None) or [])
return AgentLoopTurnUpdate(
context=AgentContext(
messages=next_messages,
tools=self.agent.state.tools[:],
),
messages=(
[*previous_messages, update_message]
if update_message is not None
else (previous_messages or None)
),
model=self.agent.state.model,
thinkingLevel=self.agent.state.thinkingLevel,
)
self.agent.prepareNextTurnWithContext = prepare_next_turn
# =========================================================================
# Canonical context and boundaries
# =========================================================================
def _refreshFinalizedContext(self) -> None:
projection = self.sessionManager.buildSessionProjection()
self._entryIdsByMessage = {}
for entry in projection.entries:
for message in entry.messages:
self._entryIdsByMessage[id(message)] = (message, str(entry.sourceEntry.get("id")))
self.agent.state.messages = projection.messages
def _applyBoundaryDrafts(self, manager: SessionManager, drafts: list[Any]) -> list[Any]:
appended: list[Any] = []
for draft in drafts:
draft_type = read_field(draft, "type")
if draft_type == "custom":
entry_id = manager.appendCustomEntry(read_field(draft, "customType"), read_field(draft, "data"))
elif draft_type == "custom_message":
entry_id = manager.appendCustomMessageEntry(
read_field(draft, "customType"),
read_field(draft, "content"),
bool(read_field(draft, "display")),
read_field(draft, "details"),
)
elif draft_type == "context_edit":
entry_id = manager.appendContextEdit(read_field(draft, "targetId"), read_field(draft, "replacement"))
elif draft_type == "compaction":
tokens_before = estimateProjectedContextTokens(
manager.buildSessionProjection(), manager.getBranch()
).tokens
entry_id = manager.appendCompaction(
read_field(draft, "summary"),
read_field(draft, "firstKeptEntryId"),
tokens_before,
read_field(draft, "details"),
True,
read_field(draft, "usage"),
)
else:
raise ValueError(f"Unsupported boundary entry type: {draft_type}")
entry = manager.getEntry(entry_id)
if entry:
appended.append(entry)
return appended
def _createBoundaryPreviewManager(self, drafts: list[Any]) -> SessionManager:
header = self.sessionManager.getHeader()
if not header:
raise RuntimeError("Session header is missing")
manager = SessionManager.inMemory(self._cwd)
manager.fileEntries = [header, *self.sessionManager.getBranch()]
manager._buildIndex()
self._applyBoundaryDrafts(manager, drafts)
return manager
def _getPendingBoundaryMessages(self) -> list[Any]:
return [*self.agent.peekQueuedMessages(), *self._pendingCustomMessages]
def _buildBoundaryContext(self, drafts: list[Any], boundary: str) -> dict[str, Any]:
projection = self._createBoundaryPreviewManager(drafts).buildSessionProjection()
pending_messages = self._getPendingBoundaryMessages()
llm_messages = convertToLlm(projection.messages)
final_role = _message_role(llm_messages[-1]) if llm_messages else None
has_non_system_context = any(_message_role(message) != "system" for message in llm_messages)
context_can_continue = has_non_system_context and final_role != "assistant"
pending_custom_context = len(self._pendingCustomMessages) > 0
return {
"contextEntries": projection.entries,
"contextMessages": projection.messages,
"llmMessages": llm_messages,
"pendingMessages": pending_messages,
"canContinue": (
context_can_continue
or pending_custom_context
or (
self.agent.hasQueuedMessages()
if boundary == "turn_end"
else final_role == "assistant" and self.agent.hasQueuedMessages()
)
),
}
def _commitBoundaryDrafts(self, drafts: list[Any]) -> None:
appended = self._applyBoundaryDrafts(self.sessionManager, drafts)
self._refreshFinalizedContext()
for entry in appended:
self._emit({"type": "entry_appended", "entry": entry})
def _reportInvalidBoundaryContinuation(self, event: str) -> None:
self._extensionRunner.emitError(
ExtensionError(
extensionPath="",
event=event,
error=f"{event} requested continuation without runnable model context",
)
)
def _findPersistedMessageEntryId(self, message: Any) -> str | None:
mapped = self._entryIdsByMessage.get(id(message))
if mapped is not None and mapped[0] is message:
return mapped[1]
for entry in reversed(self.sessionManager.getBranch()):
if entry.get("type") == "message" and entry.get("message") is message:
return str(entry.get("id"))
message_index = next((i for i, m in enumerate(self.agent.state.messages) if m is message), -1)
if message_index < 0:
return None
projection = self.sessionManager.buildSessionProjection()
projected_index = 0
for entry in projection.entries:
for _ in entry.messages:
if projected_index == message_index:
entry_id = str(entry.sourceEntry.get("id"))
self._entryIdsByMessage[id(message)] = (message, entry_id)
return entry_id
projected_index += 1
return None
def _omitRecoveryAttempt(self, message: Any, tool_results: list[Any] | None = None) -> None:
targets = [message, *(tool_results or [])]
target_ids = [self._findPersistedMessageEntryId(target) for target in targets]
unresolved_projected_target = any(
target_ids[index] is None and any(m is target for m in self.agent.state.messages)
for index, target in enumerate(targets)
)
if unresolved_projected_target:
raise RuntimeError("Cannot persist recovery omission because a projected message has no source entry")
for target_id in target_ids:
if not target_id:
continue
edit_id = self.sessionManager.appendContextEdit(target_id, None)
entry = self.sessionManager.getEntry(edit_id)
if entry:
self._emit({"type": "entry_appended", "entry": entry})
self._refreshFinalizedContext()
async def _startRun(
self,
trigger: BeforeAgentStartTrigger,
onStarted: Callable[[], None] | None = None,
*,
admit: Callable[[], None] | None = None,
) -> None:
"""Start a run from a user or custom message. The session counts as busy from here on, so
messages sent while before_agent_start handlers run are queued into this run instead of
starting another, and an abort requested meanwhile aborts the run as soon as it exists.
`onStarted` is called once the run's messages are prepared, before the first request.
MISAKA fork: `admit` is called once the hooks ran, before the run takes its messages; a
failure there undoes the start like a failing hook. The busy flag is set before the first
await, so a caller that awaits this directly owns the session from that point (a research
window's phase)."""
self._isAgentRunActive = True
self._agentRunAbortRequested = False
try:
messages = await self._prepareRun(trigger, admit)
except BaseException as error:
self._isAgentRunActive = False
self._flushPendingBashMessages()
self._flushPendingCustomMessages()
self._handBackQueuedReceipts(error)
if isinstance(error, _CustomRunBlocked):
# MISAKA fork: a hook that blocks a run a custom message starts does not lose the
# message. It is recorded, and its receipt acknowledged, without a turn: failing it
# would have the durable outbox redeliver it into the same block indefinitely.
try:
self._appendCustomMessage(trigger["message"])
self._refreshFinalizedContext()
self._emit({"type": "message_start", "message": trigger["message"]})
self._emit({"type": "message_end", "message": trigger["message"]})
finally:
self._settleAgentRun()
return
self._settleAgentRun()
raise
# Messages held while the run was starting go before its starting messages, as they would
# have while idle. No run exists yet, so they cannot split a tool call from its result.
self._flushPendingBashMessages()
self._flushPendingCustomMessages()
if onStarted is not None:
onStarted()
# Compaction before the prompt may have scheduled a retry; the new prompt replaces it.
self._failedResponse = None
self._recordSelection()
# The run records the loadout in the transcript; restored tools that did not register by now
# are dropped, so a tool that never registers does not stay pending.
self._pendingToolNames.clear()
try:
await self.agent.prompt(messages)
while not self._agentRunAbortRequested:
if await self._handlePostAgentRun():
if self._agentRunAbortRequested:
break
await self.agent.continue_()
continue
if self._agentRunAbortRequested or not await self._runBeforeSettleBoundary():
break
if self._agentRunAbortRequested:
break
await self.agent.continue_()
finally:
if self._agentRunAbortRequested:
self._finishCancelledRetry()
self._failedResponse = None
self._runSystemPromptOptions = None
self._flushPendingBashMessages()
self._flushPendingCustomMessages()
await self._emitAgentSettled()
def _handBackQueuedReceipts(self, error: BaseException) -> None:
"""MISAKA fork: custom messages whose sender redelivers them (a receipt with `_onError`: the Sister
outbox, mail) that were queued into a run that then did not start (a hook blocked it, or preparing it
failed) leave the Agent's queues and are failed back to that sender, which redelivers each into a fresh
run. Left queued they would wait for some unrelated later run, and every redelivery would meet the receipt
(`sendCustomMessage`) and be dropped. Every other message stays queued for the next run, as upstream leaves
it: one without a receipt, or with a receipt nobody redelivers (a sub-agent's or a background shell's
completion notice, `_onPersist` only) -- failing that one would lose it for good."""
def receipt_of(message: Any) -> str | None:
details = read_field(message, "details")
delivery_id = details.get("delivery_id") if isinstance(details, dict) else None
receipt = self._customMessageReceipts.get(delivery_id) if delivery_id else None
return delivery_id if receipt is not None and receipt.get("_onError") is not None else None
taken = self.agent.takeQueuedMessages(
lambda message: read_field(message, "role") == "custom" and receipt_of(message) is not None
)
if not taken:
return
reason = RuntimeError(f"The run this message was queued into did not start: {error}")
for message in taken:
self._failCustomReceipt(receipt_of(message), reason)
async def _prepareRun(
self, trigger: BeforeAgentStartTrigger, admit: Callable[[], None] | None = None
) -> list[AgentMessage]:
"""Prepare a run and return its starting messages: compact first when needed, emit
before_agent_start, apply the run's prompt options and tool loadout, and build the starting
message followed by pending nextTurn messages (consumed here) and handler messages, with a
system patch first when the prompt changed."""
# Check if we need to compact before sending (catches aborted responses).
# The starting message is sent below, so do not continue the agent here
# (pi agent-session.ts:1230-1234): continuing would emit a whole agent run —
# agent_start / turn_* / agent_end — that the user never asked for.
last_assistant = self._findLastAssistantMessage()
if last_assistant is not None:
await self._checkCompaction(last_assistant, False)
contributed, options = await self._emitBeforeAgentStart(trigger)
messages: list[Any] = []
if trigger["messageType"] == "custom":
messages.append(trigger["message"])
else:
# Normalize images after before_agent_start so extension-driven model selection
# determines the resize profile used for the request and history.
normalized_images, hints = await self._normalizePromptImages(trigger.get("images"))
text = f"{trigger['prompt']}\n\n" + "\n".join(hints) if hints else trigger["prompt"]
messages.append(self._buildUserMessage(text, normalized_images))
if admit is not None:
admit()
# Inject any pending "nextTurn" messages as context alongside the starting message
pending_next_turn = self._pendingNextTurnMessages
messages.extend(pending_next_turn)
self._pendingNextTurnMessages = []
try:
for message in contributed:
normalized_message = _message_dict(message)
messages.append(
_normalize_nullish_message_content(
{
"role": "custom",
"customType": read_field(normalized_message, "customType"),
# Untyped extensions can pass null/missing content; normalize at ingestion.
"content": _message_content(normalized_message),
"display": bool(read_field(normalized_message, "display")),
"details": read_field(normalized_message, "details"),
"timestamp": int(time.time() * 1000),
}
)
)
update_message = self._preparePromptAndToolLoadout(options)
except BaseException:
# MISAKA fork: the run did not start; its notifications wait for the next one.
self._pendingNextTurnMessages = [*pending_next_turn, *self._pendingNextTurnMessages]
raise
self._runSystemPromptOptions = options
if update_message is not None:
messages.insert(0, update_message)
return messages
def _settleAgentRun(self) -> None:
"""Release everyone waiting on idle, but only if the session really is idle.
pi's ``_resolveIdleWaitIfIdle`` (agent-session.ts:599-607): it reads the run flag,
it never clears it. The guard matters because an ``agent_settled`` handler may
start the next run while ``_emitAgentSettled`` is still awaiting handlers -- the
finally then runs with a fresh run in flight, and clearing the flag there would
report an active run as idle and wake ``waitForIdle`` callers early.
"""
if self._isAgentRunActive:
return
# MISAKA fork: a tool scope that ended while a run was working records the loadout it gave
# back now that no run can still declare it (see `toolScope`).
if self._recordLoadoutAfterRun:
self._recordLoadoutAfterRun = False
self._recordUnscopedLoadout()
waiters, self._idleWaiters = self._idleWaiters, []
for waiter in waiters:
if not waiter.done():
waiter.set_result(None)
async def _emitAgentSettled(self) -> None:
"""Announce that the run has fully settled (pi agent-session.ts:609-616,1094-1096).
Reached only once the retry / auto-compaction / queued-continuation loop in
``_handlePostAgentRun`` is done, so this is the "nothing more will run
automatically" signal that ``agent_end`` is not. pi clears the run flag before the
handlers observe it and releases the idle waiters in a finally, so a handler that
asks ``ctx.isIdle()`` gets the truth and a crashing handler still unblocks waiters.
"""
if self._cacheWarmer is not None:
self._cacheWarmer.onAgentSettled()
self._isAgentRunActive = False
self._isEmittingAgentSettled = True
try:
aborted = self._agentRunAbortRequested
await self._extensionRunner.emit({"type": "agent_settled", "aborted": aborted})
if not self._isAgentRunActive:
await self.moments.agent_settled({"type": "agent_settled", "aborted": aborted})
self._emit({"type": "agent_settled", "aborted": aborted})
finally:
self._isEmittingAgentSettled = False
# Runs requested from `agent_settled` handlers are deferred until every settled handler
# finished: they still observe `ctx.isIdle() === true`, but no longer see a reentrant
# `agent_start` during the same notification dispatch.
deferred, self._deferredSettledActions = self._deferredSettledActions, []
if deferred and _beingCancelled():
# MISAKA fork: this settle is the cleanup of a cancelled run (its `_startRun` finally): no new run
# starts inside the cancellation. The deferred routes are handed back instead (`_handBackDeferred`).
try:
self._handBackDeferred(deferred)
finally:
self._settleAgentRun()
return
if deferred:
try:
# MISAKA fork: every deferred action runs even when an earlier one fails, and the first error is
# raised after them. Upstream stops at the failure; here a skipped route keeps its delivery
# receipt, so its outbox redeliveries are dropped as duplicates and the notification is lost.
# Each failure is logged, so the ones after the first are not lost either. A `CancelledError` the
# route raised itself is such a failure. A cancellation of this task stops the loop at once: the
# routes not run yet are handed back, so none keeps its receipt held.
failure: BaseException | None = None
for index, action in enumerate(deferred):
try:
await action()
except Exception as error: # re-raised below, after the rest ran
logging.getLogger(__name__).warning("a run deferred past agent_settled failed", exc_info=True)
if failure is None:
failure = error
except asyncio.CancelledError as error:
if _beingCancelled():
self._handBackDeferred(deferred[index + 1:])
raise
logging.getLogger(__name__).warning("a run deferred past agent_settled failed", exc_info=True)
if failure is None:
failure = error
if failure is not None:
raise failure
finally:
self._settleAgentRun()
return
self._settleAgentRun()
def _handBackDeferred(self, actions: list[Callable[[], Awaitable[None]]]) -> None:
"""MISAKA fork: actions deferred past `agent_settled` that a cancellation keeps from running. A delivery is
handed back as its sender expects (`_keepOrFailCustomMessage`: the Sister outbox and the mail inbox
redeliver; a notice nobody redelivers waits in the follow-up queue for the next run); a deferred prompt is
dropped with the cancellation, as upstream drops it."""
if not actions:
return
reason = RuntimeError("A cancellation kept this delivery's run from starting")
handed = 0
for action in actions:
handBack = getattr(action, "handBack", None)
if handBack is not None:
handBack(reason)
handed += 1
logging.getLogger(__name__).warning(
"a cancellation kept %d run(s) deferred past agent_settled from starting; %d delivery(ies) handed back",
len(actions), handed)
async def _handlePostAgentRun(self) -> bool:
message = self._lastAssistantMessage
tool_results = self._lastAssistantToolResults
self._lastAssistantMessage = None
self._lastAssistantToolResults = []
if self._agentRunAbortRequested:
self._finishCancelledRetry()
return False
if message is None:
return self.agent.hasQueuedMessages()
if self._stopHookContinuationPending:
self._stopHookContinuationPending = False
return True
# MISAKA fork: a credential the provider refused is replaced once, and the turn is retried
# with the replacement. pi ends the turn here -- a 401 is not retryable and auth is resolved
# on a clock, never on a rejection -- which is what left four cards' first request dead after
# another client rotated the OAuth token they shared, until a person restarted each one by
# hand (2026-09-18, B7).
if (self._isRetryableError(message) or await self._recoverRejectedCredential(message)) \
and await self._prepareRetry(message):
if self._agentRunAbortRequested:
self._finishCancelledRetry()
self._failedResponse = message
return not self._agentRunAbortRequested
if self._agentRunAbortRequested:
self._finishCancelledRetry()
return False
if message.stopReason == "error" and self._retryAttempt > 0:
self._emit(
{
"type": "auto_retry_end",
"success": False,
"attempt": self._retryAttempt,
"finalError": message.errorMessage,
}
)
self._retryAttempt = 0
if await self._checkCompaction(message, True, tool_results):
return not self._agentRunAbortRequested
# The low-level loop drains both queues before agent_end. Messages queued by
# agent_end handlers (including a Sister/Last Order completion) require a fresh
# run before pre-settlement handlers fire.
return not self._agentRunAbortRequested and self.agent.hasQueuedMessages()
async def _runBeforeSettleBoundary(self) -> bool:
if not self._extensionRunner.hasHandlers("agent_before_settle"):
return self.agent.hasQueuedMessages()
self._isBeforeSettle = True
self._abortDuringBeforeSettle = False
try:
result = await self._extensionRunner.emitBoundary(
{"type": "agent_before_settle", "outcome": self._lastActivityOutcome},
lambda entries: self._buildBoundaryContext(entries, "agent_before_settle"),
)
self._commitBoundaryDrafts(result["entries"])
self._flushPendingCustomMessages()
final_context = self._buildBoundaryContext([], "agent_before_settle")
if self._abortDuringBeforeSettle:
return False
should_continue = bool(result["continue"]) or self.agent.hasQueuedMessages()
if should_continue and not final_context["canContinue"]:
if result["continue"]:
self._reportInvalidBoundaryContinuation("agent_before_settle")
return False
return should_continue
finally:
self._isBeforeSettle = False
def _finishCancelledRetry(self) -> None:
if self._retryAttempt == 0:
return
attempt = self._retryAttempt
self._retryAttempt = 0
self._emit(
{
"type": "auto_retry_end",
"success": False,
"attempt": attempt,
"finalError": "Retry cancelled",
}
)
def _willRetryAfterAgentEnd(self, event: Any) -> bool:
if self._agentRunAbortRequested:
return False
if self._stopHookContinuationPending:
return True
settings = self.settingsManager.getRetrySettings()
if not bool(settings.get("enabled")) or self._retryAttempt >= int(settings.get("maxRetries", 0) or 0):
return False
for message in reversed(list(_event_field(event, "messages", []) or [])):
assistant_message = _as_assistant_message(message)
if assistant_message is not None:
return self._isRetryableError(assistant_message)
return False
def _summarizationRetryCallbacks(self, source: dict[str, str]) -> RetryCallbacks:
return RetryCallbacks(
onRetryScheduled=lambda attempt, max_attempts, delay_ms, error_message: self._emit(
{
"type": "summarization_retry_scheduled",
"attempt": attempt,
"maxAttempts": max_attempts,
"delayMs": delay_ms,
"errorMessage": error_message,
}
),
onRetryAttemptStart=lambda: self._emit(
{"type": "summarization_retry_attempt_start", **source}
),
onRetryFinished=lambda _success, _attempt, _final_error=None: self._emit(
{"type": "summarization_retry_finished"}
),
)
def _summarizationRetryPolicy(self) -> RetryPolicy:
"""The retry budget summarization borrows from agent turns (pi #6647).
pi threads the same `settings.retry` into summarization so one transient stream
drop no longer throws away a whole compaction or branch summary.
"""
return self._retryPolicyFrom(self.settingsManager.getRetrySettings())
async def _recoverRejectedCredential(self, message: AssistantMessage) -> bool:
"""MISAKA fork: replace a stored credential the provider has just refused. True when it
changed, so the turn is worth running again. The provider is the one that answered this
message, not the session's current model. One rejected token is replaced once per turn;
a second refusal of the same one is the account's answer and is reported as it stands."""
if message.stopReason != "error" or not getattr(message, "provider", None):
return False
if not is_rejected_credential_error(message.errorMessage):
return False
# Rotating a token is worth doing once per turn, and only when a retry can follow it:
# `_retryAttempt` is zero only on a turn's first failure.
settings = self.settingsManager.getRetrySettings()
if (self._retryAttempt != 0 or not bool(settings.get("enabled"))
or int(settings.get("maxRetries", 0) or 0) < 1):
return False
try:
return bool(await self._modelRuntime.recoverRejectedCredential(message.provider, self.sessionId))
except Exception: # noqa: BLE001 - the provider's own error is the one that must reach the user
return False
def _isRetryableError(self, message: AssistantMessage) -> bool:
# Context overflow is handled by compaction, not retry. Everything else is the
# shared classifier's call -- the private copy that used to live here predated the
# exclusion table, so an out-of-quota 429 was retried three times for nothing.
model = self._modelForMessage(message) or self.model
context_window = model.contextWindow if model is not None else 0
if isContextOverflow(message, context_window):
return False
return isRetryableAssistantError(message)
async def _prepareRetry(self, message: AssistantMessage) -> bool:
settings = self.settingsManager.getRetrySettings()
if not bool(settings.get("enabled")):
return False
self._retryAttempt += 1
max_retries = int(settings.get("maxRetries", 0) or 0)
if self._retryAttempt > max_retries:
self._retryAttempt -= 1
return False
delay_ms = retryDelayMs(self._retryPolicyFrom(settings), self._retryAttempt)
self._emit(
{
"type": "auto_retry_start",
"attempt": self._retryAttempt,
"maxAttempts": max_retries,
"delayMs": delay_ms,
"errorMessage": message.errorMessage or "Unknown error",
}
)
# Keep the failed attempt in raw history while durably omitting it from model projection.
self._omitRecoveryAttempt(message)
# Wait with exponential backoff (abortable)
self._retryAbortController = AbortController()
try:
should_continue = await _sleep_with_abort(delay_ms, self._retryAbortController.signal)
if not should_continue:
# Aborted during sleep - emit end event so UI can clean up
self._finishCancelledRetry()
return False
finally:
self._retryAbortController = None
return True
@staticmethod
def _retryPolicyFrom(settings: Mapping[str, Any]) -> RetryPolicy:
return RetryPolicy(
enabled=bool(settings.get("enabled")),
maxRetries=int(settings.get("maxRetries", 0) or 0),
baseDelayMs=int(settings.get("baseDelayMs", 0) or 0),
maxAgentDelayMs=settings.get("maxAgentDelayMs"),
)
def _findLastAssistantMessage(self) -> AssistantMessage | None:
for message in reversed(self.agent.state.messages):
assistant_message = _as_assistant_message(message)
if assistant_message is not None:
return assistant_message
return None
def _flushPendingBashMessages(self) -> None:
if not self._pendingBashMessages:
return
for bash_message in self._pendingBashMessages:
self.sessionManager.appendMessage(bash_message)
self._pendingBashMessages = []
self._refreshFinalizedContext()
def _flushPendingCustomMessages(self) -> None:
# The conversation, the transcript and the UI are all told here rather than at
# send time. The transcript replays in file order on resume, so an entry landing
# between an assistant message and its toolResults would rebuild the same broken
# conversation the queue exists to prevent -- and the UI has to follow the
# transcript, because the TUI answers a custom message_end by clearing the chat
# and rebuilding it from the session file (interactive_mode renderCurrentSessionState).
# Announcing the message before the entry exists shows it for as long as it takes
# the next toolResult to arrive, which is the opposite of showing it.
if not self._pendingCustomMessages:
return
for custom_message in self._pendingCustomMessages:
self._appendCustomMessage(custom_message)
self._refreshFinalizedContext()
self._emit({"type": "message_start", "message": custom_message})
self._emit({"type": "message_end", "message": custom_message})
self._pendingCustomMessages = []
async def _checkCompaction(
self,
assistant_message: AssistantMessage,
skip_aborted_check: bool = True,
tool_results: list[Any] | None = None,
) -> bool:
settings_data = self.settingsManager.getCompactionSettings(self.model)
if not bool(settings_data.get("enabled")):
return False
if skip_aborted_check and assistant_message.stopReason == "aborted":
return False
# Skip overflow check if the message came from a different model.
# This handles the case where user switched from a smaller-context model (e.g. opus)
# to a larger-context model (e.g. codex) - the overflow error from the old model
# shouldn't trigger compaction for the new model. Under a virtual selection, the
# physical model that produced the message supplies the limits.
message_model = self._modelForMessage(assistant_message)
same_model = message_model is not None
limits_model = message_model or self.model
context_window = limits_model.contextWindow if limits_model is not None else 0
branch_entries = self.sessionManager.getBranch()
latest_compaction = getLatestCompactionEntry(branch_entries)
latest_compaction_timestamp = _event_timestamp_ms(_event_field(latest_compaction, "timestamp"))
assistant_timestamp = _event_timestamp_ms(assistant_message.timestamp)
if (
latest_compaction is not None
and assistant_timestamp > 0
and assistant_timestamp <= latest_compaction_timestamp
):
return False
# Automatic cases 1 and 2: context overflow.
# A length stop is recoverable when output ended below the model's original desired limit,
# independent of the configured context size or any context-clamped provider request limit.
current_projection = self.sessionManager.buildSessionProjection()
assistant_entry_id = self._findPersistedMessageEntryId(assistant_message)
assistant_is_projected = assistant_entry_id is None or any(
str(entry.sourceEntry.get("id")) == assistant_entry_id
and any(_message_role(message) == "assistant" for message in entry.messages)
for entry in current_projection.entries
)
branch = branch_entries
assistant_index = (
next((i for i, entry in enumerate(branch) if entry.get("id") == assistant_entry_id), -1)
if assistant_entry_id
else -1
)
entries_after_assistant = branch[assistant_index + 1 :] if assistant_index >= 0 else []
has_post_assistant_context_edit = any(entry.get("type") == "context_edit" for entry in entries_after_assistant)
latest_assistant_edit = next(
(
entry
for entry in reversed(entries_after_assistant)
if entry.get("type") == "context_edit" and entry.get("targetId") == assistant_entry_id
),
None,
)
assistant_retained_for_explicit_recovery = assistant_entry_id is None or (
not any(entry.get("type") == "compaction" for entry in entries_after_assistant)
and (latest_assistant_edit is None or latest_assistant_edit.get("replacement") is not None)
)
assistant_usage_matches_projection = assistant_is_projected and not has_post_assistant_context_edit
explicit_overflow = assistant_message.stopReason == "error" and isContextOverflow(assistant_message)
context_overflow = same_model and (
(explicit_overflow and assistant_retained_for_explicit_recovery)
or (assistant_usage_matches_projection and isContextOverflow(assistant_message, context_window))
)
recoverable_length = (
message_model is not None
and assistant_is_projected
and isRecoverableLength(assistant_message, message_model.maxTokens)
)
if context_overflow or recoverable_length:
will_retry = assistant_message.stopReason != "stop"
if not will_retry:
return await self._runAutoCompaction("overflow", False)
if self._overflow_recovery_attempted:
error_message = (
"Truncated response recovery failed after one compact-and-retry attempt."
if recoverable_length and not context_overflow
else "Context overflow recovery failed after one compact-and-retry "
"attempt. Try reducing context or switching to a "
"larger-context model."
)
self._emit(
{
"type": "compaction_end",
"reason": "overflow",
"result": None,
"aborted": False,
"willRetry": False,
# Report truncation and overflow separately (pi #8130/c7c763f5c): labeling
# truncation as overflow would steer the user toward a larger-context
# model when the real cause is early-ended output.
"errorMessage": error_message,
}
)
await self._emitSessionCompactFailed(
reason="overflow",
error_message=error_message,
aborted=False,
will_retry=False,
from_extension=False,
)
return False
# Persistently omit the selected final attempt before post-run recovery compaction.
self._overflow_recovery_attempted = True
self._omitRecoveryAttempt(assistant_message, tool_results or [])
retry = await self._runAutoCompaction("overflow", True)
if retry:
self._failedResponse = assistant_message
return retry
# Case 3: threshold compaction without retry.
direct_context_tokens = calculateContextTokens(assistant_message.usage)
has_context_edits = any(entry.sourceEntry.get("type") == "context_edit" for entry in current_projection.entries)
# Without provider usage direct=0 and threshold compaction would never fire,
# so fall back to a message-size estimate (pi #8328/4495469a5).
if has_context_edits:
context_tokens = estimateProjectedContextTokens(current_projection, branch).tokens
elif assistant_message.stopReason == "error" or direct_context_tokens == 0:
estimate = estimateContextTokens(list(self.agent.state.messages))
# With no usage at all, estimate.tokens is a pure message-size estimate. Only a
# usage-backed estimate needs the stale pre-compaction check: a kept old message's
# usage reflects the large pre-compaction context and would re-trigger compaction
# right after one finished.
if estimate.lastUsageIndex is not None:
usage_message = self.agent.state.messages[estimate.lastUsageIndex]
usage_timestamp = _event_timestamp_ms(read_field(usage_message, "timestamp"))
if (
latest_compaction is not None
and _message_role(usage_message) == "assistant"
and usage_timestamp > 0
and usage_timestamp <= latest_compaction_timestamp
):
return False
context_tokens = estimate.tokens
else:
context_tokens = direct_context_tokens
return await self._runAutoCompaction(
"threshold", False, current_tokens=context_tokens, context_window=context_window
)
async def _runAutoCompaction(self, reason: str, will_retry: bool, *,
preflight=False, current_tokens=None, parent_signal=None,
context_window=None) -> bool:
started = False
from_hook = False
published_result = None
abort_controller: AbortController | None = None
try:
source = self._compactionSource()
abort_controller = AbortController()
self._auto_compaction_abort_controller = abort_controller
operation_signal = AnyAbortSignal(abort_controller.signal, parent_signal) if parent_signal is not None else abort_controller.signal
operation = await self._prepareCompactionOperation(
reason, operation_signal,
preflight=preflight, current_tokens=current_tokens, will_retry=will_retry,
context_window=context_window)
if operation is None:
return False
self._checkCompactionSource(source)
self._emit({"type": "compaction_start", "reason": reason})
started = True
result, from_hook = await operation()
if result is None:
self._emit({"type": "compaction_end", "reason": reason, "result": None,
"aborted": False, "willRetry": False})
return False
if operation_signal.aborted:
self._emit(
{
"type": "compaction_end",
"reason": reason,
"result": None,
"aborted": True,
"willRetry": False,
}
)
await self._emitSessionCompactFailed(
reason=reason, aborted=True, will_retry=False,
from_extension=from_hook)
return False
saved_entry = self._publishCompaction(result, from_hook, source)
published_result = result
if saved_entry is not None:
await self.moments.session_compact({ # MISAKA fork
"type": "session_compact", "compactionEntry": saved_entry, "fromExtension": from_hook,
"reason": reason, "willRetry": will_retry,
})
await self._extensionRunner.emit(
{
"type": "session_compact",
"compactionEntry": saved_entry,
"fromExtension": from_hook,
"reason": reason,
"willRetry": will_retry,
}
)
self._emit(
{
"type": "compaction_end",
"reason": reason,
"result": result,
"aborted": False,
"willRetry": will_retry,
}
)
if will_retry:
return True
# Auto-compaction can complete while follow-up/steering/custom messages are waiting.
# Continue once so queued messages are delivered.
return self.agent.hasQueuedMessages()
except asyncio.CancelledError:
if started:
self._emit({"type": "compaction_end", "reason": reason,
"result": published_result, "aborted": published_result is None,
"willRetry": False})
# MISAKA fork: reported even before compaction_start (pi: only once started), because the context
# engine's session_context_prepare has already run and pairs with this terminal event.
if published_result is None:
await self._emitSessionCompactFailed(
reason=reason, aborted=True, will_retry=False, from_extension=from_hook)
raise
except Exception as error:
error_message = str(error) if str(error) else "compaction failed"
aborted = (
(abort_controller is not None and abort_controller.signal.aborted)
# MISAKA fork: a preflight compaction also stops with the request it runs for.
or (parent_signal is not None and parent_signal.aborted)
or isinstance(error, _CompactionCancelledByExtension)
)
formatted_error = None if aborted else (
f"Context overflow recovery failed: {error_message}"
if reason == "overflow"
else f"Auto-compaction failed: {error_message}"
)
if published_result is not None:
formatted_error = f"Compaction notification failed: {error_message}"
if started:
self._emit(
{
"type": "compaction_end",
"reason": reason,
"result": published_result,
"aborted": aborted and published_result is None,
"willRetry": False,
"errorMessage": formatted_error,
}
)
# MISAKA fork: reported even before compaction_start, as above (session_context_prepare has run).
if published_result is None:
await self._emitSessionCompactFailed(
reason=reason, aborted=aborted, will_retry=False,
error_message=formatted_error, from_extension=from_hook)
if preflight and not aborted:
raise
return False
finally:
if self._auto_compaction_abort_controller is abort_controller:
self._auto_compaction_abort_controller = None
def _holdBackgroundTask(self, task: asyncio.Task[Any], event: str) -> None:
"""Keep the task alive and make sure its failure is not swallowed.
pi fires these with `void promise`, and a JS promise is never collected. The
event loop keeps only a weak reference to a Task, so the Python equivalent has
to hold the reference itself -- the same conclusion `spawn_stream_task`
(misaka/ai/utils/event_stream.py) reached for provider streams. Retrieving
`exception()` in the done callback also turns a silently dropped extension
failure into an ExtensionError the runner's listeners can see, instead of a
"Task exception was never retrieved" line at GC time.
"""
_BACKGROUND_TASKS.add(task)
def _done(finished: asyncio.Task[Any]) -> None:
_BACKGROUND_TASKS.discard(finished)
if finished.cancelled():
return
error = finished.exception()
if error is None:
return
self._extensionRunner.emitError(
ExtensionError(extensionPath="", event=event, error=str(error))
)
task.add_done_callback(_done)
def _spawnBackground(self, awaitable: Any, event: str = "background") -> None:
# KNOWN GAP (audit core-session-10, deliberately left as-is): the no-loop
# fallback runs the coroutine on a brand-new loop. `self.abort()` /
# `self.compact()` await futures created on the session's own loop
# (`waitForIdle`'s `_idleWaiters`), so reaching this branch would be a
# cross-loop wait. Every known caller is already on the session loop; making
# this correct means giving the session a loop handle, which is a design
# change, not a patch.
try:
loop = asyncio.get_running_loop()
except RuntimeError:
asyncio.run(awaitable)
return
# `void promise()`: the call runs at once, up to its first suspension, as a JavaScript async call does.
self._holdBackgroundTask(asyncio.Task(awaitable, loop=loop, eager_start=True), event)
def _spawnExtensionMessage(self, awaitable: Any, event: str = "send_message") -> None:
"""Match JavaScript async calls by running eagerly until their first suspension."""
try:
loop = asyncio.get_running_loop()
except RuntimeError:
asyncio.run(awaitable)
return
self._holdBackgroundTask(asyncio.Task(awaitable, loop=loop, eager_start=True), event)
def _tool_execution_extension_event(event: Any) -> dict[str, Any]:
"""The extension-facing dict of a ``tool_execution_*`` event, with ``parentToolCallId`` only
for calls another tool made."""
event_type = _event_type(event)
fields = {
"tool_execution_start": ("toolCallId", "toolName", "args"),
"tool_execution_update": ("toolCallId", "toolName", "args", "partialResult"),
"tool_execution_end": ("toolCallId", "toolName", "result", "isError"),
}[event_type]
payload: dict[str, Any] = {"type": event_type, **{name: _event_field(event, name) for name in fields}}
duration_ms = _event_field(event, "durationMs") if event_type == "tool_execution_end" else None
if duration_ms is not None:
payload["durationMs"] = duration_ms
parent_tool_call_id = _event_field(event, "parentToolCallId")
if parent_tool_call_id:
payload["parentToolCallId"] = parent_tool_call_id
return payload
def _beingCancelled() -> bool:
"""Whether the running task has a cancellation requested of it (``Task.cancelling``): its `CancelledError` is the
caller's, not one a hook or route raised itself."""
task = asyncio.current_task()
return task is not None and task.cancelling() > 0
class _CustomRunBlocked(RuntimeError):
"""MISAKA fork: a before_agent_start hook blocked a run that a custom message starts."""
def _raiseRunBlocked(trigger: BeforeAgentStartTrigger, reason: str) -> NoReturn:
"""MISAKA fork: pi has no block. A blocked prompt fails; a blocked custom run is recorded
without a turn by `_startRun`."""
if trigger["messageType"] == "custom":
raise _CustomRunBlocked(reason)
raise RuntimeError(reason)
def _definition_attr(definition: Any, name: str) -> Any:
if isinstance(definition, dict):
return definition.get(name)
return getattr(definition, name, None)
def _event_type(event: Any) -> str:
return str(_event_field(event, "type"))
def _event_field(event: Any, name: str, default: Any = None) -> Any:
if isinstance(event, dict):
return event.get(name, default)
return getattr(event, name, default)
def _event_timestamp_ms(value: Any) -> int:
if isinstance(value, datetime):
return int(value.timestamp() * 1000)
if isinstance(value, int | float):
return int(value)
if isinstance(value, str):
try:
return int(datetime.fromisoformat(value).timestamp() * 1000)
except ValueError:
return 0
return 0
def _result_flag(result: Any, name: str, default: Any = None) -> Any:
if isinstance(result, dict):
return result.get(name, default)
return getattr(result, name, default)
def _message_role(message: Any) -> str | None:
role = read_field(message, "role")
return role if isinstance(role, str) else None
def _is_task_notification(message: Any) -> bool:
"""A sub-agent's or background shell's notice (````), as both send it."""
return _message_role(message) == "custom" and read_field(message, "customType") == "task-notification"
def _message_content(message: Any) -> Any:
return read_field(message, "content")
def _normalize_nullish_message_content(message: Any) -> Any:
if _message_role(message) not in {"user", "assistant", "toolResult", "custom"}:
return message
if _message_content(message) is not None:
return message
if isinstance(message, Mapping):
return {**message, "content": []}
model_copy = getattr(message, "model_copy", None)
return model_copy(update={"content": []}) if callable(model_copy) else message
def _validate_as(model_type: type, data: Any) -> Any | None:
"""Re-validate `data` as `model_type`, or None when it is not that shape."""
validate = getattr(model_type, "model_validate", None)
if not callable(validate):
return None
try:
return validate(data)
except Exception: # noqa: BLE001 - a replacement of another shape falls back to the raw mapping
return None
def _is_noop_compaction(preparation: CompactionPreparation) -> bool:
"""True when the preparation would summarize nothing at all.
Such a compaction pays for a summarization request over an empty conversation,
appends a summary entry that only grows the context, and re-fires next turn. A
split turn with a prefix is not a no-op: its prefix is what gets summarized.
"""
return not preparation.messagesToSummarize and not preparation.turnPrefixMessages
def _content_type(block: Any) -> str | None:
if isinstance(block, dict):
value = block.get("type")
else:
value = getattr(block, "type", None)
return value if isinstance(value, str) else None
def _message_dict(value: Any) -> Any:
if hasattr(value, "model_dump"):
return value.model_dump()
if isinstance(value, dict):
return {key: _message_dict(item) for key, item in value.items()}
if isinstance(value, list):
return [_message_dict(item) for item in value]
return value
def _as_assistant_message(message: Any) -> AssistantMessage | None:
if _message_role(message) != "assistant":
return None
if isinstance(message, AssistantMessage):
return message
try:
validated = validate_message(_message_dict(message))
except Exception: # noqa: BLE001 - validation errors of any shape mean 'not an assistant message'
return None
return validated if isinstance(validated, AssistantMessage) else None
def _decorate_agent_end_event(event: Any, will_retry: bool) -> dict[str, Any]:
return {
"type": "agent_end",
"messages": list(_event_field(event, "messages", []) or []),
"willRetry": will_retry,
}
def _auth_overrides(signal: Any | None) -> Any:
"""`{ signal }` for `getAuth`, or nothing when no signal was given."""
if signal is None:
return None
from misaka.ai.auth.resolve import AuthResolutionOverrides
return AuthResolutionOverrides(signal=signal)
async def _sleep_with_abort(delay_ms: int, signal: Any) -> bool:
if bool(getattr(signal, "aborted", False)):
return False
if delay_ms <= 0:
await asyncio.sleep(0)
return not bool(getattr(signal, "aborted", False))
try:
await asyncio.wait_for(signal.wait(), timeout=delay_ms / 1000)
return False
except TimeoutError:
return True
__all__ = [
"AgentSession",
"AgentSessionConfig",
"AgentSessionEvent",
"AgentSessionEventListener",
"ExtensionBindings",
"ModelCycleResult",
"ParsedSkillBlock",
"PromptOptions",
"SessionStats",
"SessionTokenStats",
"parseSkillBlock",
]