Add files using upload-large-folder tool

packages/agent-core-v2/docs/config-manifest.toml

@@ -0,0 +1,490 @@
+# Config Section Manifest
+#
+# Generated by scripts/gen-config-manifest.mts — do not edit by hand.
+# Regenerate with: pnpm --filter @moonshot-ai/agent-core-v2 gen:config-manifest
+#
+# One [table] per registered config section, in the on-disk config.toml shape
+# (snake_case keys). Un-commented assignments are registered defaults;
+# commented "# field: type" lines describe the remaining schema fields.
+# Values resolve as: default -> config.toml -> env overlay -> memory.
+
+# Index (28 sections · 2 overlay(s))
+#   background               src/agent/task/configSection.ts
+#   builtinProductSkills     src/features/skill/catalog/configSection.ts
+#   cron                     src/features/cron/configSection.ts
+#   database                 src/persistence/configSection.ts
+#   defaultPermissionMode    src/agent/permissionMode/configSection.ts
+#   defaultPlanMode          src/features/plan/configSection.ts
+#   experimental             src/app/flag/flag.ts
+#   extraAgentDirs           src/workspace/workspaceAgentProfileLoader/configSection.ts
+#   extraSkillDirs           src/features/skill/catalog/configSection.ts
+#   hooks                    src/features/externalHooks/configSection.ts
+#   identity                 src/app/agentIdentity/configSection.ts
+#   image                    src/agent/media/configSection.ts
+#   loopControl              src/agent/loop/configSection.ts
+#   mcp                      src/app/mcpConfig/configSection.ts
+#   mergeAllAvailableSkills  src/features/skill/catalog/configSection.ts
+#   modelCatalog             src/app/kosongConfig/configSection.ts
+#   models                   src/app/kosongConfig/configSection.ts
+#   permission               src/agent/permissionRules/configSection.ts
+#   providers                src/app/kosongConfig/configSection.ts
+#   read                     src/agent/tools/os/read/configSection.ts
+#   secondaryModel           src/session/subagent/configSection.ts
+#   services                 src/app/auth/configSection.ts
+#   subagent                 src/session/subagent/configSection.ts
+#   swarm                    src/features/swarm/configSection.ts
+#   task                     src/agent/task/configSection.ts
+#   thinking                 src/app/kosongConfig/configSection.ts
+#   tokenCounting            src/agent/tokenCounting/configSection.ts
+#   tools                    src/agent/toolPolicy/configSection.ts
+#   (overlay) servicesCredentialEnvOverlay  src/app/auth/configSection.ts
+#   (overlay) kimiModelEnvOverlay  src/app/kosongConfig/envOverlay.ts
+
+# ##########################################################################
+# background
+#   owner: src/agent/task/configSection.ts
+#   scope: core
+#   hooks: stripEnv
+#   env:
+#     keep_alive_on_exit <- KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT (custom parse)
+#     max_running_tasks <- KIMI_CODE_BACKGROUND_MAX_RUNNING_TASKS (custom parse)
+#     bash_task_timeout_s <- KIMI_CODE_BACKGROUND_BASH_TASK_TIMEOUT_S (custom parse)
+#     print_wait_ceiling_s <- KIMI_CODE_BACKGROUND_PRINT_WAIT_CEILING_S (custom parse)
+#     print_background_mode <- KIMI_CODE_BACKGROUND_PRINT_BACKGROUND_MODE (custom parse)
+#     print_max_turns <- KIMI_CODE_BACKGROUND_PRINT_MAX_TURNS (custom parse)
+# ##########################################################################
+
+[background]
+# max_running_tasks: integer
+# keep_alive_on_exit: boolean
+# bash_auto_background_on_timeout: boolean
+# bash_task_timeout_s: integer
+# kill_grace_period_ms: integer
+# print_wait_ceiling_s: integer
+# print_background_mode: "exit" | "drain" | "steer"
+# print_max_turns: integer
+
+# ##########################################################################
+# builtinProductSkills (config.toml: builtin_product_skills)
+#   owner: src/features/skill/catalog/configSection.ts
+#   scope: core
+#   hooks: stripEnv
+#   env:
+#      <- KIMI_CODE_BUILTIN_PRODUCT_SKILLS (custom parse)
+# ##########################################################################
+
+builtin_product_skills = true
+
+# ##########################################################################
+# cron
+#   owner: src/features/cron/configSection.ts
+#   scope: core
+#   hooks: stripEnv
+#   env:
+#     debug <- KIMI_CRON_DEBUG (custom parse)
+#     no_jitter <- KIMI_CRON_NO_JITTER (custom parse)
+#     no_stale <- KIMI_CRON_NO_STALE (custom parse)
+#     disabled <- KIMI_DISABLE_CRON (custom parse)
+#     manual_tick <- KIMI_CRON_MANUAL_TICK (custom parse)
+#     clock <- KIMI_CRON_CLOCK
+#     poll_interval_ms <- KIMI_CRON_POLL_INTERVAL_MS (custom parse)
+# ##########################################################################
+
+[cron]
+# (schema uses transforms; fields below come from the registered default)
+debug = false
+no_jitter = false
+no_stale = false
+disabled = false
+manual_tick = false
+
+# ##########################################################################
+# database
+#   owner: src/persistence/configSection.ts
+#   scope: core
+#   hooks: stripEnv
+#   env:
+#     base <- KIMI_CODE_PERSISTENCE_MINIDB_READMODEL (custom parse)
+#     search <- KIMI_CODE_SEARCH_WORKER (custom parse)
+# ##########################################################################
+
+[database]
+# base: boolean
+# search: boolean
+
+# ##########################################################################
+# defaultPermissionMode (config.toml: default_permission_mode)
+#   owner: src/agent/permissionMode/configSection.ts
+#   scope: core
+# ##########################################################################
+
+# default_permission_mode: "manual" | "auto" | "yolo"
+
+# ##########################################################################
+# defaultPlanMode (config.toml: default_plan_mode)
+#   owner: src/features/plan/configSection.ts
+#   scope: core
+# ##########################################################################
+
+default_plan_mode = false
+
+# ##########################################################################
+# experimental
+#   owner: src/app/flag/flag.ts
+#   scope: core
+#   hooks: custom fromToml · custom toToml
+# ##########################################################################
+
+[experimental]
+# <name>: boolean
+
+# ##########################################################################
+# extraAgentDirs (config.toml: extra_agent_dirs)
+#   owner: src/workspace/workspaceAgentProfileLoader/configSection.ts
+#   scope: core
+# ##########################################################################
+
+extra_agent_dirs = []
+
+# ##########################################################################
+# extraSkillDirs (config.toml: extra_skill_dirs)
+#   owner: src/features/skill/catalog/configSection.ts
+#   scope: core
+# ##########################################################################
+
+extra_skill_dirs = []
+
+# ##########################################################################
+# hooks
+#   owner: src/features/externalHooks/configSection.ts
+#   scope: core
+#   hooks: custom fromToml · custom toToml
+# ##########################################################################
+
+# one [[hooks]] table per entry:
+# [[hooks]]
+  # event: "PreToolUse" | "PostToolUse" | "PostToolUseFailure" | "PermissionRequest" | "PermissionResult" | "UserPromptSubmit" | "UserPromptQueued" | "TurnStarted" | "Stop" | "StopFailure" | "Interrupt" | "SessionStart" | "SessionEnd" | "SessionHeartbeat" | "SubagentStart" | "SubagentStop" | "TaskStarted" | "PreCompact" | "PostCompact" | "Notification"
+  # matcher: string
+  # command: string
+  # timeout: integer
+
+# ##########################################################################
+# identity
+#   owner: src/app/agentIdentity/configSection.ts
+#   scope: core
+#   hooks: stripEnv
+#   env:
+#     name <- KIMI_CODE_IDENTITY_NAME (custom parse)
+#     slug <- KIMI_CODE_IDENTITY_SLUG (custom parse)
+# ##########################################################################
+
+[identity]
+# name: string
+# slug: string
+
+# ##########################################################################
+# image
+#   owner: src/agent/media/configSection.ts
+#   scope: core
+#   hooks: stripEnv
+#   env:
+#     max_edge_px <- KIMI_IMAGE_MAX_EDGE_PX (custom parse)
+#     read_byte_budget <- KIMI_IMAGE_READ_BYTE_BUDGET (custom parse)
+# ##########################################################################
+
+[image]
+# max_edge_px: integer
+# read_byte_budget: integer
+
+# ##########################################################################
+# loopControl (config.toml: loop_control)
+#   owner: src/agent/loop/configSection.ts
+#   scope: core
+#   hooks: custom toToml · stripEnv
+#   deprecations (old key is ignored + warns; rename manually):
+#     max_retries_per_step -> max_attempts_per_step
+#     max_steps_per_run -> max_steps_per_turn
+#   env:
+#     max_steps_per_turn <- KIMI_LOOP_MAX_STEPS_PER_TURN (custom parse)
+#     max_attempts_per_step <- KIMI_LOOP_MAX_ATTEMPTS_PER_STEP (custom parse; deprecated fallback KIMI_LOOP_MAX_RETRIES_PER_STEP)
+# ##########################################################################
+
+[loop_control]
+# max_steps_per_turn: integer
+# max_attempts_per_step: integer
+# max_ralph_iterations: integer
+# reserved_context_size: integer
+# compaction_trigger_ratio: number
+# compaction_max_attempts: integer
+
+# ##########################################################################
+# mcp
+#   owner: src/app/mcpConfig/configSection.ts
+#   scope: core
+#   hooks: stripEnv
+#   env:
+#     startup_timeout_ms <- KIMI_MCP_STARTUP_TIMEOUT_MS (custom parse)
+#     tool_timeout_ms <- KIMI_MCP_TOOL_TIMEOUT_MS (custom parse)
+# ##########################################################################
+
+[mcp]
+# startup_timeout_ms: integer
+# tool_timeout_ms: integer
+
+# ##########################################################################
+# mergeAllAvailableSkills (config.toml: merge_all_available_skills)
+#   owner: src/features/skill/catalog/configSection.ts
+#   scope: core
+# ##########################################################################
+
+merge_all_available_skills = true
+
+# ##########################################################################
+# modelCatalog (config.toml: model_catalog)
+#   owner: src/app/kosongConfig/configSection.ts
+#   scope: core
+# ##########################################################################
+
+[model_catalog]
+# refresh_interval_ms: integer
+# refresh_on_start: boolean
+
+# ##########################################################################
+# models
+#   owner: src/app/kosongConfig/configSection.ts
+#   scope: core
+#   hooks: custom fromToml · custom toToml
+# ##########################################################################
+
+[models]
+
+# one [models."<name>"] table per entry:
+# [models."<name>"]
+  # provider_id: string
+  # base_url: string
+  # api_key: string
+  # oauth: object
+    # storage: "file" | "keyring"
+    # key: string
+    # oauth_host: string
+  # protocol: "anthropic" | "openai" | "openai_responses" | "google-genai"
+  # name: string
+  # aliases: string[]
+  # provider: string
+  # model: string
+  # max_context_size: integer
+  # max_input_size: integer
+  # max_output_size: integer
+  # capabilities: string[]
+  # display_name: string
+  # reasoning_key: string
+  # adaptive_thinking: boolean
+  # beta_api: boolean
+  # support_efforts: string[]
+  # default_effort: string
+  # off_effort: string
+  # overrides: object
+    # max_context_size: integer
+    # max_input_size: integer
+    # max_output_size: integer
+    # capabilities: string[]
+    # display_name: string
+    # reasoning_key: string
+    # adaptive_thinking: boolean
+    # support_efforts: string[]
+    # default_effort: string
+    # off_effort: string
+
+# ##########################################################################
+# permission
+#   owner: src/agent/permissionRules/configSection.ts
+#   scope: core
+#   hooks: custom fromToml · custom toToml · stripEnv
+#   env:
+#     dangerous_command_guard <- KIMI_CODE_DANGEROUS_COMMAND_GUARD (custom parse)
+# ##########################################################################
+
+[permission]
+# rules: object[] — one entry per item:
+  # decision: "allow" | "deny" | "ask"
+  # scope: "turn-override" | "session-runtime" | "project" | "user" (default: "user")
+  # pattern: string
+  # reason: string
+# dangerous_command_guard: boolean
+
+# ##########################################################################
+# providers
+#   owner: src/app/kosongConfig/configSection.ts
+#   scope: core
+#   hooks: custom fromToml · custom toToml · stripEnv
+#   env:
+#     __kimi_env__.api_key <- KIMI_MODEL_API_KEY
+#     __kimi_env__.type <- KIMI_MODEL_PROVIDER_TYPE
+#     __kimi_env__.base_url <- KIMI_MODEL_BASE_URL
+# ##########################################################################
+
+[providers]
+
+# one [providers."<name>"] table per entry:
+# [providers."<name>"]
+  # model_source: "static" | "discover" | "oauth-catalog"
+  # base_url: string
+  # custom_headers: record<string, string>
+  # default_model: string
+  # type: string
+  # api_key: string
+  # oauth: object
+    # storage: "file" | "keyring"
+    # key: string
+    # oauth_host: string
+  # env: record<string, string>
+  # source: record<string, any>
+
+# ##########################################################################
+# read
+#   owner: src/agent/tools/os/read/configSection.ts
+#   scope: core
+# ##########################################################################
+
+[read]
+# default_max_chars: integer
+# max_chars: integer
+
+# ##########################################################################
+# secondaryModel (config.toml: secondary_model)
+#   owner: src/session/subagent/configSection.ts
+#   scope: core
+# ##########################################################################
+
+[secondary_model]
+# default_model: string
+# models: record<string, string>
+# force: boolean
+# model: string
+# max_context_size: integer
+# max_input_size: integer
+# max_output_size: integer
+# capabilities: string[]
+# display_name: string
+# reasoning_key: string
+# adaptive_thinking: boolean
+# support_efforts: string[]
+# default_effort: string
+# off_effort: string
+
+# ##########################################################################
+# services
+#   owner: src/app/auth/configSection.ts
+#   scope: core
+#   hooks: custom fromToml · custom toToml · stripEnv
+#   env:
+#     moonshot_search.base_url <- KIMI_WEB_SEARCH_BASE_URL (custom parse)
+#     moonshot_search.api_key <- KIMI_WEB_SEARCH_API_KEY (custom parse)
+#     moonshot_fetch.base_url <- KIMI_WEB_FETCH_BASE_URL (custom parse)
+#     moonshot_fetch.api_key <- KIMI_WEB_FETCH_API_KEY (custom parse)
+# ##########################################################################
+
+[services]
+
+# [services.moonshot_search]
+  # base_url: string
+  # api_key: string
+  # oauth: object
+    # storage: "file" | "keyring"
+    # key: string
+    # oauth_host: string
+  # custom_headers: record<string, string>
+
+# [services.moonshot_fetch]
+  # base_url: string
+  # api_key: string
+  # oauth: object
+    # storage: "file" | "keyring"
+    # key: string
+    # oauth_host: string
+  # custom_headers: record<string, string>
+
+# ##########################################################################
+# subagent
+#   owner: src/session/subagent/configSection.ts
+#   scope: core
+#   hooks: stripEnv
+#   env:
+#     timeout_ms <- KIMI_SUBAGENT_TIMEOUT_MS (custom parse)
+# ##########################################################################
+
+[subagent]
+timeout_ms = 7200000
+
+# ##########################################################################
+# swarm
+#   owner: src/features/swarm/configSection.ts
+#   scope: core
+#   hooks: stripEnv
+#   env:
+#     timeout_ms <- KIMI_CODE_SWARM_TIMEOUT_MS (custom parse)
+# ##########################################################################
+
+[swarm]
+timeout_ms = 7200000
+
+# ##########################################################################
+# task
+#   owner: src/agent/task/configSection.ts
+#   scope: core
+#   hooks: stripEnv
+#   env:
+#     keep_alive_on_exit <- KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT (custom parse)
+#     max_running_tasks <- KIMI_CODE_BACKGROUND_MAX_RUNNING_TASKS (custom parse)
+#     bash_task_timeout_s <- KIMI_CODE_BACKGROUND_BASH_TASK_TIMEOUT_S (custom parse)
+#     print_wait_ceiling_s <- KIMI_CODE_BACKGROUND_PRINT_WAIT_CEILING_S (custom parse)
+#     print_background_mode <- KIMI_CODE_BACKGROUND_PRINT_BACKGROUND_MODE (custom parse)
+#     print_max_turns <- KIMI_CODE_BACKGROUND_PRINT_MAX_TURNS (custom parse)
+# ##########################################################################
+
+[task]
+# max_running_tasks: integer
+# keep_alive_on_exit: boolean
+# bash_auto_background_on_timeout: boolean
+# bash_task_timeout_s: integer
+# kill_grace_period_ms: integer
+# print_wait_ceiling_s: integer
+# print_background_mode: "exit" | "drain" | "steer"
+# print_max_turns: integer
+
+# ##########################################################################
+# thinking
+#   owner: src/app/kosongConfig/configSection.ts
+#   scope: core
+#   hooks: stripEnv
+#   env:
+#     forced_effort <- KIMI_MODEL_THINKING_EFFORT
+# ##########################################################################
+
+[thinking]
+# enabled: boolean
+# effort: string
+# forced_effort: string
+# keep: string
+
+# ##########################################################################
+# tokenCounting (config.toml: token_counting)
+#   owner: src/agent/tokenCounting/configSection.ts
+#   scope: core
+#   hooks: stripEnv
+#   env:
+#     strategy <- KIMI_TOKEN_COUNTING_STRATEGY (custom parse)
+# ##########################################################################
+
+[token_counting]
+strategy = "measured+estimated"
+
+# ##########################################################################
+# tools
+#   owner: src/agent/toolPolicy/configSection.ts
+#   scope: core
+# ##########################################################################
+
+[tools]
+# enabled: string[]
+# disabled: string[]

packages/agent-core-v2/docs/state-manifest.d.ts

@@ -0,0 +1,1270 @@
+// App, Workspace, Session & Agent State Manifest
+//
+// Generated by scripts/gen-state-manifest.mts — do not edit by hand.
+// Regenerate with: pnpm --filter @moonshot-ai/agent-core-v2 gen:state-manifest
+//
+// Every state key registered into the App-scope IAppStateService, the
+// Workspace-scope IWorkspaceStateService, the Session-scope
+// ISessionStateService, or the Agent-scope IAgentStateService (see
+// src/_base/state/stateRegistry.ts), collected statically from the
+// `states.contributeState(...)` call sites and the replayable key chains — a
+// `defineState(...).replayable(...)` key is contributed into the Agent-scope
+// service by its owner service at construction, and
+// carries a `// replayable · durable|transient · undoable? — folds: ...` line.
+// Replayable values are excluded from snapshot()/inspect(). A key defined via
+// defineState but never registered nor replayable does not appear here. Each entry shows the
+// compile-time StateKey<T> value type fully expanded inline, so the manifest is
+// self-contained (no imports, no helper declarations). A named type is marked
+// at its expansion site with a `/* TypeName — source/file.ts */` comment; a
+// `/* TypeName — recursive (...) */ unknown` marker stops a recursive expansion.
+// Lib globals (Map/Set/Record/…) are referenced as-is. Generic instantiations
+// expand structurally; classes render as their public instance shape. The
+// defining source file heads each group.
+//
+// snapshot() returns JSON-safe deep copies of these values: Maps become plain
+// objects (or [key, value] entry arrays when a key is not string/number), Sets
+// become arrays, bigints become strings, functions are dropped, circular
+// references become '(circular)', and class instances collapse to a '(ClassName)'
+// marker — the wire shape of an entry is the JSON projection of the type here.
+//
+// Index (App: 0 keys · Workspace: 6 keys · Session: 9 keys · Agent: 73 keys)
+//   App
+//   Workspace
+//     workspaceDirs.ephemeralDirs          src/workspace/workspaceDirs/workspaceDirsService.ts
+//     workspaceDirs.fileDirs               src/workspace/workspaceDirs/workspaceDirsService.ts
+//     workspaceInstructions.current        src/workspace/workspaceInstructions/workspaceInstructionsService.ts
+//     workspaceSkillCatalog.contributions  src/features/skill/workspace/workspaceSkillCatalogService.ts
+//     workspaceSkillCatalog.merged         src/features/skill/workspace/workspaceSkillCatalogService.ts
+//     workspaceTrust.trusted               src/workspace/workspaceTrust/workspaceTrustService.ts
+//   Session
+//     sessionActivity.current            src/session/sessionActivity/sessionActivityService.ts
+//     sessionActivity.folds              src/session/sessionActivity/sessionActivityService.ts
+//     sessionLog.rootLevel               src/session/sessionLog/sessionLogService.ts
+//     sessionMetadata.data               src/session/sessionMetadata/sessionMetadataService.ts
+//     sessionSkillCatalog.contributions  src/features/skill/session/skillCatalogService.ts
+//     sessionSkillCatalog.merged         src/features/skill/session/skillCatalogService.ts
+//     sessionToolPolicy.state            src/session/sessionToolPolicy/sessionToolPolicyService.ts
+//     workspaceContext.additionalDirs    src/session/workspaceContext/workspaceContextService.ts
+//     workspaceContext.workDir           src/session/workspaceContext/workspaceContextService.ts
+//   Agent
+//     agentPlugin.sessionStartRefreshPending          src/agent/plugin/agentPluginService.ts
+//     agentsMdReminder.cwd                            src/agent/agentsMdReminder/agentsMdReminderService.ts
+//     agentsMdReminder.known                          src/agent/agentsMdReminder/agentsMdReminderService.ts
+//     agentsMdReminder.seeded                         src/agent/agentsMdReminder/agentsMdReminderService.ts
+//     contextMemory                                   src/agent/contextMemory/contextOps.ts
+//     contextProjector.lastRepairSignature            src/agent/contextProjector/contextProjectorService.ts
+//     externalHooks.stopHookContinuationUsed          src/features/externalHooks/agent/agentExternalHooksService.ts
+//     fileHistory                                     src/features/fileHistory/fileHistoryOps.ts
+//     fullCompaction                                  src/agent/fullCompaction/compactionOps.ts
+//     fullCompaction.activeTurnId                     src/agent/fullCompaction/fullCompactionService.ts
+//     fullCompaction.compactionCountInTurn            src/agent/fullCompaction/fullCompactionService.ts
+//     fullCompaction.consecutiveOverflowCompactions   src/agent/fullCompaction/fullCompactionService.ts
+//     fullCompaction.lastCompactedTokenCount          src/agent/fullCompaction/fullCompactionService.ts
+//     fullCompaction.observedMaxContextTokensByModel  src/agent/fullCompaction/fullCompactionService.ts
+//     fullCompaction.wireRanges                       src/agent/fullCompaction/compactionOps.ts
+//     interruptionReminder                            src/agent/interruptionReminder/interruptionReminderOps.ts
+//     llm.requestTrace                                src/agent/llmRequester/llmRequestOps.ts
+//     llmRequester.emittedThinkingEffortWarnings      src/agent/llmRequester/llmRequesterService.ts
+//     llmRequester.lastConfigLogSignature             src/agent/llmRequester/llmRequesterService.ts
+//     llmRequester.mediaDegradedTurns                 src/agent/llmRequester/llmRequesterService.ts
+//     llmRequester.mediaStrippedTurns                 src/agent/llmRequester/llmRequesterService.ts
+//     llmRequester.turnConfigs                        src/agent/llmRequester/llmRequesterService.ts
+//     loop.disposing                                  src/agent/loop/loopService.ts
+//     loop.lastRequestTraceId                         src/agent/loop/loopService.ts
+//     mcp.discovery                                   src/agent/mcp/mcpDiscoveryOps.ts
+//     mcp.discoveryWritesReady                        src/agent/mcp/mcpService.ts
+//     mcp.mcpToolsByServer                            src/agent/mcp/mcpService.ts
+//     media.budgetDropped                             src/agent/media/mediaResolverService.ts
+//     media.registeredKey                             src/agent/media/mediaToolsRegistrar.ts
+//     media.resolved                                  src/agent/media/mediaResolverService.ts
+//     permissionMode                                  src/agent/permissionMode/permissionModeOps.ts
+//     permissionMode.configured                       src/agent/permissionMode/permissionModeOps.ts
+//     permissionMode.lastMode                         src/agent/permissionMode/injection/permissionModeInjection.ts
+//     permissionRules                                 src/agent/permissionRules/permissionRulesOps.ts
+//     plan                                            src/features/plan/planOps.ts
+//     plan.wasActive                                  src/features/plan/injection/planModeInjection.ts
+//     pluginSessionStartSnapshot                      src/agent/plugin/agentPluginOps.ts
+//     profile                                         src/agent/profile/profileOps.ts
+//     profile.activeToolNamesOverlay                  src/agent/profile/profileService.ts
+//     profile.activeTools                             src/agent/profile/profileOps.ts
+//     profile.agentsMdWarning                         src/agent/profile/profileService.ts
+//     profile.emittedPluginBudgetWarnings             src/agent/profile/profileService.ts
+//     profile.emittedThinkingEffortWarnings           src/agent/profile/profileService.ts
+//     profile.emittedToolPatternWarnings              src/agent/profile/profileService.ts
+//     runtime.binding                                 src/agent/runtimeBinding/runtimeBindingService.ts
+//     runtimeBinding                                  src/agent/runtimeBinding/runtimeBindingOps.ts
+//     shellCommand.tasks                              src/agent/shellCommand/shellCommandService.ts
+//     swarm                                           src/features/swarm/swarmOps.ts
+//     task                                            src/agent/task/taskOps.ts
+//     task.activeTaskReminderPending                  src/agent/task/taskService.ts
+//     task.deliveredNotificationKeys                  src/agent/task/taskService.ts
+//     task.ghosts                                     src/agent/task/taskService.ts
+//     task.notificationDelivery                       src/agent/task/taskService.ts
+//     task.scheduledNotificationKeys                  src/agent/task/taskService.ts
+//     toolDedupe.activeStep                           src/agent/toolDedupe/toolDedupeService.ts
+//     toolDedupe.activeTurnId                         src/agent/toolDedupe/toolDedupeService.ts
+//     toolDedupe.callKeyByCallId                      src/agent/toolDedupe/toolDedupeService.ts
+//     toolDedupe.consecutiveCount                     src/agent/toolDedupe/toolDedupeService.ts
+//     toolDedupe.consecutiveKey                       src/agent/toolDedupe/toolDedupeService.ts
+//     toolDedupe.handoffPhase                         src/agent/toolDedupe/toolDedupeService.ts
+//     toolDedupe.originalCallIndex                    src/agent/toolDedupe/toolDedupeService.ts
+//     toolDedupe.stepCalls                            src/agent/toolDedupe/toolDedupeService.ts
+//     toolDedupe.syntheticCallIds                     src/agent/toolDedupe/toolDedupeService.ts
+//     toolDedupe.turnCallRecords                      src/agent/toolDedupe/toolDedupeService.ts
+//     toolDedupe.turnRepeatCount                      src/agent/toolDedupe/toolDedupeService.ts
+//     toolExecutor.dupTypeTurnId                      src/agent/toolExecutor/toolExecutorService.ts
+//     toolExecutor.toolCallDupTypes                   src/agent/toolExecutor/toolExecutorService.ts
+//     toolSelect.pendingLoaded                        src/agent/toolSelect/toolSelectService.ts
+//     tower                                           src/features/tower/towerOps.ts
+//     tower.base                                      src/features/tower/towerOps.ts
+//     tower.owner                                     src/features/tower/towerOps.ts
+//     turn                                            src/agent/loop/turnOps.ts
+//     userTool                                        src/agent/userTool/userToolOps.ts
+
+/** App-scope keys registered into IAppStateService. */
+export interface AppStateSnapshot {
+}
+
+export type AppStateKey = keyof AppStateSnapshot;
+
+/** Workspace-scope keys registered into IWorkspaceStateService. */
+export interface WorkspaceStateSnapshot {
+  // src/features/skill/workspace/workspaceSkillCatalogService.ts
+  'workspaceSkillCatalog.contributions': Map<string, {
+    readonly c: /* SkillContribution — packages/agent-core-v2/src/features/skill/catalog/skillSource.ts */ {
+      readonly skills: readonly /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name: string;
+        readonly description: string;
+        readonly path: string;
+        readonly dir: string;
+        readonly content: string;
+        readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+          readonly name?: string;
+          readonly description?: string;
+          readonly type?: string;
+          readonly whenToUse?: string;
+          readonly disableModelInvocation?: boolean;
+          readonly isSubSkill?: boolean;
+          readonly safe?: boolean;
+          readonly arguments?: string | readonly unknown[];
+          [key: string]: unknown;
+        };
+        readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+        readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+          readonly id: string;
+          readonly instructions?: string;
+        };
+        readonly mermaid?: string;
+        readonly d2?: string;
+        readonly productSpecific?: boolean;
+        readonly experimentalFlag?: string;
+      }[];
+      readonly skipped?: readonly /* SkippedSkill — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly path: string;
+        readonly type: string;
+        readonly reason: string;
+      }[];
+      readonly scannedRoots?: readonly string[];
+    };
+    readonly priority: number;
+  }>;
+  'workspaceSkillCatalog.merged': /* InMemorySkillCatalog — packages/agent-core-v2/src/features/skill/catalog/registry.ts */ {
+    registerBuiltinSkill: (skill: /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly name: string;
+      readonly description: string;
+      readonly path: string;
+      readonly dir: string;
+      readonly content: string;
+      readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name?: string;
+        readonly description?: string;
+        readonly type?: string;
+        readonly whenToUse?: string;
+        readonly disableModelInvocation?: boolean;
+        readonly isSubSkill?: boolean;
+        readonly safe?: boolean;
+        readonly arguments?: string | readonly unknown[];
+        [key: string]: unknown;
+      };
+      readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+      readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly id: string;
+        readonly instructions?: string;
+      };
+      readonly mermaid?: string;
+      readonly d2?: string;
+      readonly productSpecific?: boolean;
+      readonly experimentalFlag?: string;
+    }) => void;
+    register: (skill: /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly name: string;
+      readonly description: string;
+      readonly path: string;
+      readonly dir: string;
+      readonly content: string;
+      readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name?: string;
+        readonly description?: string;
+        readonly type?: string;
+        readonly whenToUse?: string;
+        readonly disableModelInvocation?: boolean;
+        readonly isSubSkill?: boolean;
+        readonly safe?: boolean;
+        readonly arguments?: string | readonly unknown[];
+        [key: string]: unknown;
+      };
+      readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+      readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly id: string;
+        readonly instructions?: string;
+      };
+      readonly mermaid?: string;
+      readonly d2?: string;
+      readonly productSpecific?: boolean;
+      readonly experimentalFlag?: string;
+    }, options?: {
+      readonly replace?: boolean;
+    }) => void;
+    recordSkipped: (skills: readonly /* SkippedSkill — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly path: string;
+      readonly type: string;
+      readonly reason: string;
+    }[]) => void;
+    addRoots: (roots: readonly string[]) => void;
+    getSkill: (name: string) => /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly name: string;
+      readonly description: string;
+      readonly path: string;
+      readonly dir: string;
+      readonly content: string;
+      readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name?: string;
+        readonly description?: string;
+        readonly type?: string;
+        readonly whenToUse?: string;
+        readonly disableModelInvocation?: boolean;
+        readonly isSubSkill?: boolean;
+        readonly safe?: boolean;
+        readonly arguments?: string | readonly unknown[];
+        [key: string]: unknown;
+      };
+      readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+      readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly id: string;
+        readonly instructions?: string;
+      };
+      readonly mermaid?: string;
+      readonly d2?: string;
+      readonly productSpecific?: boolean;
+      readonly experimentalFlag?: string;
+    } | undefined;
+    getPluginSkill: (pluginId: string, name: string) => /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly name: string;
+      readonly description: string;
+      readonly path: string;
+      readonly dir: string;
+      readonly content: string;
+      readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name?: string;
+        readonly description?: string;
+        readonly type?: string;
+        readonly whenToUse?: string;
+        readonly disableModelInvocation?: boolean;
+        readonly isSubSkill?: boolean;
+        readonly safe?: boolean;
+        readonly arguments?: string | readonly unknown[];
+        [key: string]: unknown;
+      };
+      readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+      readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly id: string;
+        readonly instructions?: string;
+      };
+      readonly mermaid?: string;
+      readonly d2?: string;
+      readonly productSpecific?: boolean;
+      readonly experimentalFlag?: string;
+    } | undefined;
+    renderSkillPrompt: (skill: /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly name: string;
+      readonly description: string;
+      readonly path: string;
+      readonly dir: string;
+      readonly content: string;
+      readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name?: string;
+        readonly description?: string;
+        readonly type?: string;
+        readonly whenToUse?: string;
+        readonly disableModelInvocation?: boolean;
+        readonly isSubSkill?: boolean;
+        readonly safe?: boolean;
+        readonly arguments?: string | readonly unknown[];
+        [key: string]: unknown;
+      };
+      readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+      readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly id: string;
+        readonly instructions?: string;
+      };
+      readonly mermaid?: string;
+      readonly d2?: string;
+      readonly productSpecific?: boolean;
+      readonly experimentalFlag?: string;
+    }, rawArgs: string, context?: {
+      readonly sessionId?: string;
+    }) => string;
+    listSkills: () => readonly /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly name: string;
+      readonly description: string;
+      readonly path: string;
+      readonly dir: string;
+      readonly content: string;
+      readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name?: string;
+        readonly description?: string;
+        readonly type?: string;
+        readonly whenToUse?: string;
+        readonly disableModelInvocation?: boolean;
+        readonly isSubSkill?: boolean;
+        readonly safe?: boolean;
+        readonly arguments?: string | readonly unknown[];
+        [key: string]: unknown;
+      };
+      readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+      readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly id: string;
+        readonly instructions?: string;
+      };
+      readonly mermaid?: string;
+      readonly d2?: string;
+      readonly productSpecific?: boolean;
+      readonly experimentalFlag?: string;
+    }[];
+    listInvocableSkills: () => readonly /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly name: string;
+      readonly description: string;
+      readonly path: string;
+      readonly dir: string;
+      readonly content: string;
+      readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name?: string;
+        readonly description?: string;
+        readonly type?: string;
+        readonly whenToUse?: string;
+        readonly disableModelInvocation?: boolean;
+        readonly isSubSkill?: boolean;
+        readonly safe?: boolean;
+        readonly arguments?: string | readonly unknown[];
+        [key: string]: unknown;
+      };
+      readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+      readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly id: string;
+        readonly instructions?: string;
+      };
+      readonly mermaid?: string;
+      readonly d2?: string;
+      readonly productSpecific?: boolean;
+      readonly experimentalFlag?: string;
+    }[];
+    getSkillRoots: () => readonly string[];
+    getSkippedByPolicy: () => readonly /* SkippedSkill — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly path: string;
+      readonly type: string;
+      readonly reason: string;
+    }[];
+    getKimiSkillsDescription: () => string;
+    getModelSkillListing: () => string;
+  };
+  // src/workspace/workspaceDirs/workspaceDirsService.ts
+  'workspaceDirs.ephemeralDirs': readonly string[];
+  'workspaceDirs.fileDirs': readonly string[];
+  // src/workspace/workspaceInstructions/workspaceInstructionsService.ts
+  'workspaceInstructions.current': /* WorkspaceInstructionsSnapshot — packages/agent-core-v2/src/workspace/workspaceInstructions/workspaceInstructions.ts */ {
+    readonly agentsMd: string | undefined;
+    readonly agentsMdWarning: string | undefined;
+    readonly agentsMdPaths: readonly string[] | undefined;
+  };
+  // src/workspace/workspaceTrust/workspaceTrustService.ts
+  'workspaceTrust.trusted': boolean;
+}
+
+export type WorkspaceStateKey = keyof WorkspaceStateSnapshot;
+
+/** Session-scope keys registered into ISessionStateService. */
+export interface SessionStateSnapshot {
+  // src/features/skill/session/skillCatalogService.ts
+  'sessionSkillCatalog.contributions': Map<string, {
+    readonly c: /* SkillContribution — packages/agent-core-v2/src/features/skill/catalog/skillSource.ts */ {
+      readonly skills: readonly /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name: string;
+        readonly description: string;
+        readonly path: string;
+        readonly dir: string;
+        readonly content: string;
+        readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+          readonly name?: string;
+          readonly description?: string;
+          readonly type?: string;
+          readonly whenToUse?: string;
+          readonly disableModelInvocation?: boolean;
+          readonly isSubSkill?: boolean;
+          readonly safe?: boolean;
+          readonly arguments?: string | readonly unknown[];
+          [key: string]: unknown;
+        };
+        readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+        readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+          readonly id: string;
+          readonly instructions?: string;
+        };
+        readonly mermaid?: string;
+        readonly d2?: string;
+        readonly productSpecific?: boolean;
+        readonly experimentalFlag?: string;
+      }[];
+      readonly skipped?: readonly /* SkippedSkill — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly path: string;
+        readonly type: string;
+        readonly reason: string;
+      }[];
+      readonly scannedRoots?: readonly string[];
+    };
+    readonly priority: number;
+  }>;
+  'sessionSkillCatalog.merged': /* InMemorySkillCatalog — packages/agent-core-v2/src/features/skill/catalog/registry.ts */ {
+    registerBuiltinSkill: (skill: /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly name: string;
+      readonly description: string;
+      readonly path: string;
+      readonly dir: string;
+      readonly content: string;
+      readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name?: string;
+        readonly description?: string;
+        readonly type?: string;
+        readonly whenToUse?: string;
+        readonly disableModelInvocation?: boolean;
+        readonly isSubSkill?: boolean;
+        readonly safe?: boolean;
+        readonly arguments?: string | readonly unknown[];
+        [key: string]: unknown;
+      };
+      readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+      readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly id: string;
+        readonly instructions?: string;
+      };
+      readonly mermaid?: string;
+      readonly d2?: string;
+      readonly productSpecific?: boolean;
+      readonly experimentalFlag?: string;
+    }) => void;
+    register: (skill: /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly name: string;
+      readonly description: string;
+      readonly path: string;
+      readonly dir: string;
+      readonly content: string;
+      readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name?: string;
+        readonly description?: string;
+        readonly type?: string;
+        readonly whenToUse?: string;
+        readonly disableModelInvocation?: boolean;
+        readonly isSubSkill?: boolean;
+        readonly safe?: boolean;
+        readonly arguments?: string | readonly unknown[];
+        [key: string]: unknown;
+      };
+      readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+      readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly id: string;
+        readonly instructions?: string;
+      };
+      readonly mermaid?: string;
+      readonly d2?: string;
+      readonly productSpecific?: boolean;
+      readonly experimentalFlag?: string;
+    }, options?: {
+      readonly replace?: boolean;
+    }) => void;
+    recordSkipped: (skills: readonly /* SkippedSkill — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly path: string;
+      readonly type: string;
+      readonly reason: string;
+    }[]) => void;
+    addRoots: (roots: readonly string[]) => void;
+    getSkill: (name: string) => /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly name: string;
+      readonly description: string;
+      readonly path: string;
+      readonly dir: string;
+      readonly content: string;
+      readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name?: string;
+        readonly description?: string;
+        readonly type?: string;
+        readonly whenToUse?: string;
+        readonly disableModelInvocation?: boolean;
+        readonly isSubSkill?: boolean;
+        readonly safe?: boolean;
+        readonly arguments?: string | readonly unknown[];
+        [key: string]: unknown;
+      };
+      readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+      readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly id: string;
+        readonly instructions?: string;
+      };
+      readonly mermaid?: string;
+      readonly d2?: string;
+      readonly productSpecific?: boolean;
+      readonly experimentalFlag?: string;
+    } | undefined;
+    getPluginSkill: (pluginId: string, name: string) => /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly name: string;
+      readonly description: string;
+      readonly path: string;
+      readonly dir: string;
+      readonly content: string;
+      readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name?: string;
+        readonly description?: string;
+        readonly type?: string;
+        readonly whenToUse?: string;
+        readonly disableModelInvocation?: boolean;
+        readonly isSubSkill?: boolean;
+        readonly safe?: boolean;
+        readonly arguments?: string | readonly unknown[];
+        [key: string]: unknown;
+      };
+      readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+      readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly id: string;
+        readonly instructions?: string;
+      };
+      readonly mermaid?: string;
+      readonly d2?: string;
+      readonly productSpecific?: boolean;
+      readonly experimentalFlag?: string;
+    } | undefined;
+    renderSkillPrompt: (skill: /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly name: string;
+      readonly description: string;
+      readonly path: string;
+      readonly dir: string;
+      readonly content: string;
+      readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name?: string;
+        readonly description?: string;
+        readonly type?: string;
+        readonly whenToUse?: string;
+        readonly disableModelInvocation?: boolean;
+        readonly isSubSkill?: boolean;
+        readonly safe?: boolean;
+        readonly arguments?: string | readonly unknown[];
+        [key: string]: unknown;
+      };
+      readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+      readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly id: string;
+        readonly instructions?: string;
+      };
+      readonly mermaid?: string;
+      readonly d2?: string;
+      readonly productSpecific?: boolean;
+      readonly experimentalFlag?: string;
+    }, rawArgs: string, context?: {
+      readonly sessionId?: string;
+    }) => string;
+    listSkills: () => readonly /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly name: string;
+      readonly description: string;
+      readonly path: string;
+      readonly dir: string;
+      readonly content: string;
+      readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name?: string;
+        readonly description?: string;
+        readonly type?: string;
+        readonly whenToUse?: string;
+        readonly disableModelInvocation?: boolean;
+        readonly isSubSkill?: boolean;
+        readonly safe?: boolean;
+        readonly arguments?: string | readonly unknown[];
+        [key: string]: unknown;
+      };
+      readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+      readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly id: string;
+        readonly instructions?: string;
+      };
+      readonly mermaid?: string;
+      readonly d2?: string;
+      readonly productSpecific?: boolean;
+      readonly experimentalFlag?: string;
+    }[];
+    listInvocableSkills: () => readonly /* SkillDefinition — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly name: string;
+      readonly description: string;
+      readonly path: string;
+      readonly dir: string;
+      readonly content: string;
+      readonly metadata: /* SkillMetadata — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly name?: string;
+        readonly description?: string;
+        readonly type?: string;
+        readonly whenToUse?: string;
+        readonly disableModelInvocation?: boolean;
+        readonly isSubSkill?: boolean;
+        readonly safe?: boolean;
+        readonly arguments?: string | readonly unknown[];
+        [key: string]: unknown;
+      };
+      readonly source: /* SkillSource — packages/agent-core-v2/src/features/skill/catalog/types.ts */ 'project' | 'user' | 'extra' | 'builtin';
+      readonly plugin?: /* SkillPluginContext — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+        readonly id: string;
+        readonly instructions?: string;
+      };
+      readonly mermaid?: string;
+      readonly d2?: string;
+      readonly productSpecific?: boolean;
+      readonly experimentalFlag?: string;
+    }[];
+    getSkillRoots: () => readonly string[];
+    getSkippedByPolicy: () => readonly /* SkippedSkill — packages/agent-core-v2/src/features/skill/catalog/types.ts */ {
+      readonly path: string;
+      readonly type: string;
+      readonly reason: string;
+    }[];
+    getKimiSkillsDescription: () => string;
+    getModelSkillListing: () => string;
+  };
+  // src/session/sessionActivity/sessionActivityService.ts
+  'sessionActivity.current': /* SessionActivityState — packages/agent-core-v2/src/session/sessionActivity/sessionActivity.ts */ {
+    readonly busy: boolean;
+    readonly mainTurnActive: boolean;
+    readonly pendingInteraction: /* SessionPendingInteraction — packages/agent-core-v2/src/session/sessionActivity/sessionActivity.ts */ 'none' | 'approval' | 'question';
+    readonly lastTurnReason?: 'completed' | 'cancelled' | 'failed';
+  };
+  'sessionActivity.folds': Map<string, /* AgentWorkFold — packages/agent-core-v2/src/session/sessionActivity/sessionActivityService.ts */ {
+    turnActive: boolean;
+    background: ReadonlySet<string>;
+    compacting: boolean;
+    lastTurnReason?: 'completed' | 'cancelled' | 'failed';
+  }>;
+  // src/session/sessionLog/sessionLogService.ts
+  'sessionLog.rootLevel': /* LogLevelState — packages/agent-core-v2/src/_base/log/logService.ts */ {
+    level: /* LogLevel — packages/agent-core-v2/src/_base/log/log.ts */ 'info' | 'off' | 'error' | 'warn' | 'debug';
+  };
+  // src/session/sessionMetadata/sessionMetadataService.ts
+  'sessionMetadata.data': /* SessionMeta — packages/agent-core-v2/src/session/sessionMetadata/sessionMetadata.ts */ {
+    readonly id: string;
+    readonly version?: number;
+    readonly title?: string;
+    readonly titleKind?: 'replaceable' | 'generated' | 'custom';
+    readonly lastPrompt?: string;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly archived: boolean;
+    readonly archivedAt?: number;
+    readonly cwd?: string;
+    readonly forkedFrom?: string;
+    readonly agents?: Readonly<Record<string, /* AgentMeta — packages/agent-core-v2/src/session/sessionMetadata/sessionMetadata.ts */ {
+      readonly homedir?: string;
+      readonly type?: 'main' | 'sub' | 'independent';
+      readonly parentAgentId?: string | null;
+      readonly forkedFrom?: string;
+      readonly labels?: Readonly<Record<string, string>>;
+      readonly swarmItem?: string;
+    }>>;
+    readonly custom?: Record<string, unknown>;
+    readonly lastTurnReason?: 'completed' | 'cancelled' | 'failed';
+  } | undefined;
+  // src/session/sessionToolPolicy/sessionToolPolicyService.ts
+  'sessionToolPolicy.state': /* SessionToolPolicyState — packages/agent-core-v2/src/session/sessionToolPolicy/sessionToolPolicyService.ts */ {
+    readonly disabledTools: readonly string[];
+  };
+  // src/session/workspaceContext/workspaceContextService.ts
+  'workspaceContext.additionalDirs': string[];
+  'workspaceContext.workDir': string;
+}
+
+export type SessionStateKey = keyof SessionStateSnapshot;
+
+/** Agent-scope keys registered into IAgentStateService. */
+export interface AgentStateSnapshot {
+  // src/agent/agentsMdReminder/agentsMdReminderService.ts
+  'agentsMdReminder.cwd': string | undefined;
+  'agentsMdReminder.known': Set<string>;
+  'agentsMdReminder.seeded': boolean;
+  // src/agent/contextMemory/contextOps.ts
+  // replayable · durable · undoable — folds: ContextAppendMessage, ContextAppendLoopEvent, ContextClear, ContextApplyCompaction
+  'contextMemory': (/* ContextMessage — packages/agent-core-v2/src/agent/contextMemory/types.ts */ /* Message — packages/agent-core-v2/src/llm-adapter/contract/message.ts */ {
+    readonly role: /* Role — packages/agent-core-v2/src/human/llm/message.ts */ 'user' | 'system' | 'assistant' | 'tool';
+    readonly name?: string;
+    readonly content: (/* ContentPart — packages/agent-core-v2/src/human/llm/message.ts */ /* TextPart — packages/agent-core-v2/src/human/llm/message.ts */ {
+      type: 'text';
+      text: string;
+    } | /* ThinkPart — packages/agent-core-v2/src/human/llm/message.ts */ {
+      type: 'think';
+      think: string;
+      encrypted?: string;
+      detailsIndex?: number;
+      hidden?: boolean;
+    } | /* ImageURLPart — packages/agent-core-v2/src/human/llm/message.ts */ {
+      type: 'image_url';
+      imageUrl: {
+        url: string;
+        id?: string;
+        name?: string;
+      };
+    } | /* AudioURLPart — packages/agent-core-v2/src/human/llm/message.ts */ {
+      type: 'audio_url';
+      audioUrl: {
+        url: string;
+        id?: string;
+      };
+    } | /* VideoURLPart — packages/agent-core-v2/src/human/llm/message.ts */ {
+      type: 'video_url';
+      videoUrl: {
+        url: string;
+        id?: string;
+        name?: string;
+      };
+    })[];
+    readonly toolCalls: /* ToolCall — packages/agent-core-v2/src/human/llm/message.ts */ {
+      type: 'function';
+      id: string;
+      name: string;
+      arguments: string | null;
+      extras?: Record<string, unknown>;
+      rawId?: string;
+      _streamIndex?: string | number;
+    }[];
+    readonly toolCallId?: string;
+    readonly partial?: boolean;
+    readonly tools?: readonly /* ToolDescription — packages/agent-core-v2/src/human/llm/message.ts */ {
+      name: string;
+      description: string;
+      parameters: Record<string, unknown>;
+      deferred?: true;
+    }[];
+  } & {
+    readonly id?: string;
+    readonly providerMessageId?: string;
+    readonly origin?: /* UserPromptOrigin — packages/agent-core-v2/src/agent/contextMemory/types.ts */ {
+      readonly kind: 'user';
+      readonly clientMetadata?: readonly Readonly<Record<string, unknown>>[];
+      readonly skillActivations?: readonly /* BundledSkillActivation — packages/agent-core-v2/src/agent/contextMemory/types.ts */ {
+        readonly activationId: string;
+        readonly skillName: string;
+        readonly skillArgs?: string;
+        readonly skillType?: string;
+        readonly skillPath?: string;
+        readonly skillSource?: 'project' | 'user' | 'extra' | 'builtin';
+      }[];
+      readonly attachments?: readonly /* PromptFileAttachment — packages/agent-core-v2/src/agent/contextMemory/types.ts */ {
+        readonly name: string;
+        readonly mediaType: string;
+        readonly size: number;
+        readonly path: string;
+      }[];
+    } | /* SkillActivationOrigin — packages/agent-core-v2/src/agent/contextMemory/types.ts */ {
+      readonly kind: 'skill_activation';
+      readonly clientMetadata?: readonly Readonly<Record<string, unknown>>[];
+      readonly activationId: string;
+      readonly skillName: string;
+      readonly skillArgs?: string;
+      readonly trigger: 'user-slash' | 'model-tool' | 'nested-skill';
+      readonly skillType?: string;
+      readonly skillPath?: string;
+      readonly skillSource?: 'project' | 'user' | 'extra' | 'builtin';
+      readonly attachments?: readonly /* PromptFileAttachment — packages/agent-core-v2/src/agent/contextMemory/types.ts */ {
+        readonly name: string;
+        readonly mediaType: string;
+        readonly size: number;
+        readonly path: string;
+      }[];
+    } | /* PluginCommandOrigin — packages/agent-core-v2/src/agent/contextMemory/types.ts */ {
+      readonly kind: 'plugin_command';
+      readonly activationId: string;
+      readonly pluginId: string;
+      readonly commandName: string;
+      readonly commandArgs?: string;
+      readonly trigger: 'user-slash';
+    } | /* InjectionOrigin — packages/agent-core-v2/src/agent/contextMemory/types.ts */ {
+      readonly kind: 'injection';
+      readonly variant: string;
+      readonly ownerPromptId?: string;
+      readonly disclosure?: unknown;
+    } | /* ShellCommandOrigin — packages/agent-core-v2/src/agent/contextMemory/types.ts */ {
+      readonly kind: 'shell_command';
+      readonly phase: 'input' | 'output';
+      readonly isError?: boolean;
+    } | /* CompactionSummaryOrigin — packages/agent-core-v2/src/agent/contextMemory/types.ts */ {
+      readonly kind: 'compaction_summary';
+    } | /* SystemTriggerOrigin — packages/agent-core-v2/src/agent/contextMemory/types.ts */ {
+      readonly kind: 'system_trigger';
+      readonly name: string;
+    } | /* TaskOrigin — packages/agent-core-v2/src/agent/contextMemory/types.ts */ {
+      readonly kind: 'task';
+      readonly taskId: string;
+      readonly status: /* AgentTaskStatus — packages/agent-core-v2/src/agent/task/types.ts */ 'completed' | 'failed' | 'running' | 'timed_out' | 'killed' | 'lost';
+      readonly notificationId: string;
+    } | /* CronJobOrigin — packages/agent-core-v2/src/agent/contextMemory/types.ts */ {
+      readonly kind: 'cron_job';
+      readonly jobId: string;
+      readonly cron: string;
+      readonly recurring: boolean;
+      readonly coalescedCount: number;
+      readonly stale: boolean;
+    } | /* CronMissedOrigin — packages/agent-core-v2/src/agent/contextMemory/types.ts */ {
+      readonly kind: 'cron_missed';
+      readonly count: number;
+    } | /* HookResultOrigin — packages/agent-core-v2/src/agent/contextMemory/types.ts */ {
+      readonly kind: 'hook_result';
+      readonly event: string;
+      readonly blocked?: boolean;
+    } | /* RetryOrigin — packages/agent-core-v2/src/agent/contextMemory/types.ts */ {
+      readonly kind: 'retry';
+      readonly trigger?: string;
+    };
+    readonly isError?: boolean;
+    toolCallDisplays?: Record<string, /* ToolInputDisplay — packages/agent-core-v2/src/tool/toolInputDisplay.ts */ {
+      kind: 'command';
+      command: string;
+      cwd?: string;
+      description?: string;
+      language?: 'bash';
+    } | {
+      kind: 'file_io';
+      operation: 'read' | 'write' | 'edit' | 'glob' | 'grep';
+      path: string;
+      detail?: string;
+      content?: string;
+      before?: string;
+      after?: string;
+    } | {
+      kind: 'diff';
+      path: string;
+      before: string;
+      after: string;
+      hunks?: number;
+    } | {
+      kind: 'search';
+      query: string;
+      scope?: string;
+    } | {
+      kind: 'url_fetch';
+      url: string;
+      method?: string;
+    } | {
+      kind: 'agent_call';
+      agent_name: string;
+      prompt: string;
+      background?: boolean;
+    } | {
+      kind: 'skill_call';
+      skill_name: string;
+      args?: string;
+    } | {
+      kind: 'todo_list';
+      items: {
+        title: string;
+        status: string;
+      }[];
+    } | {
+      kind: 'task';
+      task_id: string;
+      status: string;
+      description: string;
+      task_kind?: string;
+    } | {
+      kind: 'task_stop';
+      task_id: string;
+      task_description: string;
+    } | {
+      kind: 'plan_review';
+      plan: string;
+      path?: string;
+      options?: readonly {
+        label: string;
+        description: string;
+      }[];
+    } | {
+      kind: 'goal_start';
+      objective: string;
+      completionCriterion?: string;
+      mode: 'manual' | 'yolo';
+    } | {
+      kind: 'generic';
+      summary: string;
+      detail?: unknown;
+    }>;
+    readonly note?: string;
+  })[];
+  // src/agent/contextProjector/contextProjectorService.ts
+  'contextProjector.lastRepairSignature': string | null;
+  // src/agent/fullCompaction/compactionOps.ts
+  // replayable · durable — folds: FullCompactionBegin, FullCompactionCancel, FullCompactionComplete
+  'fullCompaction': /* CompactionState — packages/agent-core-v2/src/agent/fullCompaction/compactionOps.ts */ {
+    readonly phase: /* CompactionPhase — packages/agent-core-v2/src/agent/fullCompaction/compactionOps.ts */ 'completed' | 'cancelled' | 'running' | 'idle';
+  };
+  // replayable · durable — folds: ContextApplyCompaction, ContextClear
+  'fullCompaction.wireRanges': readonly /* WireLineRange — packages/agent-core-v2/src/wire/record.ts */ {
+    readonly start: number;
+    readonly end: number;
+  }[];
+  // src/agent/fullCompaction/fullCompactionService.ts
+  'fullCompaction.activeTurnId': number | undefined;
+  'fullCompaction.compactionCountInTurn': number;
+  'fullCompaction.consecutiveOverflowCompactions': number;
+  'fullCompaction.lastCompactedTokenCount': number | null;
+  'fullCompaction.observedMaxContextTokensByModel': Map<string, number>;
+  // src/agent/interruptionReminder/interruptionReminderOps.ts
+  // replayable · durable — folds: InterruptionReminderRecorded
+  'interruptionReminder': null;
+  // src/agent/llmRequester/llmRequestOps.ts
+  // replayable · durable — folds: LlmToolsSnapshot, LlmRequest
+  'llm.requestTrace': /* LlmRequestTraceState — packages/agent-core-v2/src/agent/llmRequester/llmRequestOps.ts */ {
+    readonly seenToolsHashes: readonly string[];
+  };
+  // src/agent/llmRequester/llmRequesterService.ts
+  'llmRequester.emittedThinkingEffortWarnings': Set<string>;
+  'llmRequester.lastConfigLogSignature': string | undefined;
+  'llmRequester.mediaDegradedTurns': Set<number>;
+  'llmRequester.mediaStrippedTurns': Map<number, /* MediaStripSnapshot — packages/agent-core-v2/src/agent/contextProjector/contextProjector.ts */ {
+    readonly "__@mediaStripSnapshotBrand": undefined;
+  }>;
+  'llmRequester.turnConfigs': Map<number, /* TurnRequestConfig — packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts */ {
+    readonly resolved: /* ProfileModelContext — packages/agent-core-v2/src/agent/profile/profile.ts */ {
+      readonly modelAlias: string;
+      readonly modelCapabilities: /* ModelCapability — packages/agent-core-v2/src/llm-adapter/contract/capability.ts */ {
+        readonly image_in: boolean;
+        readonly video_in: boolean;
+        readonly audio_in: boolean;
+        readonly thinking: boolean;
+        readonly tool_use: boolean;
+        readonly max_context_tokens: number;
+        readonly max_input_tokens?: number;
+        readonly dynamically_loaded_tools?: boolean;
+      };
+      readonly maxOutputSize: number | undefined;
+      readonly alwaysThinking: boolean | undefined;
+      readonly thinkingLevel: /* ThinkingEffort — packages/agent-core-v2/src/human/llm/thinking.ts */ 'off' | 'on' | (string & {});
+      readonly reservedContextSize: number | undefined;
+      readonly compactionTriggerRatio: number | undefined;
+      readonly compactionMaxAttempts: number | undefined;
+    };
+    readonly params: /* ModelRequestParams — packages/agent-core-v2/src/llm-adapter/model/model-requester.ts */ {
+      readonly cacheKey?: string;
+      readonly sampling?: /* SamplingOptions — packages/agent-core-v2/src/llm-adapter/model/model-requester.ts */ {
+        readonly temperature?: number;
+        readonly topP?: number;
+      };
+      readonly thinkingEffort?: 'off' | 'on' | (string & {});
+      readonly thinkingKeep?: string;
+      readonly maxCompletionTokens?: number;
+      readonly usedContextTokens?: number;
+      readonly maxContextTokens?: number;
+      readonly onTraceId?: (traceId: string | null) => void;
+    };
+    readonly systemPrompt: string;
+  }>;
+  // src/agent/loop/loopService.ts
+  'loop.disposing': boolean;
+  'loop.lastRequestTraceId': string | undefined;
+  // src/agent/loop/turnOps.ts
+  // replayable · durable — folds: ContextAppendLoopEvent, TurnPrompt, TurnSteer, ContextUndo, ContextApplyCompaction, ContextClear, TurnCancel, TurnEnded
+  'turn': /* TurnModelState — packages/agent-core-v2/src/agent/loop/turnOps.ts */ {
+    readonly nextTurnId: number;
+    readonly cancelledTurnIds: readonly number[];
+    readonly anchorTurnIds: readonly number[];
+    readonly lastEnded?: {
+      readonly turnId: number;
+      readonly reason: 'completed' | 'cancelled' | 'failed' | 'blocked';
+      readonly durationMs?: number;
+    };
+  };
+  // src/agent/mcp/mcpDiscoveryOps.ts
+  // replayable · durable — folds: McpToolsDiscovered
+  'mcp.discovery': /* McpDiscoveryState — packages/agent-core-v2/src/agent/mcp/mcpDiscoveryOps.ts */ {
+    readonly seen: readonly string[];
+  };
+  // src/agent/mcp/mcpService.ts
+  'mcp.discoveryWritesReady': boolean;
+  'mcp.mcpToolsByServer': Map<string, string[]>;
+  // src/agent/media/mediaResolverService.ts
+  'media.budgetDropped': Set<string>;
+  'media.resolved': Map<string, /* ContentPart — packages/agent-core-v2/src/human/llm/message.ts */ /* TextPart — packages/agent-core-v2/src/human/llm/message.ts */ {
+    type: 'text';
+    text: string;
+  } | /* ThinkPart — packages/agent-core-v2/src/human/llm/message.ts */ {
+    type: 'think';
+    think: string;
+    encrypted?: string;
+    detailsIndex?: number;
+    hidden?: boolean;
+  } | /* ImageURLPart — packages/agent-core-v2/src/human/llm/message.ts */ {
+    type: 'image_url';
+    imageUrl: {
+      url: string;
+      id?: string;
+      name?: string;
+    };
+  } | /* AudioURLPart — packages/agent-core-v2/src/human/llm/message.ts */ {
+    type: 'audio_url';
+    audioUrl: {
+      url: string;
+      id?: string;
+    };
+  } | /* VideoURLPart — packages/agent-core-v2/src/human/llm/message.ts */ {
+    type: 'video_url';
+    videoUrl: {
+      url: string;
+      id?: string;
+      name?: string;
+    };
+  }>;
+  // src/agent/media/mediaToolsRegistrar.ts
+  'media.registeredKey': string | undefined;
+  // src/agent/permissionMode/injection/permissionModeInjection.ts
+  'permissionMode.lastMode': 'manual' | 'yolo' | 'auto' | undefined;
+  // src/agent/permissionMode/permissionModeOps.ts
+  // replayable · durable — folds: PermissionSetMode
+  'permissionMode': /* PermissionMode — packages/agent-core-v2/src/agent/permissionPolicy/types.ts */ 'manual' | 'yolo' | 'auto';
+  // replayable · durable — folds: PermissionSetMode
+  'permissionMode.configured': boolean;
+  // src/agent/permissionRules/permissionRulesOps.ts
+  // replayable · durable — folds: PermissionRulesAdd, PermissionRecordApprovalResult
+  'permissionRules': /* PermissionRulesModelState — packages/agent-core-v2/src/agent/permissionRules/permissionRulesOps.ts */ {
+    readonly rules: readonly /* PermissionRule — packages/agent-core-v2/src/agent/permissionRules/permissionRules.ts */ {
+      readonly decision: /* PermissionRuleDecision — packages/agent-core-v2/src/agent/permissionRules/permissionRules.ts */ 'allow' | 'deny' | 'ask';
+      readonly scope: /* PermissionRuleScope — packages/agent-core-v2/src/agent/permissionRules/permissionRules.ts */ 'project' | 'user' | 'turn-override' | 'session-runtime';
+      readonly pattern: string;
+      readonly reason?: string;
+    }[];
+    readonly sessionApprovalRulePatterns: readonly string[];
+  };
+  // src/agent/plugin/agentPluginOps.ts
+  // replayable · durable — folds: PluginSessionStartEvent
+  'pluginSessionStartSnapshot': /* PluginSessionStartSnapshotState — packages/agent-core-v2/src/agent/plugin/agentPluginOps.ts */ {
+    readonly initialized: boolean;
+    readonly content?: string;
+  };
+  // src/agent/plugin/agentPluginService.ts
+  'agentPlugin.sessionStartRefreshPending': boolean;
+  // src/agent/profile/profileOps.ts
+  // replayable · durable — folds: ProfileBind, ConfigUpdate
+  'profile': /* ProfileModelState — packages/agent-core-v2/src/agent/profile/profileOps.ts */ {
+    readonly modelAlias?: string;
+    readonly profileName?: string;
+    readonly thinkingLevel: string;
+    readonly systemPrompt: string;
+    readonly environmentDisclosure?: /* EnvironmentDisclosureSnapshot — packages/agent-core-v2/src/app/agentProfileCatalog/agentProfileCatalog.ts */ {
+      readonly cwd: string;
+    };
+    readonly renderGeneration: number;
+    readonly agentsMdPaths?: readonly string[];
+    readonly disallowedTools?: readonly string[];
+    readonly subagents?: readonly string[];
+  };
+  // replayable · durable — folds: ToolsSetActiveTools, ToolsResetActiveTools, ProfileBind
+  'profile.activeTools': /* ActiveToolsState — packages/agent-core-v2/src/agent/profile/profileOps.ts */ readonly string[] | undefined;
+  // src/agent/profile/profileService.ts
+  'profile.activeToolNamesOverlay': readonly string[] | undefined;
+  'profile.agentsMdWarning': string | undefined;
+  'profile.emittedPluginBudgetWarnings': Set<string>;
+  'profile.emittedThinkingEffortWarnings': Set<string>;
+  'profile.emittedToolPatternWarnings': Set<string>;
+  // src/agent/runtimeBinding/runtimeBindingOps.ts
+  // replayable · durable — folds: RuntimeSetBinding
+  'runtimeBinding': /* RuntimeBinding — packages/agent-core-v2/src/runtime/runtime.ts */ {
+    readonly workspaceId: string;
+    readonly runtimeId: string;
+  } | undefined;
+  // src/agent/runtimeBinding/runtimeBindingService.ts
+  'runtime.binding': /* RuntimeBinding — packages/agent-core-v2/src/runtime/runtime.ts */ {
+    readonly workspaceId: string;
+    readonly runtimeId: string;
+  };
+  // src/agent/shellCommand/shellCommandService.ts
+  'shellCommand.tasks': Map<string, string>;
+  // src/agent/task/taskOps.ts
+  // replayable · durable — folds: TaskStarted, TaskTerminated
+  'task': /* TaskModelState — packages/agent-core-v2/src/agent/task/taskOps.ts */ Map<string, /* AgentTaskInfo — packages/agent-core-v2/src/agent/task/types.ts */ /* QuestionTaskInfo — packages/agent-core-v2/src/agent/tools/ask-user-question/question-background-task.ts */ {
+    readonly kind: 'question';
+    readonly questionCount: number;
+    readonly toolCallId?: string;
+    readonly taskId: string;
+    readonly description: string;
+    readonly status: /* AgentTaskStatus — packages/agent-core-v2/src/agent/task/types.ts */ 'completed' | 'failed' | 'running' | 'timed_out' | 'killed' | 'lost';
+    readonly detached?: boolean;
+    readonly startedAt: number;
+    readonly endedAt: number | null;
+    readonly stopReason?: string;
+    readonly terminalNotificationSuppressed?: boolean;
+    readonly resumeReminded?: boolean;
+    readonly timeoutMs?: number;
+  } | /* SubagentTaskInfo — packages/agent-core-v2/src/agent/tools/agent/subagent-task.ts */ {
+    readonly kind: 'agent';
+    readonly agentId?: string;
+    readonly subagentType?: string;
+    readonly parentToolCallId?: string;
+    readonly model?: string;
+    readonly thinkingEffort?: string;
+    readonly stopCode?: string;
+    readonly taskId: string;
+    readonly description: string;
+    readonly status: /* AgentTaskStatus — packages/agent-core-v2/src/agent/task/types.ts */ 'completed' | 'failed' | 'running' | 'timed_out' | 'killed' | 'lost';
+    readonly detached?: boolean;
+    readonly startedAt: number;
+    readonly endedAt: number | null;
+    readonly stopReason?: string;
+    readonly terminalNotificationSuppressed?: boolean;
+    readonly resumeReminded?: boolean;
+    readonly timeoutMs?: number;
+  } | /* ProcessTaskInfo — packages/agent-core-v2/src/agent/tools/os/bash/process-task.ts */ {
+    readonly kind: 'process';
+    readonly command: string;
+    readonly pid: number;
+    readonly exitCode: number | null;
+    readonly parentToolCallId?: string;
+    readonly taskId: string;
+    readonly description: string;
+    readonly status: /* AgentTaskStatus — packages/agent-core-v2/src/agent/task/types.ts */ 'completed' | 'failed' | 'running' | 'timed_out' | 'killed' | 'lost';
+    readonly detached?: boolean;
+    readonly startedAt: number;
+    readonly endedAt: number | null;
+    readonly stopReason?: string;
+    readonly terminalNotificationSuppressed?: boolean;
+    readonly resumeReminded?: boolean;
+    readonly timeoutMs?: number;
+  }>;
+  // src/agent/task/taskService.ts
+  'task.activeTaskReminderPending': boolean;
+  'task.deliveredNotificationKeys': Set<string>;
+  'task.ghosts': Map<string, /* AgentTaskInfo — packages/agent-core-v2/src/agent/task/types.ts */ /* QuestionTaskInfo — packages/agent-core-v2/src/agent/tools/ask-user-question/question-background-task.ts */ {
+    readonly kind: 'question';
+    readonly questionCount: number;
+    readonly toolCallId?: string;
+    readonly taskId: string;
+    readonly description: string;
+    readonly status: /* AgentTaskStatus — packages/agent-core-v2/src/agent/task/types.ts */ 'completed' | 'failed' | 'running' | 'timed_out' | 'killed' | 'lost';
+    readonly detached?: boolean;
+    readonly startedAt: number;
+    readonly endedAt: number | null;
+    readonly stopReason?: string;
+    readonly terminalNotificationSuppressed?: boolean;
+    readonly resumeReminded?: boolean;
+    readonly timeoutMs?: number;
+  } | /* SubagentTaskInfo — packages/agent-core-v2/src/agent/tools/agent/subagent-task.ts */ {
+    readonly kind: 'agent';
+    readonly agentId?: string;
+    readonly subagentType?: string;
+    readonly parentToolCallId?: string;
+    readonly model?: string;
+    readonly thinkingEffort?: string;
+    readonly stopCode?: string;
+    readonly taskId: string;
+    readonly description: string;
+    readonly status: /* AgentTaskStatus — packages/agent-core-v2/src/agent/task/types.ts */ 'completed' | 'failed' | 'running' | 'timed_out' | 'killed' | 'lost';
+    readonly detached?: boolean;
+    readonly startedAt: number;
+    readonly endedAt: number | null;
+    readonly stopReason?: string;
+    readonly terminalNotificationSuppressed?: boolean;
+    readonly resumeReminded?: boolean;
+    readonly timeoutMs?: number;
+  } | /* ProcessTaskInfo — packages/agent-core-v2/src/agent/tools/os/bash/process-task.ts */ {
+    readonly kind: 'process';
+    readonly command: string;
+    readonly pid: number;
+    readonly exitCode: number | null;
+    readonly parentToolCallId?: string;
+    readonly taskId: string;
+    readonly description: string;
+    readonly status: /* AgentTaskStatus — packages/agent-core-v2/src/agent/task/types.ts */ 'completed' | 'failed' | 'running' | 'timed_out' | 'killed' | 'lost';
+    readonly detached?: boolean;
+    readonly startedAt: number;
+    readonly endedAt: number | null;
+    readonly stopReason?: string;
+    readonly terminalNotificationSuppressed?: boolean;
+    readonly resumeReminded?: boolean;
+    readonly timeoutMs?: number;
+  }>;
+  // replayable · durable · undoable — folds: ContextAppendMessage, TaskWaitDelivered
+  'task.notificationDelivery': readonly string[];
+  'task.scheduledNotificationKeys': Set<string>;
+  // src/agent/toolDedupe/toolDedupeService.ts
+  'toolDedupe.activeStep': number;
+  'toolDedupe.activeTurnId': number | undefined;
+  'toolDedupe.callKeyByCallId': Map<string, string>;
+  'toolDedupe.consecutiveCount': number;
+  'toolDedupe.consecutiveKey': string | null;
+  'toolDedupe.handoffPhase': /* HandoffPhase — packages/agent-core-v2/src/agent/toolDedupe/toolDedupeService.ts */ 'idle' | 'active' | 'pending' | 'done';
+  'toolDedupe.originalCallIndex': Map<string, number>;
+  'toolDedupe.stepCalls': string[];
+  'toolDedupe.syntheticCallIds': Set<string>;
+  'toolDedupe.turnCallRecords': Map<string, /* TurnCallRecord — packages/agent-core-v2/src/agent/toolDedupe/toolDedupeService.ts */ {
+    count: number;
+    lastStep: number;
+  }>;
+  'toolDedupe.turnRepeatCount': number;
+  // src/agent/toolExecutor/toolExecutorService.ts
+  'toolExecutor.dupTypeTurnId': number | undefined;
+  'toolExecutor.toolCallDupTypes': Map<string, /* ToolCallDupType — packages/agent-core-v2/src/agent/toolExecutor/toolExecutor.ts */ 'same_step' | 'cross_step'>;
+  // src/agent/toolSelect/toolSelectService.ts
+  'toolSelect.pendingLoaded': Set<string>;
+  // src/agent/userTool/userToolOps.ts
+  // replayable · durable — folds: ToolsRegisterUserTool, ToolsUnregisterUserTool
+  'userTool': /* UserToolModelState — packages/agent-core-v2/src/agent/userTool/userToolOps.ts */ Map<string, /* UserToolRegistration — packages/agent-core-v2/src/agent/userTool/userTool.ts */ {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+    readonly disclosure?: 'deferred' | 'inline';
+  }>;
+  // src/features/externalHooks/agent/agentExternalHooksService.ts
+  'externalHooks.stopHookContinuationUsed': boolean;
+  // src/features/fileHistory/fileHistoryOps.ts
+  // replayable · durable — folds: FileHistoryCheckpointed, FileHistoryTracked
+  'fileHistory': /* FileHistoryState — packages/agent-core-v2/src/features/fileHistory/fileHistory.ts */ {
+    readonly checkpoints: readonly /* FileHistoryCheckpointRecord — packages/agent-core-v2/src/features/fileHistory/fileHistory.ts */ {
+      readonly turnId: number;
+      readonly phase?: 'start' | 'end';
+      readonly entries: Readonly<Record<string, /* FileBackupEntry — packages/agent-core-v2/src/features/fileHistory/fileHistory.ts */ {
+        readonly key: string | null;
+        readonly version: number;
+        readonly contentHash?: string;
+        readonly size?: number;
+        readonly oversize?: boolean;
+        readonly mtimeMs?: number;
+      }>>;
+    }[];
+    readonly tracked: readonly string[];
+  };
+  // src/features/plan/injection/planModeInjection.ts
+  'plan.wasActive': boolean;
+  // src/features/plan/planOps.ts
+  // replayable · durable · undoable — folds: PlanModeEnter, PlanModeCancel, PlanModeExit, PlanRevision
+  'plan': /* PlanState — packages/agent-core-v2/src/features/plan/planOps.ts */ {
+    readonly active: boolean;
+    readonly id?: string;
+    readonly revisionCount?: Readonly<Record<string, number>>;
+  };
+  // src/features/swarm/swarmOps.ts
+  // replayable · durable — folds: SwarmModeEnter, SwarmModeExit
+  'swarm': 'tool' | 'task' | 'manual' | null;
+  // src/features/tower/towerOps.ts
+  // replayable · durable — folds: TowerModeEnter, TowerModeExit
+  'tower': boolean;
+  // replayable · durable — folds: TowerModeEnter, TowerModeExit
+  'tower.base': string | null;
+  // replayable · durable — folds: TowerModeEnter, TowerModeExit
+  'tower.owner': string | undefined;
+}
+
+export type AgentStateKey = keyof AgentStateSnapshot;

packages/agent-core-v2/docs/wire-manifest.d.ts

@@ -0,0 +1,946 @@
+// Wire Protocol Manifest
+//
+// Generated by scripts/gen-wire-manifest.mts — do not edit by hand.
+// Regenerate with: pnpm --filter @moonshot-ai/agent-core-v2 gen:wire-manifest
+//
+// protocol_version: "1.5" (migrations: 1.0 -> 1.1 -> 1.2 -> 1.3 -> 1.4 -> 1.5)
+//
+// One declaration per durable record type — an Event2 subclass declaring
+// `static type` + `static durable = true` + `static schema` — drained from the
+// runtime EVENT2_REGISTRY ("import = register"). Every payload declaration
+// carries its record type in a `_name` field. Payload sketches use TypeScript
+// type syntax; when a named type is expanded inline, its name appears as a doc
+// comment (`/** ContextMessage */`). Bare type names (ContentPart,
+// ContextMessage, …) refer to the real types in src/ — they are intentionally
+// not resolved here. `// …` marks a capped field list. On disk (wire.jsonl)
+// the journal opens with a metadata line {"type": "metadata",
+// "protocol_version", "created_at"}; each record is {"type", ...payload,
+// "time"} — object payloads spread at the top level.
+//
+// Every listed type is durable by construction — transient Event2 classes
+// never enter EVENT2_REGISTRY, so there is no persisted flag. Declaration
+// header lines: states (every state folding this record type on dispatch and
+// replay; any state beyond the first is what the retired format listed as
+// cross-reducers), blobs (the folding states whose blob codec offloads inline
+// media to blob storage), owner (the source file declaring the class).
+
+// Index (59 record types)
+//   config.update                      profile                                               src/agent/profile/profileOps.ts
+//   context.append_loop_event          contextMemory, turn                                   src/agent/contextMemory/contextEvents.ts
+//   context.append_message             contextMemory, plan, task.notificationDelivery        src/agent/contextMemory/contextEvents.ts
+//   context.apply_compaction           contextMemory, plan, task.notificationDelivery, turn  src/agent/contextMemory/contextEvents.ts
+//   context.clear                      contextMemory, plan, task.notificationDelivery, turn  src/agent/contextMemory/contextEvents.ts
+//   context.undo                       contextMemory, plan, task.notificationDelivery, turn  src/agent/contextMemory/contextEvents.ts
+//   cron.add                           (none)                                                src/features/cron/cronOps.ts
+//   cron.cursor                        (none)                                                src/features/cron/cronOps.ts
+//   cron.delete                        (none)                                                src/features/cron/cronOps.ts
+//   file_history.checkpoint            fileHistory                                           src/features/fileHistory/fileHistoryOps.ts
+//   file_history.tracked               fileHistory                                           src/features/fileHistory/fileHistoryOps.ts
+//   forked                             (none)                                                src/features/goal/goalOps.ts
+//   full_compaction.begin              fullCompaction                                        src/agent/fullCompaction/compactionOps.ts
+//   full_compaction.cancel             fullCompaction                                        src/agent/fullCompaction/compactionOps.ts
+//   full_compaction.complete           fullCompaction                                        src/agent/fullCompaction/compactionOps.ts
+//   goal.clear                         (none)                                                src/features/goal/goalOps.ts
+//   goal.create                        (none)                                                src/features/goal/goalOps.ts
+//   goal.update                        (none)                                                src/features/goal/goalOps.ts
+//   interaction.request                (none)                                                src/agent/interaction/interactionOps.ts
+//   interaction.resolved               (none)                                                src/agent/interaction/interactionOps.ts
+//   interruptionReminder.recorded      interruptionReminder                                  src/agent/interruptionReminder/interruptionReminderOps.ts
+//   llm.request                        llm.requestTrace                                      src/agent/llmRequester/llmRequestOps.ts
+//   llm.tools_snapshot                 llm.requestTrace                                      src/agent/llmRequester/llmRequestOps.ts
+//   mcp.tools_discovered               mcp.discovery                                         src/agent/mcp/mcpDiscoveryOps.ts
+//   permission.record_approval_result  permissionRules                                       src/agent/permissionRules/permissionRulesOps.ts
+//   permission.set_mode                permissionMode, permissionMode.configured             src/agent/permissionMode/permissionModeOps.ts
+//   plan_mode.cancel                   plan                                                  src/features/plan/planOps.ts
+//   plan_mode.enter                    plan                                                  src/features/plan/planOps.ts
+//   plan_mode.exit                     plan                                                  src/features/plan/planOps.ts
+//   plan.revision                      plan                                                  src/features/plan/planOps.ts
+//   plugin.session_start               pluginSessionStartSnapshot                            src/agent/plugin/agentPluginOps.ts
+//   profile.bind                       profile, profile.activeTools                          src/agent/profile/profileOps.ts
+//   prompt.aborted                     (none)                                                src/agent/prompt/promptEvents.ts
+//   prompt.completed                   (none)                                                src/agent/prompt/promptEvents.ts
+//   prompt.steered                     (none)                                                src/agent/prompt/promptEvents.ts
+//   runtime.set_binding                runtimeBinding                                        src/agent/runtimeBinding/runtimeBindingOps.ts
+//   swarm_mode.enter                   swarm                                                 src/features/swarm/swarmOps.ts
+//   swarm_mode.exit                    contextMemory, swarm                                  src/features/swarm/swarmOps.ts
+//   task.started                       task                                                  src/agent/task/taskOps.ts
+//   task.terminated                    task                                                  src/agent/task/taskOps.ts
+//   task.waitDelivered                 task.notificationDelivery                             src/agent/task/taskOps.ts
+//   token_counting.measured            (none)                                                src/agent/tokenCounting/tokenCountingOps.ts
+//   token_counting.rebased             (none)                                                src/agent/tokenCounting/tokenCountingOps.ts
+//   token_counting.truncated           (none)                                                src/agent/tokenCounting/tokenCountingOps.ts
+//   token_counting.turn_recorded       (none)                                                src/agent/tokenCounting/tokenCountingOps.ts
+//   tools.register_user_tool           userTool                                              src/agent/userTool/userToolOps.ts
+//   tools.reset_active_tools           profile.activeTools                                   src/agent/profile/profileOps.ts
+//   tools.set_active_tools             profile.activeTools                                   src/agent/profile/profileOps.ts
+//   tools.unregister_user_tool         userTool                                              src/agent/userTool/userToolOps.ts
+//   tools.update_store                 (none)                                                src/features/todo/todoOps.ts
+//   tower_mode.enter                   tower, tower.base, tower.owner                        src/features/tower/towerOps.ts
+//   tower_mode.exit                    tower, tower.base, tower.owner                        src/features/tower/towerOps.ts
+//   turn.cancel                        turn                                                  src/agent/loop/turnOps.ts
+//   turn.ended                         turn                                                  src/agent/loop/turnOps.ts
+//   turn.prompt                        turn                                                  src/agent/loop/turnOps.ts
+//   turn.steer                         turn                                                  src/agent/loop/turnOps.ts
+//   turn.step.interrupted              (none)                                                src/agent/loop/turnEvents.ts
+//   turn.step.retrying                 (none)                                                src/agent/loop/turnEvents.ts
+//   usage.record                       (none)                                                src/agent/usage/usageOps.ts
+
+/**
+ * states: profile
+ * owner: src/agent/profile/profileOps.ts
+ */
+interface ConfigUpdatePayload {
+  _name: 'config.update';
+  agentId: string;
+  modelAlias?: string;
+  profileName?: string;
+  thinkingEffort?: ThinkingEffort;
+  thinkingLevel?: ThinkingEffort;
+  systemPrompt?: string;
+  /** EnvironmentDisclosureSnapshot */
+  environmentDisclosure?: {
+    cwd: string;
+  };
+  renderGeneration?: number;
+  agentsMdPaths?: string[];
+  disallowedTools?: string[];
+}
+
+/**
+ * states: contextMemory, turn · blobs: contextMemory
+ * owner: src/agent/contextMemory/contextEvents.ts
+ */
+interface ContextAppendLoopEventPayload {
+  _name: 'context.append_loop_event';
+  agentId: string;
+  /** LoopRecordedEvent */
+  event: 'step.begin' | 'step.end' | 'content.part' | 'tool.call' | 'tool.result';
+}
+
+/**
+ * states: contextMemory, plan, task.notificationDelivery · blobs: contextMemory
+ * owner: src/agent/contextMemory/contextEvents.ts
+ */
+interface ContextAppendMessagePayload {
+  _name: 'context.append_message';
+  agentId: string;
+  /** ContextMessage */
+  message: {
+    role: Role;
+    name?: string;
+    content: ContentPart[];
+    toolCalls: ToolCall[];
+    toolCallId?: string;
+    partial?: boolean;
+    tools?: ToolDescription[];
+    id?: string;
+    providerMessageId?: string;
+    origin?: 'user' | 'skill_activation' | 'plugin_command' | 'injection' | 'shell_command' | 'compaction_summary' | 'system_trigger' | 'task' | 'cron_job' | 'cron_missed' | 'hook_result' | 'retry' | undefined;
+    isError?: boolean;
+    toolCallDisplays?: Record<string, ToolInputDisplay>;
+    note?: string;
+  };
+}
+
+/**
+ * states: contextMemory, plan, task.notificationDelivery, turn · blobs: contextMemory
+ * owner: src/agent/contextMemory/contextEvents.ts
+ * shared base: ...contextCompactionBaseShape
+ */
+type ContextApplyCompactionPayload = { _name: 'context.apply_compaction'; } & ({ summary: string, compactedCount: number, contextSummary?: string } | { contextSummary: string, compactedCount: number, summary?: string } | { summary: ContextMessage, count: number, compactedCount?: number });
+
+/**
+ * states: contextMemory, plan, task.notificationDelivery, turn · blobs: contextMemory
+ * owner: src/agent/contextMemory/contextEvents.ts
+ */
+interface ContextClearPayload {
+  _name: 'context.clear';
+  agentId: string;
+}
+
+/**
+ * states: contextMemory, plan, task.notificationDelivery, turn · blobs: contextMemory
+ * owner: src/agent/contextMemory/contextEvents.ts
+ */
+interface ContextUndoPayload {
+  _name: 'context.undo';
+  agentId: string;
+  count: number;
+}
+
+/**
+ * states: (none)
+ * owner: src/features/cron/cronOps.ts
+ */
+interface CronAddPayload {
+  _name: 'cron.add';
+  task: {
+    id: string;
+    cron: string;
+    prompt: string;
+    createdAt: number;
+    recurring?: boolean;
+    lastFiredAt?: number;
+    tags?: Record<string, string>;
+  };
+}
+
+/**
+ * states: (none)
+ * owner: src/features/cron/cronOps.ts
+ */
+interface CronCursorPayload {
+  _name: 'cron.cursor';
+  id: string;
+  lastFiredAt: number;
+}
+
+/**
+ * states: (none)
+ * owner: src/features/cron/cronOps.ts
+ */
+interface CronDeletePayload {
+  _name: 'cron.delete';
+  ids: string[];
+}
+
+/**
+ * states: fileHistory
+ * owner: src/features/fileHistory/fileHistoryOps.ts
+ */
+interface FileHistoryCheckpointPayload {
+  _name: 'file_history.checkpoint';
+  agentId: string;
+  turnId: number;
+  phase?: 'start' | 'end';
+  entries: Record<string, object>;
+}
+
+/**
+ * states: fileHistory
+ * owner: src/features/fileHistory/fileHistoryOps.ts
+ */
+interface FileHistoryTrackedPayload {
+  _name: 'file_history.tracked';
+  agentId: string;
+  turnId: number;
+  path: string;
+  entry: {
+    key: string | null;
+    version: number;
+    contentHash?: string;
+    size?: number;
+    oversize?: boolean;
+    mtimeMs?: number;
+  };
+}
+
+/**
+ * states: (none)
+ * owner: src/features/goal/goalOps.ts
+ */
+interface ForkedPayload {
+  _name: 'forked';
+  agentId: string;
+}
+
+/**
+ * states: fullCompaction
+ * owner: src/agent/fullCompaction/compactionOps.ts
+ */
+interface FullCompactionBeginPayload {
+  _name: 'full_compaction.begin';
+  agentId: string;
+  instruction?: string;
+  /** CompactionSource */
+  source: 'manual' | 'auto';
+}
+
+/**
+ * states: fullCompaction
+ * owner: src/agent/fullCompaction/compactionOps.ts
+ */
+interface FullCompactionCancelPayload {
+  _name: 'full_compaction.cancel';
+  agentId: string;
+}
+
+/**
+ * states: fullCompaction
+ * owner: src/agent/fullCompaction/compactionOps.ts
+ */
+interface FullCompactionCompletePayload {
+  _name: 'full_compaction.complete';
+  agentId: string;
+}
+
+/**
+ * states: (none)
+ * owner: src/features/goal/goalOps.ts
+ */
+interface GoalClearPayload {
+  _name: 'goal.clear';
+  agentId: string;
+}
+
+/**
+ * states: (none)
+ * owner: src/features/goal/goalOps.ts
+ */
+interface GoalCreatePayload {
+  _name: 'goal.create';
+  agentId: string;
+  goalId: string;
+  objective: string;
+  completionCriterion?: string;
+  wallClockResumedAt?: number;
+  status?: 'active' | 'paused' | 'blocked' | 'complete';
+  actor?: 'user' | 'model' | 'runtime' | 'system';
+  budgetLimits?: {
+    tokenBudget?: number;
+    turnBudget?: number;
+    wallClockBudgetMs?: number;
+  };
+}
+
+/**
+ * states: (none)
+ * owner: src/features/goal/goalOps.ts
+ */
+interface GoalUpdatePayload {
+  _name: 'goal.update';
+  agentId: string;
+  goalId?: string;
+  status?: 'active' | 'paused' | 'blocked' | 'complete';
+  reason?: string;
+  turnsUsed?: number;
+  tokensUsed?: number;
+  wallClockMs?: number;
+  wallClockResumedAt?: number;
+  budgetLimits?: {
+    tokenBudget?: number;
+    turnBudget?: number;
+    wallClockBudgetMs?: number;
+  };
+  actor?: 'user' | 'model' | 'runtime' | 'system';
+}
+
+/**
+ * states: (none)
+ * owner: src/agent/interaction/interactionOps.ts
+ */
+interface InteractionRequestPayload {
+  _name: 'interaction.request';
+  agentId: string;
+  id: string;
+  kind: 'approval' | 'question' | 'user_tool';
+  toolCallId?: string;
+  request: any;
+}
+
+/**
+ * states: (none)
+ * owner: src/agent/interaction/interactionOps.ts
+ */
+interface InteractionResolvedPayload {
+  _name: 'interaction.resolved';
+  agentId: string;
+  id: string;
+  response: any;
+}
+
+/**
+ * states: interruptionReminder
+ * owner: src/agent/interruptionReminder/interruptionReminderOps.ts
+ */
+interface InterruptionReminderRecordedPayload {
+  _name: 'interruptionReminder.recorded';
+  agentId: string;
+  turnId: number;
+}
+
+/**
+ * states: llm.requestTrace
+ * owner: src/agent/llmRequester/llmRequestOps.ts
+ */
+interface LlmRequestPayload {
+  _name: 'llm.request';
+  agentId: string;
+  kind: 'loop' | 'compaction';
+  provider: string;
+  model: string;
+  modelAlias?: string;
+  thinkingEffort?: ThinkingEffort;
+  thinkingKeep?: string;
+  temperature?: number;
+  topP?: number;
+  maxTokens?: number;
+  betaApi?: boolean;
+  toolSelect: boolean;
+  systemPromptHash: string;
+  systemPrompt?: string;
+  toolsHash: string;
+  messageCount: number;
+  turnStep?: string;
+  attempt?: string;
+  projection?: 'strict' | 'media-degraded' | 'media-stripped' | 'strict-media-degraded' | 'strict-media-stripped';
+  droppedCount?: number;
+}
+
+/**
+ * states: llm.requestTrace
+ * owner: src/agent/llmRequester/llmRequestOps.ts
+ */
+interface LlmToolsSnapshotPayload {
+  _name: 'llm.tools_snapshot';
+  agentId: string;
+  hash: string;
+  tools: {
+    name: string;
+    description: string;
+    parameters: Record<string, any>;
+  }[];
+}
+
+/**
+ * states: mcp.discovery
+ * owner: src/agent/mcp/mcpDiscoveryOps.ts
+ */
+interface McpToolsDiscoveredPayload {
+  _name: 'mcp.tools_discovered';
+  agentId: string;
+  serverName: string;
+  hash: string;
+  tools: readonly MCPToolDefinition[];
+  enabledNames: string[];
+  collisions?: {
+    qualified: string;
+    toolName: string;
+    collidesWith: { kind: 'same_server', toolName: string } | { kind: 'other_server', serverName: string };
+  }[];
+}
+
+/**
+ * states: permissionRules
+ * owner: src/agent/permissionRules/permissionRulesOps.ts
+ */
+interface PermissionRecordApprovalResultPayload {
+  _name: 'permission.record_approval_result';
+  agentId: string;
+  turnId: number;
+  toolCallId: string;
+  toolName: string;
+  action: string;
+  sessionApprovalRule?: string;
+  result: PermissionApprovalResultRecord['result'];
+}
+
+/**
+ * states: permissionMode, permissionMode.configured
+ * owner: src/agent/permissionMode/permissionModeOps.ts
+ */
+interface PermissionSetModePayload {
+  _name: 'permission.set_mode';
+  agentId: string;
+  /** PermissionMode */
+  mode: 'manual' | 'yolo' | 'auto';
+}
+
+/**
+ * states: plan
+ * owner: src/features/plan/planOps.ts
+ */
+interface PlanModeCancelPayload {
+  _name: 'plan_mode.cancel';
+  agentId: string;
+  id?: string;
+}
+
+/**
+ * states: plan
+ * owner: src/features/plan/planOps.ts
+ */
+interface PlanModeEnterPayload {
+  _name: 'plan_mode.enter';
+  agentId: string;
+  id: string;
+}
+
+/**
+ * states: plan
+ * owner: src/features/plan/planOps.ts
+ */
+interface PlanModeExitPayload {
+  _name: 'plan_mode.exit';
+  agentId: string;
+  id?: string;
+}
+
+/**
+ * states: plan
+ * owner: src/features/plan/planOps.ts
+ */
+interface PlanRevisionPayload {
+  _name: 'plan.revision';
+  agentId: string;
+  id: string;
+  version: number;
+  key: string;
+  sha256: string;
+  bytes: number;
+}
+
+/**
+ * states: pluginSessionStartSnapshot
+ * owner: src/agent/plugin/agentPluginOps.ts
+ */
+interface PluginSessionStartPayload {
+  _name: 'plugin.session_start';
+  agentId: string;
+  content: string | null;
+}
+
+/**
+ * states: profile, profile.activeTools
+ * owner: src/agent/profile/profileOps.ts
+ */
+interface ProfileBindPayload {
+  _name: 'profile.bind';
+  agentId: string;
+  modelAlias?: string;
+  profileName?: string;
+  thinkingEffort: ThinkingEffort;
+  systemPrompt: string;
+  /** EnvironmentDisclosureSnapshot */
+  environmentDisclosure?: {
+    cwd: string;
+  };
+  renderGeneration?: number;
+  agentsMdPaths?: string[];
+  activeToolNames?: string[];
+  disallowedTools: string[];
+  subagents?: string[];
+}
+
+/**
+ * states: (none)
+ * owner: src/agent/prompt/promptEvents.ts
+ */
+interface PromptAbortedPayload {
+  _name: 'prompt.aborted';
+  agentId: string;
+  promptId: string;
+  abortedAt: string;
+}
+
+/**
+ * states: (none)
+ * owner: src/agent/prompt/promptEvents.ts
+ */
+interface PromptCompletedPayload {
+  _name: 'prompt.completed';
+  agentId: string;
+  promptId: string;
+  finishedAt: string;
+  reason: 'completed' | 'failed' | 'blocked';
+}
+
+/**
+ * states: (none)
+ * owner: src/agent/prompt/promptEvents.ts
+ */
+interface PromptSteeredPayload {
+  _name: 'prompt.steered';
+  agentId: string;
+  activePromptId: string;
+  promptIds: string[];
+  content: ContentPart[];
+  steeredAt: string;
+}
+
+/**
+ * states: runtimeBinding
+ * owner: src/agent/runtimeBinding/runtimeBindingOps.ts
+ */
+interface RuntimeSetBindingPayload {
+  _name: 'runtime.set_binding';
+  agentId: string;
+  workspaceId: string;
+  runtimeId: string;
+}
+
+/**
+ * states: swarm
+ * owner: src/features/swarm/swarmOps.ts
+ */
+interface SwarmModeEnterPayload {
+  _name: 'swarm_mode.enter';
+  agentId: string;
+  /** SwarmModeTrigger */
+  trigger: 'manual' | 'task' | 'tool';
+}
+
+/**
+ * states: contextMemory, swarm · blobs: contextMemory
+ * owner: src/features/swarm/swarmOps.ts
+ */
+interface SwarmModeExitPayload {
+  _name: 'swarm_mode.exit';
+  agentId: string;
+}
+
+/**
+ * states: task
+ * owner: src/agent/task/taskOps.ts
+ */
+interface TaskStartedPayload {
+  _name: 'task.started';
+  agentId: string;
+  /** AgentTaskInfo */
+  info: AgentTaskInfoByKind[AgentTaskKind];
+}
+
+/**
+ * states: task
+ * owner: src/agent/task/taskOps.ts
+ */
+interface TaskTerminatedPayload {
+  _name: 'task.terminated';
+  agentId: string;
+  /** AgentTaskInfo */
+  info: AgentTaskInfoByKind[AgentTaskKind];
+  outputTail?: string;
+}
+
+/**
+ * states: task.notificationDelivery
+ * owner: src/agent/task/taskOps.ts
+ */
+interface TaskWaitDeliveredPayload {
+  _name: 'task.waitDelivered';
+  agentId: string;
+  keys: string[];
+}
+
+/**
+ * states: (none)
+ * owner: src/agent/tokenCounting/tokenCountingOps.ts
+ */
+interface TokenCountingMeasuredPayload {
+  _name: 'token_counting.measured';
+  agentId: string;
+  length: number;
+  tokens: number;
+}
+
+/**
+ * states: (none)
+ * owner: src/agent/tokenCounting/tokenCountingOps.ts
+ */
+interface TokenCountingRebasedPayload {
+  _name: 'token_counting.rebased';
+  agentId: string;
+  length: number;
+  tokens: number;
+  measured: boolean;
+}
+
+/**
+ * states: (none)
+ * owner: src/agent/tokenCounting/tokenCountingOps.ts
+ */
+interface TokenCountingTruncatedPayload {
+  _name: 'token_counting.truncated';
+  agentId: string;
+  length: number;
+  tokens: number;
+}
+
+/**
+ * states: (none)
+ * owner: src/agent/tokenCounting/tokenCountingOps.ts
+ */
+interface TokenCountingTurnRecordedPayload {
+  _name: 'token_counting.turn_recorded';
+  agentId: string;
+  length: number;
+  tokens: number;
+  turnId: number;
+}
+
+/**
+ * states: userTool
+ * owner: src/agent/userTool/userToolOps.ts
+ */
+interface ToolsRegisterUserToolPayload {
+  _name: 'tools.register_user_tool';
+  agentId: string;
+  name: string;
+  description: string;
+  parameters: UserToolRegistration['parameters'];
+  disclosure?: UserToolRegistration['disclosure'];
+}
+
+/**
+ * states: profile.activeTools
+ * owner: src/agent/profile/profileOps.ts
+ */
+interface ToolsResetActiveToolsPayload {
+  _name: 'tools.reset_active_tools';
+  agentId: string;
+}
+
+/**
+ * states: profile.activeTools
+ * owner: src/agent/profile/profileOps.ts
+ */
+interface ToolsSetActiveToolsPayload {
+  _name: 'tools.set_active_tools';
+  agentId: string;
+  names: string[];
+}
+
+/**
+ * states: userTool
+ * owner: src/agent/userTool/userToolOps.ts
+ */
+interface ToolsUnregisterUserToolPayload {
+  _name: 'tools.unregister_user_tool';
+  agentId: string;
+  name: string;
+}
+
+/**
+ * states: (none)
+ * owner: src/features/todo/todoOps.ts
+ */
+interface ToolsUpdateStorePayload {
+  _name: 'tools.update_store';
+  agentId: string;
+  key: string;
+  value: any;
+}
+
+/**
+ * states: tower, tower.base, tower.owner
+ * owner: src/features/tower/towerOps.ts
+ */
+interface TowerModeEnterPayload {
+  _name: 'tower_mode.enter';
+  agentId: string;
+  sessionId?: string;
+  base?: string;
+}
+
+/**
+ * states: tower, tower.base, tower.owner
+ * owner: src/features/tower/towerOps.ts
+ */
+interface TowerModeExitPayload {
+  _name: 'tower_mode.exit';
+  agentId: string;
+}
+
+/**
+ * states: turn
+ * owner: src/agent/loop/turnOps.ts
+ */
+interface TurnCancelPayload {
+  _name: 'turn.cancel';
+  agentId: string;
+  turnId?: number;
+  target?: 'active' | 'queued';
+  reason?: 'user_cancelled' | 'aborted';
+}
+
+/**
+ * states: turn
+ * owner: src/agent/loop/turnOps.ts
+ */
+interface TurnEndedPayload {
+  _name: 'turn.ended';
+  agentId: string;
+  turnId: number;
+  reason: 'completed' | 'cancelled' | 'failed' | 'blocked';
+  /** KimiErrorPayload */
+  error?: {
+    code: (typeof ErrorCodes)[keyof typeof ErrorCodes];
+    message: string;
+    name?: string;
+    details?: Readonly<Record<string, unknown>>;
+    retryable: boolean;
+    cause?: {
+      code: (typeof ErrorCodes)[keyof typeof ErrorCodes];
+      message: string;
+      name?: string;
+      details?: Readonly<Record<string, unknown>>;
+      retryable: boolean;
+      cause?: {
+        code: (typeof ErrorCodes)[keyof typeof ErrorCodes];
+        message: string;
+        name?: string;
+        details?: Readonly<Record<string, unknown>>;
+        retryable: boolean;
+        cause?: {
+          code: (typeof ErrorCodes)[keyof typeof ErrorCodes];
+          message: string;
+          name?: string;
+          details?: Readonly<Record<string, unknown>>;
+          retryable: boolean;
+          cause?: {
+            code: (typeof ErrorCodes)[keyof typeof ErrorCodes];
+            message: string;
+            name?: string;
+            details?: Readonly<Record<string, unknown>>;
+            retryable: boolean;
+            cause?: {
+              code: ErrorCode;
+              message: string;
+              name?: string;
+              details?: Readonly<Record<string, unknown>>;
+              retryable: boolean;
+              cause?: ErrorPayload;
+            };
+          };
+        };
+      };
+    };
+  };
+  durationMs?: number;
+  stopReason?: string;
+}
+
+/**
+ * states: turn
+ * owner: src/agent/loop/turnOps.ts
+ */
+interface TurnPromptPayload {
+  _name: 'turn.prompt';
+  agentId: string;
+  input: readonly ContentPart[];
+  /** PromptOrigin */
+  origin: 'user' | 'skill_activation' | 'plugin_command' | 'injection' | 'shell_command' | 'compaction_summary' | 'system_trigger' | 'task' | 'cron_job' | 'cron_missed' | 'hook_result' | 'retry';
+  promptId?: string;
+  turnId?: number;
+}
+
+/**
+ * states: turn
+ * owner: src/agent/loop/turnOps.ts
+ */
+interface TurnSteerPayload {
+  _name: 'turn.steer';
+  agentId: string;
+  input: readonly ContentPart[];
+  /** PromptOrigin */
+  origin: 'user' | 'skill_activation' | 'plugin_command' | 'injection' | 'shell_command' | 'compaction_summary' | 'system_trigger' | 'task' | 'cron_job' | 'cron_missed' | 'hook_result' | 'retry';
+}
+
+/**
+ * states: (none)
+ * owner: src/agent/loop/turnEvents.ts
+ */
+interface TurnStepInterruptedPayload {
+  _name: 'turn.step.interrupted';
+  agentId: string;
+  turnId: number;
+  step: number;
+  stepId?: string;
+  reason: string;
+  message?: string;
+}
+
+/**
+ * states: (none)
+ * owner: src/agent/loop/turnEvents.ts
+ */
+interface TurnStepRetryingPayload {
+  _name: 'turn.step.retrying';
+  agentId: string;
+  turnId: number;
+  step: number;
+  stepId?: string;
+  failedAttempt: number;
+  nextAttempt: number;
+  maxAttempts: number;
+  delayMs: number;
+  errorName: string;
+  errorMessage: string;
+  statusCode?: number;
+}
+
+/**
+ * states: (none)
+ * owner: src/agent/usage/usageOps.ts
+ */
+interface UsageRecordPayload {
+  _name: 'usage.record';
+  agentId: string;
+  model: string;
+  usage: TokenUsage;
+  /** UsageRecordScope */
+  usageScope?: 'session' | 'turn';
+}
+
+/** Record type → payload sketch. */
+interface WirePayloadMap {
+  "config.update": ConfigUpdatePayload;
+  "context.append_loop_event": ContextAppendLoopEventPayload;
+  "context.append_message": ContextAppendMessagePayload;
+  "context.apply_compaction": ContextApplyCompactionPayload;
+  "context.clear": ContextClearPayload;
+  "context.undo": ContextUndoPayload;
+  "cron.add": CronAddPayload;
+  "cron.cursor": CronCursorPayload;
+  "cron.delete": CronDeletePayload;
+  "file_history.checkpoint": FileHistoryCheckpointPayload;
+  "file_history.tracked": FileHistoryTrackedPayload;
+  "forked": ForkedPayload;
+  "full_compaction.begin": FullCompactionBeginPayload;
+  "full_compaction.cancel": FullCompactionCancelPayload;
+  "full_compaction.complete": FullCompactionCompletePayload;
+  "goal.clear": GoalClearPayload;
+  "goal.create": GoalCreatePayload;
+  "goal.update": GoalUpdatePayload;
+  "interaction.request": InteractionRequestPayload;
+  "interaction.resolved": InteractionResolvedPayload;
+  "interruptionReminder.recorded": InterruptionReminderRecordedPayload;
+  "llm.request": LlmRequestPayload;
+  "llm.tools_snapshot": LlmToolsSnapshotPayload;
+  "mcp.tools_discovered": McpToolsDiscoveredPayload;
+  "permission.record_approval_result": PermissionRecordApprovalResultPayload;
+  "permission.set_mode": PermissionSetModePayload;
+  "plan_mode.cancel": PlanModeCancelPayload;
+  "plan_mode.enter": PlanModeEnterPayload;
+  "plan_mode.exit": PlanModeExitPayload;
+  "plan.revision": PlanRevisionPayload;
+  "plugin.session_start": PluginSessionStartPayload;
+  "profile.bind": ProfileBindPayload;
+  "prompt.aborted": PromptAbortedPayload;
+  "prompt.completed": PromptCompletedPayload;
+  "prompt.steered": PromptSteeredPayload;
+  "runtime.set_binding": RuntimeSetBindingPayload;
+  "swarm_mode.enter": SwarmModeEnterPayload;
+  "swarm_mode.exit": SwarmModeExitPayload;
+  "task.started": TaskStartedPayload;
+  "task.terminated": TaskTerminatedPayload;
+  "task.waitDelivered": TaskWaitDeliveredPayload;
+  "token_counting.measured": TokenCountingMeasuredPayload;
+  "token_counting.rebased": TokenCountingRebasedPayload;
+  "token_counting.truncated": TokenCountingTruncatedPayload;
+  "token_counting.turn_recorded": TokenCountingTurnRecordedPayload;
+  "tools.register_user_tool": ToolsRegisterUserToolPayload;
+  "tools.reset_active_tools": ToolsResetActiveToolsPayload;
+  "tools.set_active_tools": ToolsSetActiveToolsPayload;
+  "tools.unregister_user_tool": ToolsUnregisterUserToolPayload;
+  "tools.update_store": ToolsUpdateStorePayload;
+  "tower_mode.enter": TowerModeEnterPayload;
+  "tower_mode.exit": TowerModeExitPayload;
+  "turn.cancel": TurnCancelPayload;
+  "turn.ended": TurnEndedPayload;
+  "turn.prompt": TurnPromptPayload;
+  "turn.steer": TurnSteerPayload;
+  "turn.step.interrupted": TurnStepInterruptedPayload;
+  "turn.step.retrying": TurnStepRetryingPayload;
+  "usage.record": UsageRecordPayload;
+}

packages/agent-core-v2/scripts/check-import-boundaries.d.mts

@@ -0,0 +1,10 @@
+export interface Violation {
+  file: string;
+  line: number;
+  message: string;
+}
+
+export const SRC_ROOT: string;
+
+export function checkSource(source: string, absFile: string): Violation[];
+export function checkFile(absFile: string): Violation[];

packages/agent-core-v2/scripts/check-import-boundaries.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+
+const PKG_ROOT = resolve(import.meta.dirname, '..');
+export const SRC_ROOT = join(PKG_ROOT, 'src');
+const TEST_ROOT = join(PKG_ROOT, 'test');
+const HUMAN_ROOT = join(SRC_ROOT, 'human');
+const ADAPTER_ROOT = join(SRC_ROOT, 'llm-adapter');
+const LOOP_MACHINE_ADAPTER_ROOT = join(SRC_ROOT, 'agent/loop/machine');
+const SESSION_LIFECYCLE_ADAPTER_ROOT = join(SRC_ROOT, 'session/agentLifecycle');
+
+const SELF_PACKAGE_PREFIX = '@moonshot-ai/agent-core-v2/';
+const KOSONG_PATH_RE = /(?:^|\/)kosong(?:\/|$)/;
+const TRAIT_FILE_RE = /\/trait\.ts$/;
+const FORMAT_LOWER_FILE_RE = /\/bases\/[^/]+\/(?:format|lower)\.ts$/;
+const FORMAT_LOWER_MODULE_RE = /\/bases\/[^/]+\/(?:format|lower)$/;
+const TRAIT_MODULE_RE = /\/trait$/;
+const BASES_DIR_RE = /\/llm\/requester\/bases(?:\/|$)/;
+const BASES_INTERNAL_MODULE_RE =
+  /\/llm\/requester\/bases\/[^/]+\/(?:format|lower|patterns|reasoning-key)$/;
+const TEST_DIR_RE = /\/test(?:\/|$)/;
+
+function traitBoundaryViolation(absFile, targetAbs, specifier) {
+  const message = `format and trait never import each other ('${specifier}') — both sides speak only the neutral wire/chunk types in the protocol's contract.ts`;
+  if (TRAIT_FILE_RE.test(absFile) && FORMAT_LOWER_MODULE_RE.test(targetAbs)) {
+    return message;
+  }
+  if (FORMAT_LOWER_FILE_RE.test(absFile) && TRAIT_MODULE_RE.test(targetAbs)) {
+    return message;
+  }
+  return undefined;
+}
+
+function basesInternalViolation(absFile, targetAbs, specifier) {
+  if (!BASES_INTERNAL_MODULE_RE.test(targetAbs)) return undefined;
+  if (TRAIT_FILE_RE.test(absFile) && FORMAT_LOWER_MODULE_RE.test(targetAbs)) return undefined;
+  if (BASES_DIR_RE.test(absFile) || TEST_DIR_RE.test(absFile)) return undefined;
+  return `protocol format modules are internal to the requester pipeline ('${specifier}') — only llm/requester/bases code and tests may import format/lower/patterns; everyone else speaks contract/trait/requester`;
+}
+
+const HUMAN_VOCABULARY = new Set([
+  'agent/origin',
+  'llm/message',
+  'llm/usage',
+  'llm/capability',
+  'llm/thinking',
+  'llm/finish-reason',
+  'llm/response-format',
+  'llm/media/upload',
+  'llm/media/image-formats',
+  'llm/requester/requester',
+  'llm/toolCallIdNormalizer',
+  'llm-kimi/trait',
+  'interaction/interaction',
+  'interaction/machine',
+  'interaction/facade',
+  'utils/watch',
+  'xstate2',
+]);
+
+const V2_ONLY_FIRST_SEGMENTS = new Set([
+  'llm-adapter',
+  'app',
+  'workspace',
+  'features',
+  'state',
+  'wire',
+  'persistence',
+  'os',
+  'mcpCore',
+  'errors',
+  'debug',
+  'program',
+  'runtime',
+  '_base',
+]);
+
+function isInside(root, absPath) {
+  const rel = relative(root, absPath);
+  return rel !== '' && !rel.startsWith('..');
+}
+
+function humanSubpathOf(specifier) {
+  if (specifier.startsWith('#human/')) return specifier.slice('#human/'.length);
+  if (specifier.startsWith(`${SELF_PACKAGE_PREFIX}human/`)) {
+    return specifier.slice(`${SELF_PACKAGE_PREFIX}human/`.length);
+  }
+  return undefined;
+}
+
+function stripTs(path) {
+  return path.endsWith('.ts') ? path.slice(0, -'.ts'.length) : path;
+}
+
+function resolveIntraV2(specifier, fromFile) {
+  if (specifier.startsWith('#human/')) {
+    return join(HUMAN_ROOT, specifier.slice('#human/'.length));
+  }
+  if (specifier.startsWith('#/')) {
+    if (isInside(HUMAN_ROOT, fromFile)) {
+      return join(HUMAN_ROOT, specifier.slice(2));
+    }
+    return join(SRC_ROOT, specifier.slice(2));
+  }
+  if (specifier.startsWith(SELF_PACKAGE_PREFIX)) {
+    return join(SRC_ROOT, specifier.slice(SELF_PACKAGE_PREFIX.length));
+  }
+  if (specifier.startsWith('.')) {
+    return resolve(dirname(fromFile), specifier);
+  }
+  return undefined;
+}
+
+const IMPORT_RE =
+  /(?:import|export)\s+(?:type\s+)?(?:[^'";]*?\s+from\s+)?['"]([^'"]+)['"]|(?:import|require)\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+export function checkSource(source, absFile) {
+  const violations = [];
+  const inSrc = !relative(SRC_ROOT, absFile).startsWith('..');
+  const inHuman = isInside(HUMAN_ROOT, absFile);
+  const inAdapter =
+    isInside(ADAPTER_ROOT, absFile) ||
+    isInside(LOOP_MACHINE_ADAPTER_ROOT, absFile) ||
+    isInside(SESSION_LIFECYCLE_ADAPTER_ROOT, absFile);
+
+  let match;
+  IMPORT_RE.lastIndex = 0;
+  while ((match = IMPORT_RE.exec(source)) !== null) {
+    const specifier = match[1] ?? match[2];
+    if (!specifier) continue;
+    const line = source.slice(0, match.index).split('\n').length;
+
+    if (KOSONG_PATH_RE.test(specifier)) {
+      violations.push({
+        file: absFile,
+        line,
+        message: `the kosong kernel is deleted (${specifier}) — request/provider code lives in #human/llm, the v2 compatibility boundary is #/llm-adapter`,
+      });
+      continue;
+    }
+
+    if (!inSrc) continue;
+
+    const targetAbs = resolveIntraV2(specifier, absFile);
+    if (targetAbs !== undefined) {
+      const basesInternal = basesInternalViolation(absFile, stripTs(targetAbs), specifier);
+      if (basesInternal !== undefined) {
+        violations.push({ file: absFile, line, message: basesInternal });
+      }
+    }
+
+    if (inHuman) {
+      if (specifier.startsWith('#/')) {
+        const first = specifier.slice(2).split('/')[0];
+        if (first !== undefined && V2_ONLY_FIRST_SEGMENTS.has(first)) {
+          violations.push({
+            file: absFile,
+            line,
+            message: `human must not import outside its kernel ('${specifier}') — human is the pure LLM/agent kernel: it never imports llm-adapter or v2 domains`,
+          });
+          continue;
+        }
+      }
+      if (targetAbs !== undefined && !isInside(HUMAN_ROOT, targetAbs)) {
+        violations.push({
+          file: absFile,
+          line,
+          message: `human must not import outside its kernel ('${specifier}') — human is the pure LLM/agent kernel: it never imports llm-adapter or v2 domains`,
+        });
+      }
+      if (targetAbs !== undefined) {
+        const traitBoundary = traitBoundaryViolation(absFile, stripTs(targetAbs), specifier);
+        if (traitBoundary !== undefined) {
+          violations.push({ file: absFile, line, message: traitBoundary });
+        }
+      }
+      continue;
+    }
+
+    const humanSub = humanSubpathOf(specifier);
+    if (humanSub !== undefined && !inAdapter && !HUMAN_VOCABULARY.has(stripTs(humanSub))) {
+      violations.push({
+        file: absFile,
+        line,
+        message: `only llm-adapter, agent/loop/machine and session/agentLifecycle may import the human implementation ('${specifier}') — v2 code outside those adapter layers is limited to the vocabulary modules (${[...HUMAN_VOCABULARY].join(', ')})`,
+      });
+    }
+  }
+
+  return violations;
+}
+
+export function checkFile(absFile) {
+  return checkSource(readFileSync(absFile, 'utf8'), absFile);
+}
+
+function walk(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    if (entry === 'node_modules' || entry === 'dist') continue;
+    const abs = join(dir, entry);
+    const st = statSync(abs);
+    if (st.isDirectory()) out.push(...walk(abs));
+    else if (abs.endsWith('.ts')) out.push(abs);
+  }
+  return out;
+}
+
+function main() {
+  const files = [...walk(SRC_ROOT), ...walk(TEST_ROOT)];
+  const violations = files.flatMap((f) => checkFile(f));
+  if (violations.length === 0) {
+    console.log(`check-import-boundaries: OK (${files.length} files)`);
+    return 0;
+  }
+  for (const v of violations) {
+    console.error(`${relative(PKG_ROOT, v.file)}:${v.line}: ${v.message}`);
+  }
+  console.error(`\ncheck-import-boundaries: ${violations.length} violation(s)`);
+  return 1;
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === import.meta.filename;
+if (isMain) {
+  process.exit(main());
+}

packages/agent-core-v2/scripts/debarrel.mjs

@@ -0,0 +1,474 @@
+#!/usr/bin/env node
+import { Project } from 'ts-morph';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG = path.resolve(__dirname, '..');
+const SRC = path.join(PKG, 'src');
+const ENTRY = path.join(SRC, 'index.ts');
+
+const args = process.argv.slice(2);
+const DRY = args.includes('--dry-run');
+const ONLY = (args.find((a) => a.startsWith('--only=')) || '').slice('--only='.length) || null;
+const ENTRY_ONLY = args.includes('--entry');
+const DELETE_BARRELS = args.includes('--delete-barrels');
+const LIST_REGS = args.includes('--list-registers');
+const VERIFY = args.includes('--verify-coverage');
+
+const project = new Project({ tsConfigFilePath: path.join(PKG, 'tsconfig.json') });
+
+const relSpec = (absFile) =>
+  '#/' + path.relative(SRC, absFile).split(path.sep).join('/').replace(/\.ts$/, '');
+
+const isUnderSrc = (abs) => abs === SRC || abs.startsWith(SRC + path.sep);
+const isIndexBasename = (abs) => path.basename(abs) === 'index.ts';
+const isBarrelFile = (sf) => {
+  const f = sf.getFilePath();
+  return isUnderSrc(f) && isIndexBasename(f) && f !== ENTRY;
+};
+const resolvedFile = (decl) => decl.getModuleSpecifierSourceFile() || null;
+const barrelOfDecl = (decl) => {
+  const sf = resolvedFile(decl);
+  return sf && isBarrelFile(sf) ? sf : null;
+};
+
+function resolveName(barrel, name) {
+  const decls = barrel.getExportedDeclarations().get(name);
+  if (!decls || decls.length === 0) return null;
+  const decl = decls[0];
+  const leaf = decl.getSourceFile();
+  const sym = decl.getSymbol();
+  let leafName = null;
+  for (const [ln, lds] of leaf.getExportedDeclarations()) {
+    if (lds.some((d) => d.getSymbol() === sym)) {
+      leafName = ln;
+      break;
+    }
+  }
+  if (leafName === null) leafName = (sym && sym.getName()) || name;
+  return { leafFile: leaf.getFilePath(), leafName };
+}
+
+function expandBarrelClauses(barrel) {
+  const clauses = [];
+  for (const ed of barrel.getExportDeclarations()) {
+    const target = resolvedFile(ed);
+    if (!target) continue;
+    if (isBarrelFile(target)) {
+      clauses.push(...expandBarrelClauses(target));
+      continue;
+    }
+    const file = target.getFilePath();
+    const isStar =
+      ed.getNamedExports().length === 0 && !ed.getNamespaceExport();
+    if (isStar) {
+      clauses.push({ kind: 'star', file });
+    } else if (ed.getNamespaceExport()) {
+      clauses.push({ kind: 'namespace', file, name: ed.getNamespaceExport().getName() });
+    } else {
+      const declType = ed.isTypeOnly();
+      const specs = ed.getNamedExports().map((s) => ({
+        name: s.getName(),
+        alias: s.getAliasNode()?.getText(),
+        isTypeOnly: declType || s.isTypeOnly(),
+      }));
+      clauses.push({ kind: 'named', file, isTypeOnly: declType, specs });
+    }
+  }
+  return clauses;
+}
+
+function allLeavesUnderDir(dirAbs) {
+  const out = [];
+  const walk = (d) => {
+    for (const ent of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, ent.name);
+      if (ent.isDirectory()) walk(p);
+      else if (
+        ent.isFile() &&
+        p.endsWith('.ts') &&
+        !p.endsWith('.test.ts') &&
+        !p.endsWith('.d.ts') &&
+        path.basename(p) !== 'index.ts'
+      ) {
+        out.push(p);
+      }
+    }
+  };
+  walk(dirAbs);
+  return out.sort((a, b) => a.localeCompare(b));
+}
+
+function rewriteConsumerFile(sf, onlyBarrelPath) {
+  const report = { imports: 0, exports: 0, manuals: [], sideEffects: 0 };
+
+  for (const decl of sf.getImportDeclarations()) {
+    const barrel = barrelOfDecl(decl);
+    if (!barrel) continue;
+    if (onlyBarrelPath && barrel.getFilePath() !== onlyBarrelPath) continue;
+
+    if (decl.getNamespaceImport()) {
+      report.manuals.push({ sf: sf.getFilePath(), text: decl.getText(), why: 'namespace import' });
+      continue;
+    }
+    const hasDefault = !!decl.getDefaultImport();
+    const named = decl.getNamedImports();
+    if (!hasDefault && named.length === 0) {
+      const leaves = [...new Set(expandBarrelClauses(barrel).map((c) => c.file))];
+      const idx = sf.getImportDeclarations().indexOf(decl);
+      sf.insertImportDeclarations(
+        idx,
+        leaves.map((leaf) => ({ moduleSpecifier: relSpec(leaf) })),
+      );
+      decl.remove();
+      report.sideEffects += leaves.length;
+      report.imports++;
+      continue;
+    }
+
+    const declType = decl.isTypeOnly();
+    const groups = new Map();
+    const add = (leaf, spec) => {
+      if (!groups.has(leaf)) groups.set(leaf, []);
+      groups.get(leaf).push(spec);
+    };
+
+    if (hasDefault) {
+      const r = resolveName(barrel, 'default');
+      if (!r) report.manuals.push({ sf: sf.getFilePath(), text: decl.getText(), why: 'default import unresolved' });
+      else add(r.leafFile, { default: decl.getDefaultImport().getText() });
+    }
+    for (const s of named) {
+      const lookup = s.getName();
+      const local = s.getAliasNode()?.getText() || s.getName();
+      const r = resolveName(barrel, lookup);
+      if (!r) {
+        report.manuals.push({ sf: sf.getFilePath(), text: s.getText(), why: 'named import unresolved' });
+        continue;
+      }
+      add(r.leafFile, {
+        name: r.leafName,
+        alias: local !== r.leafName ? local : undefined,
+        isTypeOnly: declType || s.isTypeOnly(),
+      });
+    }
+    const structures = buildImportStructures(groups);
+    const idx = sf.getImportDeclarations().indexOf(decl);
+    if (structures.length) sf.insertImportDeclarations(idx, structures);
+    decl.remove();
+    report.imports++;
+  }
+
+  for (const decl of sf.getExportDeclarations()) {
+    const barrel = barrelOfDecl(decl);
+    if (!barrel) continue;
+    if (onlyBarrelPath && barrel.getFilePath() !== onlyBarrelPath) continue;
+
+    const isStar = decl.getNamedExports().length === 0 && !decl.getNamespaceExport();
+    if (isStar) {
+      const clauses = expandBarrelClauses(barrel);
+      decl.replaceWithText(clauses.map(exportClauseToText).join('\n'));
+      report.exports++;
+      continue;
+    }
+    if (decl.getNamespaceExport()) {
+      report.manuals.push({ sf: sf.getFilePath(), text: decl.getText(), why: 'namespace export' });
+      continue;
+    }
+    const declType = decl.isTypeOnly();
+    const groups = new Map();
+    for (const s of decl.getNamedExports()) {
+      const lookup = s.getName();
+      const exportedAs = s.getAliasNode()?.getText() || s.getName();
+      const r = resolveName(barrel, lookup);
+      if (!r) {
+        report.manuals.push({ sf: sf.getFilePath(), text: s.getText(), why: 'named export unresolved' });
+        continue;
+      }
+      if (!groups.has(r.leafFile)) groups.set(r.leafFile, { specs: [], allType: true });
+      const g = groups.get(r.leafFile);
+      const t = declType || s.isTypeOnly();
+      g.allType = g.allType && t;
+      g.specs.push({
+        name: r.leafName,
+        alias: exportedAs !== r.leafName ? exportedAs : undefined,
+        isTypeOnly: t,
+      });
+    }
+    const lines = [];
+    for (const [leaf, { specs, allType }] of groups) {
+      lines.push(renderNamedExport(relSpec(leaf), specs, allType));
+    }
+    decl.replaceWithText(lines.join('\n'));
+    report.exports++;
+  }
+  return report;
+}
+
+function buildImportStructures(groups) {
+  const structures = [];
+  for (const [leaf, specs] of groups) {
+    const spec = relSpec(leaf);
+    const defaults = specs.filter((s) => s.default);
+    const namedSpecs = specs.filter((s) => !s.default);
+    for (const d of defaults) {
+      structures.push({ moduleSpecifier: spec, defaultImport: d.default });
+    }
+    const values = namedSpecs.filter((s) => !s.isTypeOnly);
+    const types = namedSpecs.filter((s) => s.isTypeOnly);
+    if (values.length)
+      structures.push({
+        moduleSpecifier: spec,
+        namedImports: values.map((v) => ({ name: v.name, alias: v.alias })),
+      });
+    if (types.length)
+      structures.push({
+        moduleSpecifier: spec,
+        isTypeOnly: true,
+        namedImports: types.map((t) => ({ name: t.name, alias: t.alias })),
+      });
+  }
+  return structures;
+}
+
+function renderNamedExport(spec, specs, allType) {
+  const body = specs
+    .map((s) => `${allType ? '' : s.isTypeOnly ? 'type ' : ''}${s.name}${s.alias ? ' as ' + s.alias : ''}`)
+    .join(', ');
+  return `${allType ? 'export type' : 'export'} { ${body} } from '${spec}';`;
+}
+
+function exportClauseToText(c) {
+  if (c.kind === 'star') return `export * from '${relSpec(c.file)}';`;
+  if (c.kind === 'namespace') return `export * as ${c.name} from '${relSpec(c.file)}';`;
+  return renderNamedExport(relSpec(c.file), c.specs, c.isTypeOnly);
+}
+
+function regenerateEntry() {
+  const entrySf = project.getSourceFileOrThrow(ENTRY);
+  const original = entrySf.getFullText();
+  const headerMatch = original.match(/^\s*\/\*\*[\s\S]*?\*\//);
+  const header = headerMatch ? headerMatch[0] : '/** agent-core-v2 public surface. */';
+
+  const refs = [];
+  for (const decl of [...entrySf.getExportDeclarations(), ...entrySf.getImportDeclarations()]) {
+    const barrel = barrelOfDecl(decl);
+    if (!barrel) continue;
+    let mode;
+    if (decl.getKindName() === 'ImportDeclaration') mode = 'side';
+    else {
+      const isStar = decl.getNamedExports().length === 0 && !decl.getNamespaceExport();
+      mode = isStar ? 'star' : 'named';
+    }
+    refs.push({ decl, barrel, mode });
+  }
+
+  const publicLines = [];
+  const loadingLines = [];
+  const processed = new Set();
+
+  for (const { decl, barrel, mode } of refs) {
+    const bf = barrel.getFilePath();
+    const dirAbs = path.dirname(bf);
+    const allLeaves = allLeavesUnderDir(dirAbs);
+    const clauses = expandBarrelClauses(barrel);
+    const starLeaves = new Set(clauses.filter((c) => c.kind === 'star').map((c) => c.file));
+
+    if (mode === 'star') {
+      for (const c of clauses) publicLines.push(exportClauseToText(c));
+    } else if (mode === 'named') {
+      const declType = decl.isTypeOnly();
+      const groups = new Map();
+      for (const s of decl.getNamedExports()) {
+        const lookup = s.getName();
+        const exportedAs = s.getAliasNode()?.getText() || s.getName();
+        const r = resolveName(barrel, lookup);
+        if (!r) continue;
+        if (!groups.has(r.leafFile)) groups.set(r.leafFile, { specs: [], allType: true });
+        const g = groups.get(r.leafFile);
+        const t = declType || s.isTypeOnly();
+        g.allType = g.allType && t;
+        g.specs.push({
+          name: r.leafName,
+          alias: exportedAs !== r.leafName ? exportedAs : undefined,
+          isTypeOnly: t,
+        });
+      }
+      for (const [leaf, { specs, allType }] of groups) {
+        publicLines.push(renderNamedExport(relSpec(leaf), specs, allType));
+      }
+    }
+    for (const leaf of allLeaves) {
+      const key = leaf;
+      if (starLeaves.has(leaf)) continue;
+      if (processed.has(key)) continue;
+      processed.add(key);
+      loadingLines.push(`import '${relSpec(leaf)}';`);
+    }
+  }
+
+  const body = [
+    header,
+    '',
+    '// Public surface — precise re-exports of each domain leaf (no barrels).',
+    ...publicLines,
+    '',
+    '// Side-effect loading — ensure every domain leaf (and its top-level',
+    '// `register*` calls) is evaluated when the package is imported.',
+    ...loadingLines,
+    '',
+  ].join('\n');
+
+  if (!DRY) fs.writeFileSync(ENTRY, body);
+  return { publicLines: publicLines.length, loadingLines: loadingLines.length };
+}
+
+const REGISTER_NAMES = new Set([
+  'registerScopedService',
+  'registerAgentToolService',
+  'registerErrorDomain',
+  'registerConfigSection',
+  'registerAgentProfile',
+  'registerFlagDefinition',
+]);
+
+function isModuleScoped(call) {
+  let n = call.getParent();
+  while (n) {
+    const k = n.getKindName();
+    if (
+      k === 'FunctionDeclaration' ||
+      k === 'FunctionExpression' ||
+      k === 'ArrowFunction' ||
+      k === 'MethodDeclaration' ||
+      k === 'Constructor' ||
+      k === 'ClassDeclaration'
+    ) {
+      return false;
+    }
+    n = n.getParent();
+  }
+  return true;
+}
+
+function findRegisterFiles() {
+  const files = [];
+  for (const sf of project.getSourceFiles()) {
+    const f = sf.getFilePath();
+    if (!isUnderSrc(f) || f.endsWith('.test.ts')) continue;
+    let hit = false;
+    sf.forEachDescendant((node) => {
+      if (hit) return;
+      if (node.getKindName() !== 'CallExpression') return;
+      const expr = node.getExpression();
+      if (expr.getKindName() !== 'Identifier') return;
+      if (!REGISTER_NAMES.has(expr.getText())) return;
+      if (isModuleScoped(node)) hit = true;
+    });
+    if (hit) files.push(f);
+  }
+  return files.sort();
+}
+
+function reachedFromEntry() {
+  const reached = new Set();
+  const visit = (sf) => {
+    const f = sf.getFilePath();
+    if (reached.has(f)) return;
+    reached.add(f);
+    if (!isUnderSrc(f)) return;
+    const edges = [...sf.getImportDeclarations(), ...sf.getExportDeclarations()];
+    for (const d of edges) {
+      if (d.isTypeOnly && d.isTypeOnly()) continue;
+      const t = resolvedFile(d);
+      if (t && isUnderSrc(t.getFilePath())) visit(t);
+    }
+  };
+  visit(project.getSourceFileOrThrow(ENTRY));
+  return reached;
+}
+
+function verifyCoverage() {
+  const regs = findRegisterFiles();
+  const reached = reachedFromEntry();
+  const missing = regs.filter((f) => !reached.has(f));
+  console.log(`register files: ${regs.length}; reachable from entry: ${reached.size}; missing: ${missing.length}`);
+  if (missing.length) {
+    console.log('MISSING (not reachable from src/index.ts):');
+    for (const m of missing) console.log('  ' + path.relative(PKG, m));
+    return false;
+  }
+  return true;
+}
+
+function deleteBarrels() {
+  let n = 0;
+  for (const sf of project.getSourceFiles()) {
+    if (!isBarrelFile(sf)) continue;
+    const f = sf.getFilePath();
+    if (!DRY) fs.unlinkSync(f);
+    n++;
+  }
+  return n;
+}
+
+function main() {
+  if (LIST_REGS) {
+    for (const f of findRegisterFiles()) console.log(path.relative(PKG, f));
+    return;
+  }
+  if (VERIFY) {
+    const ok = verifyCoverage();
+    process.exit(ok ? 0 : 1);
+  }
+  if (ENTRY_ONLY) {
+    const r = regenerateEntry();
+    console.log(`entry regenerated: ${r.publicLines} public lines, ${r.loadingLines} loading lines${DRY ? ' (dry-run)' : ''}`);
+    return;
+  }
+
+  let onlyBarrelPath = null;
+  if (ONLY) {
+    onlyBarrelPath = path.join(SRC, ONLY, 'index.ts');
+    if (!fs.existsSync(onlyBarrelPath)) {
+      console.error(`--only target not a barrel: ${path.relative(PKG, onlyBarrelPath)}`);
+      process.exit(2);
+    }
+  }
+
+  const totals = { files: 0, imports: 0, exports: 0, sideEffects: 0, manuals: [] };
+  for (const sf of project.getSourceFiles()) {
+    const f = sf.getFilePath();
+    if (!isUnderSrc(f) && !f.startsWith(path.join(PKG, 'test') + path.sep)) continue;
+    if (f === ENTRY) continue;
+    const before = sf.getFullText();
+    const r = rewriteConsumerFile(sf, onlyBarrelPath);
+    if (sf.getFullText() !== before) {
+      totals.files++;
+      totals.imports += r.imports;
+      totals.exports += r.exports;
+      totals.sideEffects += r.sideEffects;
+    }
+    totals.manuals.push(...r.manuals);
+  }
+
+  if (!DRY) project.saveSync();
+
+  console.log(
+    `rewrote ${totals.files} files: ${totals.imports} barrel imports, ${totals.exports} barrel exports, ${totals.sideEffects} side-effect loads${DRY ? ' (dry-run)' : ''}`,
+  );
+  if (totals.manuals.length) {
+    console.log(`MANUAL (${totals.manuals.length}) — could not auto-split:`);
+    for (const m of totals.manuals)
+      console.log(`  ${path.relative(PKG, m.sf)} :: ${m.why} :: ${m.text.replace(/\s+/g, ' ').slice(0, 120)}`);
+  }
+
+  if (DELETE_BARRELS) {
+    const n = deleteBarrels();
+    console.log(`deleted ${n} domain barrels${DRY ? ' (dry-run)' : ''}`);
+  }
+}
+
+main();

packages/agent-core-v2/scripts/gen-config-manifest.mts

@@ -0,0 +1,314 @@
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { getConfigOverlayContributions } from '#/app/config/configOverlayContributions';
+import type { ConfigSectionContribution } from '#/app/config/configSectionContributions';
+import { getConfigSectionContributions } from '#/app/config/configSectionContributions';
+import { camelToSnake } from '#/app/config/toml';
+
+import {
+  asJsonSchema,
+  describeType,
+  isRecord,
+  resolveRef,
+  toJsonSchema,
+  truncate,
+  type JsonSchema,
+} from './lib/jsonSchema.mts';
+
+const PKG = join(import.meta.dirname, '..');
+const SRC = join(PKG, 'src');
+export const MANIFEST_PATH = join(PKG, 'docs', 'config-manifest.toml');
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const p = join(dir, entry);
+    if (statSync(p).isDirectory()) walk(p, out);
+    else if (entry.endsWith('.ts')) out.push(p);
+  }
+  return out;
+}
+
+function constStringValue(source: string, ident: string): string | undefined {
+  const re = new RegExp(`(?:export\\s+)?const\\s+${ident}\\s*(?::[^=;]+)?=\\s*'([^']+)'`);
+  return re.exec(source)?.[1];
+}
+
+function scanSectionOwners(): Map<string, string> {
+  const owners = new Map<string, string>();
+  for (const file of walk(SRC)) {
+    const source = readFileSync(file, 'utf-8');
+    if (!source.includes('registerConfigSection(')) continue;
+    for (const match of source.matchAll(/registerConfigSection\(\s*(?:'([^']+)'|([A-Za-z0-9_$]+))/g)) {
+      const ident = match[2];
+      const domain = match[1] ?? (ident === undefined ? undefined : constStringValue(source, ident));
+      if (domain !== undefined) owners.set(domain, relative(PKG, file));
+    }
+  }
+  return owners;
+}
+
+function scanOverlayOwners(): Map<string, string> {
+  const owners = new Map<string, string>();
+  for (const file of walk(SRC)) {
+    if (file.endsWith('configOverlayContributions.ts')) continue;
+    const source = readFileSync(file, 'utf-8');
+    if (!source.includes('registerConfigOverlay(')) continue;
+    for (const match of source.matchAll(/registerConfigOverlay\(\s*([A-Za-z0-9_$]+)/g)) {
+      const ident = match[1];
+      if (ident !== undefined) owners.set(ident, relative(PKG, file));
+    }
+  }
+  return owners;
+}
+
+function toTomlValue(value: unknown): string {
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (Array.isArray(value)) return `[${value.map(toTomlValue).join(', ')}]`;
+  if (isRecord(value)) {
+    const entries = Object.entries(value).map(([k, v]) => `${camelToSnake(k)} = ${toTomlValue(v)}`);
+    return `{ ${entries.join(', ')} }`;
+  }
+  return '""';
+}
+
+interface EnvRow {
+  readonly field: string;
+  readonly env: string;
+  readonly detail: string;
+}
+
+interface EnvBindingFields {
+  readonly env?: unknown;
+  readonly deprecatedEnv?: unknown;
+  readonly parse?: unknown;
+  readonly default?: unknown;
+}
+
+function flattenEnvBindings(bindings: unknown, path: string[] = []): EnvRow[] {
+  if (typeof bindings === 'string') {
+    return [{ field: path.join('.'), env: bindings, detail: '' }];
+  }
+  if (!isRecord(bindings)) return [];
+  const binding = bindings as EnvBindingFields;
+  if (typeof binding.env === 'string') {
+    const detail: string[] = [];
+    if (binding.parse !== undefined) detail.push('custom parse');
+    if (binding.default !== undefined) detail.push(`default ${JSON.stringify(binding.default)}`);
+    if (typeof binding.deprecatedEnv === 'string') {
+      detail.push(`deprecated fallback ${binding.deprecatedEnv}`);
+    }
+    return [{ field: path.join('.'), env: binding.env, detail: detail.join('; ') }];
+  }
+  return Object.entries(bindings).flatMap(([key, value]) => flattenEnvBindings(value, [...path, key]));
+}
+
+function snakePath(field: string): string {
+  return field.split('.').map(camelToSnake).join('.');
+}
+
+const RULE = `# ${'#'.repeat(74)}`;
+
+function renderFieldComments(
+  properties: Record<string, unknown>,
+  root: JsonSchema,
+  indent: string,
+  depth = 0,
+): string[] {
+  const lines: string[] = [];
+  for (const [name, prop] of Object.entries(properties)) {
+    const resolved = resolveRef(prop, root);
+    const propDefault = asJsonSchema(resolved)?.default;
+    const defNote = propDefault !== undefined ? ` (default: ${JSON.stringify(propDefault)})` : '';
+    lines.push(`${indent}# ${camelToSnake(name)}: ${describeType(resolved)}${defNote}`);
+    const subProps = asJsonSchema(resolved)?.properties;
+    if (depth < 3 && isRecord(subProps) && Object.keys(subProps).length > 0) {
+      lines.push(...renderFieldComments(subProps, root, `${indent}  `, depth + 1));
+    }
+  }
+  return lines;
+}
+
+function renderBody(section: ConfigSectionContribution): string[] {
+  const { domain, schema, options } = section;
+  const key = camelToSnake(domain);
+  const jsonSchema = schema === undefined ? undefined : toJsonSchema(schema);
+
+  if (jsonSchema === undefined) {
+    if (isRecord(options.defaultValue)) {
+      return [
+        `[${key}]`,
+        `# (${schema === undefined ? 'no schema — passthrough' : 'schema uses transforms'}; fields below come from the registered default)`,
+        ...Object.entries(options.defaultValue).map(
+          ([k, v]) => `${camelToSnake(k)} = ${truncate(toTomlValue(v))}`,
+        ),
+      ];
+    }
+    if (options.defaultValue !== undefined) {
+      return [`${key} = ${truncate(toTomlValue(options.defaultValue))}`];
+    }
+    return [`[${key}]`, `# (${schema === undefined ? 'no schema — passthrough' : 'schema uses transforms; see the owner file'})`];
+  }
+
+  if (isRecord(jsonSchema.properties) && Object.keys(jsonSchema.properties).length > 0) {
+    const defaults = isRecord(options.defaultValue) ? options.defaultValue : {};
+    const lines = [`[${key}]`];
+    for (const [name, prop] of Object.entries(jsonSchema.properties)) {
+      const fieldKey = camelToSnake(name);
+      if (defaults[name] !== undefined) {
+        lines.push(`${fieldKey} = ${truncate(toTomlValue(defaults[name]))}`);
+        continue;
+      }
+      const resolved = resolveRef(prop, jsonSchema);
+      const subProps = asJsonSchema(resolved)?.properties;
+      if (isRecord(subProps) && Object.keys(subProps).length > 0) {
+        lines.push('');
+        lines.push(`# [${key}.${fieldKey}]`);
+        lines.push(...renderFieldComments(subProps, jsonSchema, '  '));
+        continue;
+      }
+      const itemProps = asJsonSchema(
+        resolveRef(asJsonSchema(resolved)?.items, jsonSchema),
+      )?.properties;
+      if (isRecord(itemProps) && Object.keys(itemProps).length > 0) {
+        lines.push(`# ${fieldKey}: object[] — one entry per item:`);
+        lines.push(...renderFieldComments(itemProps, jsonSchema, '  '));
+        continue;
+      }
+      lines.push(...renderFieldComments({ [name]: prop }, jsonSchema, ''));
+    }
+    return lines;
+  }
+
+  if (jsonSchema.additionalProperties !== undefined) {
+    const valueSchema = resolveRef(jsonSchema.additionalProperties, jsonSchema);
+    const valueProps = asJsonSchema(valueSchema)?.properties;
+    const lines = [`[${key}]`];
+    if (isRecord(valueProps) && Object.keys(valueProps).length > 0) {
+      lines.push('');
+      lines.push(`# one [${key}."<name>"] table per entry:`);
+      lines.push(`# [${key}."<name>"]`);
+      lines.push(...renderFieldComments(valueProps, jsonSchema, '  '));
+    } else {
+      lines.push(`# <name>: ${describeType(valueSchema)}`);
+    }
+    return lines;
+  }
+
+  if (jsonSchema.type === 'array') {
+    const itemProps = asJsonSchema(resolveRef(jsonSchema.items, jsonSchema))?.properties;
+    if (isRecord(itemProps) && Object.keys(itemProps).length > 0) {
+      return [
+        `# one [[${key}]] table per entry:`,
+        `# [[${key}]]`,
+        ...renderFieldComments(itemProps, jsonSchema, '  '),
+      ];
+    }
+  }
+
+  if (options.defaultValue !== undefined) {
+    return [`${key} = ${truncate(toTomlValue(options.defaultValue))}`];
+  }
+  return [`# ${key}: ${describeType(jsonSchema)}`];
+}
+
+function renderSection(section: ConfigSectionContribution, owner: string | undefined): string[] {
+  const { domain, options } = section;
+  const key = camelToSnake(domain);
+  const lines: string[] = [RULE];
+  lines.push(`# ${domain}${key === domain ? '' : ` (config.toml: ${key})`}`);
+  lines.push(`#   owner: ${owner ?? '(unresolved)'}`);
+  lines.push(`#   scope: ${options.scope ?? 'core'}`);
+  const hooks: string[] = [];
+  if (options.merge !== undefined) hooks.push('custom merge');
+  if (options.fromToml !== undefined) hooks.push('custom fromToml');
+  if (options.toToml !== undefined) hooks.push('custom toToml');
+  if (options.stripEnv !== undefined) hooks.push('stripEnv');
+  if (hooks.length > 0) lines.push(`#   hooks: ${hooks.join(' · ')}`);
+  const deprecations = options.deprecations ?? [];
+  if (deprecations.length > 0) {
+    lines.push('#   deprecations (old key is ignored + warns; rename manually):');
+    for (const deprecation of deprecations) {
+      lines.push(`#     ${deprecation.key} -> ${deprecation.replacement}`);
+    }
+  }
+  const envRows = flattenEnvBindings(options.env);
+  if (envRows.length > 0) {
+    lines.push('#   env:');
+    for (const row of envRows) {
+      lines.push(`#     ${snakePath(row.field)} <- ${row.env}${row.detail === '' ? '' : ` (${row.detail})`}`);
+    }
+  }
+  lines.push(RULE);
+  lines.push('');
+  lines.push(...renderBody(section));
+  return lines;
+}
+
+export async function buildConfigManifest(): Promise<string> {
+  await import('../src/index.ts');
+  const sections = getConfigSectionContributions().toSorted((a, b) =>
+    a.domain.localeCompare(b.domain),
+  );
+  const overlays = getConfigOverlayContributions();
+  const sectionOwners = scanSectionOwners();
+  const overlayOwners = scanOverlayOwners();
+
+  const out: string[] = [
+    '# Config Section Manifest',
+    '#',
+    '# Generated by scripts/gen-config-manifest.mts — do not edit by hand.',
+    '# Regenerate with: pnpm --filter @moonshot-ai/agent-core-v2 gen:config-manifest',
+    '#',
+    '# One [table] per registered config section, in the on-disk config.toml shape',
+    '# (snake_case keys). Un-commented assignments are registered defaults;',
+    '# commented "# field: type" lines describe the remaining schema fields.',
+    '# Values resolve as: default -> config.toml -> env overlay -> memory.',
+    '',
+    `# Index (${sections.length} sections · ${overlays.length} overlay(s))`,
+  ];
+  const width = Math.max(...sections.map((s) => s.domain.length));
+  for (const { domain } of sections) {
+    out.push(`#   ${domain.padEnd(width)}  ${sectionOwners.get(domain) ?? '(unresolved)'}`);
+  }
+  for (const [ident, file] of overlayOwners) {
+    out.push(`#   ${'(overlay) ' + ident}  ${file}`);
+  }
+  out.push('');
+
+  for (const section of sections) {
+    out.push(...renderSection(section, sectionOwners.get(section.domain)));
+    out.push('');
+  }
+  return out.join('\n');
+}
+
+async function main(): Promise<void> {
+  const check = process.argv.includes('--check');
+  const manifest = await buildConfigManifest();
+  if (check) {
+    let current: string | undefined;
+    try {
+      current = readFileSync(MANIFEST_PATH, 'utf-8');
+    } catch {
+      current = undefined;
+    }
+    if (current !== manifest) {
+      console.error(
+        `[gen-config-manifest] ${relative(process.cwd(), MANIFEST_PATH)} is stale. ` +
+          'Regenerate with `pnpm --filter @moonshot-ai/agent-core-v2 gen:config-manifest`.',
+      );
+      process.exit(1);
+    }
+    console.log('[gen-config-manifest] up to date');
+    return;
+  }
+  writeFileSync(MANIFEST_PATH, manifest);
+  console.log(`[gen-config-manifest] wrote ${relative(process.cwd(), MANIFEST_PATH)}`);
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}

packages/agent-core-v2/scripts/gen-contract-types.mjs

@@ -0,0 +1,171 @@
+import { execFileSync } from 'node:child_process';
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+} from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+import { Project, SyntaxKind } from 'ts-morph';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG = join(__dirname, '..');
+const SRC = join(PKG, 'src');
+const TMP = join(PKG, '.contract-types-tmp');
+const TSCONFIG = join(PKG, 'tsconfig.contract.json');
+
+const repoRoot = join(PKG, '..', '..');
+const defaultOut = join(repoRoot, '..', 'kimi-code-mini-bench', 'types', 'agent-core-v2');
+const OUT = process.argv[2] ? join(process.cwd(), process.argv[2]) : defaultOut;
+
+const require = createRequire(import.meta.url);
+const tscBin = require.resolve('typescript/bin/tsc');
+
+function log(msg) {
+  console.log(`[gen-contract-types] ${msg}`);
+}
+
+function walk(dir, out) {
+  for (const entry of readdirSync(dir)) {
+    const p = join(dir, entry);
+    const s = statSync(p);
+    if (s.isDirectory()) walk(p, out);
+    else out.push(p);
+  }
+}
+
+rmSync(TMP, { recursive: true, force: true });
+mkdirSync(TMP, { recursive: true });
+log(`emitting declarations via tsc -> ${relative(PKG, TMP)}`);
+try {
+  execFileSync(process.execPath, [tscBin, '-p', TSCONFIG, '--outDir', TMP], {
+    cwd: PKG,
+    stdio: 'pipe',
+  });
+} catch (err) {
+  const code = err && typeof err === 'object' && 'status' in err ? err.status : 'unknown';
+  log(`tsc exited ${String(code)} (non-fatal; declarations are still emitted)`);
+}
+
+log('scanning for registerScopedService(...) bindings');
+const project = new Project();
+project.addSourceFilesAtPaths(join(SRC, '**', '*.ts'));
+
+const dropByDts = new Map();
+const implFiles = [];
+
+for (const sf of project.getSourceFiles()) {
+  const calls = sf
+    .getDescendantsOfKind(SyntaxKind.CallExpression)
+    .filter((c) => c.getExpression().getText() === 'registerScopedService');
+  if (calls.length === 0) continue;
+
+  implFiles.push(sf.getFilePath());
+  const names = new Set();
+  for (const call of calls) {
+    const args = call.getArguments();
+    if (args.length < 3) continue;
+    const text = args[2].getText().trim();
+    names.add(/^[A-Za-z_$][\w$]*$/.test(text) ? text : '*');
+  }
+
+  const rel = relative(SRC, sf.getFilePath()).replace(/\.ts$/, '.d.ts');
+  const dtsPath = join(TMP, rel);
+  const existing = dropByDts.get(dtsPath) ?? new Set();
+  for (const n of names) existing.add(n);
+  dropByDts.set(dtsPath, existing);
+}
+
+log(`found ${implFiles.length} impl files`);
+
+let scrubbedFiles = 0;
+let scrubbedClasses = 0;
+for (const [dtsPath, names] of dropByDts) {
+  if (!existsSync(dtsPath)) continue;
+  const dtsProject = new Project();
+  const dts = dtsProject.addSourceFileAtPath(dtsPath);
+  const dropAll = names.has('*');
+  let removed = 0;
+  for (const cls of dts.getClasses()) {
+    const clsName = cls.getName();
+    if (dropAll || (clsName !== undefined && names.has(clsName))) {
+      cls.remove();
+      removed++;
+    }
+  }
+  if (removed > 0) {
+    dts.saveSync();
+    scrubbedFiles++;
+    scrubbedClasses += removed;
+  }
+}
+log(`scrubbed ${scrubbedClasses} impl class(es) across ${scrubbedFiles} file(s)`);
+
+function resolveReexportTarget(dtsPath, spec) {
+  const clean = spec.endsWith('.js') ? spec.slice(0, -'.js'.length) : spec;
+  if (clean.startsWith('.')) return join(dirname(dtsPath), `${clean}.d.ts`);
+  if (clean.startsWith('#/')) return join(TMP, `${clean.slice(2)}.d.ts`);
+  return undefined;
+}
+
+let scrubbedReexports = 0;
+const emittedDts = [];
+walk(TMP, emittedDts);
+const reexportProject = new Project();
+for (const dtsPath of emittedDts) {
+  if (!dtsPath.endsWith('.d.ts')) continue;
+  const dts = reexportProject.addSourceFileAtPath(dtsPath);
+  let changed = false;
+  for (const exp of dts.getExportDeclarations()) {
+    const spec = exp.getModuleSpecifierValue();
+    if (spec === undefined) continue;
+    const target = resolveReexportTarget(dtsPath, spec);
+    const names = target === undefined ? undefined : dropByDts.get(target);
+    if (names === undefined) continue;
+    let removedHere = false;
+    for (const specifier of exp.getNamedExports()) {
+      const name = specifier.getNameNode().getText();
+      if (names.has('*') || names.has(name)) {
+        specifier.remove();
+        removedHere = true;
+        scrubbedReexports++;
+      }
+    }
+    if (removedHere && exp.getNamedExports().length === 0) exp.remove();
+    changed = changed || removedHere;
+  }
+  if (changed) dts.saveSync();
+}
+log(`scrubbed ${scrubbedReexports} re-export(s) of impl classes from alias modules`);
+
+rmSync(OUT, { recursive: true, force: true });
+mkdirSync(dirname(OUT), { recursive: true });
+cpSync(TMP, OUT, { recursive: true });
+
+const emitted = [];
+walk(OUT, emitted);
+const dtsCount = emitted.filter((f) => f.endsWith('.d.ts')).length;
+log(`wrote ${dtsCount} declaration file(s) -> ${OUT}`);
+
+const leaks = [];
+for (const [dtsPath, names] of dropByDts) {
+  const outPath = join(OUT, relative(TMP, dtsPath));
+  if (!existsSync(outPath) || names.has('*')) continue;
+  const text = readFileSync(outPath, 'utf8');
+  for (const n of names) {
+    const re = new RegExp(`declare\\s+class\\s+${n}\\b`);
+    if (re.test(text)) leaks.push(`${relative(OUT, outPath)} still declares ${n}`);
+  }
+}
+if (leaks.length > 0) {
+  log(`WARNING: ${leaks.length} possible leak(s):`);
+  for (const l of leaks) log(`  - ${l}`);
+} else {
+  log('leak check passed: no registered impl class survives in its declaring file');
+}

packages/agent-core-v2/scripts/gen-state-manifest.mts

@@ -0,0 +1,882 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import {
+  type CallExpression,
+  Node,
+  Project,
+  SyntaxKind,
+  ts,
+  type Identifier,
+  type PropertyAccessExpression,
+  type Signature,
+  type SourceFile,
+  type Symbol as MorphSymbol,
+  type Type as MorphType,
+  type TypeChecker,
+  type VariableDeclaration,
+} from 'ts-morph';
+
+const PKG = join(import.meta.dirname, '..');
+const REPO_ROOT = join(PKG, '..', '..');
+const SRC = join(PKG, 'src');
+export const MANIFEST_PATH = join(PKG, 'docs', 'state-manifest.d.ts');
+
+const SCOPES = [
+  {
+    dir: 'app',
+    label: 'App',
+    interfaceName: 'AppStateSnapshot',
+    keyUnionName: 'AppStateKey',
+  },
+  {
+    dir: 'workspace',
+    label: 'Workspace',
+    interfaceName: 'WorkspaceStateSnapshot',
+    keyUnionName: 'WorkspaceStateKey',
+  },
+  {
+    dir: 'session',
+    label: 'Session',
+    interfaceName: 'SessionStateSnapshot',
+    keyUnionName: 'SessionStateKey',
+  },
+  {
+    dir: 'agent',
+    label: 'Agent',
+    interfaceName: 'AgentStateSnapshot',
+    keyUnionName: 'AgentStateKey',
+  },
+] as const;
+
+type ScopeDir = (typeof SCOPES)[number]['dir'];
+
+interface KeyDef {
+  readonly constName: string;
+  readonly keyName: string;
+  readonly file: string;
+  readonly exported: boolean;
+  readonly declaration: VariableDeclaration;
+  readonly replayable?: {
+    readonly durable: boolean;
+    readonly undoable: boolean;
+    readonly folds: readonly string[];
+  };
+}
+
+interface Registration {
+  readonly def: KeyDef;
+  readonly scope: ScopeDir;
+}
+
+interface StateManifestModel {
+  readonly registrations: readonly Registration[];
+  readonly unregistered: readonly KeyDef[];
+}
+
+function scopeDirOf(file: string): ScopeDir | undefined {
+  const first = relative(SRC, file).split(/[\\/]/)[0];
+  return SCOPES.some((scope) => scope.dir === first) ? (first as ScopeDir) : undefined;
+}
+
+function isFeaturesFile(file: string): boolean {
+  return relative(SRC, file).split(/[\\/]/)[0] === 'features';
+}
+
+const FEATURES_RECEIVER_SCOPE: Readonly<Record<string, ScopeDir>> = {
+  IAppStateService: 'app',
+  IWorkspaceStateService: 'workspace',
+  ISessionStateService: 'session',
+  IAgentStateService: 'agent',
+};
+
+function receiverScope(
+  expression: PropertyAccessExpression,
+  checker: TypeChecker,
+): ScopeDir | undefined {
+  const typeName = checker.getTypeAtLocation(expression.getExpression()).getSymbol()?.getName();
+  return typeName === undefined ? undefined : FEATURES_RECEIVER_SCOPE[typeName];
+}
+
+function featuresRegisterScope(
+  expression: PropertyAccessExpression,
+  checker: TypeChecker,
+  sf: SourceFile,
+): ScopeDir {
+  const scope = receiverScope(expression, checker);
+  if (scope === undefined) {
+    throw new Error(
+      `[gen-state-manifest] cannot resolve the state-service scope of '${expression.getText()}' ` +
+        `in ${srcRelative(sf.getFilePath())} — register through an ` +
+        'I{App,Workspace,Session,Agent}StateService-typed member.',
+    );
+  }
+  return scope;
+}
+
+function srcRelative(file: string): string {
+  return relative(PKG, file).split('\\').join('/');
+}
+
+function repoRelative(file: string): string {
+  return relative(REPO_ROOT, file).split('\\').join('/');
+}
+
+function tsFieldKey(key: string): string {
+  return /^[$A-Z_a-z][$\w]*$/.test(key) ? key : JSON.stringify(key);
+}
+
+function stableSymbolKey(key: string): string {
+  const match = /^__@(.+)@\d+$/.exec(key);
+  return match === null ? key : `__@${match[1]}`;
+}
+
+function collectKeyDefs(project: Project): Map<VariableDeclaration, KeyDef> {
+  const defs = new Map<VariableDeclaration, KeyDef>();
+  for (const sf of project.getSourceFiles()) {
+    const filePath = sf.getFilePath();
+    if (scopeDirOf(filePath) === undefined && !isFeaturesFile(filePath)) continue;
+    for (const statement of sf.getVariableStatements()) {
+      for (const declaration of statement.getDeclarations()) {
+        const initializer = declaration.getInitializer();
+        if (initializer === undefined || !Node.isCallExpression(initializer)) continue;
+        const parsed = parseDefineStateChain(initializer);
+        if (parsed === undefined) continue;
+        defs.set(declaration, {
+          constName: declaration.getName(),
+          keyName: parsed.keyName,
+          file: sf.getFilePath(),
+          exported: statement.isExported(),
+          declaration,
+          replayable: parsed.replayable,
+        });
+      }
+    }
+  }
+  return defs;
+}
+
+function parseDefineStateChain(
+  initializer: CallExpression,
+): { keyName: string; replayable?: KeyDef['replayable'] } | undefined {
+  let durable = true;
+  let undoable = false;
+  let replayable = false;
+  const folds: string[] = [];
+  let current: CallExpression = initializer;
+  for (;;) {
+    const expression = current.getExpression();
+    if (Node.isIdentifier(expression) && expression.getText() === 'defineState') {
+      const [nameArg] = current.getArguments();
+      if (nameArg === undefined || !Node.isStringLiteral(nameArg)) return undefined;
+      return {
+        keyName: nameArg.getLiteralValue(),
+        replayable: replayable ? { durable, undoable, folds } : undefined,
+      };
+    }
+    if (!Node.isPropertyAccessExpression(expression)) return undefined;
+    const method = expression.getName();
+    if (method === 'replayable') {
+      replayable = true;
+      const [arg] = current.getArguments();
+      if (arg !== undefined && Node.isObjectLiteralExpression(arg)) {
+        const durableProp = arg.getProperty('durable');
+        if (durableProp !== undefined && Node.isPropertyAssignment(durableProp)) {
+          durable = durableProp.getInitializer()?.getText() !== 'false';
+        }
+      }
+    } else if (method === 'undoable') {
+      undoable = true;
+    } else if (method === 'on') {
+      const [eventArg] = current.getArguments();
+      if (eventArg !== undefined) folds.unshift(eventArg.getText());
+    } else {
+      return undefined;
+    }
+    const inner = expression.getExpression();
+    if (!Node.isCallExpression(inner)) return undefined;
+    current = inner;
+  }
+}
+
+function resolveKeyDef(
+  identifier: Identifier,
+  defs: ReadonlyMap<VariableDeclaration, KeyDef>,
+): KeyDef | undefined {
+  for (const info of identifier.getDefinitions()) {
+    const node = info.getDeclarationNode();
+    if (node !== undefined && Node.isVariableDeclaration(node)) {
+      const def = defs.get(node);
+      if (def !== undefined) return def;
+    }
+  }
+  return undefined;
+}
+
+function collectRegistrations(
+  project: Project,
+  defs: ReadonlyMap<VariableDeclaration, KeyDef>,
+): Registration[] {
+  const checker = project.getTypeChecker();
+  const registrations: Registration[] = [];
+  const seen = new Map<string, string>();
+  for (const sf of project.getSourceFiles()) {
+    const fileScope = scopeDirOf(sf.getFilePath());
+    const featuresFile = isFeaturesFile(sf.getFilePath());
+    if (fileScope === undefined && !featuresFile) continue;
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+      const expression = call.getExpression();
+      if (
+        !Node.isPropertyAccessExpression(expression) ||
+        expression.getName() !== 'contributeState'
+      ) {
+        continue;
+      }
+      const args = call.getArguments();
+      const [arg] = args;
+      if (args.length !== 1 || arg === undefined || !Node.isIdentifier(arg)) continue;
+      const def = resolveKeyDef(arg, defs);
+      if (def === undefined) continue;
+      const scope = receiverScope(expression, checker) ?? fileScope ?? featuresRegisterScope(expression, checker, sf);
+      if (!def.exported) {
+        throw new Error(
+          `[gen-state-manifest] state key '${def.keyName}' (${srcRelative(def.file)}) is ` +
+            'registered but its key constant is not exported — the manifest cannot reference it.',
+        );
+      }
+      const dedupe = `${scope}:${def.keyName}`;
+      const seenFile = seen.get(dedupe);
+      if (seenFile !== undefined) {
+        if (seenFile === sf.getFilePath()) continue;
+        throw new Error(
+          `[gen-state-manifest] state key '${def.keyName}' is registered twice in ${scope} scope.`,
+        );
+      }
+      seen.set(dedupe, sf.getFilePath());
+      registrations.push({ def, scope });
+    }
+  }
+  return registrations;
+}
+
+function createProject(): Project {
+  const project = new Project({
+    tsConfigFilePath: join(PKG, 'tsconfig.json'),
+    skipAddingFilesFromTsConfig: true,
+  });
+  project.addSourceFilesAtPaths(join(SRC, '**', '*.ts'));
+  return project;
+}
+
+const NO_TRUNCATION = ts.TypeFormatFlags.NoTruncation;
+
+class TypeRenderer {
+  private readonly checker: ts.TypeChecker;
+  private readonly expanding = new Set<ts.Type>();
+  private readonly expandingNamed: ts.Symbol[] = [];
+  readonly externals = new Set<string>();
+  readonly warnings = new Set<string>();
+
+  constructor(private readonly project: Project) {
+    this.checker = project.getTypeChecker().compilerObject;
+  }
+
+  renderKeyType(def: KeyDef): string {
+    const valueType = def.declaration.getType().getTypeArguments()[0];
+    if (valueType === undefined) {
+      throw new Error(
+        `[gen-state-manifest] cannot resolve the value type of '${def.keyName}' (${srcRelative(def.file)}).`,
+      );
+    }
+    return this.renderType(valueType, def.declaration, 0);
+  }
+
+  private renderType(
+    type: MorphType,
+    location: Node,
+    depth: number,
+    skipSymbol?: ts.Symbol,
+  ): string {
+    if (depth > 40) return this.fallback(type, location, 'depth cap');
+
+    if ((type.getFlags() & ts.TypeFlags.EnumLiteral) !== 0) {
+      return this.renderEnumLiteral(type);
+    }
+
+    if (type.isUnion() && (type.getFlags() & ts.TypeFlags.Boolean) !== 0) return 'boolean';
+
+    if (type.isUnion()) {
+      const alias = this.tryRenderAlias(type, location, depth, skipSymbol);
+      if (alias !== undefined) return alias;
+      const enumUnion = this.tryRenderEnumUnion(type);
+      if (enumUnion !== undefined) return enumUnion;
+      return this.renderUnionMembers(type.getUnionTypes(), location, depth);
+    }
+
+    if (type.isIntersection()) {
+      const alias = this.tryRenderAlias(type, location, depth, skipSymbol);
+      if (alias !== undefined) return alias;
+      return type
+        .getIntersectionTypes()
+        .map((member) => this.renderType(member, location, depth + 1))
+        .join(' & ');
+    }
+
+    if (this.isLeaf(type)) return this.leafText(type);
+
+    if (type.isTuple()) {
+      const elements = type
+        .getTupleElements()
+        .map((element) => this.renderType(element, location, depth + 1));
+      return `[${elements.join(', ')}]`;
+    }
+
+    if (type.isArray()) {
+      const element = type.getArrayElementType();
+      if (element === undefined) return this.fallback(type, location, 'array without element');
+      const rendered = this.renderType(element, location, depth + 1);
+      const text =
+        element.isUnion() || element.isIntersection() ? `(${rendered})[]` : `${rendered}[]`;
+      return type.getSymbol()?.getName() === 'ReadonlyArray' ? `readonly ${text}` : text;
+    }
+
+    if (type.isObject()) {
+      return this.renderObjectType(type, location, depth, skipSymbol);
+    }
+
+    return this.fallback(type, location, 'unhandled type kind');
+  }
+
+  private renderUnionMembers(
+    members: readonly MorphType[],
+    location: Node,
+    depth: number,
+  ): string {
+    const booleanLiterals = members.filter((m) => m.isBooleanLiteral());
+    const collapseBoolean =
+      booleanLiterals.length === 2 &&
+      new Set(booleanLiterals.map((m) => this.leafText(m))).size === 2;
+    const rest = collapseBoolean ? members.filter((m) => !m.isBooleanLiteral()) : members;
+    const rank = (type: MorphType): number => (type.isNull() ? 1 : type.isUndefined() ? 2 : 0);
+    const rendered = rest
+      .map((member) => ({ member, rank: rank(member) }))
+      .toSorted((a, b) => a.rank - b.rank)
+      .map(({ member }) => ({
+        member,
+        text: this.renderType(member, location, depth + 1),
+      }));
+    const multi = rendered.length + (collapseBoolean ? 1 : 0) > 1;
+    const parts = rendered.map(({ member, text }) =>
+      multi && this.needsParensInUnion(member) ? `(${text})` : text,
+    );
+    if (collapseBoolean) parts.unshift('boolean');
+    return [...new Set(parts)].join(' | ');
+  }
+
+  private isLeaf(type: MorphType): boolean {
+    const flags = type.getFlags();
+    return (
+      type.isString() ||
+      type.isNumber() ||
+      type.isBoolean() ||
+      type.isStringLiteral() ||
+      type.isNumberLiteral() ||
+      type.isBooleanLiteral() ||
+      type.isNull() ||
+      type.isUndefined() ||
+      type.isUnknown() ||
+      type.isAny() ||
+      type.isNever() ||
+      type.isTypeParameter() ||
+      (flags &
+        (ts.TypeFlags.Void |
+          ts.TypeFlags.BigInt |
+          ts.TypeFlags.BigIntLiteral |
+          ts.TypeFlags.ESSymbol |
+          ts.TypeFlags.UniqueESSymbol |
+          ts.TypeFlags.TemplateLiteral)) !==
+        0
+    );
+  }
+
+  private leafText(type: MorphType): string {
+    const text = this.checker.typeToString(type.compilerType, undefined, NO_TRUNCATION);
+    if (text.length >= 2 && text.startsWith('"') && text.endsWith('"')) {
+      const value = JSON.parse(text) as string;
+      return value.includes("'") ? JSON.stringify(value) : `'${value}'`;
+    }
+    return text;
+  }
+
+  private needsParensInUnion(type: MorphType): boolean {
+    return type.isIntersection() || (type.isObject() && type.getCallSignatures().length > 0);
+  }
+
+  private fallback(type: MorphType, location: Node, reason: string): string {
+    const text = this.checker.typeToString(type.compilerType, location.compilerNode, NO_TRUNCATION);
+    this.warnings.add(`${reason}: fell back to '${text.slice(0, 80)}'`);
+    return text;
+  }
+
+  private enumLiteralValue(type: MorphType): string {
+    const value = (type.compilerType as ts.LiteralType).value;
+    if (typeof value === 'string') {
+      return value.includes("'") ? JSON.stringify(value) : `'${value}'`;
+    }
+    if (typeof value === 'number') return String(value);
+    return this.leafText(type);
+  }
+
+  private enumDeclOf(type: MorphType): Node | undefined {
+    const memberDecl = type.getSymbol()?.getDeclarations()[0];
+    if (memberDecl === undefined || !Node.isEnumMember(memberDecl)) return undefined;
+    return memberDecl.getParent();
+  }
+
+  private renderEnumLiteral(type: MorphType): string {
+    const enumDecl = this.enumDeclOf(type);
+    const text = this.enumLiteralValue(type);
+    if (enumDecl !== undefined && Node.isEnumDeclaration(enumDecl)) {
+      const sym = enumDecl.getSymbol();
+      if (sym !== undefined) {
+        return `/* ${sym.getName()} — ${repoRelative(enumDecl.getSourceFile().getFilePath())} */ ${text}`;
+      }
+    }
+    return text;
+  }
+
+  private tryRenderEnumUnion(type: MorphType): string | undefined {
+    const members = type.getUnionTypes();
+    if (members.length === 0) return undefined;
+    let enumDecl: Node | undefined;
+    for (const member of members) {
+      if ((member.getFlags() & ts.TypeFlags.EnumLiteral) === 0) return undefined;
+      const parent = this.enumDeclOf(member);
+      if (parent === undefined) return undefined;
+      if (enumDecl === undefined) enumDecl = parent;
+      else if (parent !== enumDecl) return undefined;
+    }
+    if (enumDecl === undefined || !Node.isEnumDeclaration(enumDecl)) return undefined;
+    if (enumDecl.getMembers().length !== members.length) return undefined;
+    const sym = enumDecl.getSymbol();
+    if (sym === undefined) return undefined;
+    const values = members.map((member) => this.enumLiteralValue(member));
+    return `/* ${sym.getName()} — ${repoRelative(enumDecl.getSourceFile().getFilePath())} */ ${values.join(' | ')}`;
+  }
+
+  private classify(sym: MorphSymbol): 'named' | 'ambient' | 'inline' {
+    const decls = sym.getDeclarations();
+    if (decls.length === 0) return 'inline';
+    const inNodeModules = (file: string) => /[\\/]node_modules[\\/]/.test(file);
+    if (decls.every((d) => !inNodeModules(d.getSourceFile().getFilePath()))) {
+      const named = decls.some(
+        (d) =>
+          Node.isInterfaceDeclaration(d) ||
+          Node.isClassDeclaration(d) ||
+          Node.isTypeAliasDeclaration(d) ||
+          Node.isEnumDeclaration(d),
+      );
+      const generic = decls.some(
+        (d) =>
+          (Node.isInterfaceDeclaration(d) ||
+            Node.isClassDeclaration(d) ||
+            Node.isTypeAliasDeclaration(d)) &&
+          d.getTypeParameters().length > 0,
+      );
+      return named && !generic ? 'named' : 'inline';
+    }
+    if (decls.every((d) => inNodeModules(d.getSourceFile().getFilePath()))) return 'ambient';
+    return 'inline';
+  }
+
+  private noteExternal(sym: MorphSymbol): void {
+    const isTsLib = (file: string) => /[\\/]node_modules[\\/]typescript[\\/]lib[\\/]/.test(file);
+    if (sym.getDeclarations().some((d) => !isTsLib(d.getSourceFile().getFilePath()))) {
+      this.externals.add(sym.getName());
+    }
+  }
+
+  private renderNamed(sym: MorphSymbol, expand: () => string): string {
+    const decl = sym.getDeclarations()[0];
+    const origin =
+      decl !== undefined
+        ? repoRelative(decl.getSourceFile().getFilePath())
+        : '(unknown source)';
+    const name = sym.getName();
+    if (this.expandingNamed.includes(sym.compilerSymbol)) {
+      return `/* ${name} — recursive (${origin}) */ unknown`;
+    }
+    this.expandingNamed.push(sym.compilerSymbol);
+    try {
+      return `/* ${name} — ${origin} */ ${expand()}`;
+    } finally {
+      this.expandingNamed.pop();
+    }
+  }
+
+  private tryRenderAlias(
+    type: MorphType,
+    location: Node,
+    depth: number,
+    skipSymbol?: ts.Symbol,
+  ): string | undefined {
+    const alias = type.getAliasSymbol();
+    if (alias === undefined || alias.compilerSymbol === skipSymbol) return undefined;
+    const kind = this.classify(alias);
+    if (kind === 'named') {
+      const decl = alias.getDeclarations().find((d) => Node.isTypeAliasDeclaration(d));
+      if (decl === undefined || !Node.isTypeAliasDeclaration(decl)) return undefined;
+      return this.renderNamed(alias, () =>
+        this.renderType(decl.getType(), decl, depth + 1, alias.compilerSymbol),
+      );
+    }
+    if (kind === 'ambient') {
+      const args = type.getAliasTypeArguments();
+      if (args.length === 0) return undefined;
+      this.noteExternal(alias);
+      const rendered = args.map((arg) => this.renderType(arg, location, depth + 1));
+      return `${alias.getName()}<${rendered.join(', ')}>`;
+    }
+    return undefined;
+  }
+
+  private renderObjectType(
+    type: MorphType,
+    location: Node,
+    depth: number,
+    skipSymbol?: ts.Symbol,
+  ): string {
+    const alias = this.tryRenderAlias(type, location, depth, skipSymbol);
+    if (alias !== undefined) return alias;
+    const sym = type.getSymbol();
+    const typeArgs = type.getTypeArguments();
+    const anonymous = sym === undefined || /^__(type|object)$/.test(sym.getName());
+    if (!anonymous && sym.compilerSymbol !== skipSymbol) {
+      const kind = this.classify(sym);
+      if (kind === 'named' && typeArgs.length === 0) {
+        return this.renderNamed(sym, () => this.renderStructural(type, location, depth));
+      }
+      if (kind === 'ambient') {
+        this.noteExternal(sym);
+        const name = sym.getName();
+        if (typeArgs.length === 0) return name;
+        const args = typeArgs.map((arg) => this.renderType(arg, location, depth + 1));
+        return `${name}<${args.join(', ')}>`;
+      }
+    }
+    return this.renderStructural(type, location, depth);
+  }
+
+  private renderStructural(type: MorphType, location: Node, depth: number): string {
+    if (this.expanding.has(type.compilerType)) {
+      return this.fallback(type, location, 'cycle expanding');
+    }
+    this.expanding.add(type.compilerType);
+    try {
+      const callSignatures = type.getCallSignatures();
+      const props = type.getProperties().filter((prop) => this.isPublic(prop));
+      const stringIndex = type.getStringIndexType();
+      const numberIndex = type.getNumberIndexType();
+      if (
+        callSignatures.length > 0 &&
+        props.length === 0 &&
+        stringIndex === undefined &&
+        numberIndex === undefined
+      ) {
+        if (callSignatures.length === 1 && callSignatures[0] !== undefined) {
+          return this.renderSignature(callSignatures[0], location, depth, 'arrow');
+        }
+        return callSignatures
+          .map((sig) => `(${this.renderSignature(sig, location, depth, 'arrow')})`)
+          .join(' & ');
+      }
+      const body = this.renderObjectBody(type, location, depth, callSignatures, props);
+      if (body.length === 0) return '{}';
+      return `{\n${body.join('\n')}\n}`;
+    } finally {
+      this.expanding.delete(type.compilerType);
+    }
+  }
+
+  private renderObjectBody(
+    type: MorphType,
+    location: Node,
+    depth: number,
+    callSignatures?: readonly Signature[],
+    props?: readonly MorphSymbol[],
+  ): string[] {
+    const lines: string[] = [];
+    for (const sig of callSignatures ?? type.getCallSignatures()) {
+      lines.push(`  ${this.renderSignature(sig, location, depth, 'call')};`);
+    }
+    for (const prop of props ?? type.getProperties().filter((p) => this.isPublic(p))) {
+      const decl = prop.getDeclarations()[0];
+      const at = decl ?? location;
+      const propType = prop.getTypeAtLocation(at);
+      const optional = (prop.getFlags() & ts.SymbolFlags.Optional) !== 0;
+      const rendered =
+        optional && propType.isUnion()
+          ? this.renderUnionMembers(
+              propType.getUnionTypes().filter((member) => !member.isUndefined()),
+              at,
+              depth,
+            )
+          : this.renderType(propType, at, depth + 1);
+      const readonly =
+        decl !== undefined && Node.isPropertySignature(decl) && decl.isReadonly()
+          ? 'readonly '
+          : '';
+      const propLines = rendered.split('\n');
+      propLines[propLines.length - 1] += ';';
+      lines.push(
+        `  ${readonly}${tsFieldKey(stableSymbolKey(prop.getName()))}${optional ? '?' : ''}: ${propLines[0]}`,
+        ...propLines.slice(1).map((line) => `  ${line}`),
+      );
+    }
+    const stringIndex = type.getStringIndexType();
+    if (stringIndex !== undefined) {
+      lines.push(`  [key: string]: ${this.renderType(stringIndex, location, depth + 1)};`);
+    }
+    const numberIndex = type.getNumberIndexType();
+    if (numberIndex !== undefined) {
+      lines.push(`  [key: number]: ${this.renderType(numberIndex, location, depth + 1)};`);
+    }
+    return lines;
+  }
+
+  private renderSignature(
+    sig: Signature,
+    location: Node,
+    depth: number,
+    style: 'arrow' | 'call',
+  ): string {
+    const params: string[] = [];
+    for (const param of sig.getParameters()) {
+      if (param.getName() === 'this') continue;
+      const decl = param.getDeclarations()[0];
+      const at = decl ?? location;
+      const paramType = param.getTypeAtLocation(at);
+      let optional = (param.getFlags() & ts.SymbolFlags.Optional) !== 0;
+      let rest = false;
+      if (decl !== undefined && Node.isParameterDeclaration(decl)) {
+        optional = optional || decl.hasQuestionToken() || decl.getInitializer() !== undefined;
+        rest = decl.isRestParameter();
+      }
+      const rendered =
+        optional && paramType.isUnion()
+          ? this.renderUnionMembers(
+              paramType.getUnionTypes().filter((member) => !member.isUndefined()),
+              at,
+              depth,
+            )
+          : this.renderType(paramType, at, depth + 1);
+      params.push(`${rest ? '...' : ''}${param.getName()}${optional ? '?' : ''}: ${rendered}`);
+    }
+    const returnType = this.renderType(sig.getReturnType(), location, depth + 1);
+    return style === 'arrow'
+      ? `(${params.join(', ')}) => ${returnType}`
+      : `(${params.join(', ')}): ${returnType}`;
+  }
+
+  private isPublic(prop: MorphSymbol): boolean {
+    if (prop.getName().startsWith('#')) return false;
+    return !prop.getDeclarations().some((decl) => {
+      const modifiers = ts.canHaveModifiers(decl.compilerNode)
+        ? ts.getModifiers(decl.compilerNode)
+        : undefined;
+      return (
+        modifiers !== undefined &&
+        modifiers.some(
+          (m) =>
+            m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword,
+        )
+      );
+    });
+  }
+}
+
+function renderManifest(
+  model: StateManifestModel,
+  project: Project,
+): { manifest: string; warnings: readonly string[] } {
+  const renderer = new TypeRenderer(project);
+  const byScope = new Map<ScopeDir, Registration[]>();
+  for (const scope of SCOPES) byScope.set(scope.dir, []);
+  for (const registration of model.registrations) byScope.get(registration.scope)?.push(registration);
+  for (const [dir, regs] of byScope) {
+    byScope.set(
+      dir,
+      regs.toSorted((a, b) => a.def.keyName.localeCompare(b.def.keyName)),
+    );
+  }
+
+  const sections: string[] = [];
+  for (const scope of SCOPES) {
+    const regs = byScope.get(scope.dir) ?? [];
+    const lines = [
+      `/** ${scope.label}-scope keys registered into I${scope.label}StateService. */`,
+      `export interface ${scope.interfaceName} {`,
+    ];
+    const byFile = new Map<string, Registration[]>();
+    for (const r of regs) {
+      const list = byFile.get(r.def.file) ?? [];
+      list.push(r);
+      byFile.set(r.def.file, list);
+    }
+    for (const file of [...byFile.keys()].toSorted()) {
+      lines.push(`  // ${srcRelative(file)}`);
+      for (const r of byFile.get(file) ?? []) {
+        if (r.def.replayable !== undefined) {
+          const meta = r.def.replayable;
+          const flags = [
+            meta.durable ? 'durable' : 'transient',
+            ...(meta.undoable ? ['undoable'] : []),
+          ];
+          lines.push(
+            `  // replayable · ${flags.join(' · ')} — folds: ${meta.folds.length > 0 ? meta.folds.join(', ') : '(protocol only)'}`,
+          );
+        }
+        const rendered = renderer.renderKeyType(r.def).split('\n');
+        rendered[rendered.length - 1] += ';';
+        lines.push(`  '${r.def.keyName}': ${rendered[0]}`, ...rendered.slice(1).map((l) => `  ${l}`));
+      }
+    }
+    lines.push('}');
+    lines.push('');
+    lines.push(`export type ${scope.keyUnionName} = keyof ${scope.interfaceName};`);
+    sections.push(lines.join('\n'));
+  }
+
+  const counts = SCOPES.map((s) => `${s.label}: ${byScope.get(s.dir)?.length ?? 0} keys`).join(
+    ' · ',
+  );
+  const out: string[] = [
+    '// App, Workspace, Session & Agent State Manifest',
+    '//',
+    '// Generated by scripts/gen-state-manifest.mts — do not edit by hand.',
+    '// Regenerate with: pnpm --filter @moonshot-ai/agent-core-v2 gen:state-manifest',
+    '//',
+    '// Every state key registered into the App-scope IAppStateService, the',
+    '// Workspace-scope IWorkspaceStateService, the Session-scope',
+    '// ISessionStateService, or the Agent-scope IAgentStateService (see',
+    '// src/_base/state/stateRegistry.ts), collected statically from the',
+    '// `states.contributeState(...)` call sites and the replayable key chains — a',
+    '// `defineState(...).replayable(...)` key is contributed into the Agent-scope',
+    '// service by its owner service at construction, and',
+    '// carries a `// replayable · durable|transient · undoable? — folds: ...` line.',
+    '// Replayable values are excluded from snapshot()/inspect(). A key defined via',
+    '// defineState but never registered nor replayable does not appear here. Each entry shows the',
+    '// compile-time StateKey<T> value type fully expanded inline, so the manifest is',
+    '// self-contained (no imports, no helper declarations). A named type is marked',
+    '// at its expansion site with a `/* TypeName — source/file.ts */` comment; a',
+    '// `/* TypeName — recursive (...) */ unknown` marker stops a recursive expansion.',
+    '// Lib globals (Map/Set/Record/…) are referenced as-is. Generic instantiations',
+    '// expand structurally; classes render as their public instance shape. The',
+    '// defining source file heads each group.',
+  ];
+  if (renderer.externals.size > 0) {
+    out.push(
+      '//',
+      `// External ambient types referenced but not expanded (from node_modules): ${[...renderer.externals].toSorted().join(', ')}`,
+    );
+  }
+  out.push(
+    '//',
+    '// snapshot() returns JSON-safe deep copies of these values: Maps become plain',
+    '// objects (or [key, value] entry arrays when a key is not string/number), Sets',
+    '// become arrays, bigints become strings, functions are dropped, circular',
+    "// references become '(circular)', and class instances collapse to a '(ClassName)'",
+    '// marker — the wire shape of an entry is the JSON projection of the type here.',
+    '//',
+    `// Index (${counts})`,
+  );
+  for (const scope of SCOPES) {
+    const regs = byScope.get(scope.dir) ?? [];
+    const width = Math.max(0, ...regs.map((r) => r.def.keyName.length));
+    out.push(`//   ${scope.label}`);
+    for (const r of regs) {
+      out.push(`//     ${r.def.keyName.padEnd(width)}  ${srcRelative(r.def.file)}`);
+    }
+  }
+  out.push('');
+  out.push(...sections.flatMap((section) => [section, '']));
+  return { manifest: `${out.join('\n').trimEnd()}\n`, warnings: [...renderer.warnings] };
+}
+
+interface BuildResult {
+  readonly model: StateManifestModel;
+  readonly manifest: string;
+  readonly warnings: readonly string[];
+}
+
+function buildAll(): BuildResult {
+  const project = createProject();
+  const defs = collectKeyDefs(project);
+  const registrations = collectRegistrations(project, defs);
+  const registered = new Set(registrations.map((r) => r.def));
+  for (const def of defs.values()) {
+    if (def.replayable === undefined) continue;
+    if (!registered.has(def)) {
+      throw new Error(
+        `[gen-state-manifest] replayable state key '${def.keyName}' (${srcRelative(def.file)}) is ` +
+          'never contributed — its owner service must contributeState it into the Agent-scope state service.',
+      );
+    }
+    for (const registration of registrations) {
+      if (registration.def === def && registration.scope !== 'agent') {
+        throw new Error(
+          `[gen-state-manifest] replayable state key '${def.keyName}' (${srcRelative(def.file)}) is ` +
+            `contributed into the ${registration.scope} scope — replayable keys belong to the Agent scope.`,
+        );
+      }
+    }
+  }
+  const unregistered = [...defs.values()].filter((def) => !registered.has(def));
+  const model: StateManifestModel = { registrations, unregistered };
+  const { manifest, warnings } = renderManifest(model, project);
+  return { model, manifest, warnings };
+}
+
+export function buildStateManifest(): string {
+  return buildAll().manifest;
+}
+
+function main(): void {
+  const check = process.argv.includes('--check');
+  const { model, manifest, warnings } = buildAll();
+  for (const warning of warnings) {
+    console.warn(`[gen-state-manifest] warning: ${warning}`);
+  }
+  if (check) {
+    let current: string | undefined;
+    try {
+      current = readFileSync(MANIFEST_PATH, 'utf-8');
+    } catch {
+      current = undefined;
+    }
+    if (current !== manifest) {
+      console.error(
+        `[gen-state-manifest] ${relative(process.cwd(), MANIFEST_PATH)} is stale. ` +
+          'Regenerate with `pnpm --filter @moonshot-ai/agent-core-v2 gen:state-manifest`.',
+      );
+      process.exit(1);
+    }
+    console.log('[gen-state-manifest] up to date');
+    return;
+  }
+  writeFileSync(MANIFEST_PATH, manifest);
+  console.log(`[gen-state-manifest] wrote ${relative(process.cwd(), MANIFEST_PATH)}`);
+  if (model.unregistered.length > 0) {
+    console.log(
+      `[gen-state-manifest] note: ${model.unregistered.length} defineState key(s) never registered (excluded):`,
+    );
+    for (const def of model.unregistered) {
+      console.log(`  - ${def.keyName} (${srcRelative(def.file)})`);
+    }
+  }
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

packages/agent-core-v2/scripts/gen-wire-manifest.mts

@@ -0,0 +1,1039 @@
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { EVENT2_REGISTRY } from '#/app/event/event2';
+
+import {
+  asJsonSchema,
+  describeType,
+  isRecord,
+  resolveRef,
+  toJsonSchema,
+  truncate,
+  type JsonSchema,
+} from './lib/jsonSchema.mts';
+
+const PKG = join(import.meta.dirname, '..');
+const SRC = join(PKG, 'src');
+export const MANIFEST_PATH = join(PKG, 'docs', 'wire-manifest.d.ts');
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const p = join(dir, entry);
+    if (statSync(p).isDirectory()) walk(p, out);
+    else if (entry.endsWith('.ts')) out.push(p);
+  }
+  return out;
+}
+
+const TYPE_DECL_RE = /static\s+override\s+readonly\s+type\s*=\s*'([^']+)'/g;
+const DURABLE_DECL_RE = /static\s+override\s+readonly\s+durable\s*=\s*true/;
+const CLASS_DECL_RE = /class\s+(\w+)\s+extends\s+(?:AgentEvent2|Event2)/g;
+
+function scanEventDeclarations(): {
+  owners: Map<string, string>;
+  importFiles: string[];
+  durableTypes: Set<string>;
+  classTypes: Map<string, string>;
+} {
+  const owners = new Map<string, string>();
+  const importFiles: string[] = [];
+  const durableTypes = new Set<string>();
+  const classTypes = new Map<string, string>();
+  for (const file of walk(SRC)) {
+    const source = readFileSync(file, 'utf-8');
+    const matches = [...source.matchAll(TYPE_DECL_RE)];
+    const hasStates = source.includes('.replayable(');
+    if (matches.length > 0 || hasStates) importFiles.push(file);
+    for (const [i, match] of matches.entries()) {
+      const type = match[1];
+      if (type === undefined) continue;
+      owners.set(type, relative(PKG, file));
+      const windowEnd = i + 1 < matches.length ? matches[i + 1]!.index : source.length;
+      if (DURABLE_DECL_RE.test(source.slice(match.index, windowEnd))) durableTypes.add(type);
+    }
+    const classMatches = [...source.matchAll(CLASS_DECL_RE)];
+    for (const [i, match] of classMatches.entries()) {
+      const className = match[1];
+      if (className === undefined) continue;
+      const windowEnd = i + 1 < classMatches.length ? classMatches[i + 1]!.index : source.length;
+      const typeMatch = /static\s+override\s+readonly\s+type\s*=\s*'([^']+)'/.exec(
+        source.slice(match.index, windowEnd),
+      );
+      if (typeMatch?.[1] !== undefined) classTypes.set(className, typeMatch[1]);
+    }
+  }
+  return { owners, importFiles, durableTypes, classTypes };
+}
+
+function scanMigrationChain(): string {
+  const dir = join(SRC, 'wire', 'migration');
+  const pairs: { source: string; target: string }[] = [];
+  for (const entry of readdirSync(dir)) {
+    if (!/^v[\d.]+\.ts$/.test(entry)) continue;
+    const source = readFileSync(join(dir, entry), 'utf-8');
+    const sourceVersion = /sourceVersion:\s*'([^']+)'/.exec(source)?.[1];
+    const targetVersion = /targetVersion:\s*'([^']+)'/.exec(source)?.[1];
+    if (sourceVersion !== undefined && targetVersion !== undefined) {
+      pairs.push({ source: sourceVersion, target: targetVersion });
+    }
+  }
+  pairs.sort((a, b) => a.source.localeCompare(b.source, undefined, { numeric: true }));
+  const chain = pairs.flatMap((p, i) => (i === 0 ? [p.source, p.target] : [p.target]));
+  return chain.join(' -> ');
+}
+
+interface ReplayableStateScan {
+  readonly keyName: string;
+  readonly constName: string;
+  readonly undoable: boolean;
+  readonly blobs: boolean;
+  readonly foldClasses: string[];
+}
+
+const ON_FOLD_RE = /\.on\(\s*([A-Za-z_$][\w$]*)/g;
+const KEY_ON_RE = /\b([A-Za-z_$][\w$]*)\.on\(\s*([A-Za-z_$][\w$]*)/g;
+const PROTOCOL_EVENT_RE = /(?:appendMessage|applyCompaction|clear|undo):\s*([A-Za-z_$][\w$]*)/g;
+
+function readCallArguments(text: string, parenIndex: number): string {
+  let depth = 0;
+  for (let i = parenIndex; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "'" || ch === '"' || ch === '`') {
+      const quote = ch;
+      i += 1;
+      while (i < text.length && text[i] !== quote) {
+        if (text[i] === '\\') i += 1;
+        i += 1;
+      }
+      continue;
+    }
+    if (ch === '(') depth += 1;
+    else if (ch === ')') {
+      depth -= 1;
+      if (depth === 0) return text.slice(parenIndex + 1, i);
+    }
+  }
+  return text.slice(parenIndex + 1);
+}
+
+function readChain(source: string, start: number): string {
+  let depth = 0;
+  const n = source.length;
+  for (let i = start; i < n; i++) {
+    const ch = source[i];
+    if (ch === "'" || ch === '"' || ch === '`') {
+      const quote = ch;
+      i += 1;
+      while (i < n && source[i] !== quote) {
+        if (source[i] === '\\') i += 1;
+        i += 1;
+      }
+      continue;
+    }
+    if (ch === '{' || ch === '(' || ch === '[') depth += 1;
+    else if (ch === '}' || ch === ')' || ch === ']') depth = Math.max(0, depth - 1);
+    else if (ch === ';' && depth === 0) return source.slice(start, i);
+  }
+  return source.slice(start);
+}
+
+function scanReplayableStates(): ReplayableStateScan[] {
+  const states: ReplayableStateScan[] = [];
+  const byConst = new Map<string, ReplayableStateScan>();
+  const constChainRe =
+    /(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*defineState\(\s*'([^']+)'/g;
+  for (const file of walk(SRC)) {
+    const source = readFileSync(file, 'utf-8');
+    if (!source.includes('.replayable(') && !source.includes('.on(')) continue;
+    for (const match of source.matchAll(constChainRe)) {
+      const constName = match[1];
+      const keyName = match[2];
+      if (constName === undefined || keyName === undefined) continue;
+      const chain = readChain(source, source.indexOf('defineState', match.index));
+      const replayableIndex = chain.indexOf('.replayable(');
+      if (replayableIndex === -1) continue;
+      const replayableArgs = readCallArguments(chain, replayableIndex + '.replayable'.length);
+      const scan: ReplayableStateScan = {
+        keyName,
+        constName,
+        undoable: chain.includes('.undoable('),
+        blobs: /\bblobs\s*:/.test(replayableArgs),
+        foldClasses: [...chain.matchAll(ON_FOLD_RE)].map((m) => m[1]!),
+      };
+      states.push(scan);
+      byConst.set(constName, scan);
+    }
+  }
+  for (const file of walk(SRC)) {
+    const source = readFileSync(file, 'utf-8');
+    if (!source.includes('.on(')) continue;
+    for (const match of source.matchAll(KEY_ON_RE)) {
+      const scan = byConst.get(match[1]!);
+      const cls = match[2];
+      if (scan === undefined || cls === undefined) continue;
+      if (!scan.foldClasses.includes(cls)) scan.foldClasses.push(cls);
+    }
+  }
+  return states;
+}
+
+function scanUndoableProtocolTypes(classTypes: ReadonlyMap<string, string>): string[] {
+  for (const file of walk(SRC)) {
+    const source = readFileSync(file, 'utf-8');
+    const index = source.indexOf('registerUndoableProtocol(');
+    if (index === -1) continue;
+    const window = readChain(source, index);
+    const types: string[] = [];
+    for (const match of window.matchAll(PROTOCOL_EVENT_RE)) {
+      const cls = match[1]!;
+      const type = classTypes.get(cls);
+      if (type === undefined) {
+        throw new Error(
+          `[gen-wire-manifest] undoable protocol event class '${cls}' has no resolved type`,
+        );
+      }
+      types.push(type);
+    }
+    return types;
+  }
+  throw new Error('[gen-wire-manifest] registerUndoableProtocol call not found under src/');
+}
+
+type SketchDict = { [key: string]: Sketch };
+type Sketch = string | SketchDict | [Sketch];
+
+const TYPE_KEY = '_type';
+const MORE_KEY = '…';
+
+function stringifySketch(sketch: Sketch): string {
+  if (typeof sketch === 'string') return sketch;
+  if (Array.isArray(sketch)) {
+    const inner = stringifySketch(sketch[0]);
+    return inner.includes('|') ? `(${inner})[]` : `${inner}[]`;
+  }
+  return `{ ${Object.entries(sketch)
+    .map(([k, v]) => `${k}: ${stringifySketch(v)}`)
+    .join(', ')} }`;
+}
+
+function sketchFromJsonSchema(schema: unknown, root: JsonSchema, depth: number): Sketch {
+  const resolved = resolveRef(schema, root);
+  const s = asJsonSchema(resolved);
+  if (s !== undefined && depth < 4) {
+    if (isRecord(s.properties) && Object.keys(s.properties).length > 0) {
+      const required = new Set(Array.isArray(s.required) ? s.required : []);
+      const dict: SketchDict = {};
+      for (const [name, prop] of Object.entries(s.properties)) {
+        dict[required.has(name) ? name : `${name}?`] = sketchFromJsonSchema(prop, root, depth + 1);
+      }
+      return dict;
+    }
+    if (s.type === 'array' && s.items !== undefined) {
+      const inner = sketchFromJsonSchema(s.items, root, depth + 1);
+      if (typeof inner !== 'string') return [inner];
+    }
+  }
+  return describeType(resolved, tsQuote);
+}
+
+function buildPayloadSketch(
+  schema: unknown,
+  staticSketch?: string | Map<string, Sketch>,
+): Sketch {
+  const jsonSchema = toJsonSchema(schema);
+  if (jsonSchema === undefined) {
+    if (typeof staticSketch === 'string') return staticSketch;
+    if (staticSketch !== undefined && staticSketch.size > 0) {
+      return Object.fromEntries(staticSketch);
+    }
+    return '(schema uses transforms; see the owner file)';
+  }
+  if (isRecord(jsonSchema.properties) && Object.keys(jsonSchema.properties).length > 0) {
+    const required = new Set(Array.isArray(jsonSchema.required) ? jsonSchema.required : []);
+    const dict: SketchDict = {};
+    for (const [name, prop] of Object.entries(jsonSchema.properties)) {
+      dict[required.has(name) ? name : `${name}?`] = sketchFromJsonSchema(prop, jsonSchema, 0);
+    }
+    return dict;
+  }
+  if (
+    jsonSchema.type === 'object' &&
+    (jsonSchema.additionalProperties === undefined || jsonSchema.additionalProperties === false)
+  ) {
+    return {};
+  }
+  return describeType(jsonSchema, tsQuote);
+}
+
+function pascalCase(name: string): string {
+  return name
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((part) => (part[0] ?? '').toUpperCase() + part.slice(1))
+    .join('');
+}
+
+function tsFieldKey(key: string): string {
+  return /^[$A-Z_a-z][$\w]*$/.test(key) ? key : JSON.stringify(key);
+}
+
+function sketchStringToTs(text: string): { type: string; doc?: string } {
+  let t = text.trim();
+  const docs: string[] = [];
+  const named = /^([A-Z][$\w]*) = ([\s\S]+)$/.exec(t);
+  if (named?.[1] !== undefined && named[2] !== undefined) {
+    docs.push(named[1]);
+    t = named[2].trim();
+  }
+  const spread = /^((?:\.\.\.[$\w]+(?: \+ )?)+) & ([\s\S]+)$/.exec(t);
+  if (spread?.[1] !== undefined && spread[2] !== undefined) {
+    docs.push(`shared base: ${spread[1]}`);
+    t = spread[2].trim();
+  }
+  t = t.replaceAll(/union on [$\w]+: /g, '');
+  t = t.replaceAll(/\brecord</g, 'Record<');
+  t = t.replaceAll(/\binteger\b/g, 'number');
+  return { type: t, doc: docs.length > 0 ? docs.join(' · ') : undefined };
+}
+
+function renderTsType(sketch: Sketch, indent: string): { doc?: string; lines: string[] } {
+  if (typeof sketch === 'string') {
+    const { type, doc } = sketchStringToTs(sketch);
+    return { doc, lines: [type] };
+  }
+  if (Array.isArray(sketch)) {
+    const inner = renderTsType(sketch[0], indent);
+    const lines = [...inner.lines];
+    lines[lines.length - 1] += '[]';
+    return { doc: inner.doc, lines };
+  }
+  const doc = typeof sketch[TYPE_KEY] === 'string' ? sketch[TYPE_KEY] : undefined;
+  const lines = ['{'];
+  emitTsDict(lines, sketch, indent + '  ');
+  lines.push(`${indent}}`);
+  return { doc, lines };
+}
+
+function emitTsDict(lines: string[], dict: SketchDict, indent: string): void {
+  for (const [key, sketch] of Object.entries(dict)) {
+    if (key === MORE_KEY) {
+      lines.push(`${indent}// …`);
+      continue;
+    }
+    if (key === TYPE_KEY) continue;
+    if (key.startsWith('...')) {
+      lines.push(`${indent}// spread: ${key}`);
+      continue;
+    }
+    const optional = key.endsWith('?');
+    const fieldKey = tsFieldKey(optional ? key.slice(0, -1) : key);
+    const { doc, lines: typeLines } = renderTsType(sketch, indent);
+    if (doc !== undefined) lines.push(`${indent}/** ${doc} */`);
+    lines.push(`${indent}${fieldKey}${optional ? '?' : ''}: ${typeLines[0]}${typeLines.length === 1 ? ';' : ''}`);
+    if (typeLines.length > 1) {
+      lines.push(...typeLines.slice(1, -1));
+      lines.push(`${typeLines[typeLines.length - 1]};`);
+    }
+  }
+}
+
+function renderPayloadDecl(
+  entry: { type: string },
+  owner: string | undefined,
+  states: string[],
+  flags: string[],
+  sketch: Sketch,
+): string[] {
+  const name = `${pascalCase(entry.type)}Payload`;
+  const nameField = `_name: '${entry.type}';`;
+  const header = [
+    '/**',
+    ` * states: ${states.length > 0 ? states.join(', ') : '(none)'}${flags.length > 0 ? ` · ${flags.join(' · ')}` : ''}`,
+    ` * owner: ${owner ?? '(unresolved)'}`,
+  ];
+  if (typeof sketch === 'string') {
+    const { type, doc } = sketchStringToTs(sketch);
+    if (type.startsWith('(')) {
+      header.push(` * ${type.slice(1, -1)}`);
+      header.push(' */');
+      return [...header, `interface ${name} {\n  ${nameField}\n}`, ''];
+    }
+    if (doc !== undefined) header.push(` * ${doc}`);
+    header.push(' */');
+    return [...header, `type ${name} = { ${nameField} } & (${type});`, ''];
+  }
+  if (Array.isArray(sketch)) {
+    const inner = renderTsType(sketch[0], '  ');
+    const lines = [...inner.lines];
+    lines[lines.length - 1] += '[]';
+    header.push(' */');
+    if (lines.length === 1) {
+      return [...header, `type ${name} = { ${nameField} } & (${lines[0]});`, ''];
+    }
+    return [
+      ...header,
+      `type ${name} = { ${nameField} } & (${lines[0]}`,
+      ...lines.slice(1, -1),
+      `${lines[lines.length - 1]});`,
+      '',
+    ];
+  }
+  const payloadType = typeof sketch[TYPE_KEY] === 'string' ? sketch[TYPE_KEY] : undefined;
+  if (payloadType !== undefined) header.push(` * payload type: ${payloadType}`);
+  header.push(' */');
+  const lines = [...header, `interface ${name} {`, `  ${nameField}`];
+  emitTsDict(lines, sketch, '  ');
+  lines.push('}', '');
+  return lines;
+}
+
+function matchDelimiter(source: string, start: number, open: string, close: string): number {
+  let depth = 0;
+  for (let i = start; i < source.length; i++) {
+    const ch = source[i];
+    if (ch === '/' && source[i + 1] === '/') {
+      i = source.indexOf('\n', i);
+      if (i === -1) return -1;
+      continue;
+    }
+    if (ch === '/' && source[i + 1] === '*') {
+      i = source.indexOf('*/', i);
+      if (i === -1) return -1;
+      i += 1;
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === '`') {
+      const quote = ch;
+      i += 1;
+      while (i < source.length && source[i] !== quote) {
+        if (source[i] === '\\') i += 1;
+        i += 1;
+      }
+      continue;
+    }
+    if (ch === open) depth += 1;
+    else if (ch === close) {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+function splitTopLevel(body: string, separators: readonly string[] = [',']): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let partStart = 0;
+  const n = body.length;
+  for (let i = 0; i < n; i++) {
+    const ch = body[i];
+    if (ch === "'" || ch === '"' || ch === '`') {
+      const quote = ch;
+      i += 1;
+      while (i < n && body[i] !== quote) {
+        if (body[i] === '\\') i += 1;
+        i += 1;
+      }
+      continue;
+    }
+    if (ch === '{' || ch === '(' || ch === '[' || ch === '<') depth += 1;
+    else if (ch === '}' || ch === ')' || ch === ']' || ch === '>') depth = Math.max(0, depth - 1);
+    else if (ch !== undefined && depth === 0 && separators.includes(ch)) {
+      parts.push(body.slice(partStart, i).trim());
+      partStart = i + 1;
+    }
+  }
+  parts.push(body.slice(partStart).trim());
+  return parts.filter((p) => p !== '');
+}
+
+function splitObjectFields(body: string): Map<string, string> {
+  const fields = new Map<string, string>();
+  for (const part of splitTopLevel(body)) {
+    const keyMatch = /^([$\w]+|'[^']+'|"[^"]+")\s*:/.exec(part);
+    if (keyMatch?.[1] !== undefined) {
+      const key = keyMatch[1].replace(/^['"]|['"]$/g, '');
+      fields.set(key, part.slice(keyMatch[0].length).trim());
+    } else if (part.startsWith('...')) {
+      fields.set(part, '');
+    }
+  }
+  return fields;
+}
+
+function objectBody(text: string, braceIndex: number): string | undefined {
+  const end = matchDelimiter(text, braceIndex, '{', '}');
+  return end === -1 ? undefined : text.slice(braceIndex + 1, end);
+}
+
+function readExpression(source: string, start: number): string {
+  let depth = 0;
+  const n = source.length;
+  for (let i = start; i < n; i++) {
+    const ch = source[i];
+    if (ch === "'" || ch === '"' || ch === '`') {
+      const quote = ch;
+      i += 1;
+      while (i < n && source[i] !== quote) {
+        if (source[i] === '\\') i += 1;
+        i += 1;
+      }
+      continue;
+    }
+    if (ch === '{' || ch === '(' || ch === '[' || ch === '<') depth += 1;
+    else if (ch === '}' || ch === ')' || ch === ']' || ch === '>') depth = Math.max(0, depth - 1);
+    else if (ch === ';' && depth === 0) return source.slice(start, i);
+  }
+  return source.slice(start);
+}
+
+function tsQuote(raw: string): string {
+  return raw.includes("'") ? JSON.stringify(raw) : `'${raw}'`;
+}
+
+function escapeRegExp(raw: string): string {
+  return raw.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function resolveSchemaLiteral(expr: string, source: string, depth = 0): string | undefined {
+  if (depth > 2) return undefined;
+  const inline = /^z\.\w*[oO]bject\s*\(/.exec(expr);
+  if (inline !== null) {
+    const rest = expr.slice(inline[0].length).trimStart();
+    if (rest.startsWith('{')) return objectBody(rest, 0);
+    const shapeName = /^([$\w]+)/.exec(rest)?.[1];
+    if (shapeName !== undefined) {
+      const constRe = new RegExp(`const\\s+${shapeName}\\s*(?::[^=;]+)?=\\s*\\{`);
+      const m = constRe.exec(source);
+      if (m !== null) return objectBody(source, m.index + m[0].length - 1);
+    }
+    return undefined;
+  }
+  const ident = /^([$\w]+)$/.exec(expr.trim())?.[1];
+  if (ident !== undefined) {
+    const constRe = new RegExp(`const\\s+${ident}\\s*(?::[^=;]+)?=\\s*`);
+    const m = constRe.exec(source);
+    if (m !== null) {
+      const rhs = readExpression(source, m.index + m[0].length).trim();
+      return resolveSchemaLiteral(rhs, source, depth + 1);
+    }
+  }
+  return undefined;
+}
+
+interface Budget {
+  remaining: number;
+}
+
+function spend(budget: Budget): boolean {
+  if (budget.remaining <= 0) return false;
+  budget.remaining -= 1;
+  return true;
+}
+
+const TS_BUDGET = (): Budget => ({ remaining: 24 });
+
+const _fileCache = new Map<string, string>();
+
+function readCached(file: string): string {
+  let text = _fileCache.get(file);
+  if (text === undefined) {
+    text = readFileSync(file, 'utf-8');
+    _fileCache.set(file, text);
+  }
+  return text;
+}
+
+interface TsField {
+  readonly type: string;
+  readonly optional: boolean;
+}
+
+function splitTsTypeFields(body: string): Map<string, TsField> {
+  const fields = new Map<string, TsField>();
+  for (const part of splitTopLevel(body, [';', ','])) {
+    const m = /^(?:readonly\s+)?([$\w]+|'[^']+'|"[^"]+")\s*(\?)?\s*:\s*(.+)$/.exec(part);
+    if (m?.[1] !== undefined && m[3] !== undefined) {
+      fields.set(m[1].replace(/^['"]|['"]$/g, ''), {
+        type: m[3].trim(),
+        optional: m[2] !== undefined,
+      });
+    }
+  }
+  return fields;
+}
+
+const TS_PRIMITIVES = new Set(['string', 'number', 'boolean', 'unknown', 'any', 'null', 'undefined', 'void']);
+
+function renderTsFields(
+  fields: Map<string, TsField>,
+  file: string,
+  budget: Budget,
+  charBudget: number,
+  depth: number,
+): SketchDict {
+  const dict: SketchDict = {};
+  let count = 0;
+  for (const [name, f] of fields) {
+    if (count >= 8) {
+      dict[MORE_KEY] = '…';
+      break;
+    }
+    count += 1;
+    dict[`${name}${f.optional ? '?' : ''}`] = summarizeTsTypeExpr(
+      f.type,
+      file,
+      budget,
+      Math.max(120, Math.floor(charBudget / 2)),
+      depth + 1,
+    );
+  }
+  return dict;
+}
+
+function findTsTypeDef(name: string, file: string): string | undefined {
+  const source = readCached(file);
+  const typeRe = new RegExp(`(?:export\\s+)?type\\s+${name}(?:<[^>;=]*>)?\\s*=\\s*`);
+  const m = typeRe.exec(source);
+  if (m !== null) return readExpression(source, m.index + m[0].length).trim();
+  const ifaceRe = new RegExp(`(?:export\\s+)?interface\\s+${name}(?:<[^>]*>)?(?:\\s+extends[^{]+)?\\s*\\{`);
+  const im = ifaceRe.exec(source);
+  if (im !== null) {
+    const body = objectBody(source, im.index + im[0].length - 1);
+    if (body !== undefined) return `{ ${body} }`;
+  }
+  return undefined;
+}
+
+function findImportSource(file: string, name: string): string | undefined {
+  const source = readCached(file);
+  const re = /(?:import|export)\s+(?:type\s+)?\{([^}]+)\}\s*from\s*'([^']+)'/g;
+  for (const m of source.matchAll(re)) {
+    for (const part of m[1]!.split(',')) {
+      const named = /^(?:type\s+)?([\w$]+)(?:\s+as\s+([\w$]+))?$/.exec(part.trim());
+      if (named === null) continue;
+      if ((named[2] ?? named[1]) === name) return m[2];
+    }
+  }
+  return undefined;
+}
+
+function resolveModuleFile(fromFile: string, specifier: string): string | undefined {
+  let base: string;
+  if (specifier.startsWith('#/')) base = join(SRC, specifier.slice(2));
+  else if (specifier.startsWith('.')) base = join(dirname(fromFile), specifier);
+  else return undefined;
+  for (const candidate of [`${base}.ts`, join(base, 'index.ts')]) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+function summarizeTsUnion(
+  members: string[],
+  file: string,
+  budget: Budget,
+  charBudget: number,
+  depth: number,
+): string {
+  const resolved = members.map((m) => {
+    const t = m.trim();
+    if (/^[$\w]+$/.test(t)) {
+      const def = findTsTypeDef(t, file);
+      if (def !== undefined) return def;
+    }
+    return t;
+  });
+  const bodies = resolved.map((m) => (m.trim().startsWith('{') ? objectBody(m.trim(), 0) : undefined));
+  if (bodies.length > 0 && bodies.every((b) => b !== undefined)) {
+    const fieldMaps = bodies.map((b) => splitTsTypeFields(b!));
+    for (const [name, info] of fieldMaps[0]!) {
+      if (
+        /^'[^']*'$/.test(info.type) &&
+        fieldMaps.every((fm) => /^'[^']*'$/.test(fm.get(name)?.type ?? ''))
+      ) {
+        const values = fieldMaps.map((fm) => tsQuote(fm.get(name)!.type.slice(1, -1)));
+        return truncate(`union on ${name}: ${values.join(' | ')}`, charBudget);
+      }
+    }
+    return truncate(
+      fieldMaps
+        .map((fm) => stringifySketch(renderTsFields(fm, file, budget, charBudget, depth + 1)))
+        .join(' | '),
+      charBudget * 2,
+    );
+  }
+  return truncate(
+    members
+      .map((m) => stringifySketch(summarizeTsTypeExpr(m, file, budget, charBudget, depth + 1)))
+      .join(' | '),
+    charBudget * 2,
+  );
+}
+
+function summarizeTsTypeExpr(
+  rhs: string,
+  file: string,
+  budget: Budget,
+  charBudget = 480,
+  depth = 0,
+): Sketch {
+  let text = rhs.replaceAll(/\s+/g, ' ').trim();
+  if (text.startsWith('readonly ')) text = text.slice('readonly '.length).trim();
+  const literal = /^'([^']*)'$/.exec(text);
+  if (literal?.[1] !== undefined) return tsQuote(literal[1]);
+  if (TS_PRIMITIVES.has(text)) return text;
+  if (text.endsWith('[]')) {
+    const inner = summarizeTsTypeExpr(text.slice(0, -2), file, budget, charBudget, depth + 1);
+    if (typeof inner !== 'string') return [inner];
+    return inner.includes('|') ? `(${inner})[]` : `${inner}[]`;
+  }
+  const members = splitTopLevel(text, ['|']);
+  if (members.length > 1) {
+    return spend(budget)
+      ? summarizeTsUnion(members, file, budget, charBudget, depth)
+      : truncate(text, 80);
+  }
+  const intersections = splitTopLevel(text, ['&']);
+  if (intersections.length > 1) {
+    if (!spend(budget)) return truncate(text, 80);
+    const sides = intersections.map((m) => summarizeTsTypeExpr(m, file, budget, charBudget, depth + 1));
+    if (sides.every((side) => typeof side !== 'string' && !Array.isArray(side))) {
+      return Object.assign({}, ...sides) as SketchDict;
+    }
+    return truncate(sides.map(stringifySketch).join(' & '), charBudget * 2);
+  }
+  if (text.startsWith('{')) {
+    if (!spend(budget) || depth >= 4) return 'object';
+    const body = objectBody(text, 0);
+    if (body !== undefined) {
+      return renderTsFields(splitTsTypeFields(body), file, budget, charBudget, depth);
+    }
+  }
+  if (/^[$\w]+$/.test(text)) {
+    const summary = summarizeTsType(text, file, budget);
+    if (summary !== undefined) return summary;
+  }
+  return truncate(text, 80);
+}
+
+function summarizeTsType(name: string, fromFile: string, budget: Budget): Sketch | undefined {
+  if (!spend(budget)) return undefined;
+  const def = findTsTypeDef(name, fromFile);
+  if (def !== undefined) return summarizeTsTypeExpr(def, fromFile, budget);
+  const specifier = findImportSource(fromFile, name);
+  if (specifier !== undefined) {
+    const target = resolveModuleFile(fromFile, specifier);
+    if (target !== undefined) return summarizeTsType(name, target, budget);
+  }
+  for (const m of readCached(fromFile).matchAll(/export\s+\*\s+from\s*'([^']+)'/g)) {
+    const target = m[1] === undefined ? undefined : resolveModuleFile(fromFile, m[1]);
+    if (target === undefined) continue;
+    const summary = summarizeTsType(name, target, budget);
+    if (summary !== undefined) return summary;
+  }
+  return undefined;
+}
+
+function friendlyZodExpr(expr: string, ownerFile: string, depth = 0): Sketch {
+  let text = expr.replaceAll(/\s+/g, ' ').trim();
+  let stripped = true;
+  while (stripped) {
+    stripped = false;
+    for (const suffix of ['.optional()', '.nullable()', '.nullish()', '.readonly()']) {
+      if (text.endsWith(suffix)) {
+        text = text.slice(0, -suffix.length).trim();
+        stripped = true;
+      }
+    }
+  }
+  const stringLiteral = /^'([^']*)'$/.exec(text);
+  if (stringLiteral?.[1] !== undefined) return tsQuote(stringLiteral[1]);
+  const custom = /^z\.custom<(.+)>\(\)$/.exec(text);
+  if (custom?.[1] !== undefined) {
+    const typeName = custom[1].trim();
+    if (depth > 1) return typeName;
+    const summary = summarizeTsType(typeName, ownerFile, TS_BUDGET());
+    if (summary === undefined) return typeName;
+    if (typeof summary !== 'string' && !Array.isArray(summary)) {
+      return { [TYPE_KEY]: typeName, ...summary };
+    }
+    return truncate(`${typeName} = ${stringifySketch(summary)}`, 1024);
+  }
+  if (/^z\.string\(\)$/.test(text)) return 'string';
+  if (/^z\.number\(\)$/.test(text)) return 'number';
+  if (/^z\.boolean\(\)$/.test(text)) return 'boolean';
+  if (/^z\.(?:int|integer)\(\)$/.test(text)) return 'integer';
+  const array = /^z\.array\((.+)\)$/.exec(text);
+  if (array?.[1] !== undefined) {
+    const inner = friendlyZodExpr(array[1], ownerFile, depth + 1);
+    if (typeof inner !== 'string') return [inner];
+    return `${inner}[]`;
+  }
+  const literal = /^z\.literal\((.+)\)$/.exec(text);
+  if (literal?.[1] !== undefined) return friendlyZodExpr(literal[1], ownerFile, depth + 1);
+  const union = /^z\.union\((.+)\)$/.exec(text);
+  if (union?.[1] !== undefined) return friendlyZodUnion(union[1], ownerFile, depth);
+  const enumMatch = /^z\.enum\((.+)\)$/.exec(text);
+  if (enumMatch?.[1] !== undefined) {
+    const body = enumMatch[1].trim().replace(/^\[/, '').replace(/\]$/, '');
+    return splitTopLevel(body)
+      .map((member) => stringifySketch(friendlyZodExpr(member, ownerFile, depth + 1)))
+      .join(' | ');
+  }
+  const record = /^z\.record\((.+)\)$/.exec(text);
+  if (record?.[1] !== undefined) {
+    const parts = splitTopLevel(record[1]);
+    if (parts.length === 2) {
+      return `record<string, ${stringifySketch(friendlyZodExpr(parts[1]!, ownerFile, depth + 1))}>`;
+    }
+  }
+  if (/^z\.\w*[oO]bject\(/.test(text)) {
+    if (depth >= 3) return 'object';
+    const body = resolveSchemaLiteral(text, readCached(ownerFile));
+    if (body === undefined) return 'object';
+    const dict: SketchDict = {};
+    for (const [key, fieldExpr] of splitObjectFields(body)) {
+      if (fieldExpr === '') {
+        dict[key] = '(spread)';
+        continue;
+      }
+      const optional = /\.(?:optional|nullish)\(\)$/.test(fieldExpr);
+      dict[`${key}${optional ? '?' : ''}`] = friendlyZodExpr(fieldExpr, ownerFile, depth + 1);
+    }
+    return dict;
+  }
+  const ident = /^([$\w]+)$/.exec(text)?.[1];
+  if (ident !== undefined && depth < 4) {
+    const source = readCached(ownerFile);
+    const constRe = new RegExp(`const\\s+${ident}\\s*(?::[^=;]+)?=\\s*`);
+    const m = constRe.exec(source);
+    if (m !== null) {
+      const rhs = readExpression(source, m.index + m[0].length).trim();
+      return friendlyZodExpr(rhs, ownerFile, depth + 1);
+    }
+    if (depth <= 1) {
+      const summary = summarizeTsType(ident, ownerFile, TS_BUDGET());
+      if (summary !== undefined) {
+        if (typeof summary !== 'string' && !Array.isArray(summary)) {
+          return { [TYPE_KEY]: ident, ...summary };
+        }
+        return truncate(`${ident} = ${stringifySketch(summary)}`, 320);
+      }
+    }
+  }
+  return truncate(text, 80);
+}
+
+function friendlyZodUnion(body: string, ownerFile: string, depth: number): string {
+  const members = splitTopLevel(body.trim().replace(/^\[/, '').replace(/\]$/, ''));
+  const source = readCached(ownerFile);
+  const bodies = members.map((m) => resolveSchemaLiteral(m, source));
+  if (members.length > 0 && bodies.every((b) => b !== undefined)) {
+    const fieldMaps = bodies.map((b) => splitObjectFields(b));
+    const spreadSets = fieldMaps.map((fm) => [...fm.keys()].filter((k) => fm.get(k) === ''));
+    const commonSpreads = (spreadSets[0] ?? []).filter((s) =>
+      spreadSets.every((set) => set.includes(s)),
+    );
+    const sketches = fieldMaps.map((fm) => {
+      const dict: SketchDict = {};
+      for (const [key, expr] of fm) {
+        if (expr === '') continue;
+        const optional = /\.(?:optional|nullish)\(\)$/.test(expr);
+        dict[`${key}${optional ? '?' : ''}`] = friendlyZodExpr(expr, ownerFile, depth + 1);
+      }
+      return stringifySketch(dict);
+    });
+    const prefix = commonSpreads.length > 0 ? `${commonSpreads.join(' + ')} & ` : '';
+    return truncate(`${prefix}${sketches.join(' | ')}`, 320);
+  }
+  return truncate(
+    members.map((m) => stringifySketch(friendlyZodExpr(m, ownerFile, depth + 1))).join(' | '),
+    320,
+  );
+}
+
+function sketchPayloadFromSource(
+  ownerFile: string,
+  type: string,
+): string | Map<string, Sketch> | undefined {
+  const absFile = join(PKG, ownerFile);
+  const source = readCached(absFile);
+  const typeRe = new RegExp(
+    `static\\s+override\\s+readonly\\s+type\\s*=\\s*'${escapeRegExp(type)}'`,
+  );
+  const typeMatch = typeRe.exec(source);
+  if (typeMatch === null) return undefined;
+  const rest = source.slice(typeMatch.index + typeMatch[0].length);
+  const nextType = /static\s+override\s+readonly\s+type\s*=/.exec(rest);
+  const classWindow = nextType === null ? rest : rest.slice(0, nextType.index);
+  const schemaMatch = /static\s+override\s+readonly\s+schema\s*=\s*/.exec(classWindow);
+  if (schemaMatch === null) return undefined;
+  const schemaExpr = readExpression(
+    classWindow,
+    schemaMatch.index + schemaMatch[0].length,
+  ).trim();
+  if (schemaExpr === '') return undefined;
+  const literal = resolveSchemaLiteral(schemaExpr, source);
+  if (literal === undefined) {
+    const sketch = friendlyZodExpr(schemaExpr, absFile);
+    if (typeof sketch === 'string') return sketch;
+    if (!Array.isArray(sketch)) return new Map(Object.entries(sketch));
+    return stringifySketch(sketch);
+  }
+  const sketch = new Map<string, Sketch>();
+  for (const [key, expr] of splitObjectFields(literal)) {
+    if (expr === '') {
+      sketch.set(key, '(spread)');
+      continue;
+    }
+    const optional = /\.(?:optional|nullish)\(\)$/.test(expr);
+    sketch.set(`${key}${optional ? '?' : ''}`, friendlyZodExpr(expr, absFile));
+  }
+  return sketch;
+}
+
+export async function buildWireManifest(): Promise<string> {
+  const { owners, importFiles, durableTypes, classTypes } = scanEventDeclarations();
+  await import('../src/index.ts');
+  for (const file of importFiles) {
+    await import(relative(join(PKG, 'scripts'), file));
+  }
+  const { WIRE_PROTOCOL_VERSION } = (await import('#/wire/migration/migration')) as {
+    WIRE_PROTOCOL_VERSION: string;
+  };
+
+  const entries = [...EVENT2_REGISTRY.values()].toSorted((a, b) => a.type.localeCompare(b.type));
+  const migrationChain = scanMigrationChain();
+
+  const folding = new Map<string, { states: string[]; blobs: string[] }>();
+  const protocolTypes = scanUndoableProtocolTypes(classTypes);
+  for (const state of scanReplayableStates()) {
+    const eventTypes = new Set<string>();
+    for (const cls of state.foldClasses) {
+      const type = classTypes.get(cls);
+      if (type === undefined) {
+        throw new Error(
+          `[gen-wire-manifest] state '${state.keyName}' folds unresolved event class '${cls}'`,
+        );
+      }
+      eventTypes.add(type);
+    }
+    if (state.undoable) {
+      for (const type of protocolTypes) eventTypes.add(type);
+    }
+    for (const type of eventTypes) {
+      let info = folding.get(type);
+      if (info === undefined) {
+        info = { states: [], blobs: [] };
+        folding.set(type, info);
+      }
+      info.states.push(state.keyName);
+      if (state.blobs) info.blobs.push(state.keyName);
+    }
+  }
+  for (const info of folding.values()) {
+    info.states.sort();
+    info.blobs.sort();
+  }
+
+  const unregistered = [...durableTypes].filter((type) => !EVENT2_REGISTRY.has(type));
+  if (unregistered.length > 0) {
+    console.error(
+      `[gen-wire-manifest] declared durable but never registered (no fold, not in EVENT2_REGISTRY): ${unregistered.toSorted().join(', ')}`,
+    );
+  }
+
+  const out: string[] = [
+    '// Wire Protocol Manifest',
+    '//',
+    '// Generated by scripts/gen-wire-manifest.mts — do not edit by hand.',
+    '// Regenerate with: pnpm --filter @moonshot-ai/agent-core-v2 gen:wire-manifest',
+    '//',
+    `// protocol_version: "${WIRE_PROTOCOL_VERSION}" (migrations: ${migrationChain})`,
+    '//',
+    '// One declaration per durable record type — an Event2 subclass declaring',
+    '// `static type` + `static durable = true` + `static schema` — drained from the',
+    '// runtime EVENT2_REGISTRY ("import = register"). Every payload declaration',
+    '// carries its record type in a `_name` field. Payload sketches use TypeScript',
+    '// type syntax; when a named type is expanded inline, its name appears as a doc',
+    '// comment (`/** ContextMessage */`). Bare type names (ContentPart,',
+    '// ContextMessage, …) refer to the real types in src/ — they are intentionally',
+    '// not resolved here. `// …` marks a capped field list. On disk (wire.jsonl)',
+    '// the journal opens with a metadata line {"type": "metadata",',
+    '// "protocol_version", "created_at"}; each record is {"type", ...payload,',
+    '// "time"} — object payloads spread at the top level.',
+    '//',
+    '// Every listed type is durable by construction — transient Event2 classes',
+    '// never enter EVENT2_REGISTRY, so there is no persisted flag. Declaration',
+    '// header lines: states (every state folding this record type on dispatch and',
+    '// replay; any state beyond the first is what the retired format listed as',
+    '// cross-reducers), blobs (the folding states whose blob codec offloads inline',
+    '// media to blob storage), owner (the source file declaring the class).',
+    '',
+    `// Index (${entries.length} record types)`,
+  ];
+  const width = Math.max(...entries.map((e) => e.type.length));
+  const statesWidth = Math.max(
+    ...entries.map((e) => (folding.get(e.type)?.states.join(', ') ?? '(none)').length),
+  );
+  for (const entry of entries) {
+    const states = folding.get(entry.type)?.states.join(', ') ?? '(none)';
+    out.push(
+      `//   ${entry.type.padEnd(width)}  ${states.padEnd(statesWidth)}  ${owners.get(entry.type) ?? '(unresolved)'}`,
+    );
+  }
+  out.push('');
+  const declNames: [string, string][] = [];
+  for (const entry of entries) {
+    const info = folding.get(entry.type);
+    const states = info?.states ?? [];
+    const flags: string[] = [];
+    if (info !== undefined && info.blobs.length > 0) flags.push(`blobs: ${info.blobs.join(', ')}`);
+    const owner = owners.get(entry.type);
+    const staticSketch =
+      owner === undefined ? undefined : sketchPayloadFromSource(owner, entry.type);
+    const sketch = buildPayloadSketch(entry.schema as unknown, staticSketch);
+    out.push(...renderPayloadDecl(entry, owner, states, flags, sketch));
+    declNames.push([entry.type, `${pascalCase(entry.type)}Payload`]);
+  }
+
+  out.push('/** Record type → payload sketch. */');
+  out.push('interface WirePayloadMap {');
+  for (const [type, declName] of declNames) {
+    out.push(`  ${JSON.stringify(type)}: ${declName};`);
+  }
+  out.push('}');
+  out.push('');
+  return out.join('\n');
+}
+
+async function main(): Promise<void> {
+  const check = process.argv.includes('--check');
+  const manifest = await buildWireManifest();
+  if (check) {
+    let current: string | undefined;
+    try {
+      current = readFileSync(MANIFEST_PATH, 'utf-8');
+    } catch {
+      current = undefined;
+    }
+    if (current !== manifest) {
+      console.error(
+        `[gen-wire-manifest] ${relative(process.cwd(), MANIFEST_PATH)} is stale. ` +
+          'Regenerate with `pnpm --filter @moonshot-ai/agent-core-v2 gen:wire-manifest`.',
+      );
+      process.exit(1);
+    }
+    console.log('[gen-wire-manifest] up to date');
+    return;
+  }
+  writeFileSync(MANIFEST_PATH, manifest);
+  console.log(`[gen-wire-manifest] wrote ${relative(process.cwd(), MANIFEST_PATH)}`);
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}

packages/agent-core-v2/scripts/generate-webp-dec-wasm.mjs

@@ -0,0 +1,24 @@
+import { createRequire } from 'node:module';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const packageRoot = resolve(import.meta.dirname, '..');
+const require = createRequire(resolve(packageRoot, 'package.json'));
+
+const wasmPath = require.resolve('@jsquash/webp/codec/dec/webp_dec.wasm');
+const version = require('@jsquash/webp/package.json').version;
+const wasm = readFileSync(wasmPath);
+
+const target = resolve(packageRoot, 'src/agent/media/webp-dec-wasm.ts');
+writeFileSync(
+  target,
+  `// GENERATED FILE — do not edit by hand.
+// WebP decoder wasm from @jsquash/webp@${version} (codec/dec/webp_dec.wasm),
+// base64-encoded so the bundled CLI needs no on-disk wasm asset.
+// Regenerate with: node scripts/generate-webp-dec-wasm.mjs
+
+export const WEBP_DECODER_WASM_BASE64 =
+  '${wasm.toString('base64')}';
+`,
+);
+console.log(`Wrote ${target} (${wasm.length} bytes of wasm)`);

packages/agent-core-v2/src/_base/asyncEventQueue.ts

@@ -0,0 +1,58 @@
+export class AsyncEventQueue<T> implements AsyncIterable<T>, AsyncIterator<T> {
+  private readonly values: T[] = [];
+  private readonly waiters: Array<{
+    resolve: (result: IteratorResult<T>) => void;
+    reject: (reason?: unknown) => void;
+  }> = [];
+  private error: unknown;
+  private failed = false;
+  private ended = false;
+
+  push(value: T): void {
+    if (this.failed || this.ended) return;
+    const waiter = this.waiters.shift();
+    if (waiter !== undefined) {
+      waiter.resolve({ done: false, value });
+      return;
+    }
+    this.values.push(value);
+  }
+
+  end(): void {
+    if (this.failed || this.ended) return;
+    this.ended = true;
+    for (const waiter of this.waiters.splice(0)) {
+      waiter.resolve({ done: true, value: undefined });
+    }
+  }
+
+  fail(error: unknown): void {
+    if (this.failed || this.ended) return;
+    this.error = error;
+    this.failed = true;
+    if (this.values.length > 0) return;
+    for (const waiter of this.waiters.splice(0)) {
+      waiter.reject(error);
+    }
+  }
+
+  next(): Promise<IteratorResult<T>> {
+    if (this.values.length > 0) {
+      const value = this.values.shift()!;
+      return Promise.resolve({ done: false, value });
+    }
+    if (this.failed) {
+      return Promise.reject(this.error);
+    }
+    if (this.ended) {
+      return Promise.resolve({ done: true, value: undefined });
+    }
+    return new Promise<IteratorResult<T>>((resolve, reject) => {
+      this.waiters.push({ resolve, reject });
+    });
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    return this;
+  }
+}

packages/agent-core-v2/src/_base/event.ts

@@ -0,0 +1,281 @@
+import { onUnexpectedError, safelyCallListener } from './errors/unexpectedError';
+import {
+  Disposable,
+  DisposableStore,
+  combinedDisposable,
+  type IDisposable,
+  type IDisposableDebugLabel,
+} from './di/lifecycle';
+import { LinkedList } from './di/util/linkedList';
+
+export interface Event<T> {
+  (
+    listener: (e: T) => unknown,
+    thisArg?: unknown,
+    disposables?: IDisposable[] | DisposableStore,
+  ): IDisposable;
+}
+
+interface ListenerEntry<T> {
+  listener: (e: T) => unknown;
+  thisArg: unknown;
+}
+
+export class EventSubscription implements IDisposable, IDisposableDebugLabel {
+  readonly debugLabel: string | undefined;
+  private _removed = false;
+
+  constructor(
+    debugName: string | undefined,
+    private readonly _remove: () => void,
+  ) {
+    this.debugLabel = debugName === undefined ? undefined : `on:${debugName}`;
+  }
+
+  dispose(): void {
+    if (this._removed) return;
+    this._removed = true;
+    this._remove();
+  }
+}
+
+export class Emitter<T> {
+  protected _listeners: Set<ListenerEntry<T>> | undefined;
+  private _disposed = false;
+  private _event: Event<T> | undefined;
+
+  constructor(public readonly debugName?: string) {}
+
+  get event(): Event<T> {
+    this._event ??= (listener, thisArg, disposables) => {
+      if (this._disposed) {
+        return Disposable.None;
+      }
+      this._listeners ??= new Set();
+      const entry: ListenerEntry<T> = { listener, thisArg };
+      this._listeners.add(entry);
+
+      const subscription = new EventSubscription(this.debugName, () => {
+        if (this._disposed) {
+          return;
+        }
+        this._listeners?.delete(entry);
+      });
+
+      if (disposables !== undefined) {
+        if (disposables instanceof DisposableStore) {
+          disposables.add(subscription);
+        } else {
+          disposables.push(subscription);
+        }
+      }
+      return subscription;
+    };
+    return this._event;
+  }
+
+  get listenerCount(): number {
+    return this._listeners?.size ?? 0;
+  }
+
+  fire(value: T): void {
+    if (this._disposed || this._listeners === undefined) {
+      return;
+    }
+    const snapshot = Array.from(this._listeners);
+    for (const entry of snapshot) {
+      safelyCallListener(() => {
+        entry.listener.call(entry.thisArg, value);
+      });
+    }
+  }
+
+  dispose(): void {
+    if (this._disposed) return;
+    this._disposed = true;
+    this._listeners?.clear();
+    this._listeners = undefined;
+  }
+
+  get isDisposed(): boolean {
+    return this._disposed;
+  }
+}
+
+export interface IWaitUntil {
+  readonly signal: AbortSignal;
+  waitUntil(thenable: Promise<unknown>): void;
+}
+
+export type IWaitUntilData<T> = Omit<T, 'waitUntil' | 'signal'>;
+
+export class AsyncEmitter<T extends IWaitUntil> extends Emitter<T> {
+  private _asyncDeliveryQueue?: LinkedList<[(event: T) => void, IWaitUntilData<T>]>;
+
+  async fireAsyncConcurrent(data: IWaitUntilData<T>, signal: AbortSignal): Promise<void> {
+    if (this.isDisposed || this._listeners === undefined || signal.aborted) {
+      return;
+    }
+    const snapshot = Array.from(this._listeners);
+    await Promise.all(
+      snapshot.map((entry) =>
+        this.deliverAsync(
+          (event) => {
+            entry.listener.call(entry.thisArg, event);
+          },
+          data,
+          signal,
+        ),
+      ),
+    );
+  }
+
+  async fireAsync(data: IWaitUntilData<T>, signal: AbortSignal): Promise<void> {
+    if (this.isDisposed || this._listeners === undefined) {
+      return;
+    }
+
+    this._asyncDeliveryQueue ??= new LinkedList();
+    for (const entry of this._listeners) {
+      this._asyncDeliveryQueue.push([
+        (event) => {
+          entry.listener.call(entry.thisArg, event);
+        },
+        data,
+      ]);
+    }
+
+    while (this._asyncDeliveryQueue.size > 0 && !signal.aborted) {
+      const [deliver, eventData] = this._asyncDeliveryQueue.shift()!;
+      await this.deliverAsync(deliver, eventData, signal);
+    }
+  }
+
+  private async deliverAsync(
+    deliver: (event: T) => void,
+    data: IWaitUntilData<T>,
+    signal: AbortSignal,
+  ): Promise<void> {
+    const thenables: Promise<unknown>[] = [];
+    const event = {
+      ...data,
+      signal,
+      waitUntil: (p: Promise<unknown>): void => {
+        if (Object.isFrozen(thenables)) {
+          throw new Error('waitUntil can NOT be called asynchronously');
+        }
+        thenables.push(p);
+      },
+    } as T;
+    try {
+      deliver(event);
+    } catch (error) {
+      onUnexpectedError(error);
+      return;
+    }
+    void Object.freeze(thenables);
+    const settled = await Promise.allSettled(thenables);
+    for (const result of settled) {
+      if (result.status === 'rejected') {
+        onUnexpectedError(result.reason);
+      }
+    }
+  }
+}
+
+export function handleVetos(
+  vetos: (boolean | Promise<boolean>)[],
+  onError: (error: unknown) => void,
+): Promise<boolean> {
+  if (vetos.length === 0) {
+    return Promise.resolve(false);
+  }
+
+  const promises: Promise<void>[] = [];
+  let lazyValue = false;
+
+  for (const valueOrPromise of vetos) {
+    if (valueOrPromise === true) {
+      return Promise.resolve(true);
+    }
+    if (typeof valueOrPromise === 'boolean') {
+      continue;
+    }
+    promises.push(
+      valueOrPromise.then(
+        (value) => {
+          if (value) {
+            lazyValue = true;
+          }
+        },
+        (error) => {
+          onError(error);
+          lazyValue = true;
+        },
+      ),
+    );
+  }
+
+  return Promise.allSettled(promises).then(() => lazyValue);
+}
+
+export namespace Event {
+  export const None: Event<unknown> = () => Disposable.None;
+
+  export function once<T>(event: Event<T>): Event<T> {
+    return (listener, thisArg, disposables) => {
+      let fired = false;
+      const subscription = event(
+        (e) => {
+          if (fired) return;
+          fired = true;
+          subscription.dispose();
+          try {
+            listener.call(thisArg, e);
+          } catch (error) {
+            onUnexpectedError(error);
+          }
+        },
+        undefined,
+        disposables,
+      );
+      return subscription;
+    };
+  }
+
+  export function map<I, O>(event: Event<I>, map: (i: I) => O): Event<O> {
+    return (listener, thisArg, disposables) =>
+      event(
+        (i) => listener.call(thisArg, map(i)),
+        undefined,
+        disposables,
+      );
+  }
+
+  export function filter<T>(event: Event<T>, filter: (e: T) => boolean): Event<T> {
+    return (listener, thisArg, disposables) =>
+      event(
+        (e) => {
+          if (filter(e)) listener.call(thisArg, e);
+        },
+        undefined,
+        disposables,
+      );
+  }
+
+  export function any<T>(...events: Event<T>[]): Event<T> {
+    return (listener, thisArg, disposables) => {
+      const combined = combinedDisposable(
+        ...events.map((e) => e((value) => listener.call(thisArg, value))),
+      );
+      if (disposables !== undefined) {
+        if (disposables instanceof DisposableStore) {
+          disposables.add(combined);
+        } else {
+          disposables.push(combined);
+        }
+      }
+      return combined;
+    };
+  }
+}

packages/agent-core-v2/src/_base/version.ts

@@ -0,0 +1,3 @@
+export function getCoreVersion(): string {
+  return '0.0.0';
+}

packages/agent-core-v2/src/app/scopes.ts

@@ -0,0 +1,15 @@
+import { setScopeTopology } from '#/_base/di/scope';
+
+export enum LifecycleScope {
+  App = 'app',
+  Session = 'session',
+  Agent = 'agent',
+}
+
+export const SCOPE_TOPOLOGY: readonly LifecycleScope[] = [
+  LifecycleScope.App,
+  LifecycleScope.Session,
+  LifecycleScope.Agent,
+];
+
+setScopeTopology(SCOPE_TOPOLOGY);

packages/agent-core-v2/src/debug/debugCascade.ts

@@ -0,0 +1,63 @@
+/* oxlint-disable typescript-eslint/no-unsafe-declaration-merging, eslint-plugin-import/namespace -- Event2 class+payload-interface declaration merging is the sanctioned event-declaration idiom. */
+import type { CascadeAction, UnitState } from '#/_base/di/cascadeEngine';
+import { createDecorator } from '#/_base/di/instantiation';
+import { Event2 } from '#/app/event/event2';
+
+export interface DebugCascadeEntry {
+  readonly scopePath: string;
+  readonly seq: number;
+  readonly reason: string;
+  readonly changes: ReadonlyArray<{ token: string; action: CascadeAction }>;
+  readonly affected: readonly string[];
+  readonly tornDown: readonly string[];
+  readonly rebuilt: readonly string[];
+  readonly failed: readonly string[];
+  readonly abortWaited: boolean;
+  readonly abortTimedOut: boolean;
+  readonly durationMs: number;
+}
+
+export interface DebugPendingUnit {
+  readonly token: string;
+  readonly missing: string[];
+}
+
+export interface DebugFailedUnit {
+  readonly token: string;
+  readonly error?: string;
+}
+
+export interface DebugPendingGroup {
+  readonly scopePath: string;
+  readonly waiting: DebugPendingUnit[];
+  readonly failed: DebugFailedUnit[];
+}
+
+export interface DiUnitChangedPayload {
+  readonly scope: string;
+  readonly token: string;
+  readonly state: UnitState;
+  readonly error?: string;
+}
+
+export class DiUnitChanged extends Event2<{ readonly payload: DiUnitChangedPayload }> {
+  static override readonly type = 'event.di.unit_changed';
+}
+export interface DiUnitChanged {
+  readonly payload: DiUnitChangedPayload;
+}
+
+export const DI_UNIT_CHANGED_EVENT = DiUnitChanged.type;
+
+export interface IDebugCascadeService {
+  readonly _serviceBrand: undefined;
+
+  history(): DebugCascadeEntry[];
+  pending(): DebugPendingGroup[];
+  unprovide(scopePath: string, token: string): Promise<void>;
+  update(scopePath: string, token: string, config?: unknown): Promise<void>;
+  dispose(scopePath: string, token: string): Promise<void>;
+}
+
+export const IDebugCascadeService =
+  createDecorator<IDebugCascadeService>('debugCascadeService');

packages/agent-core-v2/src/debug/debugCascadeService.ts

@@ -0,0 +1,183 @@
+import type { CascadeEngine } from '#/_base/di/cascadeEngine';
+import {
+  IInstantiationService,
+  type ServiceIdentifier,
+} from '#/_base/di/instantiation';
+import type { InstantiationService } from '#/_base/di/instantiationService';
+import { DisposableStore, type IDisposable } from '#/_base/di/lifecycle';
+import { ScopeActivation, registerScopedService } from '#/_base/di/scope';
+import { IEventService } from '#/app/event/event';
+import { LifecycleScope } from '#/app/scopes';
+import { Error2, ErrorCodes } from '#/errors';
+
+import {
+  DiUnitChanged,
+  IDebugCascadeService,
+  type DebugCascadeEntry,
+  type DebugFailedUnit,
+  type DebugPendingGroup,
+  type DebugPendingUnit,
+  type DiUnitChangedPayload,
+} from './debugCascade';
+import {
+  resolveScopeContainer,
+  scopePathOfEngine,
+  walkScopeContainers,
+} from './scopeTree';
+
+export class DebugCascadeService implements IDebugCascadeService {
+  declare readonly _serviceBrand: undefined;
+
+  private readonly root: InstantiationService;
+  private readonly events: IEventService;
+  private readonly store = new DisposableStore();
+  private readonly engineSubscriptions = new Map<CascadeEngine, IDisposable>();
+  private tornDown = false;
+
+  constructor(
+    @IInstantiationService instantiation: IInstantiationService,
+    @IEventService events: IEventService,
+  ) {
+    this.root = instantiation as InstantiationService;
+    this.events = events;
+    const tree = this.root.cascadeTree;
+    for (const engine of tree.engines) {
+      this._watchEngine(engine);
+    }
+    this.store.add(
+      tree.onDidAddEngine((engine) => {
+        this._watchEngine(engine);
+      }),
+    );
+    this.store.add(
+      tree.onDidRemoveEngine((engine) => {
+        this._unwatchEngine(engine);
+      }),
+    );
+  }
+
+  history(): DebugCascadeEntry[] {
+    const entries: DebugCascadeEntry[] = [];
+    for (const info of walkScopeContainers(this.root)) {
+      for (const entry of info.container.cascade.history()) {
+        entries.push({ scopePath: info.path, ...entry });
+      }
+    }
+    return entries.toSorted(
+      (a, b) => a.seq - b.seq || a.scopePath.localeCompare(b.scopePath),
+    );
+  }
+
+  pending(): DebugPendingGroup[] {
+    const groups: DebugPendingGroup[] = [];
+    for (const info of walkScopeContainers(this.root)) {
+      const waiting: DebugPendingUnit[] = [];
+      for (const [token, missing] of info.container.cascade.pendingSnapshot()) {
+        waiting.push({ token, missing: [...missing] });
+      }
+      const failed: DebugFailedUnit[] = info.container.cascade
+        .unitsSnapshot()
+        .filter((unit) => unit.state === 'Failed')
+        .map((unit) => ({ token: unit.token, error: unit.error }));
+      if (waiting.length > 0 || failed.length > 0) {
+        groups.push({ scopePath: info.path, waiting, failed });
+      }
+    }
+    return groups;
+  }
+
+  async unprovide(scopePath: string, token: string): Promise<void> {
+    const { container, id } = this._resolve(scopePath, token);
+    container.unprovide(id);
+    await container.cascade.whenIdle();
+  }
+
+  async update(scopePath: string, token: string, config?: unknown): Promise<void> {
+    const { container, id } = this._resolve(scopePath, token);
+    if (config === undefined) {
+      await container.cascade.update(id, `debug update ${token}`);
+    } else {
+      await container.fiberHost.updateToken(id, config, true);
+    }
+  }
+
+  async dispose(scopePath: string, token: string): Promise<void>;
+  dispose(): void;
+  async dispose(scopePath?: string, token?: string): Promise<void> {
+    if (scopePath === undefined && token === undefined) {
+      if (!this.tornDown) {
+        this.tornDown = true;
+        this.store.dispose();
+        for (const subscription of this.engineSubscriptions.values()) {
+          subscription.dispose();
+        }
+        this.engineSubscriptions.clear();
+      }
+      return;
+    }
+    if (scopePath === undefined || token === undefined) {
+      throw new Error2(
+        ErrorCodes.DEBUG_TOKEN_NOT_FOUND,
+        'dispose requires both a scope path and a token',
+      );
+    }
+    const { container, id } = this._resolve(scopePath, token);
+    await container.cascade.submit({
+      action: 'unprovide',
+      token: id,
+      reason: `debug dispose ${token}`,
+    });
+  }
+
+  private _resolve(
+    scopePath: string,
+    token: string,
+  ): { container: InstantiationService; id: ServiceIdentifier<unknown> } {
+    const container = resolveScopeContainer(this.root, scopePath);
+    if (container === undefined) {
+      throw new Error2(
+        ErrorCodes.DEBUG_SCOPE_NOT_FOUND,
+        `no DI container at scope path '${scopePath}'`,
+      );
+    }
+    const id = container.findIdentifier(token);
+    if (id === undefined) {
+      throw new Error2(
+        ErrorCodes.DEBUG_TOKEN_NOT_FOUND,
+        `token '${token}' is not registered in container '${scopePath}'`,
+      );
+    }
+    return { container, id };
+  }
+
+  private _watchEngine(engine: CascadeEngine): void {
+    if (this.engineSubscriptions.has(engine)) {
+      return;
+    }
+    this.engineSubscriptions.set(
+      engine,
+      engine.onDidChangeUnitState((change) => {
+        const payload: DiUnitChangedPayload = {
+          scope: scopePathOfEngine(this.root, engine) ?? '#unknown',
+          token: change.token,
+          state: change.state,
+          error: change.error,
+        };
+        this.events.publish(new DiUnitChanged({ payload }));
+      }),
+    );
+  }
+
+  private _unwatchEngine(engine: CascadeEngine): void {
+    this.engineSubscriptions.get(engine)?.dispose();
+    this.engineSubscriptions.delete(engine);
+  }
+}
+
+registerScopedService(
+  LifecycleScope.App,
+  IDebugCascadeService,
+  DebugCascadeService,
+  ScopeActivation.OnScopeCreated,
+  'debug',
+);

packages/agent-core-v2/src/debug/debugGraph.ts

@@ -0,0 +1,30 @@
+import type { UnitState } from '#/_base/di/cascadeEngine';
+import type { DependencyEdgeKind } from '#/_base/di/dependencyGraph';
+import { createDecorator } from '#/_base/di/instantiation';
+
+export interface DebugGraphNode {
+  readonly id: string;
+  readonly token: string;
+  readonly scopePath: string;
+  readonly uid?: number;
+  readonly state?: UnitState;
+}
+
+export interface DebugGraphEdge {
+  readonly from: string;
+  readonly to: string;
+  readonly kind: DependencyEdgeKind;
+}
+
+export interface DebugGraph {
+  readonly nodes: DebugGraphNode[];
+  readonly edges: DebugGraphEdge[];
+}
+
+export interface IDebugGraphService {
+  readonly _serviceBrand: undefined;
+
+  graph(): DebugGraph;
+}
+
+export const IDebugGraphService = createDecorator<IDebugGraphService>('debugGraphService');

packages/agent-core-v2/src/debug/debugGraphService.ts

@@ -0,0 +1,76 @@
+import { IInstantiationService } from '#/_base/di/instantiation';
+import type { InstantiationService } from '#/_base/di/instantiationService';
+import { ScopeActivation, registerScopedService } from '#/_base/di/scope';
+import { LifecycleScope } from '#/app/scopes';
+
+import {
+  IDebugGraphService,
+  type DebugGraph,
+  type DebugGraphEdge,
+  type DebugGraphNode,
+} from './debugGraph';
+import { walkScopeContainers } from './scopeTree';
+
+export class DebugGraphService implements IDebugGraphService {
+  declare readonly _serviceBrand: undefined;
+
+  private readonly root: InstantiationService;
+
+  constructor(@IInstantiationService instantiation: IInstantiationService) {
+    this.root = instantiation as InstantiationService;
+  }
+
+  graph(): DebugGraph {
+    const infos = walkScopeContainers(this.root);
+    const pathByContainer = new Map<InstantiationService, string>(
+      infos.map((info) => [info.container, info.path]),
+    );
+    const nodes = new Map<string, DebugGraphNode>();
+    for (const info of infos) {
+      const states = new Map(
+        info.container.cascade.unitsSnapshot().map((unit) => [unit.token, unit]),
+      );
+      for (const registration of info.container.servicesSnapshot()) {
+        const id = nodeId(info.path, registration.token);
+        nodes.set(id, {
+          id,
+          token: registration.token,
+          scopePath: info.path,
+          uid: registration.uid,
+          state: states.get(registration.token)?.state,
+        });
+      }
+    }
+    const pathOf = (scope: object): string =>
+      pathByContainer.get(scope as InstantiationService) ??
+      `#${this.root.cascadeTree.seqOf(scope)}`;
+    const edges: DebugGraphEdge[] = [];
+    const endpointNode = (path: string, token: string): string => {
+      const id = nodeId(path, token);
+      if (!nodes.has(id)) {
+        nodes.set(id, { id, token, scopePath: path });
+      }
+      return id;
+    };
+    for (const edge of this.root.dependencyGraph.edges()) {
+      edges.push({
+        from: endpointNode(pathOf(edge.consumer.scope), edge.consumer.token.toString()),
+        to: endpointNode(pathOf(edge.dependency.scope), edge.dependency.token.toString()),
+        kind: edge.kind,
+      });
+    }
+    return { nodes: [...nodes.values()], edges };
+  }
+}
+
+function nodeId(scopePath: string, token: string): string {
+  return `${scopePath}::${token}`;
+}
+
+registerScopedService(
+  LifecycleScope.App,
+  IDebugGraphService,
+  DebugGraphService,
+  ScopeActivation.OnDemand,
+  'debug',
+);

packages/agent-core-v2/src/debug/debugLedger.ts

@@ -0,0 +1,29 @@
+import type { UnitState } from '#/_base/di/cascadeEngine';
+import { createDecorator } from '#/_base/di/instantiation';
+import type { LedgerEntryInfo } from '#/_base/lifecycle/ledger';
+
+export interface DebugUnit {
+  readonly token: string;
+  readonly uid: number;
+  readonly state?: UnitState;
+  readonly error?: string;
+  readonly everActive?: boolean;
+  readonly inFlight?: boolean;
+}
+
+export interface DebugLedgerNode {
+  readonly path: string;
+  readonly label: string;
+  readonly units: DebugUnit[];
+  readonly ledger: LedgerEntryInfo[];
+  readonly children: DebugLedgerNode[];
+}
+
+export interface IDebugLedgerService {
+  readonly _serviceBrand: undefined;
+
+  tree(): DebugLedgerNode;
+}
+
+export const IDebugLedgerService =
+  createDecorator<IDebugLedgerService>('debugLedgerService');

packages/agent-core-v2/src/debug/debugLedgerService.ts

@@ -0,0 +1,56 @@
+import { IInstantiationService } from '#/_base/di/instantiation';
+import type { InstantiationService } from '#/_base/di/instantiationService';
+import { ScopeActivation, registerScopedService } from '#/_base/di/scope';
+import { LifecycleScope } from '#/app/scopes';
+
+import { IDebugLedgerService, type DebugLedgerNode, type DebugUnit } from './debugLedger';
+import { scopeContainerLabel } from './scopeTree';
+
+export class DebugLedgerService implements IDebugLedgerService {
+  declare readonly _serviceBrand: undefined;
+
+  private readonly root: InstantiationService;
+
+  constructor(@IInstantiationService instantiation: IInstantiationService) {
+    this.root = instantiation as InstantiationService;
+  }
+
+  tree(): DebugLedgerNode {
+    return this._node(this.root, scopeContainerLabel(this.root));
+  }
+
+  private _node(container: InstantiationService, path: string): DebugLedgerNode {
+    return {
+      path,
+      label: scopeContainerLabel(container),
+      units: joinUnits(container),
+      ledger: container.ledger.entries(),
+      children: container.children.map((child) =>
+        this._node(child, `${path}/${scopeContainerLabel(child)}`),
+      ),
+    };
+  }
+}
+
+function joinUnits(container: InstantiationService): DebugUnit[] {
+  const states = new Map(container.cascade.unitsSnapshot().map((unit) => [unit.token, unit]));
+  return container.servicesSnapshot().map((registration) => {
+    const unit = states.get(registration.token);
+    return {
+      token: registration.token,
+      uid: registration.uid,
+      state: unit?.state,
+      error: unit?.error,
+      everActive: unit?.everActive,
+      inFlight: unit?.inFlight,
+    };
+  });
+}
+
+registerScopedService(
+  LifecycleScope.App,
+  IDebugLedgerService,
+  DebugLedgerService,
+  ScopeActivation.OnDemand,
+  'debug',
+);

packages/agent-core-v2/src/debug/errors.ts

@@ -0,0 +1,10 @@
+import { registerErrorDomain, type ErrorDomain } from '#/_base/errors/codes';
+
+export const DebugErrors = {
+  codes: {
+    DEBUG_SCOPE_NOT_FOUND: 'debug.scope_not_found',
+    DEBUG_TOKEN_NOT_FOUND: 'debug.token_not_found',
+  },
+} as const satisfies ErrorDomain;
+
+registerErrorDomain(DebugErrors);

packages/agent-core-v2/src/debug/index.ts

@@ -0,0 +1,7 @@
+export * from './debugLedger';
+export * from './debugGraph';
+export * from './debugCascade';
+export * from './errors';
+export * from './debugLedgerService';
+export * from './debugGraphService';
+export * from './debugCascadeService';

packages/agent-core-v2/src/debug/scopeTree.ts

@@ -0,0 +1,38 @@
+import type { CascadeEngine } from '#/_base/di/cascadeEngine';
+import type { InstantiationService } from '#/_base/di/instantiationService';
+
+export interface ScopeContainerInfo {
+  readonly container: InstantiationService;
+  readonly path: string;
+  readonly label: string;
+}
+
+export function scopeContainerLabel(container: InstantiationService): string {
+  return container.debugLabel ?? `#${container.cascadeTree.seqOf(container)}`;
+}
+
+export function walkScopeContainers(root: InstantiationService): ScopeContainerInfo[] {
+  const out: ScopeContainerInfo[] = [];
+  const visit = (container: InstantiationService, path: string): void => {
+    out.push({ container, path, label: scopeContainerLabel(container) });
+    for (const child of container.children) {
+      visit(child, `${path}/${scopeContainerLabel(child)}`);
+    }
+  };
+  visit(root, scopeContainerLabel(root));
+  return out;
+}
+
+export function resolveScopeContainer(
+  root: InstantiationService,
+  path: string,
+): InstantiationService | undefined {
+  return walkScopeContainers(root).find((info) => info.path === path)?.container;
+}
+
+export function scopePathOfEngine(
+  root: InstantiationService,
+  engine: CascadeEngine,
+): string | undefined {
+  return walkScopeContainers(root).find((info) => info.container.cascade === engine)?.path;
+}

packages/agent-core-v2/src/env.d.ts

@@ -0,0 +1,4 @@
+declare module '*?raw' {
+  const content: string;
+  export default content;
+}

packages/agent-core-v2/src/errors.ts

@@ -0,0 +1,257 @@
+import { CoreErrors } from '#/_base/errors/codes';
+import type { KimiErrorPayload } from '#/_base/errors/serialize';
+import { AgentLifecycleErrors } from '#/session/agentLifecycle/errors';
+import { AuthErrors } from '#/app/auth/errors';
+import { TaskErrors } from '#/agent/task/errors';
+import { ProtocolErrors } from '#/llm-adapter/protocol/errors';
+import { ConfigErrors } from '#/app/config/errors';
+import { CapabilityErrors } from '#/app/capability/errors';
+import { CronErrors } from '#/features/cron/errors';
+import { DebugErrors } from '#/debug/errors';
+import { EventErrors } from '#/app/event/errors';
+import { FileErrors } from '#/app/file/fileService';
+import { FsErrors } from '#/workspace/workspaceFs/internal/errors';
+import { FullCompactionErrors } from '#/agent/fullCompaction/errors';
+import { GoalErrors } from '#/features/goal/errors';
+import { LoopErrors } from '#/agent/loop/errors';
+import { McpErrors } from '#/mcpCore/errors';
+import { ModelCatalogErrors } from '#/llm-adapter/model/errors';
+import { OsFsErrors } from '#/os/interface/hostFsErrors';
+import { OsProcessErrors } from '#/os/interface/hostProcess';
+import { PluginErrors } from '#/app/plugin/errors';
+import { ProfileErrors } from '#/agent/profile/errors';
+import { PromptErrors } from '#/agent/prompt/errors';
+import { ModelsDevImportErrors } from '#/app/kosongConfig/errors';
+import { SessionExportErrors } from '#/app/sessionExport/errors';
+import { SessionErrors } from '#/session/errors';
+import { SkillErrors } from '#/features/skill/catalog/errors';
+import { StateErrors } from '#/state/errors';
+import { StorageErrors } from '#/persistence/interface/storage';
+import { TerminalErrors } from '#/os/interface/terminalErrors';
+import { UsageErrors } from '#/agent/usage/errors';
+import { WebErrors } from '#/app/web/errors';
+import { WireErrors } from '#/wire/errors';
+import { WorkspaceErrors } from '#/app/workspace/errors';
+
+export * from '#/_base/errors/codes';
+export * from '#/_base/errors/errorMessage';
+export * from '#/_base/errors/errors';
+export * from '#/_base/errors/serialize';
+export * from '#/_base/errors/unexpectedError';
+export { AgentLifecycleErrors } from '#/session/agentLifecycle/errors';
+export { AuthErrors } from '#/app/auth/errors';
+export { TaskErrors } from '#/agent/task/errors';
+export { ProtocolErrors } from '#/llm-adapter/protocol/errors';
+export { ConfigErrors } from '#/app/config/errors';
+export { CapabilityErrors } from '#/app/capability/errors';
+export { CronErrors } from '#/features/cron/errors';
+export { DebugErrors } from '#/debug/errors';
+export { FileErrors } from '#/app/file/fileService';
+export { FsErrors } from '#/workspace/workspaceFs/internal/errors';
+export { FullCompactionErrors } from '#/agent/fullCompaction/errors';
+export { GoalErrors } from '#/features/goal/errors';
+export { LoopErrors } from '#/agent/loop/errors';
+export { McpErrors } from '#/mcpCore/errors';
+export { ModelCatalogErrors } from '#/llm-adapter/model/errors';
+export { OsFsErrors } from '#/os/interface/hostFsErrors';
+export { OsProcessErrors } from '#/os/interface/hostProcess';
+export { PluginErrors } from '#/app/plugin/errors';
+export { ProfileErrors } from '#/agent/profile/errors';
+export { PromptErrors } from '#/agent/prompt/errors';
+export { ModelsDevImportErrors } from '#/app/kosongConfig/errors';
+export { SessionExportErrors } from '#/app/sessionExport/errors';
+export { SessionErrors } from '#/session/errors';
+export { SkillErrors } from '#/features/skill/catalog/errors';
+export { StorageErrors } from '#/persistence/interface/storage';
+export { TerminalErrors } from '#/os/interface/terminalErrors';
+export { UsageErrors } from '#/agent/usage/errors';
+export { WebErrors } from '#/app/web/errors';
+export { WireErrors } from '#/wire/errors';
+export { WorkspaceErrors } from '#/app/workspace/errors';
+export { EventErrors } from '#/app/event/errors';
+export { StateErrors } from '#/state/errors';
+
+export const ErrorCodes = {
+  ...CoreErrors.codes,
+  ...AgentLifecycleErrors.codes,
+  ...AuthErrors.codes,
+  ...TaskErrors.codes,
+  ...ProtocolErrors.codes,
+  ...ConfigErrors.codes,
+  ...CapabilityErrors.codes,
+  ...CronErrors.codes,
+  ...DebugErrors.codes,
+  ...FileErrors.codes,
+  ...FsErrors.codes,
+  ...FullCompactionErrors.codes,
+  ...GoalErrors.codes,
+  ...LoopErrors.codes,
+  ...McpErrors.codes,
+  ...ModelCatalogErrors.codes,
+  ...OsFsErrors.codes,
+  ...OsProcessErrors.codes,
+  ...PluginErrors.codes,
+  ...ProfileErrors.codes,
+  ...PromptErrors.codes,
+  ...ModelsDevImportErrors.codes,
+  ...SessionExportErrors.codes,
+  ...SessionErrors.codes,
+  ...SkillErrors.codes,
+  ...StorageErrors.codes,
+  ...TerminalErrors.codes,
+  ...UsageErrors.codes,
+  ...WebErrors.codes,
+  ...WireErrors.codes,
+  ...WorkspaceErrors.codes,
+  ...EventErrors.codes,
+  ...StateErrors.codes,
+} as const;
+
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+export type KimiErrorCode =
+  | 'config.invalid'
+  | 'config.persist_blocked'
+  | 'session.not_found'
+  | 'session.already_exists'
+  | 'session.id_invalid'
+  | 'session.id_required'
+  | 'session.id_empty'
+  | 'session.title_empty'
+  | 'session.state_not_found'
+  | 'session.state_invalid'
+  | 'session.fork_active_turn'
+  | 'session.undo_unavailable'
+  | 'session.export_not_found'
+  | 'session.export_missing_version'
+  | 'session.export_output_conflict'
+  | 'session.export_too_large'
+  | 'session.closed'
+  | 'session.permission_mode_invalid'
+  | 'session.thinking_empty'
+  | 'session.model_empty'
+  | 'session.plan_mode_invalid'
+  | 'session.approval_handler_error'
+  | 'session.question_handler_error'
+  | 'session.init_failed'
+  | 'agent.not_found'
+  | 'agent.already_exists'
+  | 'agent.already_running'
+  | 'agent.not_a_subagent'
+  | 'agent.not_owned'
+  | 'agent.type_not_allowed'
+  | 'agent.max_tokens_exceeded'
+  | 'turn.agent_busy'
+  | 'goal.already_exists'
+  | 'goal.not_found'
+  | 'goal.objective_empty'
+  | 'goal.objective_too_long'
+  | 'goal.status_invalid'
+  | 'goal.metadata_reserved'
+  | 'goal.not_resumable'
+  | 'goal.unsupported_agent'
+  | 'model.not_configured'
+  | 'model.config_invalid'
+  | 'profile.thinking_alias_conflict'
+  | 'profile.unknown'
+  | 'profile.already_bound'
+  | 'profile.not_bound'
+  | 'model.not_found'
+  | 'auth.login_required'
+  | 'auth.provisioning_required'
+  | 'auth.token_missing'
+  | 'auth.token_unauthorized'
+  | 'auth.model_not_resolved'
+  | 'context.overflow'
+  | 'loop.max_steps_exceeded'
+  | 'provider.api_error'
+  | 'provider.filtered'
+  | 'provider.rate_limit'
+  | 'provider.auth_error'
+  | 'provider.connection_error'
+  | 'provider.overloaded'
+  | 'provider.not_found'
+  | 'skill.not_found'
+  | 'skill.type_unsupported'
+  | 'skill.name_empty'
+  | 'skill.parse_failed'
+  | 'skill.nested_too_deep'
+  | 'records.write_failed'
+  | 'compaction.failed'
+  | 'compaction.unable'
+  | 'task.task_id_empty'
+  | 'task.limit_exceeded'
+  | 'usage.turn_id_conflict'
+  | 'mcp.server_not_found'
+  | 'mcp.server_disabled'
+  | 'mcp.startup_failed'
+  | 'mcp.tool_name_collision'
+  | 'mcp.oauth_failed'
+  | 'message.not_found'
+  | 'plugin.not_found'
+  | 'plugin.load_failed'
+  | 'request.invalid'
+  | 'request.work_dir_required'
+  | 'request.prompt_input_empty'
+  | 'prompt.id_conflict'
+  | 'prompt.not_found'
+  | 'session.busy'
+  | 'shell.git_bash_not_found'
+  | 'workspace.not_found'
+  | 'terminal.not_found'
+  | 'file.not_found'
+  | 'file.too_large'
+  | 'fs.path_not_found'
+  | 'fs.permission_denied'
+  | 'fs.path_escapes'
+  | 'fs.is_directory'
+  | 'fs.is_binary'
+  | 'fs.too_large'
+  | 'fs.already_exists'
+  | 'fs.too_many_results'
+  | 'fs.grep_timeout'
+  | 'fs.git_unavailable'
+  | 'os.fs.not_found'
+  | 'os.fs.is_directory'
+  | 'os.fs.not_directory'
+  | 'os.fs.already_exists'
+  | 'os.fs.permission_denied'
+  | 'os.fs.not_empty'
+  | 'os.fs.unavailable'
+  | 'os.fs.unknown'
+  | 'os.process.spawn_failed'
+  | 'os.process.kill_failed'
+  | 'storage.not_found'
+  | 'storage.decode_failed'
+  | 'storage.corrupted'
+  | 'storage.io_failed'
+  | 'storage.locked'
+  | 'storage.permission_denied'
+  | 'storage.disk_full'
+  | 'wire.duplicate_op'
+  | 'wire.cycle'
+  | 'wire.unknown_record'
+  | 'wire.migration_missing'
+  | 'cron.expression_invalid'
+  | 'web.invalid_url'
+  | 'web.private_address'
+  | 'web.fetch_failed'
+  | 'validation.failed'
+  | 'not_implemented'
+  | 'internal';
+
+export interface ErrorEvent {
+  readonly type: 'error';
+  readonly code: KimiErrorCode;
+  readonly message: string;
+  readonly name?: string;
+  readonly details?: Record<string, unknown>;
+  readonly retryable: boolean;
+  readonly cause?: KimiErrorPayload;
+}
+
+export interface WarningEvent {
+  readonly type: 'warning';
+  readonly message: string;
+  readonly code?: string;
+}

packages/agent-core-v2/src/events.ts

@@ -0,0 +1,87 @@
+import type { CompactionBlockedEvent, CompactionCancelledEvent, CompactionCompletedEvent, CompactionStartedEvent } from '#/agent/fullCompaction/compactionOps';
+import type { TurnStartedEvent, TurnStepCompletedEvent, TurnStepInterruptedEvent, TurnStepRetryingEvent, TurnStepStartedEvent, AssistantDeltaEvent, ThinkingDeltaEvent } from '#/agent/loop/turnEvents';
+import type { TurnEndedEvent } from '#/agent/loop/turnOps';
+import type { PluginCommandActivatedEvent } from '#/agent/pluginCommand/pluginCommand';
+import type { PromptAbortedEvent, PromptCompletedEvent, PromptSteeredEvent, PromptSubmittedEvent } from '#/agent/prompt/promptEvents';
+import type { BackgroundTaskStartedEvent, BackgroundTaskTerminatedEvent, TaskStartedEvent, TaskTerminatedEvent } from '#/agent/task/types';
+import type { McpServerStatusEvent, ShellCompletedEvent, ShellOutputEvent, ShellStartedEvent, ToolCallDeltaEvent, ToolCallStartedEvent, ToolListUpdatedEvent, ToolProgressEvent } from '#/agent/toolExecutor/toolExecutorEvents';
+import type { ToolResultEventPayload } from '#/agent/toolExecutor/toolExecutorEvents';
+import type { AgentStatusUpdatedEvent } from '#/agent/usage/usageEvents';
+import type { CapabilityChangedEvent } from '#/app/capability/capabilityEvents';
+import type { ConfigChangedEvent, ConfigWarningEvent } from '#/app/config/configEvents';
+import type { ModelCatalogChangedEvent } from '#/app/kosongConfig/discovery';
+import type { PluginChangedEvent } from '#/app/plugin/pluginEvents';
+import type { SessionCreatedEvent, SessionStatusChangedEvent, SessionWorkChangedEvent } from '#/app/sessionLegacy/sessionProtocol';
+import type { WorkspaceCreatedEvent, WorkspaceDeletedEvent, WorkspaceUpdatedEvent } from '#/app/workspace/workspaceProtocol';
+import type { CronFiredEvent } from '#/features/cron/cronOps';
+import type { HookResultEvent } from '#/features/externalHooks/agent/agentExternalHooksService';
+import type { GoalUpdatedEvent } from '#/features/goal/goalOps';
+import type { SkillActivatedEvent } from '#/features/skill/skillOps';
+import type { SubagentSuspendedEvent } from '#/features/swarm/session/sessionSwarmService';
+import type { SessionMetaUpdatedEvent } from '#/session/sessionMetadata/sessionMetaEvents';
+import type { SubagentCancelledEvent, SubagentCompletedEvent, SubagentFailedEvent, SubagentSpawnedEvent, SubagentStartedEvent } from '#/session/subagent/mirrorAgentRun';
+
+import type { ErrorEvent, WarningEvent } from './errors';
+
+export interface ToolResultEvent extends Omit<ToolResultEventPayload, 'agentId'> {
+  readonly type: 'tool.result';
+}
+
+export type AgentEvent =
+  | ErrorEvent
+  | WarningEvent
+  | AgentStatusUpdatedEvent
+  | SessionMetaUpdatedEvent
+  | SessionCreatedEvent
+  | WorkspaceCreatedEvent
+  | WorkspaceUpdatedEvent
+  | WorkspaceDeletedEvent
+  | SessionWorkChangedEvent
+  | SessionStatusChangedEvent
+  | ConfigChangedEvent
+  | ConfigWarningEvent
+  | ModelCatalogChangedEvent
+  | PluginChangedEvent
+  | CapabilityChangedEvent
+  | GoalUpdatedEvent
+  | SkillActivatedEvent
+  | PluginCommandActivatedEvent
+  | TurnStartedEvent
+  | TurnEndedEvent
+  | TurnStepStartedEvent
+  | TurnStepCompletedEvent
+  | TurnStepRetryingEvent
+  | TurnStepInterruptedEvent
+  | AssistantDeltaEvent
+  | HookResultEvent
+  | ThinkingDeltaEvent
+  | ToolCallDeltaEvent
+  | ToolCallStartedEvent
+  | ToolProgressEvent
+  | ShellOutputEvent
+  | ShellStartedEvent
+  | ShellCompletedEvent
+  | ToolResultEvent
+  | ToolListUpdatedEvent
+  | McpServerStatusEvent
+  | SubagentSpawnedEvent
+  | SubagentStartedEvent
+  | SubagentSuspendedEvent
+  | SubagentCompletedEvent
+  | SubagentFailedEvent
+  | SubagentCancelledEvent
+  | CompactionStartedEvent
+  | CompactionBlockedEvent
+  | CompactionCancelledEvent
+  | CompactionCompletedEvent
+  | TaskStartedEvent
+  | TaskTerminatedEvent
+  | BackgroundTaskStartedEvent
+  | BackgroundTaskTerminatedEvent
+  | CronFiredEvent
+  | PromptSubmittedEvent
+  | PromptCompletedEvent
+  | PromptAbortedEvent
+  | PromptSteeredEvent;
+
+export type Event = AgentEvent & { agentId: string; sessionId: string };

packages/agent-core-v2/src/features/feature.ts

@@ -0,0 +1,117 @@
+import { type CollectionToken } from '#/_base/di/collection';
+import {
+  ScopeUnits,
+  type Fiber,
+  type FiberHandle,
+  type FiberProvideOptions,
+  type ServiceClassRecipe,
+} from '#/_base/di/fiber';
+import { ScopeActivation, type ServiceIdentifier } from '#/_base/di/instantiation';
+import { toDisposable } from '#/_base/di/lifecycle';
+import { Service } from '#/_base/di/service';
+import {
+  AgentProfileContribution,
+  AGENT_PROFILE_SOURCE_PRIORITY,
+} from '#/app/agentProfileCatalog/agentProfileContribution';
+import { FeatureServiceContribution } from '#/app/feature/featureServiceContribution';
+import type { AgentProfile } from '#/app/agentProfileCatalog/agentProfileCatalog';
+import type { ConfigSchema, RegisterSectionOptions } from '#/app/config/config';
+import { ConfigSectionContribution } from '#/app/config/configSectionContributions';
+import { LifecycleScope } from '#/app/scopes';
+import {
+  CommandContribution,
+  type CommandContribution as CommandContributionPayload,
+} from '#/agent/command/commandContribution';
+import {
+  AgentToolContribution,
+  type AgentToolContributionOptions,
+  type AgentToolCtor,
+  type AnyAgentTool,
+} from '#/agent/toolRegistry/toolContribution';
+import type {
+  AgentModel,
+  AgentModelDefinition,
+  SessionModelDefinition,
+} from '#/state/agentModel';
+import { AgentModelContribution, SessionModelContribution } from '#/state/agentModel';
+
+export abstract class Feature extends Service {
+  contribute<T>(token: CollectionToken<T>, value: T): FiberHandle {
+    return this.provide(token, value);
+  }
+
+  contributeSessionModel<State>(definition: SessionModelDefinition<State>): FiberHandle {
+    return this.provide(SessionModelContribution, definition as SessionModelDefinition);
+  }
+
+  contributeAgentModel<S, M extends AgentModel<S>>(
+    definition: AgentModelDefinition<S, M>,
+  ): FiberHandle {
+    return this.provide(AgentModelContribution, definition as AgentModelDefinition<any, any>);
+  }
+
+  contributeConfig<T>(
+    domain: string,
+    schema: ConfigSchema<T>,
+    options: RegisterSectionOptions<T> = {},
+  ): FiberHandle {
+    return this.provide(ConfigSectionContribution, {
+      domain,
+      schema: schema as ConfigSchema<unknown>,
+      options: options as RegisterSectionOptions<unknown>,
+    });
+  }
+
+  contributeService<T>(
+    scope: LifecycleScope,
+    id: ServiceIdentifier<T>,
+    ctor: ServiceClassRecipe,
+    opts?: FiberProvideOptions,
+  ): FiberHandle {
+    this.provide(FeatureServiceContribution, { scope, id });
+    return this.provide(ScopeUnits(scope), {
+      name: `${this.name}:${String(id)}`,
+      apply(fiber: Fiber): void {
+        fiber.provide(id, ctor, opts);
+      },
+    });
+  }
+
+  contributeAgentService<T>(
+    id: ServiceIdentifier<T>,
+    ctor: ServiceClassRecipe,
+    opts?: FiberProvideOptions,
+  ): FiberHandle {
+    return this.contributeService(LifecycleScope.Agent, id, ctor, opts);
+  }
+
+  contributeTool<T extends AnyAgentTool>(
+    id: ServiceIdentifier<T>,
+    ctor: AgentToolCtor<T>,
+    options: AgentToolContributionOptions,
+  ): void {
+    this.contributeService(LifecycleScope.Agent, id, ctor, {
+      activation: ScopeActivation.OnDemand,
+    });
+    this.provide(AgentToolContribution, { id, ctor, options });
+  }
+
+  contributeCommand(contribution: CommandContributionPayload): FiberHandle {
+    return this.provide(CommandContribution, contribution);
+  }
+
+  contributeProfiles(
+    profiles: readonly AgentProfile[],
+    opts?: { readonly sourceId?: string; readonly priority?: number },
+  ): FiberHandle {
+    return this.provide(AgentProfileContribution, {
+      sourceId: opts?.sourceId ?? `feature:${this.name}`,
+      priority: opts?.priority ?? AGENT_PROFILE_SOURCE_PRIORITY.builtin,
+      contribution: { profiles },
+    });
+  }
+
+  onDispose(fn: () => void): void {
+    this._register(toDisposable(fn));
+  }
+}

packages/agent-core-v2/src/features/featureAssembly.ts

@@ -0,0 +1,8 @@
+import { createDecorator, type ServiceIdentifier } from '#/_base/di/instantiation';
+
+export interface IFeatureAssemblyService {
+  readonly _serviceBrand: undefined;
+}
+
+export const IFeatureAssemblyService: ServiceIdentifier<IFeatureAssemblyService> =
+  createDecorator<IFeatureAssemblyService>('featureAssemblyService');

packages/agent-core-v2/src/features/featureAssemblyService.ts

@@ -0,0 +1,26 @@
+import { IFeatureManager } from '#/app/feature/featureManager';
+import { LifecycleScope } from '#/app/scopes';
+import { ScopeActivation, registerScopedService } from '#/_base/di/scope';
+import { Service } from '#/_base/di/service';
+
+import { IFeatureAssemblyService } from './featureAssembly';
+import { getFeatureRecipes } from './featureRegistry';
+
+export class FeatureAssemblyService extends Service implements IFeatureAssemblyService {
+  declare readonly _serviceBrand: undefined;
+
+  constructor(@IFeatureManager featureManager: IFeatureManager) {
+    super();
+    for (const recipe of getFeatureRecipes()) {
+      featureManager.provideUnit(recipe);
+    }
+  }
+}
+
+registerScopedService(
+  LifecycleScope.App,
+  IFeatureAssemblyService,
+  FeatureAssemblyService,
+  ScopeActivation.OnScopeCreated,
+  'features',
+);

packages/agent-core-v2/src/features/featureRegistry.ts

@@ -0,0 +1,15 @@
+import type { ServiceClassRecipe } from '#/_base/di/fiber';
+
+const _featureRecipes: ServiceClassRecipe[] = [];
+
+export function registerFeature(recipe: ServiceClassRecipe): void {
+  _featureRecipes.push(recipe);
+}
+
+export function getFeatureRecipes(): readonly ServiceClassRecipe[] {
+  return _featureRecipes;
+}
+
+export function _clearFeatureRecipesForTests(): void {
+  _featureRecipes.length = 0;
+}

packages/agent-core-v2/src/hooks.ts

@@ -0,0 +1,112 @@
+import { toDisposable, type IDisposable } from "#/_base/di/lifecycle";
+import { BugIndicatingError } from "#/errors";
+
+export type Hooks<TEvents extends Record<string, unknown>> = {
+  readonly [K in keyof TEvents]: HookSlot<TEvents[K]>;
+};
+
+export interface HookSlot<TContext> {
+  register(
+    id: string,
+    handler: HookHandler<TContext>,
+    options?: HookRegisterOptions,
+  ): IDisposable;
+
+  delete(id: string): boolean;
+
+  run(context: TContext, terminal?: (context: TContext) => Promise<void>): Promise<void>;
+}
+
+export type HookHandler<TContext> = (
+  context: TContext,
+  next: (context?: TContext) => Promise<void>,
+) => void | Promise<void>;
+
+export interface HookRegisterOptions {
+  before?: string;
+  after?: string;
+}
+
+interface HookEntry<TContext> {
+  readonly id: string;
+  readonly handler: HookHandler<TContext>;
+}
+
+export class OrderedHookSlot<TContext> implements HookSlot<TContext> {
+  private entries: HookEntry<TContext>[] = [];
+
+  register(
+    id: string,
+    handler: HookHandler<TContext>,
+    options: HookRegisterOptions = {},
+  ): IDisposable {
+    if (options.before !== undefined && options.after !== undefined) {
+      throw new BugIndicatingError('Hook registration cannot specify both before and after');
+    }
+
+    this.delete(id);
+    const entry = { id, handler };
+    const target = options.before ?? options.after;
+    if (target === undefined) {
+      this.entries.push(entry);
+      return this.toEntryDisposable(entry);
+    }
+
+    const targetIndex = this.entries.findIndex((item) => item.id === target);
+    if (targetIndex < 0) {
+      throw new BugIndicatingError(`Hook target "${target}" is not registered`);
+    }
+
+    const insertAt = options.before !== undefined ? targetIndex : targetIndex + 1;
+    this.entries.splice(insertAt, 0, entry);
+    return this.toEntryDisposable(entry);
+  }
+
+  delete(id: string): boolean {
+    const index = this.entries.findIndex((entry) => entry.id === id);
+    if (index < 0) return false;
+    this.entries.splice(index, 1);
+    return true;
+  }
+
+  asDisposable(id: string): IDisposable {
+    return toDisposable(() => {
+      this.delete(id);
+    });
+  }
+
+  private toEntryDisposable(entry: HookEntry<TContext>): IDisposable {
+    return toDisposable(() => {
+      const index = this.entries.indexOf(entry);
+      if (index < 0) return;
+      this.entries.splice(index, 1);
+    });
+  }
+
+  async run(
+    context: TContext,
+    terminal: (context: TContext) => Promise<void> = async () => {},
+  ): Promise<void> {
+    const entries = [...this.entries];
+    const dispatch = (index: number, ctx: TContext): ((override?: TContext) => Promise<void>) => {
+      return async (override?: TContext): Promise<void> => {
+        const current = override ?? ctx;
+        const entry = entries[index];
+        if (entry === undefined) {
+          await terminal(current);
+          return;
+        }
+        await entry.handler(current, dispatch(index + 1, current));
+      };
+    };
+    await dispatch(0, context)();
+  }
+}
+
+export function createHooks<TEvents extends Record<string, unknown>, TKeys extends keyof TEvents>(
+  keys: readonly TKeys[],
+): Hooks<TEvents> {
+  return Object.fromEntries(
+    keys.map((key) => [key, new OrderedHookSlot<TEvents[TKeys]>()]),
+  ) as unknown as Hooks<TEvents>;
+}

packages/agent-core-v2/src/human/index.ts

@@ -0,0 +1,97 @@
+export * from './llm/message';
+export * from './llm/model';
+export * from './llm/capability';
+export * from './models-dev/models-dev';
+export * from './llm/errors';
+export * from './llm/syntax-errors';
+export * from './llm/thinking';
+export * from './llm/response-format';
+export * from './llm/finish-reason';
+export * from './llm/usage';
+export * from './plugin';
+export * from './llm/protocol/format';
+export * from './llm/protocol/base';
+export * from './llm/protocol/connection';
+export * from './llm/protocol/thinking';
+export * from './llm/protocol/rewrite';
+export * from './llm/protocol/patterns';
+export * from './llm/media';
+export * from './llm/requester/requester';
+export * from './llm/empty-response';
+export * from './llm/requester/actor';
+export * from './llm/requester/recovery';
+export * from './llm/requester/retry';
+export * from './llm/requester/bases/openai/contract';
+export * from './llm/requester/bases/openai/capability';
+export * from './llm/requester/bases/openai/trait';
+export * from './llm/requester/bases/openai/extra-params';
+export * from './llm/requester/bases/openai/requester';
+export * from './llm/requester/bases/openai-responses/contract';
+export * from './llm/requester/bases/openai-responses/capability';
+export * from './llm/requester/bases/openai-responses/trait';
+export * from './llm/requester/bases/openai-responses/extra-params';
+export * from './llm/requester/bases/openai-responses/requester';
+export * from './llm/requester/bases/google-genai/contract';
+export * from './llm/requester/bases/google-genai/capability';
+export * from './llm/requester/bases/google-genai/trait';
+export * from './llm/requester/bases/google-genai/extra-params';
+export * from './llm/requester/bases/google-genai/requester';
+export * from './llm/requester/bases/anthropic/contract';
+export * from './llm/requester/bases/anthropic/capability';
+export * from './llm/requester/bases/anthropic/trait';
+export * from './llm/requester/bases/anthropic/extra-params';
+export * from './llm/requester/bases/anthropic/profile';
+export * from './llm/requester/bases/anthropic/requester';
+export * from './llm/requester/bases/tool-call-id';
+export * from './llm/requester/bases/tool-result-text';
+export * from './llm/provider/definition';
+export * from './llm/provider-catalog';
+export * from './llm-kimi/provider';
+export * from './llm-kimi/errors';
+export * from './llm-kimi/files';
+export * from './llm-kimi/media';
+export * from './llm-kimi/schema';
+export * from './llm-kimi/trait';
+export * from './llm/provider/providers/standard';
+export * from './credentials';
+export * from './tool/executor';
+export * from './tool/machine';
+export * from './tool/wait-for';
+export * from './tool/tool';
+export * from './media/tool';
+export * from './agent/errors';
+export * from './agent/machine';
+export * from './agent/wait-for';
+export * from './agent/turn';
+export * from './agent/context-usage';
+export * from './agent/events';
+export * from './agent/slices';
+export * from './agent/historySchema';
+export * from './persist/open';
+export * from './eventStore/index';
+export * from './persist/v2/migrate';
+export * from './session/machine';
+export * from './session/events';
+export * from './session/slices';
+export * from './session/stores';
+export * from './compaction/controller';
+export * from './compaction/errors';
+export * from './compaction/shape';
+export * from './compaction/summarize';
+export * from './usage/usage';
+export * from './usage/machine';
+export * from './usage/plugin';
+export * from './timing/plugin';
+export * from './interaction/interaction';
+export * from './interaction/machine';
+export * from './interaction/facade';
+export * from './kimi/trace';
+export * from './todo/todoItem';
+export * from './todo/slice';
+export * from './todo/tool';
+export * from './todo/plugin';
+export * from './tool-select/state';
+export * from './tool-select/tool';
+export * from './tool-select/plugin';
+export * from './tool-select/resolver';
+export * from './store';

packages/agent-core-v2/src/human/package.json

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "imports": {
+    "#/*": "./*.ts"
+  }
+}

packages/agent-core-v2/src/human/plugin.ts

@@ -0,0 +1,54 @@
+import type { SystemMessage, UserMessage } from '#/llm/message';
+import type { AgentEmitted } from '#/agent/machine';
+import { createSystemEntry, createUserEntry, type SystemEntry, type UserEntry } from '#/agent/turn';
+import type { ToolDefinition } from '#/tool/tool';
+
+export interface AgentPluginTarget {
+  kind: 'agent';
+  on(type: AgentEmitted['type'], handler: (event: AgentEmitted) => void): unknown;
+  notify(message: UserMessage): void;
+  remind(key: string, message: UserMessage | SystemMessage): void;
+}
+
+export type PluginTarget = AgentPluginTarget;
+
+export interface Plugin {
+  readonly name: string;
+  tools?(): readonly ToolDefinition[];
+  connect?(target: PluginTarget): void;
+}
+
+export function collectPluginTools(plugins: readonly Plugin[]): readonly ToolDefinition[] {
+  return plugins.flatMap((plugin) => plugin.tools?.() ?? []);
+}
+
+export interface AgentPluginSource {
+  on(type: AgentEmitted['type'], handler: (event: AgentEmitted) => void): unknown;
+  send(
+    event:
+      | { type: 'input.notify'; entry: UserEntry }
+      | { type: 'input.remind'; key: string; entry: SystemEntry | UserEntry },
+  ): void;
+}
+
+export function connectPlugins(actor: AgentPluginSource, plugins: readonly Plugin[]): void {
+  const target: AgentPluginTarget = {
+    kind: 'agent',
+    on: (type, handler) => {
+      actor.on(type, handler);
+    },
+    notify: (message) => {
+      actor.send({ type: 'input.notify', entry: { message } });
+    },
+    remind: (key, message) => {
+      actor.send({
+        type: 'input.remind',
+        key,
+        entry: message.role === 'system' ? createSystemEntry(message) : createUserEntry(message),
+      });
+    },
+  };
+  for (const plugin of plugins) {
+    plugin.connect?.(target);
+  }
+}

packages/agent-core-v2/src/human/xstate2.ts

@@ -0,0 +1,49 @@
+import { createActor as createXStateActor } from 'xstate';
+import type { Actor, ActorOptions, AnyActorLogic } from 'xstate';
+
+import { isAbortError } from '#/llm/errors';
+import { xstateInspectionCollector } from '#/xstateInspection';
+
+export * from 'xstate';
+
+export type RootActorErrorReporter = (err: unknown) => void;
+
+let reportRootActorError: RootActorErrorReporter = () => {};
+
+export function setRootActorErrorReporter(reporter: RootActorErrorReporter): void {
+  reportRootActorError = reporter;
+}
+
+function createActorWithInspect<TLogic extends AnyActorLogic>(
+  logic: TLogic,
+  options?: ActorOptions<TLogic>,
+): Actor<TLogic> {
+  const inspect = options?.inspect;
+  const actor = createXStateActor(logic, {
+    ...options,
+    inspect: (event) => {
+      xstateInspectionCollector.publish(event);
+      if (typeof inspect === 'function') {
+        inspect(event);
+      } else {
+        inspect?.next?.(event);
+      }
+    },
+  });
+  swallowRootAbortError(actor);
+  return actor;
+}
+
+function swallowRootAbortError(actor: Actor<AnyActorLogic>): void {
+  const internal = actor as unknown as { _reportError(err: unknown): void };
+  const reportError = internal._reportError.bind(actor);
+  internal._reportError = (err: unknown) => {
+    if (isAbortError(err)) {
+      reportRootActorError(err);
+      return;
+    }
+    reportError(err);
+  };
+}
+
+export const createActor = createActorWithInspect as typeof createXStateActor;

packages/agent-core-v2/src/human/xstateInspection.ts

@@ -0,0 +1,72 @@
+import type { InspectionEvent } from 'xstate';
+
+export type XstateInspectionEventType = InspectionEvent['type'];
+
+export interface XstateInspectionEnvelope {
+  readonly type: XstateInspectionEventType;
+  readonly timestamp: number;
+  readonly actorSessionId: string;
+  readonly actorId?: string;
+  readonly logicId?: string;
+  readonly eventType?: string;
+  readonly stateValue?: unknown;
+  readonly unhandled?: boolean;
+}
+
+export type XstateInspectionListener = (envelope: XstateInspectionEnvelope) => void;
+
+export interface XstateInspectionCollector {
+  subscribe(listener: XstateInspectionListener): () => void;
+  publish(event: InspectionEvent): void;
+}
+
+function scalar(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+function toEnvelope(event: InspectionEvent, now: () => number): XstateInspectionEnvelope {
+  const actorRef = event.actorRef as { id?: unknown; logic?: unknown };
+  const logic = actorRef.logic as { id?: unknown } | undefined;
+  const snapshot = 'snapshot' in event ? (event.snapshot as { value?: unknown }) : undefined;
+  const unhandled =
+    event.type === '@xstate.microstep' &&
+    event._transitions.length === 0 &&
+    !event.event.type.startsWith('xstate.');
+  return {
+    type: event.type,
+    timestamp: now(),
+    actorSessionId: event.actorRef.sessionId,
+    actorId: scalar(actorRef.id),
+    logicId: scalar(logic?.id),
+    eventType:
+      'event' in event
+        ? event.event.type
+        : event.type === '@xstate.action'
+          ? event.action.type
+          : undefined,
+    stateValue: snapshot?.value,
+    unhandled: unhandled || undefined,
+  };
+}
+
+export function createXstateInspectionCollector(input?: {
+  now?: () => number;
+}): XstateInspectionCollector {
+  const now = input?.now ?? Date.now;
+  const listeners = new Set<XstateInspectionListener>();
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    publish(event) {
+      if (listeners.size === 0) return;
+      const envelope = toEnvelope(event, now);
+      for (const listener of listeners) listener(envelope);
+    },
+  };
+}
+
+export const xstateInspectionCollector = createXstateInspectionCollector();

packages/agent-core-v2/src/index.ts

@@ -0,0 +1,758 @@
+export * from '#/_base/di/descriptors';
+export * from '#/_base/di/errors';
+export * from '#/_base/di/graph';
+export * from '#/_base/di/instantiation';
+export * from '#/_base/di/instantiationService';
+export * from '#/_base/di/lifecycle';
+export * from '#/_base/di/scope';
+export * from './app/scopes';
+export * from '#/_base/di/serviceCollection';
+export * from '#/_base/di/cascadeEngine';
+export * from '#/_base/di/dependencyGraph';
+export * from '#/_base/lifecycle/ledger';
+export {
+  collection,
+  isCollectionToken,
+  type CollectionChange,
+  type CollectionRecord,
+  type CollectionToken,
+  type CollectionView,
+} from '#/_base/di/collection';
+export {
+  FiberProtocolError,
+  FiberState,
+  ScopeUnits,
+  ServiceRecipeError,
+  setFiberEventResolver,
+  type ConfigSchema,
+  type Fiber,
+  type FiberHandle,
+  type FiberProvideOptions,
+  type RecipeStatics,
+  type ServiceRecipe,
+} from '#/_base/di/fiber';
+export { Service } from '#/_base/di/service';
+export * from './errors';
+export * from './events';
+export * from '#/runtime/runtime';
+export * from '#/runtime/runtimeRegistry';
+export * from '#/runtime/runtimeWorkspaceView';
+export * from '#/runtime/runtimeProvider';
+export * from '#/runtime/runtimeUnitHost';
+export * from '#/runtime/localRuntime';
+export * from '#/runtime/standaloneRuntime';
+export * from '#/program/program';
+export * from '#/workspace/workspaceInstance/workspaceInstance';
+export * from '#/workspace/workspaceInstance/workspaceInstanceManager';
+export * from '#/workspace/workspaceInstance/workspaceInstanceManagerService';
+export * from '#/agent/runtimeBinding/runtimeBinding';
+export * from '#/agent/runtimeBinding/runtimeBindingService';
+export * from '#/agent/runtimeBinding/agentRuntime';
+export * from '#/app/sessionManager/sessionManager';
+export * from '#/app/sessionManager/sessionManagerService';
+
+export * from '#/_base/log/log';
+export * from '#/_base/log/logConfig';
+export * from '#/_base/log/formatter';
+export * from '#/_base/log/fileLog';
+export * from '#/_base/log/logService';
+export * from '#/wire/wire';
+export * from '#/wire/wireService';
+export * from '#/wire/journal';
+export * from '#/wire/tree/index';
+export * from '#/wire/record';
+export * from '#/wire/migration/migration';
+export * from '#/session/sessionLog/sessionLogService';
+export * from '#/app/telemetry/telemetry';
+export * from '#/app/telemetry/context';
+export * from '#/app/telemetry/events';
+export * from '#/app/telemetry/telemetryService';
+export * from '#/app/telemetry/consoleAppender';
+export * from '#/app/telemetry/cloudAppender';
+export * from '#/app/bootstrap/bootstrap';
+export * from '#/app/bootstrap/bootstrapService';
+export * from '#/os/interface/hostClock';
+export * from '#/os/interface/hostEnvironment';
+export * from '#/os/interface/hostFileSystem';
+export * from '#/os/interface/hostProcess';
+export * from '#/os/interface/terminal';
+export * from '#/os/interface/terminalErrors';
+export * from '#/os/backends/node-local/hostClockService';
+export * from '#/os/backends/node-local/hostEnvironmentService';
+export * from '#/os/backends/node-local/hostFsService';
+export * from '#/os/backends/node-local/hostProcessService';
+export * from '#/os/backends/node-local/hostTerminalService';
+export * from '#/agent/tools/os/bash/bash';
+import '#/agent/tools/os/bash/bashTool';
+export * from '#/agent/tools/os/glob/glob';
+import '#/agent/tools/os/glob/globTool';
+export * from '#/agent/tools/os/grep/grep';
+import '#/agent/tools/os/grep/grepTool';
+export * from '#/agent/tools/os/read/read';
+import '#/agent/tools/os/read/readTool';
+export * from '#/agent/tools/os/write/write';
+import '#/agent/tools/os/write/writeTool';
+export * from '#/os/interface/terminal';
+export * from '#/os/interface/terminalErrors';
+export * from '#/os/backends/node-local/hostTerminalService';
+export * from '#/session/terminal/terminalService';
+export * from '#/app/task/task';
+import '#/app/task/taskService';
+export { TaskService } from '#/app/task/taskService';
+import '#/app/event/eventBusService';
+import '#/app/event/eventService';
+import '#/app/event/fiberEventResolver';
+export { IEventBus } from '#/app/event/eventBus';
+export { IEventService } from '#/app/event/event';
+export * from '#/app/event/errors';
+export * from '#/app/event/event2';
+export * from '#/state/errors';
+export * from '#/state/state';
+export * from '#/state/stateContribution';
+export * from '#/state/agentModel';
+export * from '#/state/eventDispatcher';
+import '#/state/eventDispatcherService';
+export * from '#/_base/state/stateRegistry';
+export * from '#/_base/contribution/registry';
+export * from '#/app/state/appState';
+import '#/app/state/appStateService';
+export * from '#/workspace/state/workspaceState';
+import '#/workspace/state/workspaceStateService';
+export * from '#/session/state/sessionState';
+import '#/session/state/sessionStateService';
+export * from '#/agent/state/agentState';
+import '#/agent/state/agentStateService';
+export * from '#/llm-adapter/contract/capability';
+export * from '#/llm-adapter/contract/errors';
+export {
+  createAssistantMessage,
+  createToolMessage,
+  createUserMessage,
+  isToolDeclarationOnlyMessage,
+  mergeInPlace,
+  type Message,
+} from '#/llm-adapter/contract/message';
+export {
+  extractText,
+  getTextContent,
+  isContentPart,
+  isToolCall,
+  isToolCallPart,
+  type AudioURLPart,
+  type ContentPart,
+  type ImageURLPart,
+  type Role,
+  type StreamedMessagePart,
+  type TextPart,
+  type ThinkPart,
+  type ToolCall,
+  type ToolCallPart,
+  type VideoURLPart,
+} from '#human/llm/message';
+export type { ToolDescription as Tool } from '#human/llm/message';
+export { addUsage, emptyUsage, grandTotal, inputTotal, type TokenUsage } from '#human/llm/usage';
+export type { FinishReason } from '#human/llm/finish-reason';
+export type {
+  JsonObjectResponseFormat,
+  JsonSchemaObject,
+  JsonSchemaResponseFormat,
+  ResponseFormat,
+} from '#human/llm/response-format';
+export type { ThinkingEffort, ThinkingRequestOptions } from '#human/llm/thinking';
+export type { VideoUploadInput } from '#human/llm/media/upload';
+export type { ToolCallIdPolicy } from '#human/llm/requester/requester';
+export type { SamplingOptions } from '#/llm-adapter/model/model-requester';
+export * from '#/llm-adapter/contract/request-trace';
+export type { KimiThinkingConfig } from '#human/llm-kimi/trait';
+
+export * from '#/app/sessionIndex/sessionIndex';
+export * from '#/app/sessionIndex/sessionIndexService';
+export * from '#/app/sessionIndex/sessionIndexMirrorService';
+export * from '#/session/sessionMetadata/sessionMetadata';
+export * from '#/session/sessionMetadata/sessionMetadataService';
+export * from '#/session/sessionMetadata/promptMetadata';
+export * from '#/session/sessionActivity/sessionActivity';
+export * from '#/session/sessionActivity/sessionActivityService';
+export * from '#/session/sessionActivity/sessionOutcomeMirror';
+export * from '#/session/sessionActivity/sessionOutcomeMirrorService';
+export * from '#/session/sessionTitle/agentTitlePromptSource';
+import '#/session/sessionTitle/agentTitlePromptSourceService';
+export * from '#/session/sessionTitle/sessionTitle';
+export * from '#/session/sessionTitle/sessionTitleService';
+export * from '#/session/sessionToolPolicy/sessionToolPolicy';
+export * from '#/session/sessionToolPolicy/sessionToolPolicyService';
+export * from '#/app/config/config';
+export * from '#/app/config/configEvents';
+export type { ConfigChangedEvent } from '#/app/config/configEvents';
+export * from '#/app/config/configService';
+export * from '#/app/config/configSectionContributions';
+import '#/app/kosongConfig/configSection';
+export * from '#/llm-adapter/provider/provider';
+export * from '#/llm-adapter/provider/provider-service';
+export * from '#/llm-adapter/provider/provider-definition';
+export * from '#/llm-adapter/protocol/protocolAdapterRegistry';
+import '#/features/skill/catalog/configSection';
+import '#/app/agentIdentity/configSection';
+export * from '#/app/agentIdentity/configSection';
+export * from '#/app/agentIdentity/agentIdentity';
+export * from '#/app/agentIdentity/agentIdentityService';
+import '#/llm-adapter/protocol/errors';
+export * from '#/llm-adapter/protocol/errors';
+export * from '#/llm-adapter/protocol/protocol';
+export * from '#/llm-adapter/protocol/protocol-base';
+import '#/app/kosongConfig/envOverlay';
+export * from '#/llm-adapter/model/completion-budget';
+export * from '#/llm-adapter/model/host-request-headers';
+export * from '#/llm-adapter/model/model';
+export * from '#/llm-adapter/model/model.types';
+export * from '#/llm-adapter/model/model-service';
+export * from '#/llm-adapter/model/thinking';
+export * from '#/llm-adapter/model/catalog';
+export * from '#/llm-adapter/model/catalog-service';
+export * from '#/llm-adapter/model/model-requester';
+import '#/llm-adapter/model/errors';
+export {
+  MODEL_CATALOG_SECTION,
+  ModelCatalogConfigSchema,
+  type ModelCatalogConfig,
+} from '#/app/kosongConfig/configSection';
+export * from '#/app/kosongConfig/kosongConfig';
+export * from '#/app/kosongConfig/kosongConfigService';
+export * from '#/llm-adapter/model/model-oauth';
+export * from '#/app/kosongConfig/oauthTokenAdapter';
+export * from '#/app/kosongConfig/hostRequestHeadersAdapter';
+export * from '#/app/kosongConfig/discovery';
+export * from '#/app/kosongConfig/discoveryService';
+export * from '#/app/kosongConfig/errors';
+export * from '#/app/kosongConfig/modelsDevImport';
+export * from '#/app/kosongConfig/modelsDevImportService';
+export * from '#/app/kosongConfig/modelsDevUpstream';
+export * from '#/app/kosongConfig/modelsDev';
+export * from '#/app/agentProfileCatalog/agentProfileCatalog';
+export * from '#/app/agentProfileCatalog/agentProfileContribution';
+export * from '#/app/agentProfileCatalog/agentProfileRegistry';
+export * from '#/app/agentProfileCatalog/agentProfileRegistryService';
+export * from '#/app/agentProfileCatalog/builtinAgentProfileLoader';
+export * from '#/app/agentProfileCatalog/builtinAgentProfileLoaderService';
+export * from '#/app/agentProfileCatalog/profile-shared';
+export * from '#/app/agentProfileCatalog/promptPrefix';
+export {
+  registerAgentProfile,
+  getAgentProfileContributions,
+  _clearAgentProfileContributionsForTests,
+} from '#/app/agentProfileCatalog/contribution';
+export * from '#/workspace/workspaceAgentProfileLoader/configSection';
+export { parseAgentFileText } from '#/workspace/workspaceAgentProfileLoader/internal/agentFile';
+export { resolveAgentPath } from '#/workspace/workspaceAgentProfileLoader/internal/paths';
+export * from '#/workspace/workspaceAgentProfileLoader/userAgentProfileLoader';
+export * from '#/workspace/workspaceAgentProfileLoader/userAgentProfileLoaderService';
+export * from '#/app/plugin/types';
+export * from '#/app/plugin/commands';
+export * from '#/app/plugin/manifest';
+export * from '#/app/plugin/store';
+export * from '#/app/plugin/source';
+export * from '#/app/plugin/github-resolver';
+export * from '#/app/plugin/archive';
+export * from '#/app/plugin/manager';
+export * from '#/app/plugin/marketplace';
+export * from '#/app/plugin/plugin';
+export * from '#/app/plugin/pluginEvents';
+export * from '#/app/plugin/pluginService';
+export * from '#/app/capability/capability';
+export * from '#/app/capability/capabilityEvents';
+export * from '#/app/capability/capabilityService';
+export * from '#/app/capability/errors';
+export * from '#/app/capability/types';
+export * from '#/app/feature/featureManager';
+export * from '#/app/feature/featureServiceContribution';
+import '#/app/feature/featureManagerService';
+export * from '#/features/feature';
+export * from '#/features/featureAssembly';
+export * from '#/features/featureRegistry';
+import '#/features/featureAssemblyService';
+export * from '#/agent/command/agentCommand';
+export * from '#/agent/command/commandContribution';
+import '#/agent/command/agentCommandService';
+export * from '#/debug/index';
+export * from '#/workspace/workspaceAgentProfileLoader/pluginAgentProfileLoader';
+export * from '#/workspace/workspaceAgentProfileLoader/pluginAgentProfileLoaderService';
+
+export type { SkillSource } from '#/features/skill/catalog/types';
+export * from '#/features/skill/tools/skill';
+export * from '#/features/skill/skill';
+export * from '#/features/skill/skillService';
+import '#/features/skill/skillFeature';
+export * from '#/features/skill/catalog/types';
+export * from '#/features/skill/catalog/configSection';
+export * from '#/features/skill/catalog/parser';
+export * from '#/features/skill/catalog/registry';
+export * from '#/features/skill/catalog/errors';
+export * from '#/features/skill/catalog/skillDiscovery';
+export * from '#/features/skill/catalog/inMemorySkillDiscovery';
+export * from '#/features/skill/catalog/skillSource';
+export * from '#/features/skill/catalog/skillRoots';
+export * from '#/features/skill/catalog/builtin/builtin';
+export * from '#/features/skill/catalog/builtinSkillSource';
+export * from '#/features/skill/catalog/userFileSkillSource';
+export * from '#/features/skill/session/skillCatalog';
+export * from '#/features/skill/session/skillCatalogData';
+export * from '#/features/skill/session/skillCatalogService';
+export * from '#/session/sessionAgentProfileCatalog/sessionAgentProfileCatalog';
+export * from '#/session/sessionAgentProfileCatalog/agentProfileCatalogSeed';
+export * from '#/session/sessionAgentProfileCatalog/sessionAgentProfileCatalogService';
+export * from '#/session/sessionInstructions/instructionsProvider';
+export * from '#/session/workspaceInfo/workspaceInfo';
+export * from '#/workspace/workspaceDirs/workspaceDirs';
+export * from '#/workspace/workspaceDirs/workspaceDirsService';
+export * from '#/features/skill/workspace/workspaceSkillCatalog';
+export * from '#/features/skill/workspace/workspaceSkillCatalogService';
+export * from '#/features/skill/workspace/extraFileSkillSource';
+export * from '#/features/skill/workspace/explicitFileSkillSource';
+export * from '#/features/skill/workspace/rootFileSkillSource';
+export * from '#/features/skill/workspace/pluginSkillSource';
+export * from '#/workspace/workspaceAgentProfileLoader/workspaceAgentProfileLoader';
+export * from '#/workspace/workspaceAgentProfileLoader/workspaceAgentProfileLoaderService';
+export * from '#/workspace/workspaceAgentProfileLoader/extraAgentProfileLoader';
+export * from '#/workspace/workspaceAgentProfileLoader/extraAgentProfileLoaderService';
+export * from '#/workspace/workspaceAgentProfileLoader/explicitAgentProfileLoader';
+export * from '#/workspace/workspaceAgentProfileLoader/explicitAgentProfileLoaderService';
+export * from '#/workspace/workspaceInstructions/workspaceInstructions';
+export * from '#/workspace/workspaceInstructions/workspaceInstructionsService';
+export * from '#/agent/permissionGate/permissionGate';
+export * from '#/agent/permissionGate/permissionGateService';
+export * from '#/agent/toolApproval/toolApproval';
+export * from '#/agent/toolApproval/toolApprovalService';
+import '#/app/flag/flag';
+import '#/app/flag/flagRegistry';
+import '#/app/flag/flagRegistryService';
+import '#/app/flag/flagService';
+export * from '#/app/flag/flagRegistry';
+export * from '#/app/flag/flagRegistryService';
+export * from '#/app/flag/flag';
+export * from '#/app/flag/flagService';
+
+export * from '#/agent/modeMutex/modeMutex';
+import '#/agent/modeMutex/modeMutexService';
+export * from '#/features/btw/btw';
+export * from '#/features/btw/btwService';
+import '#/features/btw/btwFeature';
+import '#/features/plan/profile/plan';
+export * from '#/features/plan/tools/enter-plan-mode/enter-plan-mode';
+import '#/features/plan/tools/enter-plan-mode/enterPlanModeTool';
+export * from '#/features/plan/tools/exit-plan-mode/exit-plan-mode';
+import '#/features/plan/tools/exit-plan-mode/exitPlanModeTool';
+export * from '#/features/plan/configSection';
+export * from '#/features/plan/plan';
+export * from '#/features/plan/planOps';
+export * from '#/features/plan/planService';
+import '#/features/dateChange/dateChangeFeature';
+import '#/features/plan/planFeature';
+export * from '#/features/fileHistory/fileHistory';
+export * from '#/features/fileHistory/fileHistoryOps';
+export * from '#/features/fileHistory/fileHistoryService';
+import '#/features/fileHistory/fileHistoryFeature';
+export * from '#/features/externalHooks/configSection';
+export * from '#/features/externalHooks/app/externalHooksRunner';
+export * from '#/features/externalHooks/app/externalHooksRunnerService';
+export * from '#/features/externalHooks/session/sessionExternalHooks';
+export * from '#/features/externalHooks/session/sessionExternalHooksService';
+export * from '#/features/externalHooks/agent/agentExternalHooks';
+export * from '#/features/externalHooks/agent/agentExternalHooksService';
+import '#/features/externalHooks/externalHooksFeature';
+export * from '#/features/debugEvents/debugEvents';
+export * from '#/features/debugEvents/debugEventsService';
+import '#/features/debugEvents/debugEventsFeature';
+export * from '#/features/swarm/configSection';
+export * from '#/features/swarm/agent/swarm';
+export * from '#/features/swarm/agent/swarmService';
+export * from '#/features/swarm/session/sessionSwarm';
+export * from '#/features/swarm/session/sessionSwarmService';
+export * from '#/features/swarm/tools/agent-swarm/agent-swarm';
+import '#/features/swarm/tools/agent-swarm/agentSwarmTool';
+import '#/features/swarm/swarmFeature';
+export * from '#/features/goal/tools/create-goal/create-goal';
+import '#/features/goal/tools/create-goal/createGoalTool';
+export * from '#/features/goal/tools/get-goal/get-goal';
+import '#/features/goal/tools/get-goal/getGoalTool';
+export * from '#/features/goal/tools/set-goal-budget/set-goal-budget';
+import '#/features/goal/tools/set-goal-budget/setGoalBudgetTool';
+export * from '#/features/goal/tools/update-goal/update-goal';
+import '#/features/goal/tools/update-goal/updateGoalTool';
+export * from '#/features/goal/goalDeadlineScheduler';
+export * from '#/features/goal/goal';
+export * from '#/features/goal/goalService';
+export * from '#/features/goal/goalOps';
+export * from '#/features/goal/types';
+import '#/features/goal/goalFeature';
+export * from '#/features/tower/flag';
+export * from '#/features/tower/tower';
+export * from '#/features/tower/towerFeature';
+export * from '#/features/tower/towerService';
+export * from '#/features/tower/towerRateLimit';
+export * from '#/features/tower/towerRateLimitService';
+export * from '#/features/tower/tools/init/init';
+export * from '#/features/tower/tools/plan/plan';
+export * from '#/features/tower/tools/spawn/spawn';
+export * from '#/features/tower/tools/merge/merge';
+export * from '#/features/tower/tools/teardown/teardown';
+export * from '#/features/tower/tools/send/send';
+export * from '#/features/tower/tools/inbox/inbox';
+export * from '#/features/tower/tools/finding/finding';
+export * from '#/features/tower/tools/review/review';
+export * from '#/features/tower/tools/mission/mission';
+export * from '#/features/tower/tools/status/status';
+import '#/features/tower/flag';
+import '#/features/tower/towerFeature';
+export * from '#/agent/usage/usage';
+export * from '#/agent/usage/cacheProbe';
+export * from '#/agent/usage/cacheProbeService';
+export * from '#/session/usage/sessionUsage';
+export * from '#/session/usage/usageAgentModel';
+export * from '#/session/usage/sessionUsageService';
+import '#/features/usage/usageFeature';
+export * from '#/agent/toolDedupe/toolDedupe';
+export * from '#/agent/toolDedupe/toolDedupeService';
+export * from '#/agent/agentsMdReminder/agentsMdReminder';
+export * from '#/agent/agentsMdReminder/agentsMdReminderService';
+import '#/agent/toolSelect/flag';
+export * from '#/agent/tools/select-tools/select-tools';
+import '#/agent/tools/select-tools/selectToolsTool';
+export * from '#/agent/toolSelect/dynamicTools';
+export * from '#/agent/toolSelect/toolSelect';
+export * from '#/agent/toolSelect/toolSelectService';
+export * from '#/agent/toolSelect/toolSelectAnnouncements';
+export * from '#/agent/toolSelect/toolSelectAnnouncementsService';
+export * from '#/agent/toolSelect/toolSelectSchemas';
+export * from '#/agent/toolSelect/toolSelectSchemasService';
+import '#/agent/toolPolicy/configSection';
+export * from '#/agent/toolPolicy/configSection';
+export * from '#/agent/toolPolicy/evaluate';
+export * from '#/agent/toolPolicy/toolPolicy';
+export * from '#/agent/toolPolicy/toolPolicyService';
+
+import '#/agent/task/configSection';
+export {
+  resolveAgentTaskConfig,
+  resolvePrintBackgroundMode,
+  type AgentTaskConfig,
+  type PrintBackgroundMode,
+} from '#/agent/task/configSection';
+export * from '#/agent/task/printDefaults';
+export * from '#/agent/tools/task/task-list/task-list';
+import '#/agent/tools/task/task-list/taskListTool';
+export * from '#/agent/tools/task/task-output/task-output';
+import '#/agent/tools/task/task-output/taskOutputTool';
+export * from '#/agent/tools/task/task-stop/task-stop';
+import '#/agent/tools/task/task-stop/taskStopTool';
+export * from '#/agent/tools/task/task-wait/task-wait';
+import '#/agent/tools/task/task-wait/taskWaitTool';
+export * from '#/agent/task/task';
+export * from '#/agent/task/taskOps';
+export * from '#/agent/task/taskService';
+import '#/features/cron/configSection';
+export * from '#/features/cron/cronTask';
+export * from '#/features/cron/configSection';
+export * from '#/features/cron/cronService';
+export * from '#/features/cron/cronOps';
+export type { CronFiredEvent } from '#/features/cron/cronOps';
+import '#/features/cron/cronFeature';
+export * from '#/features/cron/tools/cron-create/cron-create';
+export * from '#/features/cron/tools/cron-list/cron-list';
+export * from '#/features/cron/tools/cron-delete/cron-delete';
+
+import '#/session/agentLifecycle/profile/profiles';
+export * from '#/session/agentLifecycle/agentLifecycle';
+export * from '#/session/agentLifecycle/agentLifecycleService';
+export * from '#/session/agentLifecycle/mainAgent';
+export * from '#/session/mcp/sessionMcpHandle';
+import '#/app/mcpConfig/configSection';
+export {
+  MCP_SECTION,
+  McpSectionSchema,
+  type McpSection,
+} from '#/app/mcpConfig/configSection';
+export * from '#/app/mcpConfig/oauthStore';
+export { IMcpConfigStore } from '#/app/mcpConfig/configStore';
+import '#/app/mcpConfig/configStore';
+export { IMcpOAuthService } from '#/app/mcpConfig/oauthService';
+import '#/app/mcpConfig/oauthService';
+export * from '#/app/mcpRegistry/mcpRegistry';
+import '#/app/mcpRegistry/mcpRegistryService';
+export * from '#/app/mcpManagement/mcpManagement';
+import '#/app/mcpManagement/mcpManagementService';
+export * from '#/workspace/workspaceMcpConfig/workspaceMcpConfig';
+export * from '#/workspace/workspaceMcpConfig/workspaceMcpConfigService';
+export * from '#/workspace/workspaceMcp/workspaceMcp';
+export * from '#/workspace/workspaceMcp/workspaceMcpService';
+export * from '#/session/subagent/subagent';
+export * from '#/session/subagent/subagentService';
+export * from '#/session/subagent/spawn';
+import '#/session/subagent/flag';
+export * from '#/session/subagent/subagentModelsValidation';
+import '#/session/subagent/subagentModelsValidationService';
+export * from '#/agent/tools/agent/subagent-task';
+export { AGENT_RUN_PROMPT_ORIGIN } from '#/session/subagent/runAgentTurn';
+export * from '#/session/subagent/mirrorAgentRun';
+export * from '#/session/subagent/subagentScopeCache';
+import '#/session/subagent/subagentScopeCacheService';
+import '#/session/subagent/configSection';
+export * from '#/agent/tools/agent/agent';
+import '#/agent/tools/agent/agentTool';
+export * from '#/app/sessionManager/sessionLookup';
+export * from '#/workspace/workspaceContext/workspaceContext';
+export * from '#/workspace/sessionLifecycle/sessionLifecycle';
+export * from '#/workspace/sessionLifecycle/sessionLifecycleEvents';
+export * from '#/workspace/sessionLifecycle/sessionLifecycleService';
+export * from '#/workspace/sessionLifecycle/coldSessionArchive';
+export * from '#/workspace/sessionLifecycle/internal/addressing';
+import '#/app/sessionExport/errors';
+export * from '#/app/sessionExport/sessionExport';
+export * from '#/app/sessionExport/sessionExportService';
+export * from '#/app/sessionExport/manifest';
+export * from '#/app/sessionExport/wire-scan';
+export * from '#/app/sessionExport/zip';
+export * from '#/app/sessionLegacy/sessionLegacy';
+export * from '#/app/sessionLegacy/sessionLegacyService';
+export * from '#/human/interaction/interaction';
+export * from '#/human/interaction/facade';
+export * from '#/agent/interaction/interactionOps';
+export * from '#/session/sessionContext/sessionContext';
+
+export * from '#/agent/interaction/question';
+export {
+  type ApprovalDecision,
+  type ApprovalRequest as SessionApprovalRequest,
+  type ApprovalResponse as SessionApprovalResponse,
+} from '#/agent/interaction/approval';
+export * from '#/agent/tools/ask-user-question/ask-user-question';
+import '#/agent/tools/ask-user-question/askUserQuestionTool';
+export * from '#/app/gateway/gateway';
+export * from '#/app/gateway/gatewayService';
+
+export * from '#/session/workspaceContext/workspaceContext';
+export * from '#/session/workspaceContext/workspaceContextService';
+export * from '#/app/projectLocalConfig/projectLocalConfig';
+export * from '#/app/workspace/workspace';
+export * from '#/app/workspace/workspaceService';
+export * from '#/app/workspace/workspaceAlias';
+export * from '#/app/workspace/workspaceEvents';
+export * from '#/app/workspace/workspacePersistence';
+export * from '#/app/workspace/fileWorkspacePersistence';
+export * from '#/app/workspaceAliases/workspaceAliases';
+import '#/app/workspaceAliases/workspaceAliasesService';
+export * from '#/app/workspaceSessions/workspaceSessions';
+import '#/app/workspaceSessions/workspaceSessionsService';
+import '#/app/git/gitService';
+export * from '#/app/bashParser/bashParser';
+import '#/app/bashParser/bashParserService';
+export * from '#/workspace/workspaceFs/internal/errors';
+export * from '#/workspace/workspaceFs/fs';
+export * from '#/workspace/workspaceFs/fsService';
+export * from '#/session/agentLifecycle/profile/gitContext';
+export * from '#/workspace/workspaceFs/internal/rgLocator';
+export * from '#/workspace/workspaceFs/internal/runRg';
+export * from '#/workspace/workspaceGit/workspaceGit';
+export * from '#/workspace/workspaceGit/workspaceGitService';
+export * from '#/session/sessionToolPolicyGate/sessionToolPolicyGate';
+export * from '#/session/sessionToolPolicyGate/sessionToolPolicyGateService';
+export * from '#/workspace/workspaceTrust/workspaceTrust';
+export * from '#/workspace/workspaceTrust/workspaceTrustService';
+export * from '#/app/hostFolderBrowser/hostFolderBrowser';
+export * from '#/app/hostFolderBrowser/hostFolderBrowserService';
+export * from '#/persistence/interface/storage';
+export * from '#/persistence/interface/appendLogStore';
+export * from '#/persistence/interface/atomicDocumentStore';
+export * from '#/persistence/interface/queryStore';
+export * from '#/persistence/interface/blobStore';
+export * from '#/persistence/backends/node-fs/fileStorageService';
+export * from '#/persistence/backends/node-fs/appendLogStore';
+export * from '#/persistence/backends/node-fs/atomicDocumentStore';
+export * from '#/persistence/backends/node-fs/blobStoreService';
+export * from '#/persistence/backends/node-fs/projectLocalConfigService';
+export * from '#/persistence/configSection';
+import '#/persistence/configSection';
+export * from '#/persistence/backends/minidb/miniDbQueryStore';
+export * from '#/persistence/backends/memory/inMemoryStorageService';
+export * from '#/agent/tools/web-search/web-search';
+import '#/agent/tools/web-search/webSearchTool';
+export * from '#/app/auth/auth';
+export * from '#/app/auth/authService';
+export * from '#/app/auth/configSection';
+export * from '#/app/auth/webSearch/webSearch';
+export * from '#/app/auth/webSearch/webSearchService';
+export * from '#/app/auth/webSearch/providers/moonshot-web-search';
+export * from '#/app/authLegacy/authLegacy';
+export * from '#/app/authLegacy/authLegacyService';
+export * from '#/app/file/fileService';
+export * from '#/app/file/fileServiceImpl';
+export {
+  buildImageCompressionCaption,
+  compressBase64ForModel,
+  compressImageForModel,
+  gateImageFormatParts,
+  IMAGE_BYTE_BUDGET,
+  MAX_IMAGE_DECODE_BYTES,
+  MAX_IMAGE_EDGE_PX,
+  READ_IMAGE_BYTE_BUDGET,
+  resolveMaxImageEdgePx,
+  resolveReadImageByteBudget,
+} from '#/agent/media/image-compress';
+export { providerImagePolicy, type ProviderImagePolicy } from '#human/llm/media/image-formats';
+export {
+  buildImageConversionGuidance,
+  buildUnsupportedImageNotice,
+  decodeBase64Prefix,
+  isModelAcceptedImageMime,
+  normalizeImageMime,
+  parseImageDataUrl,
+  resolveEffectiveImageMime,
+  unsupportedImageMimeFromUrl,
+} from '#/agent/media/image-format-policy';
+export {
+  persistOriginalImage,
+  sessionMediaOriginalsDir,
+} from '#/agent/media/image-originals';
+export * from '#/app/edit/fileEdit';
+export * from '#/app/edit/fileEditService';
+export * from '#/app/edit/editService';
+export * from '#/app/edit/textModel';
+export * from '#/agent/tools/edit/edit';
+import '#/agent/tools/edit/editTool';
+export * from '#/agent/tools/fetch-url/fetch-url';
+import '#/agent/tools/fetch-url/fetchUrlTool';
+export * from '#/app/web/web';
+export * from '#/app/web/webService';
+export * from '#/app/web/providers/local-fetch-url';
+export * from '#/app/web/providers/moonshot-fetch-url';
+
+export * from '#/agent/blob/agentBlobService';
+export * from '#/agent/blob/agentBlobServiceImpl';
+export * from '#/agent/contextMemory/contextMemory';
+export * from '#/agent/contextMemory/contextMemoryService';
+export * from '#/agent/contextMemory/contextOps';
+export * from '#/agent/contextMemory/compactionHandoff';
+export * from '#/agent/contextMemory/conversationUndoParticipants';
+export * from '#/agent/contextMemory/conversationTime';
+export * from '#/agent/contextMemory/loopEventFold';
+export * from '#/agent/contextMemory/messageId';
+export * from '#/agent/contextMemory/contextTranscript';
+export * from '#/agent/contextMemory/types';
+export * from '#/features/reminder/reminderService';
+export * from '#/features/reminder/systemReminder';
+export * from '#/features/reminder/types';
+import '#/features/reminder/reminderFeature';
+export * from '#/features/dateChange/dateChange';
+export * from '#/features/dateChange/dateChangeService';
+export * from '#/agent/contextProjector/contextProjector';
+export * from '#/agent/contextProjector/contextProjectorService';
+export * from '#/agent/contextProjector/mediaProjection';
+export * from '#/agent/tokenCounting/tokenCounting';
+export * from '#/agent/tokenCounting/tokenCountingOps';
+export * from '#/session/tokenCounting/sessionTokenCounting';
+export * from '#/session/tokenCounting/tokenCountingAgentModel';
+export * from '#/session/tokenCounting/sessionTokenCountingService';
+import '#/features/tokenCounting/tokenCountingFeature';
+export * from '#/agent/plugin/agentPlugin';
+export * from '#/agent/plugin/agentPluginOps';
+export * from '#/agent/plugin/agentPluginService';
+export * from '#/agent/fullCompaction/strategy';
+export * from '#/agent/fullCompaction/fullCompaction';
+export * from '#/agent/fullCompaction/fullCompactionService';
+export * from '#/agent/fullCompaction/compactionOps';
+export * from '#/agent/fullCompaction/types';
+export * from '#/agent/fullCompaction/contextRecovery';
+export * from '#/agent/fullCompaction/compactionInstruction';
+export * from '#/agent/llmRequester/llmRequester';
+export * from '#/agent/llmRequester/llmRequesterService';
+export * from '#/agent/llmRequester/llmRequestOps';
+export * from '#/_base/utils/promise';
+export * from '#/_base/utils/retry';
+export * from '#/_base/utils/timer';
+import '#/agent/loop/configSection';
+export * from '#/agent/loop/loop';
+export * from '#/agent/loop/loopService';
+export * from '#/agent/loop/promptChannel';
+export * from '#/agent/interruptionReminder/interruptionReminder';
+export * from '#/agent/interruptionReminder/interruptionReminderService';
+export * from '#/agent/interruptionReminder/interruptionReminderOps';
+export * from '#/agent/mcp/mcp';
+export * from '#/agent/mcp/mcpService';
+export * from '#/agent/mcp/mcpDiscoveryOps';
+export * from '#/mcpCore/config-schema';
+export * from '#/agent/media/mediaTools';
+export * from '#/agent/media/mediaToolsRegistrar';
+export * from '#/agent/media/registerMediaTools';
+export {
+  buildDaemonFileUrl,
+  buildMediaPathTag,
+  daemonFileRefFromPart,
+  mediaExtensionForMime,
+  matchSingleMediaPathTag,
+  parseDaemonFileUrl,
+} from '#/agent/media/mediaRef';
+export type { DaemonFileRef, MediaKind } from '#/agent/media/mediaRef';
+export * from '#/agent/media/sessionMediaStore';
+import '#/agent/media/sessionMediaStoreService';
+export * from '#/agent/media/kimiFileUrl';
+export * from '#/agent/media/videoUpload';
+export * from '#/agent/media/mediaResolver';
+export * from '#/agent/media/mediaResolverService';
+import '#/agent/media/configSection';
+export * from '#/agent/media/imageConfigBridge';
+import '#/agent/permissionMode/configSection';
+export * from '#/agent/permissionMode/permissionMode';
+export * from '#/agent/permissionMode/permissionModeService';
+export * from '#/agent/permissionPolicy/permissionPolicy';
+export * from '#/agent/permissionPolicy/permissionPolicyService';
+export * from '#/agent/permissionPolicy/types';
+import '#/agent/permissionRules/configSection';
+export * from '#/agent/permissionRules/permissionRules';
+export * from '#/agent/permissionRules/matchesRule';
+export * from '#/agent/permissionRules/permissionRulesService';
+export * from '#/agent/pluginCommand/pluginCommand';
+export * from '#/agent/pluginCommand/pluginCommandService';
+export * from '#/agent/profile/profile';
+export * from '#/agent/profile/profileService';
+export * from '#/agent/profile/context';
+export * from '#/agent/prompt/promptEvents';
+export * from '#/agent/prompt/promptMetadataText';
+export * from '#/agent/replayBuilder/types';
+export * from '#/agent/replayBuilder/fold';
+export { type SessionSummary } from '#/app/sessionIndex/sessionIndex';
+export * from '#/agent/undo/undo';
+export * from '#/agent/undo/undoService';
+export * from '#/agent/shellCommand/shellCommand';
+export * from '#/agent/shellCommand/shellCommandService';
+export * from '#/agent/agentContext/agentContext';
+export * from '#/agent/agentContext/agentSpace';
+export * from '#/agent/scopeContext/scopeContext';
+export * from '#/features/sessionInit/sessionInit';
+export * from '#/features/sessionInit/sessionInitService';
+export * from '#/features/sessionInit/profile/init';
+import '#/features/sessionInit/sessionInitFeature';
+export * from '#/features/todo/todoItem';
+export * from '#/features/todo/todoListReminder';
+export * from '#/features/todo/todoService';
+export * from '#/features/todo/tools/todo-list/todo-list';
+import '#/features/todo/todoFeature';
+export * from '#/features/notify/flag';
+export * from '#/features/notify/notifyUserAvailability';
+export * from '#/features/notify/tools/notify-user/notify-user';
+import '#/features/notify/notifyFeature';
+export * from '#/tool/toolContract';
+export * from '#/agent/toolExecutor/toolHooks';
+export * from '#/agent/toolExecutor/toolExecutor';
+export * from '#/agent/toolExecutor/toolExecutorService';
+export * from '#/agent/toolResultTruncation/toolResultTruncation';
+import '#/agent/toolResultTruncation/toolResultTruncationService';
+import '#/agent/toolActivation/toolActivationService';
+import '#/agent/toolRegistry/toolContribution';
+import '#/agent/toolRegistry/toolRegistry';
+import '#/agent/toolRegistry/toolRegistryService';
+export { IAgentToolActivationService } from '#/agent/toolActivation/toolActivation';
+export { IAgentToolRegistryService } from '#/agent/toolRegistry/toolRegistry';
+export { registerAgentToolService, AgentToolContribution } from '#/agent/toolRegistry/toolContribution';
+export type { AgentToolContributionOptions } from '#/agent/toolRegistry/toolContribution';
+export * from '#/agent/userTool/userTool';
+export * from '#/agent/userTool/userToolOps';
+export * from '#/agent/userTool/userToolService';

packages/agent-core-v2/src/llm-adapter/record-diff.ts

@@ -0,0 +1,49 @@
+export interface RecordDiff {
+  readonly added: readonly string[];
+  readonly removed: readonly string[];
+  readonly changed: readonly string[];
+}
+
+export function isEmptyDiff(diff: RecordDiff): boolean {
+  return diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0;
+}
+
+export function diffRecords<T>(
+  previous: Readonly<Record<string, T>> | undefined,
+  current: Readonly<Record<string, T>> | undefined,
+): RecordDiff {
+  const prev = previous ?? {};
+  const curr = current ?? {};
+  const added: string[] = [];
+  const removed: string[] = [];
+  const changed: string[] = [];
+  for (const key of Object.keys(curr)) {
+    if (!(key in prev)) {
+      added.push(key);
+    } else if (!deepEqual(prev[key], curr[key])) {
+      changed.push(key);
+    }
+  }
+  for (const key of Object.keys(prev)) {
+    if (!(key in curr)) {
+      removed.push(key);
+    }
+  }
+  return { added, removed, changed };
+}
+
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+    if (!deepEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])) {
+      return false;
+    }
+  }
+  return true;
+}

packages/agent-core-v2/src/mcpCore/client-http.ts

@@ -0,0 +1,169 @@
+import { ErrorCodes, Error2 } from '#/errors';
+import type { McpServerHttpConfig } from './config-schema';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+import {
+  buildRequestOptions,
+  KIMI_MCP_CLIENT_NAME,
+  KIMI_MCP_CLIENT_VERSION,
+  MCP_LIVENESS_PROBE_TIMEOUT_MS,
+  toMcpToolDefinition,
+  toMcpToolResult,
+  type UnexpectedCloseListener,
+  type UnexpectedCloseReason,
+} from './client-shared';
+import { buildMcpRemoteHeaders } from './client-remote';
+import { createMcpOAuthFetch } from './oauth/provider';
+import type { MCPClient, MCPToolDefinition, MCPToolResult } from './types';
+
+export interface HttpMcpClientOptions {
+  readonly clientName?: string;
+  readonly clientVersion?: string;
+  readonly startupTimeoutMs?: number;
+  readonly toolCallTimeoutMs?: number;
+  readonly envLookup?: (name: string) => string | undefined;
+  readonly fetch?: typeof fetch;
+  readonly oauthProvider?: OAuthClientProvider;
+}
+
+export class HttpMcpClient implements MCPClient {
+  private readonly client: Client;
+  private readonly transport: StreamableHTTPClientTransport;
+  private readonly startupTimeoutMs?: number;
+  private readonly toolCallTimeoutMs?: number;
+  private started = false;
+  private closed = false;
+  private ready = false;
+  private hooksInstalled = false;
+  private unexpectedCloseListener: UnexpectedCloseListener | undefined;
+  private lastTransportError: Error | undefined;
+  private pendingUnexpectedClose: UnexpectedCloseReason | undefined;
+  private unexpectedCloseFired = false;
+
+  constructor(config: McpServerHttpConfig, options: HttpMcpClientOptions = {}) {
+    const envLookup = options.envLookup ?? ((name) => process.env[name]);
+    const headers = buildMcpHttpHeaders(config, envLookup);
+
+    this.transport = new StreamableHTTPClientTransport(new URL(config.url), {
+      requestInit: headers !== undefined ? { headers } : undefined,
+      fetch: createMcpOAuthFetch(options.oauthProvider, options.fetch),
+      authProvider: options.oauthProvider,
+    });
+    this.client = new Client({
+      name: options.clientName ?? KIMI_MCP_CLIENT_NAME,
+      version: options.clientVersion ?? KIMI_MCP_CLIENT_VERSION,
+    });
+    this.startupTimeoutMs = options.startupTimeoutMs;
+    this.toolCallTimeoutMs = options.toolCallTimeoutMs;
+  }
+
+  async connect(): Promise<void> {
+    if (this.closed) {
+      throw new Error2(ErrorCodes.MCP_STARTUP_FAILED, 'MCP HTTP client is closed');
+    }
+    if (this.started) return;
+    this.started = true;
+    this.installTransportHooks();
+    try {
+      await this.client.connect(
+        this.transport,
+        buildRequestOptions(this.startupTimeoutMs, undefined),
+      );
+    } catch (error) {
+      await this.closeStartedClient();
+      throw error;
+    }
+    if (this.closed) {
+      await this.closeStartedClient();
+      throw new Error2(ErrorCodes.MCP_STARTUP_FAILED, 'MCP HTTP client was closed during startup');
+    }
+    this.ready = true;
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    await this.closeStartedClient();
+  }
+
+  onUnexpectedClose(listener: UnexpectedCloseListener): void {
+    this.unexpectedCloseListener = listener;
+    const pending = this.pendingUnexpectedClose;
+    if (pending !== undefined) {
+      this.pendingUnexpectedClose = undefined;
+      listener(pending);
+    }
+  }
+
+  async listTools(): Promise<MCPToolDefinition[]> {
+    const result = await this.client.listTools(
+      undefined,
+      buildRequestOptions(this.startupTimeoutMs, undefined),
+    );
+    return result.tools.map(toMcpToolDefinition);
+  }
+
+  async callTool(
+    name: string,
+    args: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<MCPToolResult> {
+    const requestOptions = buildRequestOptions(this.toolCallTimeoutMs, signal);
+    const result = await this.client.callTool({ name, arguments: args }, undefined, requestOptions);
+    return toMcpToolResult(result);
+  }
+
+  async ping(signal?: AbortSignal): Promise<void> {
+    await this.client.ping(buildRequestOptions(MCP_LIVENESS_PROBE_TIMEOUT_MS, signal));
+  }
+
+  private async closeStartedClient(): Promise<void> {
+    if (!this.started) return;
+    this.started = false;
+    await this.client.close();
+  }
+
+  private installTransportHooks(): void {
+    if (this.hooksInstalled) return;
+    this.hooksInstalled = true;
+    this.client.onclose = () => {
+      if (this.closed) return;
+      if (!this.ready) return;
+      this.fireUnexpectedClose({ error: this.lastTransportError });
+    };
+    this.client.onerror = (error) => {
+      this.lastTransportError = error;
+      if (this.closed) return;
+      if (!this.ready) return;
+      if (isTerminalTransportError(error)) {
+        this.fireUnexpectedClose({ error });
+      }
+    };
+  }
+
+  private fireUnexpectedClose(reason: UnexpectedCloseReason): void {
+    if (this.unexpectedCloseFired) return;
+    this.unexpectedCloseFired = true;
+    const listener = this.unexpectedCloseListener;
+    if (listener !== undefined) {
+      listener(reason);
+    } else {
+      this.pendingUnexpectedClose = reason;
+    }
+  }
+}
+
+export function isTerminalTransportError(error: Error): boolean {
+  if (error.name === 'UnauthorizedError') return true;
+  if (/Maximum reconnection attempts/i.test(error.message)) return true;
+  return false;
+}
+
+export function buildMcpHttpHeaders(
+  config: McpServerHttpConfig,
+  envLookup: (name: string) => string | undefined,
+): Record<string, string> | undefined {
+  return buildMcpRemoteHeaders(config, envLookup);
+}

packages/agent-core-v2/src/mcpCore/client-remote.ts

@@ -0,0 +1,29 @@
+import type { McpRemoteServerConfig, McpServerConfig } from './config-schema';
+import { ErrorCodes, Error2 } from '#/errors';
+
+export function buildMcpRemoteHeaders(
+  config: McpRemoteServerConfig,
+  envLookup: (name: string) => string | undefined,
+): Record<string, string> | undefined {
+  const headers: Record<string, string> = { ...config.headers };
+  if (config.bearerTokenEnvVar !== undefined) {
+    const token = envLookup(config.bearerTokenEnvVar);
+    if (token === undefined || token.length === 0) {
+      throw new Error2(
+        ErrorCodes.CONFIG_INVALID,
+        `MCP ${config.transport.toUpperCase()} bearer token env var "${config.bearerTokenEnvVar}" is not set or is empty`,
+      );
+    }
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === 'authorization') {
+        delete headers[key];
+      }
+    }
+    headers['Authorization'] = `Bearer ${token}`;
+  }
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
+
+export function isRemoteMcpConfig(config: McpServerConfig): config is McpRemoteServerConfig {
+  return config.transport === 'http' || config.transport === 'sse';
+}

packages/agent-core-v2/src/mcpCore/client-shared.ts

@@ -0,0 +1,109 @@
+import { getCoreVersion } from '#/_base/version';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+
+import type { MCPClient, MCPToolDefinition, MCPToolResult } from './types';
+
+export const KIMI_MCP_CLIENT_NAME = 'kimi-code';
+export const KIMI_MCP_CLIENT_VERSION = getCoreVersion();
+
+export interface UnexpectedCloseReason {
+  readonly error?: Error;
+  readonly stderr?: string;
+}
+
+export type UnexpectedCloseListener = (reason: UnexpectedCloseReason) => void;
+
+export function isMcpConnectionClosedError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    (error as Error & { readonly code?: unknown }).code === ErrorCode.ConnectionClosed
+  );
+}
+
+export function isMcpTransportFailure(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  if (isMcpConnectionClosedError(error)) return true;
+  return !(error instanceof McpError);
+}
+
+export const MCP_LIVENESS_PROBE_TIMEOUT_MS = 5_000;
+
+export function isMcpMalformedResultError(error: unknown): boolean {
+  return error instanceof Error && error.name === 'ZodError';
+}
+
+export async function probeMcpLiveness(client: MCPClient, signal: AbortSignal): Promise<boolean> {
+  try {
+    await client.ping(signal);
+    return true;
+  } catch (error) {
+    if (isMcpConnectionClosedError(error)) return false;
+    if (isMcpMalformedResultError(error)) return true;
+    if (error instanceof McpError) {
+      return (error as Error & { readonly code?: unknown }).code !== ErrorCode.RequestTimeout;
+    }
+    return false;
+  }
+}
+
+export interface McpRequestOptions {
+  readonly timeout?: number;
+  readonly signal?: AbortSignal;
+}
+
+export function buildRequestOptions(
+  timeoutMs: number | undefined,
+  signal: AbortSignal | undefined,
+): McpRequestOptions | undefined {
+  if (timeoutMs === undefined && signal === undefined) return undefined;
+  return { timeout: timeoutMs, signal };
+}
+
+interface SdkListedTool {
+  readonly name: string;
+  readonly description?: string;
+  readonly inputSchema: Record<string, unknown>;
+}
+
+export function toMcpToolDefinition(tool: SdkListedTool): MCPToolDefinition {
+  return {
+    name: tool.name,
+    description: tool.description ?? '',
+    inputSchema: tool.inputSchema,
+  };
+}
+
+export function toMcpToolResult(result: unknown): MCPToolResult {
+  if (typeof result === 'object' && result !== null && 'content' in result) {
+    const typed = result as {
+      content: unknown;
+      isError?: unknown;
+      structuredContent?: unknown;
+      _meta?: unknown;
+    };
+    if (Array.isArray(typed.content)) {
+      return {
+        content: typed.content as MCPToolResult['content'],
+        isError: typed.isError === true,
+        structuredContent: typed.structuredContent,
+        _meta:
+          typeof typed._meta === 'object' && typed._meta !== null
+            ? (typed._meta as Record<string, unknown>)
+            : undefined,
+      };
+    }
+  }
+  if (typeof result === 'object' && result !== null && 'toolResult' in result) {
+    const legacy = (result as { toolResult: unknown }).toolResult;
+    return {
+      content: [
+        {
+          type: 'text',
+          text: typeof legacy === 'string' ? legacy : JSON.stringify(legacy),
+        },
+      ],
+      isError: false,
+    };
+  }
+  return { content: [], isError: false };
+}

packages/agent-core-v2/src/mcpCore/client-sse.ts

@@ -0,0 +1,161 @@
+import { ErrorCodes, Error2 } from '#/errors';
+import type { McpServerSseConfig } from './config-schema';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import { SSEClientTransport, SseError } from '@modelcontextprotocol/sdk/client/sse.js';
+
+import {
+  buildRequestOptions,
+  KIMI_MCP_CLIENT_NAME,
+  KIMI_MCP_CLIENT_VERSION,
+  MCP_LIVENESS_PROBE_TIMEOUT_MS,
+  toMcpToolDefinition,
+  toMcpToolResult,
+  type UnexpectedCloseListener,
+  type UnexpectedCloseReason,
+} from './client-shared';
+import { buildMcpRemoteHeaders } from './client-remote';
+import { createMcpOAuthFetch } from './oauth/provider';
+import type { MCPClient, MCPToolDefinition, MCPToolResult } from './types';
+
+export interface SseMcpClientOptions {
+  readonly clientName?: string;
+  readonly clientVersion?: string;
+  readonly startupTimeoutMs?: number;
+  readonly toolCallTimeoutMs?: number;
+  readonly envLookup?: (name: string) => string | undefined;
+  readonly fetch?: typeof fetch;
+  readonly oauthProvider?: OAuthClientProvider;
+}
+
+export class SseMcpClient implements MCPClient {
+  private readonly client: Client;
+  private readonly transport: SSEClientTransport;
+  private readonly startupTimeoutMs?: number;
+  private readonly toolCallTimeoutMs?: number;
+  private started = false;
+  private closed = false;
+  private ready = false;
+  private hooksInstalled = false;
+  private unexpectedCloseListener: UnexpectedCloseListener | undefined;
+  private lastTransportError: Error | undefined;
+  private pendingUnexpectedClose: UnexpectedCloseReason | undefined;
+  private unexpectedCloseFired = false;
+
+  constructor(config: McpServerSseConfig, options: SseMcpClientOptions = {}) {
+    const envLookup = options.envLookup ?? ((name) => process.env[name]);
+    const headers = buildMcpRemoteHeaders(config, envLookup);
+
+    this.transport = new SSEClientTransport(new URL(config.url), {
+      requestInit: headers !== undefined ? { headers } : undefined,
+      fetch: createMcpOAuthFetch(options.oauthProvider, options.fetch),
+      authProvider: options.oauthProvider,
+    });
+    this.client = new Client({
+      name: options.clientName ?? KIMI_MCP_CLIENT_NAME,
+      version: options.clientVersion ?? KIMI_MCP_CLIENT_VERSION,
+    });
+    this.startupTimeoutMs = options.startupTimeoutMs;
+    this.toolCallTimeoutMs = options.toolCallTimeoutMs;
+  }
+
+  async connect(): Promise<void> {
+    if (this.closed) {
+      throw new Error2(ErrorCodes.MCP_STARTUP_FAILED, 'MCP SSE client is closed');
+    }
+    if (this.started) return;
+    this.started = true;
+    this.installTransportHooks();
+    try {
+      await this.client.connect(
+        this.transport,
+        buildRequestOptions(this.startupTimeoutMs, undefined),
+      );
+    } catch (error) {
+      await this.closeStartedClient();
+      throw error;
+    }
+    if (this.closed) {
+      await this.closeStartedClient();
+      throw new Error2(ErrorCodes.MCP_STARTUP_FAILED, 'MCP SSE client was closed during startup');
+    }
+    this.ready = true;
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    await this.closeStartedClient();
+  }
+
+  onUnexpectedClose(listener: UnexpectedCloseListener): void {
+    this.unexpectedCloseListener = listener;
+    const pending = this.pendingUnexpectedClose;
+    if (pending !== undefined) {
+      this.pendingUnexpectedClose = undefined;
+      listener(pending);
+    }
+  }
+
+  async listTools(): Promise<MCPToolDefinition[]> {
+    const result = await this.client.listTools(
+      undefined,
+      buildRequestOptions(this.startupTimeoutMs, undefined),
+    );
+    return result.tools.map(toMcpToolDefinition);
+  }
+
+  async callTool(
+    name: string,
+    args: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<MCPToolResult> {
+    const requestOptions = buildRequestOptions(this.toolCallTimeoutMs, signal);
+    const result = await this.client.callTool({ name, arguments: args }, undefined, requestOptions);
+    return toMcpToolResult(result);
+  }
+
+  async ping(signal?: AbortSignal): Promise<void> {
+    await this.client.ping(buildRequestOptions(MCP_LIVENESS_PROBE_TIMEOUT_MS, signal));
+  }
+
+  private async closeStartedClient(): Promise<void> {
+    if (!this.started) return;
+    this.started = false;
+    await this.client.close();
+  }
+
+  private installTransportHooks(): void {
+    if (this.hooksInstalled) return;
+    this.hooksInstalled = true;
+    this.client.onclose = () => {
+      if (this.closed) return;
+      if (!this.ready) return;
+      this.fireUnexpectedClose({ error: this.lastTransportError });
+    };
+    this.client.onerror = (error) => {
+      this.lastTransportError = error;
+      if (this.closed) return;
+      if (!this.ready) return;
+      if (isTerminalSseTransportError(error)) {
+        this.fireUnexpectedClose({ error });
+      }
+    };
+  }
+
+  private fireUnexpectedClose(reason: UnexpectedCloseReason): void {
+    if (this.unexpectedCloseFired) return;
+    this.unexpectedCloseFired = true;
+    const listener = this.unexpectedCloseListener;
+    if (listener !== undefined) {
+      listener(reason);
+    } else {
+      this.pendingUnexpectedClose = reason;
+    }
+  }
+}
+
+export function isTerminalSseTransportError(error: Error): boolean {
+  if (error.name === 'UnauthorizedError') return true;
+  return error instanceof SseError && error.code !== undefined;
+}

packages/agent-core-v2/src/mcpCore/client-stdio.ts

@@ -0,0 +1,304 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { ReadBuffer, serializeMessage } from '@modelcontextprotocol/sdk/shared/stdio.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+
+import { ErrorCodes, Error2 } from '#/errors';
+import type { IHostProcess } from '#/os/interface/hostProcess';
+import type { IRuntimeResolver } from '#/workspace/workspaceInstance/workspaceInstanceManager';
+import { proxyEnvForChild, reconcileChildNoProxy } from '#/_base/utils/proxy';
+
+import {
+  buildRequestOptions,
+  KIMI_MCP_CLIENT_NAME,
+  KIMI_MCP_CLIENT_VERSION,
+  MCP_LIVENESS_PROBE_TIMEOUT_MS,
+  toMcpToolDefinition,
+  toMcpToolResult,
+  type UnexpectedCloseListener,
+  type UnexpectedCloseReason,
+} from './client-shared';
+import type { McpServerStdioConfig } from './config-schema';
+import type { MCPClient, MCPToolDefinition, MCPToolResult } from './types';
+
+export interface StdioMcpClientOptions {
+  readonly clientName?: string;
+  readonly clientVersion?: string;
+  readonly startupTimeoutMs?: number;
+  readonly toolCallTimeoutMs?: number;
+  readonly defaultCwd?: string;
+  readonly runtimeResolver: IRuntimeResolver;
+  readonly workspaceId: string;
+  readonly runtimeId: string;
+}
+
+const STDERR_BUFFER_CAPACITY = 4 * 1024;
+
+export class StdioMcpClient implements MCPClient {
+  private readonly client: Client;
+  private readonly transport: RuntimeStdioTransport;
+  private readonly startupTimeoutMs?: number;
+  private readonly toolCallTimeoutMs?: number;
+  private readonly stderrBuffer = new BoundedTail(STDERR_BUFFER_CAPACITY);
+  private started = false;
+  private closed = false;
+  private ready = false;
+  private hooksInstalled = false;
+  private unexpectedCloseListener: UnexpectedCloseListener | undefined;
+  private lastTransportError: Error | undefined;
+  private pendingUnexpectedClose: UnexpectedCloseReason | undefined;
+
+  static readonly stderrBufferCapacity = STDERR_BUFFER_CAPACITY;
+
+  constructor(config: McpServerStdioConfig, options: StdioMcpClientOptions) {
+    if (config.executor !== undefined && config.executor !== 'local') {
+      throw new Error2(ErrorCodes.NOT_IMPLEMENTED, `MCP stdio executor '${config.executor}' is not yet implemented`);
+    }
+    this.transport = new RuntimeStdioTransport(config, options, this.stderrBuffer);
+    this.client = new Client({
+      name: options.clientName ?? KIMI_MCP_CLIENT_NAME,
+      version: options.clientVersion ?? KIMI_MCP_CLIENT_VERSION,
+    });
+    this.startupTimeoutMs = options.startupTimeoutMs;
+    this.toolCallTimeoutMs = options.toolCallTimeoutMs;
+  }
+
+  async connect(): Promise<void> {
+    if (this.closed) {
+      throw new Error2(ErrorCodes.MCP_STARTUP_FAILED, 'MCP stdio client is closed');
+    }
+    if (this.started) return;
+    this.started = true;
+    this.installTransportHooks();
+    try {
+      await this.client.connect(
+        this.transport,
+        buildRequestOptions(this.startupTimeoutMs, undefined),
+      );
+    } catch (error) {
+      await this.closeStartedClient();
+      throw error;
+    }
+    if (this.closed) {
+      await this.closeStartedClient();
+      throw new Error2(ErrorCodes.MCP_STARTUP_FAILED, 'MCP stdio client was closed during startup');
+    }
+    this.ready = true;
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    await this.closeStartedClient();
+  }
+
+  onUnexpectedClose(listener: UnexpectedCloseListener): void {
+    this.unexpectedCloseListener = listener;
+    const pending = this.pendingUnexpectedClose;
+    if (pending !== undefined) {
+      this.pendingUnexpectedClose = undefined;
+      listener(pending);
+    }
+  }
+
+  stderrSnapshot(): string {
+    return this.stderrBuffer.snapshot();
+  }
+
+  async listTools(): Promise<MCPToolDefinition[]> {
+    const result = await this.client.listTools(
+      undefined,
+      buildRequestOptions(this.startupTimeoutMs, undefined),
+    );
+    return result.tools.map(toMcpToolDefinition);
+  }
+
+  async callTool(
+    name: string,
+    args: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<MCPToolResult> {
+    const requestOptions = buildRequestOptions(this.toolCallTimeoutMs, signal);
+    const result = await this.client.callTool({ name, arguments: args }, undefined, requestOptions);
+    return toMcpToolResult(result);
+  }
+
+  async ping(signal?: AbortSignal): Promise<void> {
+    await this.client.ping(buildRequestOptions(MCP_LIVENESS_PROBE_TIMEOUT_MS, signal));
+  }
+
+  private async closeStartedClient(): Promise<void> {
+    if (!this.started) return;
+    this.started = false;
+    await this.client.close();
+  }
+
+  private installTransportHooks(): void {
+    if (this.hooksInstalled) return;
+    this.hooksInstalled = true;
+    this.client.onclose = () => {
+      if (this.closed) return;
+      if (!this.ready) return;
+      const stderr = this.stderrBuffer.snapshot();
+      const reason: UnexpectedCloseReason = {
+        error: this.lastTransportError,
+        stderr: stderr.length > 0 ? stderr : undefined,
+      };
+      const listener = this.unexpectedCloseListener;
+      if (listener !== undefined) {
+        listener(reason);
+      } else {
+        this.pendingUnexpectedClose = reason;
+      }
+    };
+    this.client.onerror = (error) => {
+      this.lastTransportError = error;
+    };
+  }
+}
+
+class RuntimeStdioTransport implements Transport {
+  onclose?: () => void;
+  onerror?: (error: Error) => void;
+  onmessage?: <T extends JSONRPCMessage>(message: T) => void;
+  private readonly readBuffer = new ReadBuffer();
+  private process: IHostProcess | undefined;
+  private lease: ReturnType<IRuntimeResolver['acquire']> | undefined;
+  private started = false;
+  private closed = false;
+
+  constructor(
+    private readonly config: McpServerStdioConfig,
+    private readonly options: StdioMcpClientOptions,
+    private readonly stderr: BoundedTail,
+  ) {}
+
+  async start(): Promise<void> {
+    if (this.started) throw new Error('Runtime stdio transport is already started');
+    if (this.closed) throw new Error('Runtime stdio transport is closed');
+    this.started = true;
+    const lease = this.options.runtimeResolver.acquire(
+      { workspaceId: this.options.workspaceId, runtimeId: this.options.runtimeId },
+      ['process'],
+    );
+    this.lease = lease;
+    try {
+      const base = lease.runtime.path.resolve(this.options.defaultCwd ?? lease.runtime.environment.homeDir);
+      const cwd = this.config.cwd === undefined ? base : lease.runtime.path.resolve(base, this.config.cwd);
+      const process = lease.track(await lease.runtime.process!.spawn(
+        this.config.command,
+        this.config.args,
+        { cwd, env: mergeStdioEnv(this.config.env) },
+      ));
+      this.process = process;
+      lease.track(this);
+      process.stdin.on('error', (error: Error) => this.onerror?.(error));
+      process.stdout.on('data', (chunk: Buffer | string) => this.onData(chunk));
+      process.stdout.on('end', () => this.finish());
+      process.stdout.on('error', (error: Error) => this.onerror?.(error));
+      process.stderr.on('data', (chunk: Buffer | string) => {
+        this.stderr.push(typeof chunk === 'string' ? chunk : chunk.toString('utf8'));
+      });
+      process.stderr.on('error', (error: Error) => this.onerror?.(error));
+      void process.wait().then(
+        () => this.finish(),
+        (error: unknown) => {
+          this.onerror?.(error instanceof Error ? error : new Error(String(error)));
+          this.finish();
+        },
+      );
+    } catch (error) {
+      this.lease = undefined;
+      lease.dispose();
+      throw error;
+    }
+  }
+
+  async send(message: JSONRPCMessage): Promise<void> {
+    const process = this.process;
+    if (process === undefined || this.closed) throw new Error('Runtime stdio transport is not running');
+    const data = serializeMessage(message);
+    await new Promise<void>((resolve, reject) => {
+      process.stdin.write(data, (error) => {
+        if (error !== null && error !== undefined) reject(error);
+        else resolve();
+      });
+    });
+  }
+
+  dispose(): Promise<void> {
+    return this.close();
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    const process = this.process;
+    this.process = undefined;
+    if (process !== undefined) {
+      try {
+        await process.kill();
+      } catch {}
+      void process.dispose();
+    }
+    this.readBuffer.clear();
+    const lease = this.lease;
+    this.lease = undefined;
+    lease?.dispose();
+    this.onclose?.();
+  }
+
+  private onData(chunk: Buffer | string): void {
+    this.readBuffer.append(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    while (true) {
+      try {
+        const message = this.readBuffer.readMessage();
+        if (message === null) return;
+        this.onmessage?.(message);
+      } catch (error) {
+        this.onerror?.(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+  }
+
+  private finish(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.process = undefined;
+    this.readBuffer.clear();
+    const lease = this.lease;
+    this.lease = undefined;
+    lease?.dispose();
+    this.onclose?.();
+  }
+}
+
+class BoundedTail {
+  private buffer = '';
+  constructor(private readonly capacity: number) {}
+
+  push(chunk: string): void {
+    this.buffer += chunk;
+    if (this.buffer.length > this.capacity) {
+      this.buffer = this.buffer.slice(this.buffer.length - this.capacity);
+    }
+  }
+
+  snapshot(): string {
+    return this.buffer;
+  }
+}
+
+export function mergeStdioEnv(
+  configEnv?: Record<string, string>,
+  parentEnv: Readonly<Record<string, string | undefined>> = process.env,
+): Record<string, string> {
+  const merged: Record<string, string> = {};
+  for (const [key, value] of Object.entries(parentEnv)) {
+    if (value !== undefined) merged[key] = value;
+  }
+  if (configEnv !== undefined) Object.assign(merged, configEnv);
+  Object.assign(merged, proxyEnvForChild(merged));
+  reconcileChildNoProxy(merged, configEnv);
+  return merged;
+}

packages/agent-core-v2/src/mcpCore/config-schema.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+
+const StringRecordSchema = z.record(z.string(), z.string());
+
+export const MAX_MCP_TIMEOUT_MS = 2_147_483_647;
+export const McpTimeoutMsSchema = z.number().int().min(1).max(MAX_MCP_TIMEOUT_MS);
+
+const McpServerCommonFields = {
+  enabled: z.boolean().optional(),
+  deferred: z.boolean().optional(),
+  startupTimeoutMs: McpTimeoutMsSchema.optional(),
+  toolTimeoutMs: McpTimeoutMsSchema.optional(),
+  enabledTools: z.array(z.string()).optional(),
+  disabledTools: z.array(z.string()).optional(),
+} as const;
+
+export const McpServerStdioConfigSchema = z.object({
+  transport: z.literal('stdio'),
+  command: z.string().min(1),
+  args: z.array(z.string()).optional(),
+  env: StringRecordSchema.optional(),
+  cwd: z.string().optional(),
+  executor: z.enum(['local', 'kaos']).optional(),
+  runtime_id: z.string().min(1).optional(),
+  ...McpServerCommonFields,
+});
+
+export type McpServerStdioConfig = z.infer<typeof McpServerStdioConfigSchema>;
+
+export const McpServerHttpConfigSchema = z.object({
+  transport: z.literal('http'),
+  url: z.string().url(),
+  headers: StringRecordSchema.optional(),
+  auth: z.literal('oauth').optional(),
+  bearerTokenEnvVar: z.string().min(1).optional(),
+  ...McpServerCommonFields,
+});
+
+export type McpServerHttpConfig = z.infer<typeof McpServerHttpConfigSchema>;
+
+export const McpServerSseConfigSchema = z.object({
+  transport: z.literal('sse'),
+  url: z.string().url(),
+  headers: StringRecordSchema.optional(),
+  auth: z.literal('oauth').optional(),
+  bearerTokenEnvVar: z.string().min(1).optional(),
+  ...McpServerCommonFields,
+});
+
+export type McpServerSseConfig = z.infer<typeof McpServerSseConfigSchema>;
+export type McpRemoteServerConfig = McpServerHttpConfig | McpServerSseConfig;
+
+const McpServerConfigDiscriminatedSchema = z.discriminatedUnion('transport', [
+  McpServerStdioConfigSchema,
+  McpServerHttpConfigSchema,
+  McpServerSseConfigSchema,
+]);
+
+export const McpServerConfigSchema = z.preprocess((raw) => {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return raw;
+  const obj = raw as Record<string, unknown>;
+  if ('transport' in obj) return obj;
+  if (typeof obj['command'] === 'string') return { ...obj, transport: 'stdio' };
+  if (typeof obj['url'] === 'string') return { ...obj, transport: 'http' };
+  return obj;
+}, McpServerConfigDiscriminatedSchema);
+
+export type McpServerConfig = z.infer<typeof McpServerConfigSchema>;

packages/agent-core-v2/src/mcpCore/configView.ts

@@ -0,0 +1,18 @@
+import type { McpServerConfig } from './config-schema';
+
+export type McpServerConfigView =
+  | (Omit<Extract<McpServerConfig, { readonly transport: 'stdio' }>, 'env'> & {
+      readonly envKeys?: readonly string[];
+    })
+  | (Omit<Exclude<McpServerConfig, { readonly transport: 'stdio' }>, 'headers'> & {
+      readonly headerKeys?: readonly string[];
+    });
+
+export function toMcpServerConfigView(config: McpServerConfig): McpServerConfigView {
+  if (config.transport === 'stdio') {
+    const { env, ...safe } = config;
+    return env === undefined ? safe : { ...safe, envKeys: Object.keys(env).toSorted() };
+  }
+  const { headers, ...safe } = config;
+  return headers === undefined ? safe : { ...safe, headerKeys: Object.keys(headers).toSorted() };
+}

packages/agent-core-v2/src/mcpCore/connection-manager.ts

@@ -0,0 +1,603 @@
+import { ErrorCodes, Error2 } from '#/errors';
+import type { McpServerConfig } from './config-schema';
+import type { ILogger as Logger } from '#/_base/log/log';
+import type { ToolDescription as Tool } from '#human/llm/message';
+import { HostProcessError, HostProcessErrorCode } from '#/os/interface/hostProcess';
+
+import { abortable } from '#/_base/utils/abort';
+import { HttpMcpClient } from './client-http';
+import { isRemoteMcpConfig } from './client-remote';
+import { SseMcpClient } from './client-sse';
+import type { UnexpectedCloseReason } from './client-shared';
+import { StdioMcpClient } from './client-stdio';
+import type { McpOAuthService } from '#/mcpCore/oauth/service';
+import { assertMcpInputSchema, type MCPClient, type MCPToolDefinition } from './types';
+
+export type McpServerStatus = 'pending' | 'connected' | 'failed' | 'disabled' | 'needs-auth' | 'removed';
+
+export interface McpServerEntry {
+  readonly name: string;
+  readonly transport: McpServerConfig['transport'];
+  readonly status: McpServerStatus;
+  readonly toolCount: number;
+  readonly error?: string;
+}
+
+interface InternalEntry {
+  readonly name: string;
+  readonly config: McpServerConfig;
+  attemptId: number;
+  status: McpServerStatus;
+  tools?: readonly Tool[];
+  rawTools?: readonly MCPToolDefinition[];
+  enabledNames?: ReadonlySet<string>;
+  error?: string;
+  client?: RuntimeMcpClient;
+}
+
+export type McpStatusListener = (entry: McpServerEntry) => void;
+
+export interface McpConnectionView {
+  readonly oauthService: McpOAuthService | undefined;
+  list(): readonly McpServerEntry[];
+  get(name: string): McpServerEntry | undefined;
+  configOf(name: string): McpServerConfig | undefined;
+  resolved(
+    name: string,
+  ):
+    | {
+        client: MCPClient;
+        tools: readonly Tool[];
+        rawTools: readonly MCPToolDefinition[];
+        enabledNames: ReadonlySet<string>;
+        deferred: boolean;
+      }
+    | undefined;
+  getRemoteServerUrl(name: string): string | undefined;
+  reconnect(name: string): Promise<void>;
+  reconnectAndJoin(name: string): Promise<void>;
+  waitForInitialLoad(signal?: AbortSignal): Promise<void>;
+  initialLoadDurationMs(): number;
+  onStatusChange(listener: McpStatusListener): () => void;
+}
+
+const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
+
+type RuntimeMcpClient = StdioMcpClient | HttpMcpClient | SseMcpClient;
+const defaultLog: Logger = {
+  error: () => {},
+  warn: () => {},
+  info: () => {},
+  debug: () => {},
+  child: () => defaultLog,
+};
+
+export interface McpDefaultTimeouts {
+  readonly startupTimeoutMs?: number;
+  readonly toolTimeoutMs?: number;
+}
+
+export interface McpConnectionManagerOptions {
+  readonly envLookup?: (name: string) => string | undefined;
+  readonly stdioCwd?: string;
+  readonly runtimeResolver?: import('#/workspace/workspaceInstance/workspaceInstanceManager').IRuntimeResolver;
+  readonly workspaceId?: string;
+  readonly runtimeId?: string;
+  readonly requireStdioRuntimeId?: boolean;
+  readonly oauthService?: McpOAuthService;
+  readonly log?: Logger;
+  readonly resolveDefaultTimeouts?: () => McpDefaultTimeouts;
+  readonly resolveClientName?: () => string | undefined;
+}
+
+export class McpConnectionManager implements McpConnectionView {
+  private readonly entries = new Map<string, InternalEntry>();
+  private readonly listeners = new Set<McpStatusListener>();
+  private readonly inFlightReconnects = new Map<string, Promise<void>>();
+  private initialLoad: Promise<void> = Promise.resolve();
+  private initialLoadAttemptId = 0;
+  private initialLoadStartedAt: number | undefined;
+  private initialLoadFinishedAt: number | undefined;
+
+  readonly oauthService: McpOAuthService | undefined;
+  private readonly log: Logger;
+
+  constructor(private readonly options: McpConnectionManagerOptions = {}) {
+    this.oauthService = options.oauthService;
+    this.log = options.log ?? defaultLog;
+  }
+
+  getRemoteServerUrl(name: string): string | undefined {
+    const entry = this.entries.get(name);
+    if (entry === undefined) return undefined;
+    if (!isRemoteMcpConfig(entry.config)) return undefined;
+    return entry.config.url;
+  }
+
+  getHttpServerUrl(name: string): string | undefined {
+    return this.getRemoteServerUrl(name);
+  }
+
+  onStatusChange(listener: McpStatusListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  list(): readonly McpServerEntry[] {
+    return Array.from(this.entries.values(), toPublicEntry);
+  }
+
+  get(name: string): McpServerEntry | undefined {
+    const entry = this.entries.get(name);
+    return entry !== undefined ? toPublicEntry(entry) : undefined;
+  }
+
+  configOf(name: string): McpServerConfig | undefined {
+    return this.entries.get(name)?.config;
+  }
+
+  resolved(
+    name: string,
+  ):
+    | {
+        client: MCPClient;
+        tools: readonly Tool[];
+        rawTools: readonly MCPToolDefinition[];
+        enabledNames: ReadonlySet<string>;
+        deferred: boolean;
+      }
+    | undefined {
+    const entry = this.entries.get(name);
+    if (
+      entry?.status !== 'connected' ||
+      entry.tools === undefined ||
+      entry.rawTools === undefined ||
+      entry.client === undefined
+    ) {
+      return undefined;
+    }
+    return {
+      client: entry.client,
+      tools: entry.tools,
+      rawTools: entry.rawTools,
+      enabledNames: entry.enabledNames ?? new Set(entry.tools.map((t) => t.name)),
+      deferred: entry.config.deferred === true,
+    };
+  }
+
+  connectAll(configs: Record<string, McpServerConfig>): Promise<void> {
+    const attemptId = ++this.initialLoadAttemptId;
+    this.initialLoadStartedAt = Date.now();
+    this.initialLoadFinishedAt = undefined;
+    const initialLoad = this.connectAllNow(configs).finally(() => {
+      if (this.initialLoadAttemptId === attemptId) {
+        this.initialLoadFinishedAt = Date.now();
+      }
+    });
+    this.initialLoad = initialLoad;
+    return initialLoad;
+  }
+
+  async connect(name: string, config: McpServerConfig): Promise<void> {
+    const previous = this.entries.get(name);
+    if (previous !== undefined) {
+      if (
+        (previous.status === 'pending' || previous.status === 'connected') &&
+        mcpServerConfigsEqual(previous.config, config)
+      ) {
+        return;
+      }
+      await this.closeClient(previous);
+    }
+    const disabled = config.enabled === false;
+    const entry: InternalEntry = {
+      name,
+      config,
+      attemptId: 0,
+      status: disabled ? 'disabled' : 'pending',
+    };
+    this.entries.set(name, entry);
+    this.emit(entry);
+    if (!disabled) {
+      await this.connectOne(entry, this.beginConnectAttempt(entry));
+    }
+  }
+
+  async remove(name: string): Promise<boolean> {
+    const entry = this.entries.get(name);
+    if (entry === undefined) return false;
+    await this.closeClient(entry);
+    entry.status = 'disabled';
+    entry.tools = undefined;
+    entry.enabledNames = undefined;
+    entry.rawTools = undefined;
+    entry.error = undefined;
+    this.emit(entry);
+    this.entries.delete(name);
+    return true;
+  }
+
+  async markRemoved(name: string): Promise<boolean> {
+    const entry = this.entries.get(name);
+    if (entry === undefined) return false;
+    await this.closeClient(entry);
+    entry.status = 'removed';
+    entry.tools = undefined;
+    entry.enabledNames = undefined;
+    entry.rawTools = undefined;
+    entry.error = undefined;
+    this.emit(entry);
+    return true;
+  }
+
+  waitForInitialLoad(signal?: AbortSignal): Promise<void> {
+    signal?.throwIfAborted();
+    if (signal === undefined) return this.initialLoad;
+    return abortable(this.initialLoad, signal);
+  }
+
+  initialLoadDurationMs(): number {
+    if (this.initialLoadStartedAt === undefined) return 0;
+    const endedAt = this.initialLoadFinishedAt ?? Date.now();
+    return Math.max(0, endedAt - this.initialLoadStartedAt);
+  }
+
+  private async connectAllNow(configs: Record<string, McpServerConfig>): Promise<void> {
+    const tasks: Promise<unknown>[] = [];
+    for (const [name, config] of Object.entries(configs)) {
+      const disabled = config.enabled === false;
+      const entry: InternalEntry = {
+        name,
+        config,
+        attemptId: 0,
+        status: disabled ? 'disabled' : 'pending',
+      };
+      this.entries.set(name, entry);
+      this.emit(entry);
+      if (!disabled) {
+        tasks.push(this.connectOne(entry, this.beginConnectAttempt(entry)));
+      }
+    }
+    await Promise.allSettled(tasks);
+  }
+
+  async reconnect(name: string): Promise<void> {
+    const entry = this.entries.get(name);
+    if (entry === undefined || entry.status === 'removed') {
+      throw new Error2(ErrorCodes.MCP_SERVER_NOT_FOUND, `Unknown MCP server: ${name}`);
+    }
+    if (entry.config.enabled === false) {
+      throw new Error2(ErrorCodes.MCP_SERVER_DISABLED, `MCP server is disabled: ${name}`);
+    }
+    const attemptId = this.beginConnectAttempt(entry);
+    await this.closeClient(entry);
+    if (!this.isCurrent(entry, attemptId)) return;
+    entry.status = 'pending';
+    entry.tools = undefined;
+    entry.enabledNames = undefined;
+    entry.rawTools = undefined;
+    entry.error = undefined;
+    this.emit(entry);
+    await this.connectOne(entry, attemptId);
+  }
+
+  reconnectAndJoin(name: string): Promise<void> {
+    const existing = this.inFlightReconnects.get(name);
+    if (existing !== undefined) return existing;
+    const work = this.reconnect(name).finally(() => {
+      if (this.inFlightReconnects.get(name) === work) {
+        this.inFlightReconnects.delete(name);
+      }
+    });
+    this.inFlightReconnects.set(name, work);
+    return work;
+  }
+
+  async reconnectAfterCurrent(name: string): Promise<void> {
+    const existing = this.inFlightReconnects.get(name);
+    if (existing !== undefined) await existing.catch(() => undefined);
+    await this.reconnectAndJoin(name);
+  }
+
+  async shutdown(): Promise<void> {
+    const entries = Array.from(this.entries.values());
+    this.entries.clear();
+    const tasks = entries.map((entry) => this.closeClient(entry));
+    await Promise.allSettled(tasks);
+  }
+
+  private async connectOne(entry: InternalEntry, attemptId: number): Promise<void> {
+    const timeoutMs =
+      entry.config.startupTimeoutMs ??
+      this.options.resolveDefaultTimeouts?.().startupTimeoutMs ??
+      DEFAULT_STARTUP_TIMEOUT_MS;
+
+    let client: RuntimeMcpClient | undefined;
+    try {
+      const startupClient = await this.createClient(entry.config, entry.name, timeoutMs);
+      client = startupClient;
+      entry.client = startupClient;
+      const discovered = await withTimeout(
+        this.connectAndDiscoverTools(startupClient),
+        timeoutMs,
+        () => {
+          void this.closeRuntimeClient(startupClient);
+        },
+      );
+      if (!this.isCurrent(entry, attemptId)) {
+        await this.closeRuntimeClient(startupClient);
+        return;
+      }
+      entry.tools = discovered.tools;
+      entry.rawTools = discovered.rawTools;
+      entry.enabledNames = computeEnabledNames(entry.config, discovered.tools);
+      entry.status = 'connected';
+      this.watchForUnexpectedClose(entry, startupClient, attemptId);
+    } catch (error) {
+      if (!this.isCurrent(entry, attemptId)) {
+        if (client !== undefined) {
+          await this.closeRuntimeClient(client);
+        }
+        return;
+      }
+      if (this.shouldMarkNeedsAuth(entry, error)) {
+        entry.status = 'needs-auth';
+        entry.error = `${entry.name} requires OAuth — run /mcp-config login ${entry.name}`;
+      } else {
+        entry.status = 'failed';
+        entry.error = formatStartupError(error, client);
+      }
+      entry.tools = undefined;
+      entry.enabledNames = undefined;
+      entry.rawTools = undefined;
+      await this.closeClient(entry);
+    }
+    if (!this.isCurrent(entry, attemptId)) return;
+    this.emit(entry);
+  }
+
+  private watchForUnexpectedClose(
+    entry: InternalEntry,
+    client: RuntimeMcpClient,
+    attemptId: number,
+  ): void {
+    client.onUnexpectedClose((reason) => {
+      if (!this.isCurrent(entry, attemptId)) return;
+      if (entry.client !== client) return;
+      entry.status = 'failed';
+      entry.error = formatUnexpectedCloseError(entry.name, reason);
+      entry.tools = undefined;
+      entry.enabledNames = undefined;
+      entry.rawTools = undefined;
+      entry.client = undefined;
+      void this.closeRuntimeClient(client);
+      this.emit(entry);
+    });
+  }
+
+  private beginConnectAttempt(entry: InternalEntry): number {
+    entry.attemptId += 1;
+    return entry.attemptId;
+  }
+
+  private async createClient(
+    config: McpServerConfig,
+    name: string,
+    startupTimeoutMs: number,
+  ): Promise<RuntimeMcpClient> {
+    const toolCallTimeoutMs =
+      config.toolTimeoutMs ?? this.options.resolveDefaultTimeouts?.().toolTimeoutMs;
+    const clientName = this.options.resolveClientName?.();
+    if (config.transport === 'stdio') {
+      const runtimeResolver = this.options.runtimeResolver;
+      const workspaceId = this.options.workspaceId;
+      const runtimeId = config.runtime_id ?? this.options.runtimeId;
+      if (runtimeResolver === undefined || workspaceId === undefined || runtimeId === undefined || (this.options.requireStdioRuntimeId === true && config.runtime_id === undefined)) {
+        throw new Error('MCP stdio requires runtime_id and runtime binding');
+      }
+      return new StdioMcpClient(config, {
+        startupTimeoutMs,
+        toolCallTimeoutMs,
+        defaultCwd: this.options.stdioCwd,
+        clientName,
+        runtimeResolver,
+        workspaceId,
+        runtimeId,
+      });
+    }
+    if (config.transport === 'sse') {
+      return new SseMcpClient(config, {
+        startupTimeoutMs,
+        toolCallTimeoutMs,
+        envLookup: this.options.envLookup,
+        oauthProvider: await this.resolveOAuthProvider(config, name),
+        clientName,
+      });
+    }
+    return new HttpMcpClient(config, {
+      startupTimeoutMs,
+      toolCallTimeoutMs,
+      envLookup: this.options.envLookup,
+      oauthProvider: await this.resolveOAuthProvider(config, name),
+      clientName,
+    });
+  }
+
+  private async resolveOAuthProvider(
+    config: McpServerConfig,
+    name: string,
+  ): Promise<ReturnType<McpOAuthService['getProvider']> | undefined> {
+    const oauthService = this.oauthService;
+    if (oauthService === undefined) return undefined;
+    if (!isRemoteMcpConfig(config)) return undefined;
+    if (config.bearerTokenEnvVar !== undefined) return undefined;
+    if (!(await oauthService.hasTokens(name, config.url))) return undefined;
+    return oauthService.getProvider(name, config.url);
+  }
+
+  private shouldMarkNeedsAuth(entry: InternalEntry, error: unknown): boolean {
+    if (this.oauthService === undefined) return false;
+    if (!isRemoteMcpConfig(entry.config)) return false;
+    if (entry.config.bearerTokenEnvVar !== undefined) return false;
+    if (entry.config.headers !== undefined && entry.config.auth !== 'oauth') return false;
+    return isUnauthorizedLikeError(error);
+  }
+
+  private async connectAndDiscoverTools(
+    client: RuntimeMcpClient,
+  ): Promise<{ tools: Tool[]; rawTools: MCPToolDefinition[] }> {
+    await client.connect();
+    const mcpTools = await client.listTools();
+    return {
+      rawTools: mcpTools,
+      tools: mcpTools.map((mcpTool) => ({
+        name: mcpTool.name,
+        description: mcpTool.description,
+        parameters: assertMcpInputSchema(mcpTool.name, mcpTool.inputSchema),
+      })),
+    };
+  }
+
+  private async closeClient(entry: InternalEntry): Promise<void> {
+    if (entry.client === undefined) return;
+    const client = entry.client;
+    entry.client = undefined;
+    await this.closeRuntimeClient(client);
+  }
+
+  private async closeRuntimeClient(client: RuntimeMcpClient): Promise<void> {
+    try {
+      await client.close();
+    } catch {
+    }
+  }
+
+  private isCurrent(entry: InternalEntry, attemptId: number): boolean {
+    return this.entries.get(entry.name) === entry && entry.attemptId === attemptId;
+  }
+
+  private emit(entry: InternalEntry): void {
+    const view = toPublicEntry(entry);
+    if (view.status === 'failed' || view.status === 'needs-auth') {
+      this.log.error('mcp server unavailable', {
+        server: view.name,
+        transport: view.transport,
+        status: view.status,
+        reason: view.error,
+      });
+    }
+    for (const listener of this.listeners) {
+      try {
+        listener(view);
+      } catch {
+      }
+    }
+  }
+}
+
+function toPublicEntry(entry: InternalEntry): McpServerEntry {
+  return {
+    name: entry.name,
+    transport: entry.config.transport,
+    status: entry.status,
+    toolCount:
+      entry.status === 'connected' && entry.enabledNames !== undefined
+        ? entry.enabledNames.size
+        : 0,
+    error: entry.error,
+  };
+}
+
+function computeEnabledNames(config: McpServerConfig, tools: readonly Tool[]): Set<string> {
+  const all = tools.map((t) => t.name);
+  const enabledFilter =
+    config.enabledTools !== undefined ? new Set(config.enabledTools) : undefined;
+  const disabledFilter =
+    config.disabledTools !== undefined ? new Set(config.disabledTools) : undefined;
+  const allowed = new Set<string>();
+  for (const name of all) {
+    if (enabledFilter !== undefined && !enabledFilter.has(name)) continue;
+    if (disabledFilter !== undefined && disabledFilter.has(name)) continue;
+    allowed.add(name);
+  }
+  return allowed;
+}
+
+function isUnauthorizedLikeError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  if (error.name === 'UnauthorizedError') return true;
+  const code = (error as { code?: unknown }).code;
+  if (typeof code === 'number' && code === 401) return true;
+  if (typeof code === 'string' && code === '401') return true;
+  return /\b401\b/.test(error.message) || /unauthorized/i.test(error.message);
+}
+
+function formatStartupError(error: unknown, client: RuntimeMcpClient | undefined): string {
+  const source = error instanceof HostProcessError &&
+    error.code === HostProcessErrorCode.SpawnFailed &&
+    error.cause instanceof Error
+    ? error.cause
+    : error;
+  const base = source instanceof Error ? source.message : String(source);
+  const tail = stderrTail(client);
+  if (tail === undefined) return base;
+  return `${base}\nstderr: ${tail}`;
+}
+
+function formatUnexpectedCloseError(name: string, reason: UnexpectedCloseReason): string {
+  const parts = [`MCP server "${name}" closed unexpectedly`];
+  if (reason.error !== undefined) {
+    parts.push(reason.error.message);
+  }
+  if (reason.stderr !== undefined && reason.stderr.length > 0) {
+    parts.push(`stderr: ${reason.stderr.trimEnd()}`);
+  }
+  return parts.join('\n');
+}
+
+function stderrTail(client: RuntimeMcpClient | undefined): string | undefined {
+  if (client === undefined) return undefined;
+  if (!(client instanceof StdioMcpClient)) return undefined;
+  const snapshot = client.stderrSnapshot();
+  if (snapshot.length === 0) return undefined;
+  return snapshot.trimEnd();
+}
+
+export function mcpServerConfigsEqual(a: McpServerConfig, b: McpServerConfig): boolean {
+  return stableConfigJson(a) === stableConfigJson(b);
+}
+
+function stableConfigJson(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableConfigJson).join(',')}]`;
+  }
+  if (typeof value === 'object' && value !== null) {
+    const entries = Object.entries(value)
+      .filter(([, entryValue]) => entryValue !== undefined)
+      .map(([key, entryValue]) => `${JSON.stringify(key)}:${stableConfigJson(entryValue)}`)
+      .toSorted();
+    return `{${entries.join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'undefined';
+}
+
+async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  onTimeout?: () => void,
+): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    return await new Promise<T>((resolve, reject) => {
+      timer = setTimeout(() => {
+        onTimeout?.();
+        reject(new Error2(ErrorCodes.MCP_STARTUP_FAILED, `Timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      promise.then(resolve, reject);
+    });
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}

packages/agent-core-v2/src/mcpCore/errors.ts

@@ -0,0 +1,13 @@
+import { registerErrorDomain, type ErrorDomain } from '#/_base/errors/codes';
+
+export const McpErrors = {
+  codes: {
+    MCP_SERVER_NOT_FOUND: 'mcp.server_not_found',
+    MCP_SERVER_DISABLED: 'mcp.server_disabled',
+    MCP_STARTUP_FAILED: 'mcp.startup_failed',
+    MCP_TOOL_NAME_COLLISION: 'mcp.tool_name_collision',
+    MCP_OAUTH_FAILED: 'mcp.oauth_failed',
+  },
+} as const satisfies ErrorDomain;
+
+registerErrorDomain(McpErrors);

packages/agent-core-v2/src/mcpCore/tool-naming.ts

@@ -0,0 +1,26 @@
+const MCP_NAME_PREFIX = 'mcp__';
+const MCP_NAME_SEPARATOR = '__';
+
+const MAX_QUALIFIED_LENGTH = 64;
+
+export function sanitizeMcpNamePart(part: string): string {
+  return part.replaceAll(/[^a-zA-Z0-9_-]/g, '_').replaceAll(/_+/g, '_');
+}
+
+export function qualifyMcpToolName(serverName: string, toolName: string): string {
+  const full = `${MCP_NAME_PREFIX}${sanitizeMcpNamePart(serverName)}${MCP_NAME_SEPARATOR}${sanitizeMcpNamePart(toolName)}`;
+  if (full.length <= MAX_QUALIFIED_LENGTH) return full;
+
+  const hash = stableHash8(full);
+  const head = full.slice(0, MAX_QUALIFIED_LENGTH - hash.length - 1);
+  return `${head}_${hash}`;
+}
+
+function stableHash8(input: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.codePointAt(i)!;
+    hash = Math.trunc(Math.imul(hash, 0x01000193));
+  }
+  return hash.toString(16).padStart(8, '0');
+}

packages/agent-core-v2/src/mcpCore/types.ts

@@ -0,0 +1,55 @@
+import { ErrorCodes, Error2 } from '#/errors';
+
+export interface MCPEmbeddedResourceContents {
+  uri: string;
+  mimeType?: string;
+  text?: string;
+  blob?: string;
+  [key: string]: unknown;
+}
+
+export interface MCPContentBlock {
+  type: string;
+  text?: string;
+  data?: string;
+  mimeType?: string;
+  uri?: string;
+  resource?: MCPEmbeddedResourceContents;
+  [key: string]: unknown;
+}
+
+export interface MCPToolResult {
+  content: MCPContentBlock[];
+  isError: boolean;
+  structuredContent?: unknown;
+  _meta?: Record<string, unknown>;
+}
+
+export interface MCPToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: unknown;
+}
+
+export interface MCPClient {
+  listTools(): Promise<MCPToolDefinition[]>;
+  callTool(
+    name: string,
+    args: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<MCPToolResult>;
+  ping(signal?: AbortSignal): Promise<void>;
+}
+
+export function assertMcpInputSchema(
+  toolName: string,
+  inputSchema: unknown,
+): Record<string, unknown> {
+  if (typeof inputSchema === 'object' && inputSchema !== null && !Array.isArray(inputSchema)) {
+    return inputSchema as Record<string, unknown>;
+  }
+  throw new Error2(
+    ErrorCodes.MCP_STARTUP_FAILED,
+    `Invalid inputSchema for MCP tool "${toolName}": schema must be a JSON object`,
+  );
+}