Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

135 KB
Raw Blame
/**
 * BaseAgent — Claude Code / Codex 等具体 agent 的统一抽象。
 *
 * 设计要点:
 * - 接口面与现有 vendor/types.ts:VendorSession 对齐,desktop adapter 层只做 thin wrapper
 * - 不支持的能力默认抛 NotSupportedError,子类按 capabilities 覆盖
 * - 持有依赖注入的 deps,但具体使用由子类决定
 */

import type { AutoReviewUserIntent, AutoReviewUserReferences } from './shared/auto-review-decision.js';
import { LIBRARY_READ_ROOT } from './shared/library-native-read.js';
import { canonicalSkillPath, isSkillDisabled } from './shared/skill-activation.js';

import type {
  AgentEvent,
  InteractionDecision,
  InteractionResolver,
  UsageSnapshot,
  RewindFilesResult,
  RewindCommitOptions,
  RewindCommitResult,
  ForkSdkSessionOptions,
  ForkSdkSessionResult,
  SendOrigin,
} from '../types/events.js';
import type { ContextUsageData } from '../types/context-usage.js';
import {
  coerceSessionPermissionUpdates,
  createSessionPermissionUpdate,
  hasSessionPermissionUpdates,
  type SessionPermissionUpdate,
} from '../types/permissions.js';
import type { AgentKind, Effort, PermissionMode, ReasoningDisplay, UserMessage, WorkspaceKind } from '../types/common.js';
import type {
  Capabilities,
  EffortDescriptor,
  ManualCompactResult,
  ModelDescriptor,
  NavigateSessionTreeOptions,
  NavigateSessionTreeResult,
  SessionTreeSnapshot,
} from '../types/capabilities.js';
import type { CapabilityRoutingPolicy } from '../types/capability-routing.js';
import { NotSupportedError } from '../types/capabilities.js';
import type { AgentCredentialMode, AuthLoginOptions } from '../interfaces/auth-adapter.js';
import type { ContactsPromptState } from '../contacts/system-prompt.js';
import type {
  MemoryStatus,
  MemorySetResult,
  MemoryResetResult,
} from '../types/memory.js';
import type {
  AccountRateLimitsResponse,
  ConsumeAccountRateLimitResetCreditParams,
  ConsumeAccountRateLimitResetCreditResponse,
} from '../types/account-rate-limits.js';
import type { HookEvent, HookCallbackMatcher, Query } from '@anthropic-ai/claude-agent-sdk';

import type { AuthAdapter } from '../interfaces/auth-adapter.js';
import type { AgentRuntimeConfig } from '../interfaces/runtime-config.js';
import type { Logger } from '../interfaces/logger.js';
import type { McpProvider } from '../interfaces/mcp-provider.js';
import type { MakerMemoryManager } from '../memory/manager.js';
import type {
  CodexModelListItem,
  ReasoningEffort,
} from './codex/app-server/protocol.js';
import type {
  ScanAtResourcesOptions,
  ScanAtResourcesResult,
  AgentBuiltinCommand,
  AgentSkillCommand,
  ListAgentSkillsOptions,
  ListAgentSkillsResult,
  ListRuntimeSkillsOptions,
} from '../types/palette.js';
import type {
  ListCustomizationsOptions,
  ListCustomizationsResult,
} from '../types/customizations.js';
import type { PiRuntimeCapabilityManifest } from '../types/pi-runtime-capabilities.js';
import type { PiProjectTrustInputSnapshot } from '../types/pi-project-trust.js';
import { scanWorkspaceFileResources } from './shared/palette-scanner.js';
import type { AutoReviewDelegate, AutoReviewDecision, AutoReviewRequest } from './shared/auto-review-decision.js';
import type { ReviewableAction } from './shared/auto-review.js';
import type { ClaudeSubagentModelAccessResult } from './claude-code/subagent-model-access.js';

export type CodexLocalAuthPolicyResolution = 'isolated' | 'legacy-shared' | {
  policy: 'isolated' | 'legacy-shared';
  /** Synchronous check of the host routing transaction that produced this policy. */
  isCurrent: () => boolean;
};

export interface AgentCapabilityAdditions {
  /** Extra models exposed by the host for this agent. Existing built-in ids are ignored. */
  availableModels?: readonly ModelDescriptor[];
  /** Extra effort labels exposed by the host. Existing built-in ids are ignored. */
  effortLevels?: readonly EffortDescriptor[];
}

export interface CodexMcpThreadContextArgs {
  threadId: string;
  sessionId: string;
  /** Host-owned app-server thread lineage. */
  mcpCallerKind: 'root' | 'descendant' | 'unknown';
  mcpCallerAttested: boolean;
  /** 当前 Maker Session 实例代号;同 business session 重建后必须变化。 */
  sessionInstanceId?: string;
  workingDir: string;
  /** Host-owned memory namespace override shared with prompt injection and MCP tools. */
  memoryScopeKey?: string;
  /** Whether this concrete Session should receive the memory bridge server. */
  memoryEnabled?: boolean;
  /**
   * SSH remote 会话的 host id。cindy_memory 的 store 定位键要靠它区分
   * 「远端路径」与「本地同名路径」(buildMemoryScopeKey), 缺省 = 本地会话。
   */
  remoteHostId?: string;
  vendorOptions: Record<string, unknown>;
}

/** Metadata Codex attaches to an MCP tool approval elicitation. */
export interface McpToolApprovalContext {
  serverName: string;
  /** Top-level MCP tool name, for example `list_tools` or `call_tool`. */
  toolName?: string;
  /** Top-level MCP arguments. Progressive servers carry the inner name/args here. */
  toolParams?: unknown;
}

export type McpToolApprovalPolicy =
  | 'auto-approve'
  | 'prompt'
  | 'prompt-each-time';

/** Pi 内 MCP client 的 server 描述;remote 存在时直接访问外部 Streamable HTTP MCP。 */
export interface PiMcpServerRef {
  name: string;
  url: string;
  remote?: {
    /** HTTP header 名 → Pi 父进程 env var 名;描述符里绝不放 header 真值。 */
    headerEnvVars: Record<string, string>;
    /** extension 启动时 initialize + tools/list 的总预算;必须短于 Pi RPC ready 超时。 */
    startupTimeoutMs: number;
    /** 完成启动探测后的单次工具调用预算。 */
    requestTimeoutMs: number;
  };
}

/** pi spawn 附加配置:host 的 MCP HTTP bridge / 外部 HTTP MCP 出口。 */
export interface PiExtraSpawnConfig {
  mcpBridge?: {
    token: string;
    servers: PiMcpServerRef[];
    /** Bot-scoped memory is exposed as one typed Pi tool instead of nested discovery. */
    botMemoryFacade?: boolean;
  } | null;
  /** 外部 MCP header 真值;只进 Pi 父进程 env,并在 bash spawn 边界剥离。 */
  mcpEnv?: Record<string, string>;
  /**
   * 释放本 session 的 bridge lease;带 sessionId 时同时注销身份 ctx。PiAgent 在
   * close() 时调用且要求幂等。只要拿到 bridge(包括匿名会话)就应提供。
   */
  disposeSessionCtx?: () => void;
}

/** pi models.json 原生 provider 的 api 形态(BYOM 用;不过 anthropic-compat 代理)。 */
export type PiNativeApi =
  | 'anthropic-messages'
  | 'openai-responses'
  | 'openai-completions'
  | 'google-generative-ai'
  | 'bedrock-converse-stream'
  | 'azure-openai-responses'
  | 'google-vertex'
  | 'mistral-conversations'
  /** PI's native ChatGPT subscription adapter; not a portable BYOM protocol. */
  | 'openai-codex-responses';

export type PiNativeThinkingLevel = 'off' | Exclude<Effort, 'ultra'>;

export interface PiNativeModelCost {
  input: number;
  output: number;
  cacheRead: number;
  cacheWrite: number;
  tiers?: Array<{
    inputTokensAbove: number;
    input: number;
    output: number;
    cacheRead: number;
    cacheWrite: number;
  }>;
}

/** BYOM:写进 pi models.json 的一个模型(原生 provider 块内)。 */
export interface PiNativeModelSpec {
  /** Current connection's explicit support for OpenAI priority service tier. */
  supportsFastMode?: boolean;
  /** Cindy/public model id used by provider-aware routing and the UI. */
  id: string;
  /** PI provider's native model id; omitted when it is identical to id. */
  wireId?: string;
  /** Sparse models.json override/addition; absent means retain PI's bundled model entry. */
  api?: PiNativeApi;
  /** Per-model native endpoint retained from PI's bundled provider table. */
  baseUrl?: string;
  /** Host-only identity for learned compatibility when baseUrl is a local auth proxy. */
  cacheIdentityBaseUrl?: string;
  /** Add a model missing from PI's bundled catalog while inheriting the provider's bundled API. */
  catalogAddition?: boolean;
  name?: string;
  /** Per-model request headers from the authoritative Pi catalog. */
  headers?: Record<string, string>;
  reasoning?: boolean;
  /** Pi models.json 的 provider-specific thinking level 映射;null 明确禁用该档。 */
  thinkingLevelMap?: Partial<Record<PiNativeThinkingLevel, string | null>>;
  contextWindow?: number;
  maxTokens?: number;
  input?: Array<'text' | 'image'>;
  /** Preserve bundled accounting metadata when a protocol correction replaces a model entry. */
  cost?: PiNativeModelCost;
  /** Preserve model-specific request metadata on a required full-entry replacement. */
  compat?: Record<string, unknown>;
  samplingParams?: Record<string, unknown>;
}

/**
 * 远端 pi agentHome 的文件操作原语(host 经 SSH 实现)。
 *
 * 只暴露 pi 会话真正需要的子集:
 *   - mkdirp / writeFile(agentHome 内文件:models.json、bridge/subagent 扩展、perm、
 *     subagent 快照、受管 rg)
 *   - stat(文件存在性:resume session 预检、plan-mode 扩展存在性)
 *   - rm(清理:configHome / perm / subagent / forkHome)
 * 所有路径都是远端机器上的绝对路径(与 pi 进程 cwd 一致)。
 */
export interface RemoteAgentFileOps {
  stat(file: string): Promise<{ isFile: boolean } | null>;
  /**
   * lstat without following symlinks, used to keep namespace traversal inside
   * the discovery root. Absent on older hosts; callers must treat a missing
   * implementation as "cannot verify" and stay conservative.
   */
  lstat?(file: string): Promise<{ isSymbolicLink: boolean } | null>;
  /** Missing/unreadable directories return an empty array. */
  listDir(dir: string): Promise<string[]>;
  /** Bounded UTF-8 read used for remote runtime metadata such as SKILL.md. */
  readFile(file: string, maxBytes?: number): Promise<string>;
  /** Bounded UTF-8 tail for native history receipts; absent on older hosts. */
  readFileTail?(file: string, maxBytes: number): Promise<string>;
  /** Hash the complete remote file without transferring its contents to the client. */
  sha256File(file: string): Promise<string>;
}

export interface PiRemoteFileOps extends RemoteAgentFileOps {
  mkdirp(dir: string): Promise<void>;
  writeFile(file: string, content: string, mode?: number): Promise<void>;
  rm(fileOrDir: string, opts?: { recursive?: boolean }): Promise<void>;
}

/** Gateway rows carry only host-resolved API/compat metadata, never a native provider endpoint. */
export type PiGatewayModelSpec = Pick<
  PiNativeModelSpec,
  'api' | 'compat' | 'samplingParams' | 'thinkingLevelMap'
>;

/**
 * BYOM:一个**原生 pi provider**(用户自定义/本地模型)—— 直连用户端点,不经 Cindy 的
 * anthropic-compat 代理(设计原则:pi 主导,禁双重转义)。host 从 custom-provider-store
 * 解析产出;PiAgent 写进 models.json 的独立 provider 块,并按 model→provider 路由 set_model。
 */
export interface PiNativeProviderSpec {
  /** Pi adapter identity; the user connection retains its independent ID and credential. */
  adapterProvider?: string;
  /** PI runtime provider id(slug,禁与网关 provider `cindy` 撞名)。 */
  id: string;
  /** Cindy catalog / persisted provider id; defaults to the runtime id. */
  sourceProviderId?: string;
  name: string;
  baseUrl: string;
  /** True upstream endpoint behind a local auth proxy; never serialized to models.json. */
  cacheIdentityBaseUrl?: string;
  /** BYOM provider default. Omitted only when inheriting PI's bundled provider catalog. */
  api?: PiNativeApi;
  /** Keep PI's bundled models and serialize only models carrying an explicit api override. */
  inheritModels?: boolean;
  /**
   * 存放该 provider api key 的 env 变量名;models.json 用 `$<envVar>` 插值引用(与网关
   * CINDY_PI_API_KEY 同机制,密钥只进子进程 env、不落盘)。keyless(本机 Ollama 等)留空 →
   * 写 dummy key(pi 要求有 key 才在 /model 显示)。
   */
  apiKeyEnvVar?: string;
  headers?: Record<string, string>;
  models: PiNativeModelSpec[];
  /** Translate Cindy's persisted/public model id to the Pi-native model id for this provider. */
  modelIdAliases?: Record<string, string>;
  /**
   * This provider is backed by a loopback service owned by the Desktop host. Remote Pi may use
   * it only after the host establishes the exact SSH reverse-forward described here. The marker
   * is host control-plane data and is never serialized into models.json.
   */
  hostProxyForward?: {
    localUrl: string;
    remotePort: number;
  };
}

/** host 解析出的 pi 原生 provider + 需注入子进程的 env(api keys)。 */
export interface PiNativeProvidersResult {
  providers: PiNativeProviderSpec[];
  /** 注入 spawn env 的键值(通常是各 provider 的 api key,键名对应 spec.apiKeyEnvVar)。 */
  env: Record<string, string>;
}

/**
 * The host could not construct the first-party Pi provider because its local
 * compatibility proxy is not ready. This is a fatal startup condition for
 * every SuperGrok route, including provider-less and legacy sessions; it must
 * not be converted into a silent fallback to the Cindy gateway.
 */
export class PiNativeProviderProxyNotReadyError extends Error {
  readonly code = 'PI_NATIVE_PROVIDER_PROXY_NOT_READY';

  constructor(message = 'SuperGrok Pi provider unavailable: local compatibility proxy is not ready') {
    super(message);
    this.name = 'PiNativeProviderProxyNotReadyError';
  }
}

/**
 * pi MCP 桥的 per-session 身份上下文(host 用它在 bridge 上注册当前 pi 会话)。
 *
 * 为什么需要:pi 是独立子进程,其 MCP 请求不带 codex 那样的 _meta.threadId。控制类
 * 工具(orca start_team/create_worker、会话身份类)靠 `getLiziMcpSessionContext()`
 * 拿"当前是哪个 session";没有身份注册时该 ctx 为空,工具回落 LEAD_NOT_SUPPORTED。
 * host 据此把 sessionId 注册到 bridge 并给该 session 的 server URL 打 `?session=`
 * 路由 —— 与远端 Claude Code 的身份通道同机制。
 *
 * sessionId 缺省 → host 不注册、URL 不带 query(匿名会话走无 ctx 兜底,行为同改动前)。
 */
export interface PiExtraSpawnConfigContext {
  /** 使用这些工具的 Agent(缺省 pi)。Agent 在另一台电脑上运行的任务也借这套桥身份。 */
  agentKind?: AgentKind;
  sessionId?: string;
  /** 当前 Maker Session 实例代号;用于阻断旧 bridge 请求借用新实例权限。 */
  sessionInstanceId?: string;
  workingDir: string;
  /**
   * 本会话的 Maker Memory 作用域键 (startSession opts.makerMemoryScopeKey)。
   *
   * 必须透到 bridge 注册的 session ctx 上:cindy_memory 的 withStore 优先用
   * ctx.memoryScopeKey 定位 store, 缺失时才回落 buildMemoryScopeKey(workingDir)。
   * Cindy Bot 会话的注入索引来自 `bot:<botId>` store —— 这里丢掉就会出现
   * 「prompt 读伙伴记忆、工具写项目记忆」的两张皮。
  */
  memoryScopeKey?: string;
  /** Whether this concrete Pi Session should receive the memory bridge server. */
  memoryEnabled?: boolean;
  /** Frozen per-Bot custom MCP policy; the host filters each session's bridge descriptor. */
  botMcpPolicy?: BotRuntimeMcpPolicy;
  vendorOptions?: Record<string, unknown>;
  mcpCallerKind?: 'root' | 'descendant' | 'unknown';
  mcpCallerAttested?: boolean;
  /** SSH remote 会话的 host id;host 据此把 bridge URL 改成 remote-forward 地址。 */
  remoteHostId?: string | null;
}

export type CodexSubagentRoutingProfile = 'default' | 'configured' | 'oauth-default' | 'smart';

/**
 * Session facts the host may consult when building per-thread MCP config
 * overrides (e.g. hiding a session-purpose server from ordinary threads).
 */
export interface CodexSessionMcpConfigInput {
  vendorOptions?: Record<string, unknown>;
}

export interface CodexExtraSpawnConfig {
  extraArgs: string[];
  extraEnv: Record<string, string>;
  /** Host 路由要求更强的 Codex 进程凭证时,冷启动以该模式重建 app-server。 */
  requiredSpawnCredentialMode?: 'oauth-bearer';
  /** Cindy-side display fallback for Codex subagent cards. */
  subagentModelFallback?: string;
  /** Provider route frozen alongside the locked subagent model for this app-server. */
  subagentRoute?: {
    providerId: string;
    catalogModel: string;
    reasoningEffort?: ReasoningEffort | null;
  };
  /** Per-model Provider routes exposed only when Cindy smart Subagent routing is enabled. */
  smartSubagentRoutes?: Array<{
    providerId: string;
    catalogModel: string;
    reasoningEffort?: ReasoningEffort | null;
  }>;
  /** Frozen identity of the Subagent routing/catalog snapshot used by this host. */
  codexSubagentRoutingSignature?: string;
  /** Whether this exact app-server spawn was provisioned with Codex Chrome. */
  codexBrowserUseAvailable?: boolean;
  /** Whether the OpenAI identity provider on this app-server may use Responses WebSocket. */
  codexOpenAiWebSocketsEnabled?: boolean;
  /** Host-level Subagent route profile used to prevent incompatible local host reuse. */
  codexSubagentRoutingProfile?: CodexSubagentRoutingProfile;
  /** Exact verified Chrome plugin version provisioned into this app-server. */
  codexBrowserUseVersion?: string;
  /** Maximum startup wait copied from the verified companion descriptor. */
  codexBrowserUseStartupTimeoutMs?: number;
  /**
   * Build per-thread config overrides that bind host-owned HTTP MCP URLs to one
   * in-memory Session instance. The app-server process is shared, so the spawn
   * config only supplies the unbound base URL; thread/start|resume must add the
   * opaque route identity for the concrete Session using this callback.
   */
  buildSessionMcpConfig?: (
    sessionInstanceId: string,
    session?: CodexSessionMcpConfigInput,
  ) => Record<string, unknown>;
  codexProxyActive?: boolean;
  /**
   * ChatGPT 订阅直连的内部 OpenAI transport identity,仅 oauth-bearer spawn 下发。
   */
  codexRemoteCompactionProviderId?: string;
  /** Cindy Provider codex/* 的内部 OpenAI transport identity;固定走 HTTP。 */
  codexCindyRemoteCompactionProviderId?: string;
  /** Native summary identity persisted per thread after remote auto-compaction fails. */
  codexLocalCompactionProviderId?: string;
  /** Generic custom Provider identities and capabilities frozen into this app-server spawn. */
  codexCustomProviderRoutes?: Array<{
    providerId: string;
    modelProviderId: string;
    capabilities: Readonly<Record<string, boolean | undefined>>;
    responseModels: readonly string[];
  }>;
  /** One-shot cleanup for spawn-time resources when this Host is terminally retired. */
  onHostRetired?: () => void | Promise<void>;
}

export type CodexAppServerProcessRole = 'task-host' | 'control-plane-service';

export interface CodexAppServerProcessRegistration {
  pid: number;
  role: CodexAppServerProcessRole;
}

export interface LocalAgentProcessRegistration {
  pid: number;
  kind: 'claude' | 'pi';
  role: 'task-host' | 'control-plane-service';
  /**
   * 承载本进程的宿主 session id,供资源监视器显示归属任务。远端 transport
   * 不触发登记,宿主可忽略。
   */
  sessionId?: string | null;
}

export interface CodexLocalCredentialModeSwitchContext {
  /** Exact local host being replaced; omitted by legacy hosts. */
  hostKey?: string;
  fromMode?: AgentCredentialMode;
  /**
   * 当前 host 的归一化生效形态(createHost 时按 auth fallback 推出并登记)。
   * fromMode 是原始登记值(隐式来源时为 undefined → 宿主显示成 fallback),
   * 排查"为什么要切"时只有归一化形态能说明 host 实际拿的是哪种钥匙。
   */
  fromModeEffective?: AgentCredentialMode;
  toMode?: AgentCredentialMode;
  activeSubscriptions: number;
}

export interface RefreshLocalModelsOptions {
  providerId?: string;
  /**
   * Bind model discovery to a specific local credential route.
   * Codex serves explicit routes from an isolated control-plane host so live
   * session hosts never need a credential-mode switch.
   */
  credentialMode?: AgentCredentialMode;
  /**
   * Claude Code:把本次读到的 SDK `supportedModels()` 原样交给调用方,而不是全局
   * 捕获监听器,让调用方按发起时的登录代际决定是否采用。
   */
  onSupportedModels?: (models: unknown[]) => void;
}

export interface ClaudeSubagentTaskRegistration {
  taskId: string;
  parentToolUseId: string;
  prompt: string;
  model?: string;
}

export interface ClaudeSubagentTaskUsage {
  totalTokens: number;
}

/**
 * The host has positively identified a resume state that must not be handed to
 * Codex yet (for example, a rollout file that may still have a live writer).
 * Unlike an incidental preparation failure, this error deliberately blocks
 * thread/resume so Codex cannot append to an unsafe path.
 */
export class CodexResumePreparationBlockedError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'CodexResumePreparationBlockedError';
  }
}

export interface TurnChangeCaptureHooks {
  /** Capture one known target before the provider is allowed to mutate it. */
  beforeKnownFileWrite(input: {
    sessionId: string;
    provider: 'claude-code' | 'pi';
    cwd: string;
    targetPath: string;
    remote?: boolean;
  }): Promise<void>;
  /** Record a tool whose filesystem effects cannot be known before execution. */
  noteOpaqueWrite(input: {
    sessionId: string;
    provider: 'claude-code' | 'pi';
    cwd: string;
    remote?: boolean;
  }): void;
}

export type PiNativePackageEntry = string | ({ source: string } & Record<string, unknown>);

export type PiManagedPackageMutationRequest = import('./pi/managed-command.js').PiManagementCommand & {
  /** Host-trusted evidence. This value is never accepted from Renderer or model input. */
  authorization:
    | 'local-desktop-command'
    | 'authenticated-im-command'
    | 'confirmed-tool-call';
}

/** Main-owned native confirmation was dismissed before any package mutation began. */
export class PiManagedPackageMutationCancelledError extends Error {
  readonly code = 'PI_PACKAGE_MUTATION_CANCELLED';

  constructor() {
    super('Pi extension mutation cancelled');
    this.name = 'PiManagedPackageMutationCancelledError';
  }
}

export type PiManagedPackageMutationFailureCode =
  | 'source-unavailable'
  | 'package-not-found'
  | 'version-not-found'
  | 'state-unavailable'
  | 'native-command-failed';

/** Public diagnostics contain only host-selected enums/numbers, never CLI text or argv. */
export interface PiPackageCommandDiagnostic {
  phase: 'prepare' | 'native-command' | 'cindy-analysis';
  outcome: 'failed' | 'timed-out' | 'unknown';
  command?: 'install' | 'update' | 'remove' | 'list' | 'version' | 'dependency-install' | 'build';
  exitCode?: number | null;
  nativeCode?: 'E401' | 'E403' | 'EACCES' | 'EPERM' | 'ETARGET' | 'E404' | 'ENOTFOUND'
    | 'EAI_AGAIN' | 'ECONNREFUSED' | 'ETIMEDOUT' | 'ENOSPC' | 'ENOENT' | 'ELIFECYCLE';
  signal?: 'SIGTERM' | 'SIGKILL' | 'SIGINT' | 'other';
  reason: 'authentication' | 'permission' | 'network' | 'package-not-found'
    | 'version-not-found' | 'missing-executable' | 'disk-full' | 'build-failed'
    | 'state-unavailable' | 'missing-file' | 'unknown';
  recovery: 'check-credentials' | 'check-permissions' | 'check-network'
    | 'check-source' | 'check-version' | 'check-runtime' | 'free-disk-space'
    | 'check-build-dependencies' | 'refresh-package-state' | 'inspect-state-before-retry';
}

/** Pick bounded diagnostic fields at transcript boundaries. Keep self-contained: embedded in the Pi bridge. */
export function projectPiPackageCommandDiagnostic(value: unknown): PiPackageCommandDiagnostic | undefined {
  if (!value || typeof value !== 'object') return undefined;
  const data = value as Record<string, unknown>;
  const choices = {
    phase: ['prepare', 'native-command', 'cindy-analysis'],
    outcome: ['failed', 'timed-out', 'unknown'],
    reason: ['authentication', 'permission', 'network', 'package-not-found', 'version-not-found',
      'missing-executable', 'disk-full', 'build-failed', 'state-unavailable', 'missing-file', 'unknown'],
    recovery: ['check-credentials', 'check-permissions', 'check-network', 'check-source', 'check-version',
      'check-runtime', 'free-disk-space', 'check-build-dependencies', 'refresh-package-state', 'inspect-state-before-retry'],
  };
  for (const [key, values] of Object.entries(choices)) {
    if (typeof data[key] !== 'string' || !values.includes(data[key] as string)) return undefined;
  }
  return {
    phase: data.phase as PiPackageCommandDiagnostic['phase'],
    outcome: data.outcome as PiPackageCommandDiagnostic['outcome'],
    reason: data.reason as PiPackageCommandDiagnostic['reason'],
    recovery: data.recovery as PiPackageCommandDiagnostic['recovery'],
    ...(data.exitCode === null || (Number.isSafeInteger(data.exitCode) && Math.abs(data.exitCode as number) <= 0xffffffff)
      ? { exitCode: data.exitCode as number | null } : {}),
    ...(typeof data.command === 'string' && ['install', 'update', 'remove', 'list', 'version', 'dependency-install', 'build'].includes(data.command)
      ? { command: data.command as PiPackageCommandDiagnostic['command'] } : {}),
    ...(typeof data.nativeCode === 'string' && ['E401', 'E403', 'EACCES', 'EPERM', 'ETARGET', 'E404', 'ENOTFOUND',
      'EAI_AGAIN', 'ECONNREFUSED', 'ETIMEDOUT', 'ENOSPC', 'ENOENT', 'ELIFECYCLE'].includes(data.nativeCode)
      ? { nativeCode: data.nativeCode as PiPackageCommandDiagnostic['nativeCode'] } : {}),
    ...(typeof data.signal === 'string' && ['SIGTERM', 'SIGKILL', 'SIGINT', 'other'].includes(data.signal)
      ? { signal: data.signal as PiPackageCommandDiagnostic['signal'] } : {}),
  };
}

/** Safe command-stage evidence, also embedded in the generated Pi bridge. */
export function projectPiManagedCommandFailure(value: unknown): import('./pi/managed-command.js').PiManagedCommandFailure | undefined {
  if (!value || typeof value !== 'object') return undefined;
  const data = value as Record<string, unknown>;
  if (typeof data.phase !== 'string' || !['native-packages', 'native-core', 'native-query', 'host-binary-update'].includes(data.phase)
    || typeof data.packagesUpdated !== 'boolean'
    || typeof data.recovery !== 'string' || !['retry-core-only', 'check-host-update-and-retry-core', 'inspect-state-before-retry'].includes(data.recovery)) return undefined;
  return {
    phase: data.phase as import('./pi/managed-command.js').PiManagedCommandFailure['phase'],
    packagesUpdated: data.packagesUpdated,
    recovery: data.recovery as import('./pi/managed-command.js').PiManagedCommandFailure['recovery'],
    ...(typeof data.hostStage === 'string' && ['release-lookup', 'asset-validation', 'prepare', 'download', 'extract', 'version-verification', 'publish'].includes(data.hostStage)
      ? { hostStage: data.hostStage as import('./pi/managed-command.js').PiBinaryUpdateFailureStage } : {}),
  };
}

/** Host-classified package failure; raw cause remains Main-local. */
export class PiManagedPackageMutationFailedError extends Error {
  readonly code = 'PI_PACKAGE_MUTATION_FAILED';
  readonly diagnostic?: PiPackageCommandDiagnostic;
  readonly commandFailure?: import('./pi/managed-command.js').PiManagedCommandFailure;

  constructor(
    readonly mayHaveChangedState: boolean,
    readonly failureCode: PiManagedPackageMutationFailureCode,
    details?: PiPackageCommandDiagnostic | import('./pi/managed-command.js').PiManagedCommandFailure,
    diagnostic?: PiPackageCommandDiagnostic,
  ) {
    super('Pi extension mutation failed');
    this.name = 'PiManagedPackageMutationFailedError';
    this.diagnostic = projectPiPackageCommandDiagnostic(diagnostic ?? details);
    this.commandFailure = projectPiManagedCommandFailure(details);
  }
}

export interface PiExtensionUiStrings {
  confirm: string;
  cancel: string;
  mutationFailed: string;
  mutationFailure?: Partial<Record<PiManagedPackageMutationFailureCode, string>>;
  mutationSuccess: Record<'install' | 'update' | 'remove', string> & {
    /** Only used when the returned package explicitly confirms enablement. */
    installEnabled?: string;
  };
}

export interface PiManagedPackageRuntimeConvergence {
  runtimeConvergence: 'complete' | 'partial' | 'deferred';
  recoveryAction?: 'restart-cindy-to-refresh-packages';
}

export interface PiSubagentRunnerProcess {
  readonly pid?: number;
  readonly killed: boolean;
  once(event: 'spawn', listener: () => void): this;
  once(event: 'error', listener: (error: Error) => void): this;
  once(
    event: 'exit' | 'close',
    listener: (code: number | null, signal: NodeJS.Signals | null) => void,
  ): this;
  kill(signal?: NodeJS.Signals): boolean;
}

export interface PiSubagentRunnerLaunchRequest {
  runId: string;
  runDir: string;
  runnerFile: string;
  configFile: string;
  cwd: string;
  env: NodeJS.ProcessEnv;
}

export interface AgentDeps {
  /** Opaque companion credential identity, freshly resolved at startup. No values enter the harness. */
  resolveSessionEnvironment?: (sessionId: string) => Promise<{ identity: string; assertCurrent?(): void } | undefined>;
  /** Cindy-only local Skill overrides. Freeze at native runtime startup; never apply to SSH. */
  getDisabledSkillPaths?: () => readonly string[];
  /** Optional host isolation for SkillHub discovery; native runtime discovery is unaffected. */
  scanLocalCustomizations?: (
    engine: 'claude-code' | 'codex' | 'pi',
    options: ListCustomizationsOptions,
  ) => Promise<ListCustomizationsResult>;
  /** Host-owned local Skills, loaded without writing user/project discovery directories. */
  getManagedSkills?: () => Promise<Array<AgentSkillCommand & {
    claudeCommandName: string;
  }>>;
  /** Refresh host-owned Skill links in the actual local Codex home before each thread, including reused servers. */
  prepareCodexSkills?: (codexHome: string) => Promise<void>;
  /** Optional low-I/O, provider-neutral turn change recorder supplied by the host. */
  turnChangeCapture?: TurnChangeCaptureHooks;
  auth: AuthAdapter;
  runtimeConfig: AgentRuntimeConfig;
  /**
   * Agent CLI 二进制绝对路径。host 在构造 agent 前必须已经把二进制 provisioned 好
   * (splash 阶段下载/解压); maker-core 自己不下载、不解析 manifest, 拿到就用。
   * 缺省 / 空串 → BaseAgent 构造期立即抛错, 不让 session 进半就绪状态。
   */
  binaryPath: string;
  logger: Logger;

  /**
   * Claude Code 专用:按本次会话的当前 provider、账号与父模型实时判定显式
   * Agent/Task 模型是否可路由。只有 `denied` 会形成产品硬阻断;目录未就绪、
   * 非权威快照或读取失败必须返回 `unknown`,不能把静态 catalog 当权限清单。
   */
  resolveClaudeSubagentModelAccess?: (context: {
    providerId?: string | null;
    parentModel: string;
    credentialMode?: AgentCredentialMode;
    model: string;
  }) => ClaudeSubagentModelAccessResult | Promise<ClaudeSubagentModelAccessResult>;

  /**
   * 解析某 session 的 cc-debug raw 文件落盘路径 (host 注入)。host 用 logger 的 logDir 拼
   * sessions/<sessionId>/cc-debug.raw.log 并 mkdir, 返回绝对路径; ClaudeCodeAgent 在开
   * debug 时把它作为 SDK debugFile 传给 cc 子进程, 让每个 session 的网络 debug 落到各自
   * 的 session 目录 (cc 外部进程只控制内容格式, 写哪个路径由我们决定)。
   * 缺省 / 返回 undefined → 回退到全局 process.env.XDT_CC_DEBUG_FILE。
   */
  resolveCcDebugFile?: (sessionId?: string) => string | undefined;
  /** Register one local debug writer; the returned disposer runs on process exit/error. */
  trackCcDebugFile?: (filePath: string, sessionId?: string) => () => void;

  /**
   * MCP server 提供者列表(host 注入)。agent 在 startSession 时按上下文挑选
   * provider,并转换成底层 SDK 接受的 MCP 配置。
   */
  mcpProviders?: McpProvider[];

  /**
   * pi 专用:pi 配置目录(PI_CODING_AGENT_DIR,内含 models.json / sessions/ 等)
   * 的解析器(host 注入)。文件落盘位置归 host 管;PiAgent 只在返回的目录里生成
   * 配置与会话文件。缺省 → 落系统临时目录(数据不保久,仅兜底)。
   * 其它 agent 不消费此字段。
   */
  resolvePiAgentHome?: (remoteHostId?: string | null) => string | undefined;
  /** Native user context root, separate from Cindy's models/auth runtime home. */
  resolvePiGlobalContextHome?: (remoteHostId?: string | null) => string | undefined;

  /**
   * Pi-only: advisory metadata for Cindy UI/command projection. This resolver
   * may inspect or snapshot known resources, but its result is never the launch
   * allowlist; resolvePiNativePackagePaths preserves Pi-native discovery.
   */
  resolvePiManagedPackageResources?: (options?: {
    snapshotRoot?: string;
    /** Redacted per-start correlation id for structured startup timing logs. */
    startupTraceId?: string;
  }) => Promise<{
    extensions: string[];
    skills: Array<{ path: string; name: string; description?: string }>;
    promptTemplates: string[];
    packageRoots: string[];
  }>;

  /**
   * Pi-only: installed local package roots that Pi must discover natively.
   * Cindy inspection metadata is advisory; a host analyzer that does not
   * understand a valid future package shape must not remove Pi functionality.
   */
  resolvePiNativePackagePaths?: () => Promise<PiNativePackageEntry[]>;

  /**
   * Pi-only: shared Host service for typed Pi management commands and legacy
   * package mutations. Core operations never invoke package retirement hooks.
   * Host routing binds an exact user/tool action but must not add a second
   * compatibility, fingerprint, or content-approval decision.
   */
  mutatePiManagedPackage?: (request: PiManagedPackageMutationRequest) => Promise<unknown>;

  /**
   * Pi-only: host callback after a package mutation receipt has been queued/sent.
   * Desktop retires idle instances and defers busy captured instances until
   * their product turn settles. A sent receipt is not proof Pi consumed it.
   * Native package success remains authoritative; deferred is not a failure.
   * publishOutcome returns the exact queued event so the Host can retain its
   * caller lease until Session dispatches that receipt (not a persistence ACK).
   * The event factory supplies a fresh complete receipt for eventual retirement
   * failure, without writing into the possibly closed caller queue.
   */
  onPiManagedPackageMutationSettled?: (
    callerSessionId: string | undefined,
    publishOutcome: (outcome: PiManagedPackageRuntimeConvergence) => AgentEvent,
    createRetirementFailureEvent: () => AgentEvent,
  ) => Promise<void>;

  /**
   * Pi-only: host-localized copy for extension dialogs and deterministic
   * mutation receipts. The same strings flow through Desktop and attached IM
   * interaction surfaces, so maker-core never hard-codes one UI language.
   */
  getPiExtensionUiStrings?: () => PiExtensionUiStrings;

  /**
   * Pi-only: start a durable Subagent runner through a host-supported Node
   * process boundary. Desktop injects Electron utilityProcess; maker-core never
   * assumes that the application executable can run JavaScript.
   */
  spawnPiSubagentRunner?: (
    request: PiSubagentRunnerLaunchRequest,
  ) => PiSubagentRunnerProcess;

  /**
   * Pi-only: resolve the immutable Cindy project-approval input for one new
   * runtime. The host owns identity canonicalization, approval audit/revocation,
   * and discovered-resource provenance. Missing/throwing resolvers fail closed.
   */
  resolvePiProjectTrustInput?: (ctx: {
    sessionId?: string;
    workingDir: string;
    remoteHostId?: string;
  }) => Promise<PiProjectTrustInputSnapshot | null>;

  /**
   * pi 专用钩子:把 mcpProviders 转成 pi 子进程可消费的 MCP 桥配置。
   *
   * 与 prepareCodexExtraSpawnConfig 同因:pi 是独立子进程,没法消费 in-process
   * JS McpServer instance —— host 起 streamable-HTTP bridge 把 instance 暴露到
   * localhost,PiAgent 把 {token, servers} 经 env(CINDY_PI_MCP_BRIDGE)交给
   * agentHome/extensions/cindy-bridge.ts,由它在 pi 内注册成工具。
   *
   * 缺省 / 返回 null → pi 跑纯内置工具(read/bash/edit/write),仍能基础对话。
   *
   * ctx(可选):本次 session 的身份上下文。host 用它在 bridge 上注册 sessionId +
   * 给该 session 的 server URL 打 `?session=` 路由,让 orca / 会话身份类工具能绑定
   * 到当前 pi 会话(否则回落 LEAD_NOT_SUPPORTED)。缺省 → 匿名注入(无 ctx 兜底)。
   */
  preparePiExtraSpawnConfig?: (
    providers: McpProvider[],
    ctx?: PiExtraSpawnConfigContext,
  ) => Promise<PiExtraSpawnConfig | null>;

  /**
   * Pi-only: authenticate a child process to the host's loopback model proxy.
   * PiAgent creates a high-entropy token per session, registers it before spawn,
   * and disposes the exact registration when startup fails or the session closes.
   */
  registerPiProxySession?: (
    sessionId: string,
    token: string,
    resolveProviderId: () => string | null,
    options?: { scope?: 'session' | 'subagent-route' },
  ) => (() => void) | void;

  /**
   * Pi-only: host-owned derivation for restart-stable remote proxy tokens.
   * Desktop persists the secret key; maker-core receives only the per-session
   * result. Missing hooks preserve the legacy process-stable fallback.
   */
  derivePiProxySessionToken?: (sessionId: string) => string;

  /**
   * BYOM:host 解析出当前会话可用的 pi **原生 provider**(用户自定义/本地模型)+ 需注入的
   * env(api keys)。PiAgent 把这些写进 models.json 的独立 provider 块(直连用户端点,不过
   * anthropic-compat 代理),并按 model→provider 路由 set_model / 初始 --provider。
   *
   * 缺省 / 返回空 → 只有网关 provider `cindy`(现状,行为不变)。keyless provider 的 key 可省。
   */
  resolvePiNativeProviders?: (
    ctx: {
      workingDir: string;
      remoteHostId?: string | null;
      providerId?: string | null;
      model: string;
      /** Local Pi binary frozen for this session; host catalog probes must use the same build. */
      runtimeBinaryPath?: string;
      /** Present only when restoring an existing Pi session; permits private compatibility ids. */
      resumeSessionId?: string;
      /** Preview must not prepare global skills or start a local model service. */
      purpose?: 'startup' | 'preview' | 'live-refresh';
      sessionId?: string;
    },
  ) => Promise<PiNativeProvidersResult | null>;

  /**
   * Pi-only:按实际 provider/model 路由解析运行时描述符。用于启动前校验已持久化 effort,
   * 以及恢复已 retired 模型时补齐当前 session 的私有 models.json;结果不得进入公开
   * availableModels 或授予新选择准入。
   */
  resolvePiRuntimeModelDescriptor?: (
    providerId: string | null | undefined,
    modelId: string,
  ) => ModelDescriptor | null;
  /** Current Pi-selectable catalog projection for live registry refreshes. */
  resolvePiRuntimeModels?: () => ModelDescriptor[];

  /**
   * Pi-only:为 `cindy` gateway 的 models.json 块按会话实际来源解析 provider-aware 描述符。
   * 与上面的续跑私有解析器分开,避免生成 gateway 配置放宽 retired/disabled
   * 准入或改变新会话的私有解析时机。缺省时 Pi 保留 flat descriptor fallback。
   */
  resolvePiGatewayModelDescriptor?: (
    providerId: string | null | undefined,
    modelId: string,
  ) => ModelDescriptor | null;

  /**
   * Pi-only:按 Cindy Server > 执行环境本地 Pi 目录 > Gateway hint 解析 `cindy` API。
   * `remote` 让 host 在无法探测实际远端 Pi 时跳过本机目录,禁止跨二进制借 metadata。
   * null = 已知 Gateway Pi 模型但无法安全解析;undefined = 不属于 Gateway Pi 目录。
   */
  resolvePiGatewayModelApi?: (
    providerId: string | null | undefined,
    modelId: string,
    context?: { remote: boolean; runtimeBinaryPath?: string },
  ) => PiNativeApi | null | undefined;

  /** Host-resolved model-specific PI compatibility metadata for the Gateway block. */
  resolvePiGatewayModelSpec?: (
    providerId: string | null | undefined,
    modelId: string,
    context?: { remote: boolean; runtimeBinaryPath?: string },
  ) => PiGatewayModelSpec | null | undefined;

  /** Execution-local cache compatibility store; never copy local records to SSH. */
  resolvePiNativeCompatStorePath?: (remoteHostId?: string | null) => string;

  /** Legacy host recovery snapshot; native Pi applies learning at final payload time. */
  resolvePiNativeCompatOverride?: (
    providerId: string,
    modelId: string,
    routeKey?: string,
  ) => Record<string, unknown> | undefined;

  /**
   * Host-provided capability descriptor additions.
   *
   * This is append-only: additions with ids already present in the agent's built-in
   * capability lists are ignored. Use a future explicit override path if a host
   * needs to replace built-in behavior.
   */
  capabilityAdditions?: AgentCapabilityAdditions;

  /**
   * Pi-only:视觉桥后端 env(层 C)。host 解析视觉桥配置(主/fallback 视觉后端 →
   * OpenAI 兼容端点 + model + key)后返回键值对,PiAgent 注入 pi 子进程 spawnEnv,
   * cindy-bridge 的 vision 工具读取。缺省 = 不注入(视觉桥工具不可用,零干扰)。
   * model 参数供 host 按 session 模型判定是否命中视觉桥目标模型——未命中返回 null,
   * 保证非目标/已有视觉能力的 Pi 模型不注册 vision 工具、不改变工具面(零干扰)。
   * sessionId 供需要上游会话头的后端(OpenCode Go)确定性派生头值:spawn env 必须
   * 同 session 重建逐字节稳定(pi-harness §4.10),不得用随机值。
   * 返回的键应纳入 piSecretEnvNames 剥离面(host 实现应把含 key 的键名一并声明)。
   */
  resolvePiVisionBridgeEnv?: (model: string, sessionId?: string) => Record<string, string> | null;

  /**
   * Host-owned arbitration for capabilities that overlap with harness-native
   * plugins, skills, MCP servers, apps, or tools.
   *
   * Each harness adapter translates the neutral directives it understands and
   * leaves unsupported directives untouched. Keeping this out of AgentKind
   * conditionals lets a future harness add one adapter without changing the
   * product policy.
   */
  capabilityRouting?: CapabilityRoutingPolicy;

  /**
   * Resolve capability arbitration once for a new session. Use this for
   * workspace-scoped sources whose effective state is already frozen into
   * vendorOptions by the host. Static capabilityRouting remains the fallback.
   */
  resolveCapabilityRouting?: (ctx: {
    workingDir: string;
    remoteHostId?: string | null;
    vendorOptions: Readonly<Record<string, unknown>>;
    /** Frozen fact: the concrete app-server was provisioned with the companion. */
    codexBrowserUseProvisioned: boolean;
    /** Exact Chrome plugin version bound to that host, when provisioned. */
    codexBrowserUseVersion: string | null;
    /** Post-start readiness check, invoked only when this session needs the fallback. */
    ensureCodexBrowserUseReady: () => Promise<boolean>;
  }) => CapabilityRoutingPolicy | undefined | Promise<CapabilityRoutingPolicy | undefined>;

  /** Host working budget for this route (user override, optionally catalog default).
   * Missing means the adapter uses its route/native defaults. */
  resolveModelContextLimit?: (
    providerId: string | null | undefined,
    modelId: string,
  ) => number | null;

  /** Host-resolved model percentage. Hosts without a policy retain their runtime defaults. */
  resolveModelCompactionPct?: (
    providerId: string | null | undefined,
    modelId: string,
  ) => number | null;

  /** Resolve native metadata using the exact app-server config and usage report. */
  resolveCodexContextWindowInfo?: (
    modelId: string,
    config: Record<string, unknown>,
    reportedUsableWindow: number | null,
    codexHome?: string,
  ) => Promise<CodexContextWindowInfo | null>;

  /** Private native catalog with executable edit tools removed for a host-owned conversation. */
  prepareCodexHostToolCatalog?: (modelId: string, contextWindow: number | null) => Promise<string>;

  /**
   * Resolve verified catalog capacity for a concrete (provider, model) route.
   * Return null for unknown, ambiguous, or derived fallback metadata. Do not use
   * the provider-deduplicated capabilities.availableModels table for this lookup.
   * Codex uses this only until native reports its effective usable window;
   * catalog metadata must not overwrite an observed native capacity.
   */
  resolveVerifiedContextWindow?: (
    providerId: string | null | undefined,
    modelId: string,
  ) => number | null;

  /**
   * Resolve the declared efforts of a concrete (provider, model) route, used to
   * narrow an outgoing effort to what that route accepts. Return null for unknown
   * or ambiguous routes. Same-ID models from different providers can declare
   * different efforts, so do not use capabilities.availableModels for this.
   */
  resolveModelEfforts?: (
    providerId: string | null | undefined,
    modelId: string,
  ) => readonly Effort[] | null;

  /** Local disk-auth policy, independent of the actual Provider credential mode. */
  resolveCodexLocalAuthPolicy?: (
    providerId: string | null | undefined,
    modelId: string,
    signal?: AbortSignal,
  ) => CodexLocalAuthPolicyResolution | Promise<CodexLocalAuthPolicyResolution>;

  /**
   * Per-model requested context window (user override first, explicit provider default second).
   * A one-session native catalog permits this window without changing sibling routes.
   * null preserves native defaults. A changed value requires a handle rebuild, preserving rollout.
   */
  resolveCodexThreadContextWindow?: (
    providerId: string | null | undefined,
    modelId: string,
  ) => number | null | Promise<number | null>;

  /**
   * Agent 起 session 时追加到 system prompt 末尾的字符串(host 注入)。
   * **本轮一阶段不消费**,仅占位。后续接通后 desktop 可以传项目级 prompt。
   */
  // (host-product layer removed — desktop 端只通过 runtimeConfig.systemPrompt
  // 走 host runtime 一段;不再单独维护 deps.appendSystemPrompt 注入路径。)

  /**
   * Codex 专用钩子:把 mcpProviders 转成 codex spawn 时用的 extraArgs (-c flags)
   * + extraEnv (bearer token)。CodexAgent.getHost() 调用,desktop host 实现。
   *
   * 为什么 codex 单独走一条路 (而不是复用 mcpProviders.toClaudeSdkConfig):
   * codex 是独立 Rust 子进程,没法消费 in-process JS McpServer instance — 必须
   * 通过 streamable-HTTP bridge 把 instance 暴露到 localhost,再用 codex 的
   * `-c mcp_servers.x.url=...` 注入。这层桥接逻辑在 desktop host (用 Electron
   * 内置 http 模块 + @modelcontextprotocol/sdk 的 StreamableHTTPServerTransport),
   * 不属于 maker-core 范畴。
   *
   * 缺省 / providers 为空 → CodexAgent 不传 extraArgs/extraEnv,跑没 lizi MCP 的
   * codex (仍能基础对话)。
   */
  prepareCodexExtraSpawnConfig?: (
    providers: McpProvider[],
    ctx: {
      providerId?: string;
      codexHome?: string;
      /** Actual native config/history root; credential/catalog preparation keeps codexHome above. */
      runtimeCodexHome?: string;
      accountHostKey?: string;
      remoteHostId?: string;
      credentialMode?: AgentCredentialMode;
      /** Frozen disk OAuth policy; independent of the actual Provider credential. */
      localAuthPolicy?: 'isolated' | 'legacy-shared';
      hostScopeKey?: string;
      /** Original session request when the shared host was upgraded to a credential superset. */
      requestedCredentialMode?: AgentCredentialMode;
      /** Marks app-server work that must not share the normal local task host. */
      hostPurpose?: 'control-plane' | 'review' | 'custom-context';
      /**
       * Control-plane host that only serves native thread storage RPCs
       * (thread/read, thread/archive, thread/unarchive) and never runs a turn,
       * so it must not start the Cindy MCP bridge.
       */
      nativeStorageOnly?: boolean;
      /** Wire model id whose native catalog entry must allow the requested window. */
      customContextModel?: string;
      /** Requested context window for a one-session custom-context host. */
      customContextWindow?: number;
      /** Budget route, distinct from the host's OAuth account identity. */
      customContextProviderId?: string | null;
      /** Unique app-server Host-generation identity used to scope custom-context resources. */
      customContextHostKey?: string;
      /**
       * 受邀者(供应商分享)任务的 app-server,值是分享给它的供应商。host 不开智能 Subagent
       * 调配、不暴露 spawn 的模型覆写,自定义供应商路由与按模型分流也只保留这个供应商。
       */
      deviceHostedGuestProviderId?: string;
      /** Owning guest session for model authorization on requests without thread headers. */
      deviceHostedGuestSessionId?: string;
      deviceHostedGuestModelIds?: readonly string[];
    },
  ) => Promise<CodexExtraSpawnConfig>;

  /** Recomputes the desired local Subagent routing identity before reusing a host. */
  resolveCodexSubagentRoutingSignature?: (
    providers: McpProvider[],
    ctx: {
      providerId?: string;
      credentialMode?: AgentCredentialMode;
      hostPurpose?: 'control-plane' | 'review' | 'custom-context';
      /** 受邀者任务的 app-server 不开智能 Subagent 调配(见 prepareCodexExtraSpawnConfig)。 */
      deviceHostedGuestProviderId?: string;
    },
  ) => Promise<string>;

  /**
   * Codex-only host policy: disable local app-server plugin runtimes even when
   * dynamic spawn configuration degrades after a non-fatal preparation error.
   * Remote transports own their runtime and ignore this local policy.
   */
  disableCodexPluginRuntime?: boolean;

  /**
   * Codex 专用:登记本机 stdio app-server 的 PID 与职责。
   * 返回 disposer 时会跟随 transport close 调用;远端 SSH transport 不触发。
   */
  registerLocalCodexAppServerProcess?: (
    info: CodexAppServerProcessRegistration,
  ) => void | (() => void);

  /**
   * Register a locally spawned Claude/Pi root process with the host. The returned
   * disposer follows that exact process generation; remote transports never call it.
   */
  registerLocalAgentProcess?: (
    info: LocalAgentProcessRegistration,
  ) => void | (() => void);

  /**
   * Codex 本地 shared app-server 凭证形态要切换前的宿主协调点。
   *
   * maker-core 不知道 desktop 的 active session / worktree / attachment 生命周期;
   * 这里给宿主先 soft-close 或拒绝 busy session 的机会。回调返回后若旧 host 仍有
   * active subscription,CodexAgent 会 fail closed,不会静默 retire 正在被使用的 host。
   */
  prepareCodexLocalCredentialModeSwitch?: (
    ctx: CodexLocalCredentialModeSwitchContext,
  ) => Promise<void>;

  /**
   * Codex 专用:本地 app-server `model/list` 返回完整分页快照后通知宿主。
   * maker-core 只负责拿官方运行时清单;如何映射、存入产品目录及广播由 host 决定。
   * 远端 SSH host 不触发,避免把远端账号的模型清单覆盖本机账号目录。
   */
  onCodexLocalModelsListed?: (
    models: readonly CodexModelListItem[],
    providerId?: string,
  ) => void | Promise<void>;

  /** Host-confirmed native account identity; ordinary custom API providers return false. */
  isCodexAccountProvider?: (providerId?: string | null) => boolean;
  /** Retire each local task's writer on close so native history can change accounts. */
  isolateCodexAccountSessions?: boolean;

  /**
   * Host-owned lightweight reviewer for routes without a healthy vendor-native
   * reviewer. The host must use this session's selected provider + model and pass
   * only the request supplied here; null/throw is treated as a silent block.
   */
  reviewAutoPermissionAction?: AutoReviewDelegate;

  /**
   * Claude Code 工具循环疑似命中时的辅助模型复核入口(与 MakerDeps.toolLoopReviewer
   * 同一实现)。缺省放行疑似,保留最终上限。
   */
  toolLoopReviewer?: import('./shared/tool-loop-review.js').ToolLoopReviewer;

  /** Scope tools/list during native startup, before a real thread id exists. Never authorizes tools/call. */
  withCodexMcpDiscoveryContext?: <T>(
    args: Pick<CodexMcpThreadContextArgs, 'sessionId' | 'sessionInstanceId' | 'workingDir' | 'vendorOptions' | 'remoteHostId'>,
    run: () => Promise<T>,
  ) => Promise<T>;
  /**
   * Codex-only: bind app-server thread ids back to xdt-maker session context
   * for host-owned HTTP MCP bridges. Missing hooks keep the old no-session
   * behavior; implementations should be in-memory and best-effort.
   */
  /** Synchronous local policy registration; no RPC or IO on a send. Returns owner-scoped cleanup. */
  registerCodexTextOnlyPolicy?: (threadId: string, disabled: () => boolean) => () => void;
  registerCodexMcpThreadContext?: (args: CodexMcpThreadContextArgs) => void;
  unregisterCodexMcpThreadContext?: (
    threadId: string,
    expectedSessionInstanceId?: string,
  ) => void;

  /**
   * Codex 专用:为远端机器构造一个 codex app-server transport。
   *
   * 当 session 标了 remoteHostId (新建 maker 时选了远端目录), CodexAgent 会调这个
   * 钩子拿一个连远端 daemon 的 transport (替代本地 spawn)。host 层实现 — 通常用
   * `createSshDaemonTransport({ remoteHost: pool.get(remoteHostId), ... })`。
   *
   * 返回的 transport 必须实现 codex app-server 的 NDJSON 协议 transport 接口
   * (writeLine / onLine / onClose / close)。CodexAgent 拿到就当 stdio 用, 完全
   * 不感知背后是 SSH + WebSocket 桥接。
   *
   * 缺省 / undefined → 不支持远端, 任何带 remoteHostId 的 session 会被拒。
   */
  getRemoteCodexTransport?: (remoteHostId: string) => import('./codex/app-server/transport.js').Transport;

  /**
   * Pi 专用:为远端机器构造一个 pi `--mode rpc` transport。
   *
   * 当 session 标了 remoteHostId, PiAgent 会调这个钩子拿一个连远端 pi 进程的
   * transport (替代本地 spawn)。host 层实现 — 通常用 `RemoteHost.execStream`
   * 在远端跑 `pi --mode rpc ...` 并把 stdin/stdout 拽回本地 (SshPiTransport)。
   *
   * 返回的 transport 必须实现 PiTransport 接口 (writeLine / onLine / onClose /
   * close)。PiAgent 拿到就当 stdio 用, 完全不感知背后是 SSH 桥接。
   *
   * 缺省 / undefined → 不支持远端 pi, 任何带 remoteHostId 的 pi session 会被拒。
   */
  getRemotePiTransport?: (
    remoteHostId: string,
    opts: {
      /** 本地 pi 二进制路径(远端场景不可用,host 应改用它 resolve 的远端路径)。 */
      binaryPath: string;
      /** 远端 pi 二进制绝对路径(host 已 probe;plan-mode 扩展 / subagent spawn 用它)。 */
      remoteBinaryPath: string;
      args: string[];
      cwd: string;
      env: Record<string, string | undefined>;
      logger: AgentDeps['logger'];
      /** maker sessionId(daemon 模式用作远端 daemon 的 session key)。 */
      sessionId?: string | null;
      /** Host-owned loopback providers that must be reverse-forwarded before remote Pi starts. */
      hostProxyForwards?: ReadonlyArray<{
        localUrl: string;
        remotePort: number;
      }>;
    },
  ) => import('./pi/transport.js').PiTransport | Promise<import('./pi/transport.js').PiTransport>;

  /**
   * Pi 专用:解析远端 pi 二进制绝对路径(probe 远端安装)。缺省 → 远端会话回落
   * 本地 binaryPath(错误语义,host 应在 getRemotePiTransport 之前 resolve)。
   */
  resolveRemotePiBinaryPath?: (remoteHostId: string) => Promise<string>;

  /**
   * Pi 专用:远端会话是否跳过 MCP bridge 注入。Phase 1 远端不桥 in-process MCP
   * (cindy_orca / orca_worker_bridge / cindy_memory 的 loopback URL 远端够不到),
   * host 据此 gate 掉 preparePiExtraSpawnConfig 的 bridge 部分;外部 HTTP MCP
   * 直连不受影响。缺省 false = 本地行为不变。
   */
  remotePiSkipMcpBridge?: (remoteHostId: string) => boolean;

  /**
   * Pi 专用:远端会话的 agent-proxy env(HTTPS_PROXY/HTTP_PROXY/NO_PROXY 指向本地
   * 代理经 SSH remote-forward 隧道)。host 装配;缺省 null = 远端不走本地代理。
   */
  getRemotePiAgentProxyEnv?: (remoteHostId: string) => Promise<Record<string, string> | null>;

  /**
   * Pi 专用:远端 agentHome 文件操作原语。
   *
   * 本地 pi 会话的 models.json / cindy-bridge 扩展 / perm 权限档 / subagent 路由快照
   * / 受管 rg 都写在本地 agentHome(父子进程共享文件系统)。远端会话里这些文件必须写
   * 到**远端机器**(pi 进程在远端读), host 侧经 SSH 通道实现这套 fs 原语(remote-file-service
   * 或 ssh heredoc)。缺省 → 远端 pi 会话的 agentHome 文件操作走本地 fs(错误语义,由
   * host 在 getRemotePiTransport 阶段前置校验,或按 fail-closed 处理)。
   */
  getRemotePiFileOps?: (
    remoteHostId: string,
  ) => PiRemoteFileOps;

  /** Read-only filesystem truth used by remote Skill catalog discovery. */
  getRemoteAgentFileOps?: (
    remoteHostId: string,
  ) => RemoteAgentFileOps;


  /**
   * Codex 专用:读**这个 thread 本次实际出口**的出站代理路径判定,用于把「后端不可达」
   * 的通用猜测换成实测事实(走了哪个代理 / 确认直连 / 配了但用不了 / 判定没问出来)。
   *
   * 必须传 threadId:codex 的出口随会话选定的 provider 变(订阅直连、网关、xAI、
   * 自定义供应商),host 侧要靠它定位本次请求真正打的上游。拿不到对应记录时**必须**
   * 返回 null(例:本次请求没经过 loopback proxy),而不是回退到「最近一条」——
   * 报一条本次没走过的路径比不报更糟。
   *
   * 只在**本地** session 的 retry-loop 终局升级时读一次,不进任何热路径;实现必须是
   * 同步、只读、不抛的内存快照读取(desktop 侧 = outbound-proxy-resolver 的快照 +
   * codex-proxy-host 的 thread→上游映射)。返回的 proxy 字段必须已脱敏 —— 它会进
   * 用户可见的错误消息。
   *
   * 缺省 / undefined / 返回 null → 保留原有的通用排查文案,不降级任何行为。
   */
  getOutboundPathFact?: (
    ctx: { threadId?: string },
  ) => import('./codex/retry-escalation.js').OutboundPathFact | null;

  /**
   * Maker Memory 顶层单例 (host 注入). 当 runtimeConfig.makerMemoryEnabled === true 时,
   * agent.startSession 会从这里拉当前 workdir 的 MEMORY.md 索引拼进 system prompt;
   * cindy_memory MCP server 也通过 host 端的 createDesktopMcpProviders({ memory: { getManager } })
   * 拿到同一个引用。
   *
   * 缺省 / undefined → 即使 runtimeConfig.makerMemoryEnabled=true 也不注入 (host 没接好 manager,
   * 视为禁用), agent 走原 system prompt 拼接路径。
   */
  makerMemory?: MakerMemoryManager;

  /**
   * 智能通讯录「本会话有效状态」(host 注入)。决定注入哪段 contacts prompt
   * (enabled = 使用规范, disabled = 可选功能告示, unavailable = 不注入, 语义见
   * contacts/system-prompt.ts 的 ContactsPromptState)。host 必须按**有效策略**
   * 计算, 不能只读全局开关: desktop 侧 = 全局开关 ∧ PluginRegistry 的
   * 工作区/用户覆盖(workingDir 传入即为此), codex 侧还要与实际应用到 running
   * app-server 的 spawn 快照对齐(失效失败时 stale 配置里没有新工具面)。
   * 求值时机与 MCP 工具注册对齐, 保证 prompt 状态与工具可用性不分叉:
   *  - claude-code: 每次 buildQuery(含 rewind/fresh 重建)与 buildMcpServers
   *    同点求值, enabled 还会与本次 build 实际注册的 server 集合取交;
   *    单次 build 内恒定, 前缀缓存不受影响。
   *  - codex: session 启动求值一次(MCP flags 冻结在 spawn 配置)。
   * remote 会话两端都不注入(cindy_contacts 不随远端转发)。
   *
   * 缺省 / undefined → 两段都不注入 (host 未接线, 与改造前行为一致)。
   */
  getContactsPromptState?: (ctx: { workingDir?: string }) => ContactsPromptState;

  /** Session 装配时求值一次的插件花名册 system/developer 段;空清单返回空串。 */
  getGhostRosterPrompt?: (ctx: { workingDir?: string }) => string;

  /**
   * Host MCP risk classification shared by Claude Code, Codex and Pi.
   * `auto-approve` permits a trusted shortcut. In Auto, both other grades go
   * through the AI reviewer with the actual tool identity and arguments;
   * only its ask verdict (including unavailable fallback) opens a user card.
   * Outside Auto, prompt retains normal UI/session grants and prompt-each-time
   * requires a one-time decision without persisting a server/tool grant.
   * Missing or failed classifiers cannot grant a trusted shortcut.
   */
  getMcpToolApprovalPolicy?: (context: McpToolApprovalContext) => McpToolApprovalPolicy;

  /**
   * Codex 专用钩子:resume / fork 外部本地 thread 前由 host 准备底层 session state。
   *
   * maker-core 只知道 "即将读取某个 Codex threadId" 这个生命周期点;
   * 具体如何从本机 Codex CLI / App 的 CODEX_HOME 发现并同步 state_*.sqlite / rollout
   * 文件,是 desktop host 的文件系统适配职责。
   *
   * 缺省 / no-op → 行为与改动前一致。
   */
  prepareCodexResumeSession?: (threadId: string, context?: { codexHome: string; providerId?: string }) => Promise<string | void>;
  recordCodexThreadLocation?: (threadId: string, codexHome: string, rolloutPath?: string) => Promise<void>;
  /** readOnly locates existing storage without invoking resume recovery or copying history. */
  resolveCodexThreadStorage?: (threadId: string, options?: { readOnly?: boolean }) => Promise<{ historyHome: string; sqliteHome: string; rolloutPath?: string } | undefined>;
  /** Freeze the owner/account scope before async host startup; never expose tokens to the renderer. */
  createCodexAuthTokenReader?: (providerId?: string) => () => Promise<import('./codex/app-server/external-auth.js').CodexChatgptTokens>;

  /**
   * Codex 专用:把已拼好的产品级 system prompt 同步登记到 host 的 codex proxy registry。
   *
   * 约束:
   *   - 同步、内存 Map 写入,不可做 IO / 网络
   *   - 不可失败;若实现抛错,CodexAgent 会中止当前 start/resume,避免 thread 已创建但
   *     prompt 既没进 developerInstructions、也没进 proxy registry 的裸奔状态
   *
   * 缺省 / undefined → CodexAgent 不启用 proxy prompt 通道,继续走老 developerInstructions。
   */
  registerCodexSystemPromptForThread?: (args: {
    sessionId: string;
    threadId: string;
    text: string;
    subagentRoute?: {
      providerId: string;
      catalogModel: string;
      reasoningEffort?: ReasoningEffort | null;
    };
    smartSubagentRoutes?: Array<{
      providerId: string;
      catalogModel: string;
      reasoningEffort?: ReasoningEffort | null;
    }>;
  }) => void;

  /** Desktop proxy observation of the model actually sent for one Codex child thread. */
  getCodexSubagentIdentity?: (args: { childThreadId: string }) => {
    model: string;
    reasoningEffort?: string;
  } | undefined;

  /**
   * Codex 专用:WS turn 命中仅 HTTP proxy 能处理的请求体恢复错误时,通知宿主把
   * 该 thread 的后续 WS upgrade 导回 HTTP。
   *
   * 宿主负责按自己的 recovery rules 识别错误并登记 transport policy;返回稳定
   * reason 表示已登记,null 表示不匹配。调用必须同步、纯内存且不得抛错。
   * maker-core 只在零产出 turn 上据此自动重投一次,不解析供应商错误协议。
   */
  armCodexHttpRecovery?: (args: {
    sessionId: string;
    threadId: string;
    message: string;
    additionalDetails?: string | null;
  }) => string | null;

  /**
   * Codex 专用:app-server 创建子 Agent thread 后,把明确的父子 thread 关系同步给宿主。
   *
   * 子 thread 会独立发起 Responses 请求,但仍属于父业务 session;宿主据此继承
   * provider / bridge 路由和 proxy prompt。该钩子必须是同步内存操作,确保在子
   * thread 首个网络请求前完成登记。
   */
  registerCodexChildThreadForParent?: (args: {
     parentThreadId: string;
     childThreadId: string;
   }) => void;

  /**
   * Claude 专用: host 明确认定可无提示执行的只读工具名, 透传到 SDK
   * `options.allowedTools`。maker-core 不维护任何产品工具名, 也不做 wildcard /
   * 前缀推断; 远端 cc-manager 分支必须透传同一份列表, 避免本地与 SSH 会话权限
   * 语义分叉。
   *
   * 缺省 / undefined → 不传 allowedTools, 行为与改动前一致。Codex 不消费此字段。
   */
  claudeAllowedTools?: readonly string[];

  /**
   * Claude 专用 SDK hook 注入点。host 在构造 ClaudeCodeAgent 时按 HookEvent
   * (PreToolUse / PostToolUse / UserPromptSubmit / SessionStart / ...) 注册一组
   * in-process JS 回调; ClaudeCodeAgent.startSession 透传给 SDK options.hooks。
   *
   * 设计说明:
   *  - 这里只是 host hook 注入点;图片 read、Bash 并发等产品逻辑都在 host 层。
   *    maker-core 的 Claude adapter 会在必要时把窄范围协议闸门(例如能力来源路由)
   *    放在这些 host hooks 之前。
   *  - 类型直接复用 Claude SDK 的 HookCallbackMatcher (含 matcher / hooks / timeout),
   *    host 直接 import @anthropic-ai/claude-agent-sdk 的类型即可, 与 mcpProviders
   *    用 McpServerConfig 同模式。
   *  - 与 canUseTool 的关系: PreToolUse 比 canUseTool 更早, 返回 'allow' / 'deny'
   *    会跳过 canUseTool; 返回 'defer' 或不给 permissionDecision 才继续走原 permission
   *    流程。host 注入时要先想清楚拦截顺序, 避免打穿 Orca / 协同模式那套 permission UI。
   *  - 闭包语义: hooks 在 startSession 时被传给 SDK 一次, 之后无法再换 (与 vendorOptions
   *    同坑). 如果要做运行时可替换, host 应自己包一层 `(input) => current(input)` 走可变引用。
   *
   * 缺省 / undefined → 不传 hooks 字段, 行为与改动前一致。
   * Codex 不消费此字段。
   */
  claudeHooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;

  /** Host bridge for repairing Claude Code subagent usage when provider usage is zero. */
  registerClaudeSubagentTask?: (task: ClaudeSubagentTaskRegistration) => void;
  getClaudeSubagentTaskUsage?: (taskId: string) => ClaudeSubagentTaskUsage | undefined;

  /**
   * Claude Code 专用:为远端机器构造一个 SDK `Query` (实际是 cc-mgr daemon 端
   * SDK Query 的 RPC wrapper, 在 maker-core 看就是 Query interface)。
   *
   * 跟 `getRemoteCodexTransport` 同模式但走更高抽象:codex 是字节级 transport
   * 桥, cc remote 是 NDJSON RPC + RemoteQuery 包装 (因 cc 没 daemon 协议, 我们
   * 自造 manager + SDK wrap, 见 packages/maker-cc-manager)。
   *
   * 当 session 标了 remoteHostId 且 host 注入了这个 factory, ClaudeCodeAgent
   * 在 buildQuery 时会调它拿一个连远端 cc-mgr daemon 的 Query 实例 (替代本地
   * `sdkQuery` 起 cc subprocess); host 层实现里通常 unique key=remoteHostId
   * 复用同一个 daemon (一 daemon 多 session)。
   *
   * 返回的 Query 必须满足 SDK Query interface 的子集 — ClaudeCodeAgent 实际只
   * 调:`for await of` (event 流) / `interrupt` / `setModel` /
   * `setPermissionMode` / `applyFlagSettings` / `stopTask`(可选 — 缺失时用户
   * Stop 退化为 interrupt-only,后台 wake 任务不被连带停止)。`RemoteQuery`
   * (`@cindy/maker-cc-manager`) 全部已实现, host 直接 cast as Query 即可。
   *
   * **MVP 不支持**:rewind / fork 等需要 SDK 内部重建 Query 的操作 — 远端
   * cc-mgr daemon 协议没暴露, ClaudeCodeAgent 撞到会 throw。
   *
   * 缺省 / undefined → 不支持远端 cc, 任何带 remoteHostId 的 cc session 会被拒。
   * Codex 不消费此字段 (Codex 走 `getRemoteCodexTransport`)。
   */
  remoteCcQueryFactory?: (opts: {
    remoteHostId: string;
    /** Inject the narrow helper transport for a Bot runtime. */
    botSession?: boolean;
    sessionId: string;
    /** 当前 Maker Session 实例代号;只在宿主 MCP 身份上下文中流转。 */
    sessionInstanceId?: string;
    /**
     * 给 cc-mgr daemon 起 SDK Query 时用的全部 options
     * (cwd / model / env / mcpServers / systemPrompt / additionalDirectories /
     *  permissionMode / extraOptions)。结构参见
     *  `import('@cindy/maker-cc-manager').QueryStartParams`。
     *
     * 用 `unknown` 是为了避免 maker-core 顶层 import @cindy/maker-cc-manager
     * (那是 host-only 包, maker-core 不该耦合)。host 层实现时 cast 进去即可。
     */
    startParams: Record<string, unknown>;
    /**
     * session 自己的 vendorOptions (startSession 入参透传)。远端 cc 的协同
     * MCP ctx 必须以它为准:worker 首次创建时 DB 的 orca 标记/markOrcaRole
     * 发生在 bootstrap 之后, host 侧现场查 DB 会拿到空角色 (fail-closed
     * "not an orca worker session");opts 里的 vendorOptions 才是创建方
     * 显式声明的身份。host 实现可在缺失时回退 DB 合成。
     */
    vendorOptions?: Record<string, unknown>;
    /**
     * Callback for daemon-side approval requests (canUseTool / AskUserQuestion /
     * ExitPlanMode). Host layer registers this on the RPC client; maker-core wires
     * it to the session's interactionResolver.
     *
     * Params/Result shapes follow `@cindy/maker-cc-manager` ApprovalRequestParams/Result
     * but typed as unknown here to avoid cross-package dependency.
     */
    onApprovalRequest?: (params: unknown) => Promise<unknown>;
    /**
     * 远端 daemon 的 PreToolUse 通过反向 RPC 调回同一个实时模型准入 resolver。
     * Params/Result 采用 maker-cc-manager 的同名协议形状,但保持 unknown 以免耦包。
     */
    onSubagentModelAccessRequest?: (params: unknown) => Promise<unknown>;
    /**
     * 本 session 的 Maker Memory 注入开关 (startSession 时已按 per-session flag
     * + manager 就绪归一)。host 据此决定是否把 cindy_memory 以 http 形态经
     * bridge 注进远端 startParams.mcpServers — prompt 段 (rules + MEMORY.md
     * index) 由 maker-core 自己拼, 两侧必须同源同值, 否则模型被 rules 引导去
     * 调不存在的工具。缺省视为 false。
     */
    makerMemoryEnabled?: boolean;
    /**
     * 本 session 的 Maker Memory 作用域键 (startSession opts.makerMemoryScopeKey)。
     *
     * host 必须把它注册到远端 bridge 的 per-session ctx 上 —— cindy_memory 的
     * withStore 优先用 ctx.memoryScopeKey 定位 store, 缺失时回落
     * buildMemoryScopeKey(workingDir, remoteHostId)。Cindy Bot 会话的 prompt
     * 索引来自 `bot:<botId>` store, 丢掉这个键就会「读伙伴记忆、写远端项目记忆」。
     */
    makerMemoryScopeKey?: string;
    /**
     * Callback for daemon-side subscription OAuth refresh (remote cc hit 401
     * mid-turn). ClaudeCodeAgent wires it to auth.getFreshSubscriptionToken —
     * only when the remote env actually carries CLAUDE_CODE_OAUTH_TOKEN
     * (native OAuth route), never for gateway-key sessions.
     *
     * Params/Result follow `@cindy/maker-cc-manager` OAuthRefreshParams/Result
     * ({ sessionId } → { token: string | null }), typed as unknown
     * to avoid cross-package dependency.
     */
    onOAuthRefresh?: (params: unknown) => Promise<unknown>;
  }) => Promise<Query>;

  /**
   * 远端 Claude Code 会话的「路由 materialization」(host 注入)。
   *
   * 背景:本地会话按模型在「订阅直连 / 网关 / 自定义供应商」之间分流的逻辑活在本机
   * loopback compat-proxy 里(按请求覆盖 upstream + 鉴权头)。远端 cc-mgr 会话够不到这个
   * proxy,因此必须把「该会话应走的上游 + 鉴权 + 定制请求头」在 spawn 前解析好,直接烤进
   * 远端 cc 子进程的 env(ANTHROPIC_BASE_URL / ANTHROPIC_API_KEY | ANTHROPIC_AUTH_TOKEN /
   * ANTHROPIC_CUSTOM_HEADERS / CLAUDE_CODE_OAUTH_TOKEN…)。host 层用当前生效目录的
   * RoutingDescriptor + 本地凭证读取器解析(catalog / safeStorage 都在 host 侧),
   * maker-core 只负责把结果覆盖进远端 env。
   *
   * 返回值:
   *   - 非 null:用 `endpoint` 作 ANTHROPIC_BASE_URL,`env` 覆盖鉴权 / 定制头字段
   *     (native OAuth 订阅、自定义 Claude Code 供应商都走这条)。
   *   - null:该会话的有效路由就是 XD 网关(或默认回落网关)—— ClaudeCodeAgent 把远端
   *     credentialMode 回落 'gateway-key',env 走网关 key + remoteEndpoint,与升级前
   *     「远端恒用网关」字节级一致。**不回落会出现凭证形态漂移**:getAuthEnv 按本地
   *     fallback 注入订阅 token / 占位 key,却打网关 endpoint(泄漏或 401)。
   *   - throw:显式选定的供应商在远端无法表达(如声明了自定义 requestPath / modelIdRewrite,
   *     cc env 无对应旋钮),host 抛出明确错误,由 startSession 透传给 renderer,不静默错路由。
   *
   * 缺省 / undefined(旧 host)→ ClaudeCodeAgent 同样回落 'gateway-key',保持既有
   * 「远端恒用网关」行为。
   */
  resolveRemoteClaudeRoute?: (opts: {
    sessionId?: string;
    providerId?: string | null;
    model: string;
  }) => Promise<RemoteClaudeRoute | null>;
}

/**
 * 远端 Claude Code 会话解析出的上游 + 鉴权 env(见 AgentDeps.resolveRemoteClaudeRoute)。
 */
export interface RemoteClaudeRoute {
  /** 远端 cc 子进程 ANTHROPIC_BASE_URL 的最终取值(供应商真上游,绝不是本机 loopback)。 */
  endpoint: string;
  /**
   * 覆盖进远端 env 的鉴权 / 定制头字段。恰好携带一个鉴权门(ANTHROPIC_API_KEY 或
   * ANTHROPIC_AUTH_TOKEN 或 CLAUDE_CODE_OAUTH_TOKEN),其余需要下发的请求头(含另一个
   * 鉴权头、供应商定制头)统一放进 ANTHROPIC_CUSTOM_HEADERS —— 避免同时设两个鉴权 env
   * 触发 cc 的 shouldDisableAuth(见 claude-code/index.ts 远端分支实测记录)。
   */
  env: Record<string, string>;
}

export interface OneShotOptions {
  /** 输出 token 上限。默认 100 (起标题用); skillReview 这种大 prompt 应传 4096。 */
  maxTokens?: number;
  /**
   * 模型 ID。不传时 agent 内部用各自默认 (Claude → claude-haiku-4-5, Codex → gpt-5.4-mini)。
   * 仅当调用方对模型敏感时才传 (例如 skillReview 锁定 haiku 控制成本)。
   */
  model?: string;
  /** 整体超时 (ms)。默认 30_000;skillReview 大 prompt 应放宽到 120_000。 */
  timeoutMs?: number;
  /**
   * 外部 abort signal —— 跟内部 timeout controller 合并。
   * 用于 skillReview "用户主动取消发布" 等场景。
   */
  signal?: AbortSignal;
  /** Provider-native system/developer instructions for this one-shot request. */
  systemPrompt?: string;
  /** Additional provider-native output-shape instructions for this request. */
  responseInstructions?: string;
  /**
   * Internal ownership/configuration fence checked immediately before a
   * provider dispatch. Returning false must fail closed without sending the
   * one-shot request (for example when the owning workflow was replaced while
   * the agent host was starting).
   */
  beforeDispatch?: () => boolean | Promise<boolean>;
}

/**
 * oneShot 失败抛此 error,reason 跟 skillReview ReviewServiceUnavailableError 对齐
 * (timeout / auth / network / malformed),便于上层一对一映射 errorCode。
 *
 * - timeout:  自家 timeoutMs 触发 / SDK 408/504
 * - auth:     缺 API key / SDK 401/403
 * - network:  fetch 网络层失败 / SDK 5xx / 429
 * - malformed:模型空响应 / 协议层异常 (Codex 端 error notification 也归这)
 *
 * "宽容"调用方 (起标题) 自己 try/catch 返空串即可,不要在 agent 里做 swallow。
 */
export type OneShotErrorReason = 'timeout' | 'auth' | 'network' | 'malformed';

export class OneShotError extends Error {
  constructor(
    public readonly reason: OneShotErrorReason,
    msg?: string,
  ) {
    super(msg ?? `oneshot-failed:${reason}`);
    this.name = 'OneShotError';
  }
}

/**
 * Agent 未授权 — 由 agent 实现在 lazy spawn / RPC 入口处自检 AuthAdapter.getState()
 * 后抛出。语义:用户从来没在本机授权过这个 agent(或刚登出),不要 spawn 子进程 / 发请求。
 *
 * 调用方处理约定:
 * - listSlashCommands / listCustomizations 这种 ChatInput mount 时无条件预扫的入口 →
 *   catch 这个 error 并返回空结果(不污染 UI、不打 error 日志)
 * - startSession / oneShot / forkSdkSession 这种用户显式触发的入口 → 让它冒上去,
 *   renderer 据此引导用户去 settings 完成授权
 *
 * 用 instanceof 判断;不要靠 message 文本。
 */
export class AgentNotAuthenticatedError extends Error {
  constructor(public readonly agentKind: string, msg?: string) {
    super(msg ?? `agent-not-authenticated:${agentKind}`);
    this.name = 'AgentNotAuthenticatedError';
  }
}

/**
 * An adapter failed before returning a handle and has confirmed its process stopped.
 * Maker unwraps the cause after releasing only this startup's host resources.
 */
export class AgentStartupStoppedError extends Error {
  constructor(cause: unknown) {
    super(cause instanceof Error ? cause.message : String(cause), { cause });
    this.name = 'AgentStartupStoppedError';
  }
}

/** An adapter failed before returning a handle, but its process has not confirmed exit. */
export class AgentStartupCleanupPendingError extends Error {
  readonly whenStopped: Promise<void>;

  constructor(message: string, options: { cause: unknown; whenStopped: Promise<void> }) {
    super(message, { cause: options.cause });
    this.name = 'AgentStartupCleanupPendingError';
    this.whenStopped = options.whenStopped;
  }
}

export interface BotRuntimeSkillEntry {
  name: string;
  runtimeCommandName?: string;
  path?: string;
  enabled?: boolean;
  runtimeStatus?: 'discovered' | 'approved' | 'loaded' | 'failed' | 'unknown';
  scope?: string;
}

/** A Skill the Bot wrote for itself, stored in Cindy-owned per-Bot storage. */
export interface BotRuntimeOwnSkillEntry {
  name: string;
  description?: string;
  /** Absolute path to the Skill directory (the folder holding SKILL.md). */
  path: string;
  /** Absolute path to SKILL.md for harnesses whose config expects the file. */
  filePath?: string;
}

export interface BotRuntimeSkillPolicy {
  mode: 'inherit' | 'allowlist';
  configured: string[];
  catalog: BotRuntimeSkillEntry[];
  /**
   * Skills this Bot distilled from its own finished work.
   *
   * These are deliberately kept out of `catalog` / `configured`: the allowlist
   * describes which of the *harness-discovered* Skills a user let this Bot keep,
   * while these are Cindy-owned files the Bot authored itself. They are always
   * mounted, they are never something the user's allowlist can accidentally
   * switch off, and they must not participate in the runtime resource drift
   * freeze — a Bot that just learned something has to stay able to resume its
   * own task.
   */
  ownSkills?: BotRuntimeOwnSkillEntry[];
  /**
   * Directories to mount as Claude Code local plugins so the Skills above reach
   * a harness that only toggles what it discovered by itself. Other harnesses
   * take the per-Skill paths in `ownSkills` instead.
   */
  ownSkillPluginRoots?: string[];
}

export interface BotRuntimeMcpEntry {
  name: string;
  source: 'builtin' | 'custom' | 'harness';
  available?: boolean;
}

export interface BotRuntimeMcpPolicy {
  mode: 'inherit' | 'allowlist';
  configured: string[];
  catalog: BotRuntimeMcpEntry[];
}

export interface BotRuntimeToolsetEntry {
  id: string;
  name: string;
  essential?: boolean;
  available?: boolean;
}

export interface BotRuntimeToolsetPolicy {
  mode: 'inherit' | 'allowlist';
  configured: string[];
  catalog: BotRuntimeToolsetEntry[];
}

export interface BotRuntimeProfile {
  botId: string;
  profileVersion: number;
  skillPolicy: BotRuntimeSkillPolicy;
  mcpPolicy: BotRuntimeMcpPolicy;
  toolsetPolicy: BotRuntimeToolsetPolicy;
}

/**
 * The adapter dispatched a turn request but could not determine whether the
 * provider accepted it. The Session wrapper must fence the ambiguous handle
 * before surfacing this error. Fencing prevents further execution but does not
 * roll back completed side effects, so orchestrators must not blindly replay
 * the same turn.
 */
export class TurnDispatchUnconfirmedError extends Error {
  readonly code = 'TURN_DISPATCH_UNCONFIRMED';

  constructor(msg: string, options?: ErrorOptions) {
    super(msg, options);
    this.name = 'TurnDispatchUnconfirmedError';
  }
}

/** Persistable evidence that native Pi compaction could not recover an upstream byte limit. */
export const PI_REQUEST_BODY_RECOVERY_EXHAUSTED = 'PI_REQUEST_BODY_RECOVERY_EXHAUSTED';

/** The provider explicitly rejected the turn before accepting any work. */
export class TurnDispatchRejectedError extends Error {
  readonly code = 'TURN_DISPATCH_REJECTED';

  constructor(msg: string, options?: ErrorOptions) {
    super(msg, options);
    this.name = 'TurnDispatchRejectedError';
  }
}

/** 设备托管会话的描述(见 StartSessionOptions.deviceHosted)。 */
export interface DeviceHostedSession {
  /** Agent 主机上的虚拟工作目录,执行器映射到任务真实目录;旧协议兼容真实路径。 */
  workingDir: string;
  extraDirs: string[];
  writableDirs: string[];
  /** 任务所在电脑的平台与 shell(写进给模型的环境说明)。 */
  platform: NodeJS.Platform;
  /** 虚拟工作区路径采用 Agent 进程所在主机的路径风格;缺省按当前进程判断。 */
  pathPlatform?: NodeJS.Platform;
  shell: string;
  osVersion?: string;
  homeDir?: string;
  isGitRepo: boolean;
  /** 本机 loopback 隧道:Agent 经它访问任务所在电脑的执行器与 Cindy 工具。 */
  tunnelUrl: string;
  tunnelToken: string;
  /** 经隧道可用的 Cindy MCP 服务名(`<tunnelUrl>/mcp/<name>`)。 */
  mcpServers: string[];
  /**
   * 本机虚拟工作区根:父目录层级对应执行端的上级说明文件,Agent 照常向上加载。
   */
  mirrorRoot?: string;
  /** 任务所在电脑上用户的个人说明(该 Agent 的用户级说明文件),写进给模型的环境说明。 */
  personalInstructions?: string;
  /**
   * 任务属于另一个账号(供应商分享的受邀者)。Agent 不加载本机的 hooks、托管技能,也不读取
   * 会话目录之外的说明文件;本机用户自己的配置与可执行配置不进入这个会话。
   */
  guest?: boolean;
  /**
   * 受邀者专用的本机目录(远程 Agent 运行根下按控制端分开,跨任务保留,分享删除时整体清理)。
   * Codex 的 CODEX_HOME 与 Pi 的会话目录放在这里,不与本机用户自己的历史、配置混在一起。
   * 只在 guest 时使用;缺省时 Codex 受邀者会话按本机全局说明 fail-closed。
   */
  guestHome?: string;
  /**
   * 受邀者会话的供应商边界(只在 guest 时提供):会话只能经分享给受邀者的这一个供应商出站。
   *  - providerId:分享的供应商(启动与切模都钉在它上面);
   *  - modelIds:它为本 Agent 提供的模型(Claude Code 的可选模型只列这些);
   *  - routeToken:本机 proxy 认出这条会话请求的令牌(Claude Code 经请求头带上,Pi / Codex 按会话登记)。
   * Pi / Codex 子代理与按模型分流的路由也只保留这个供应商。
   */
  guestProvider?: DeviceHostedGuestProvider;
  /**
   * 任务隧道的往来记录。托管会话里 Codex 每读一个项目文件都要过一次设备互联,慢链路下线程启动会
   * 合法地超过关键 RPC 的固定上限(#5764):链路上还有往来就顺延等待,超时时把这里的计数写进错误说明。
   * 不提供时按固定上限。
   */
  linkActivity?: () => DeviceHostedLinkActivity;
}

/**
 * 设备托管会话的链路往来快照(运行 Agent 的电脑上、任务隧道记下的)。只含方法名、计数与耗时,
 * 可以写进日志与错误说明。
 */
export interface DeviceHostedLinkActivity {
  /**
   * 最近一次往来的时间(Date.now 毫秒):Agent 发给执行环境的消息、执行环境的回复或 Cindy 工具请求;
   * 执行环境主动推的通知(后台命令输出等)不算。还没有往来时为 null。
   */
  lastActivityAt: number | null;
  /** Agent 发给执行环境(Codex exec-server)的请求数,与其中已收到回复的数量。 */
  execRequests: number;
  execResponses: number;
  /** 同时在等回复的执行环境请求数的峰值。 */
  execMaxInFlight: number;
  /** 还在等回复的执行环境请求里最早的一个:方法名与已等时长(毫秒)。 */
  execOldestPending?: { method: string; waitedMs: number };
  /** 最近若干次执行环境往返的平均与最大耗时(毫秒);还没有完成的往返时缺省。 */
  execRoundTripAvgMs?: number;
  execRoundTripMaxMs?: number;
  /** 正在经隧道处理的 Cindy 工具(HTTP)请求数。 */
  httpInFlight: number;
  /**
   * 隧道上现在开着的 WebSocket 连接数(Codex 的执行环境连接走这里)。为 0 时执行环境可能已断开或从没连上;
   * 旧接线不提供时缺省。
   */
  wsConnectionsOpen?: number;
}

/** 受邀者会话的供应商边界,见 DeviceHostedSession.guestProvider。 */
export interface DeviceHostedGuestProvider {
  providerId: string;
  modelIds: readonly string[];
  routeToken: string;
}

/** 受邀者会话的 Claude Code 请求带上的路由令牌请求头(本机 proxy 据此只走分享的供应商)。 */
export const DEVICE_HOSTED_GUEST_ROUTE_HEADER = 'x-cindy-guest-route';

/** Main-process capability: symbols cannot cross the renderer/device IPC boundary. */
export const LOCAL_AGENT_CLIENT = Symbol('local-agent-client');

export interface LocalAgentClient {
  /** Main-resolved remote supplier; never accepted from a client request. */
  agentDeviceId?: string;
  /** Main has already selected a member of the application's provider group. */
  groupAssigned?: boolean;
  url: string;
  token: string;
  hostToolsOnly: boolean;
  /** Host-issued namespace; old stored grants may retain their historical name. */
  mcpName?: string;
  /** Owner/grant-scoped runtime storage supplied only by Desktop Main. */
  storageDirectory?: string;
}

export interface StartSessionOptions {
  [LOCAL_AGENT_CLIENT]?: LocalAgentClient;
  /**
   * Business 层 session id (host 调用 maker.createSession 时传的 opts.id, 由
   * maker.ts 透传到这里)。agent 把它放到 McpProviderContext.sessionId, 让 MCP
   * server 工厂能闭包绑定 "当前 session 是谁", 工具 handler 据此回调到 host 的
   * session 级业务函数 (例如 start_team / create_worker 需要传 leadSessionId)。
   *
   * 与 AgentSessionHandle.id (sdkSessionId, SDK 自己生成) 不是同一个值。
   * 未提供时, MCP ctx.sessionId 为 undefined, 标准范式是工具返业务错误码
   * (如 LEAD_NOT_SUPPORTED) 让 LLM 知道当前调用无法绑定到具体 session。
   */
  sessionId?: string;
  /**
   * Maker 为本次内存 Session 实例铸造的唯一代号。业务 sessionId 可在重建后
   * 复用;MCP 权限读取必须同时匹配本代号。Maker 会覆盖外部同名输入。宿主可
   * 将它作为 opaque route identity 放进 harness 的本地 MCP URL,但不得把它
   * 暴露成模型或插件可控的工具参数。
   */
  sessionInstanceId?: string;
  workingDir: string;
  /**
   * Product workspace classification. `dialogue` sessions may still receive an
   * app-managed cwd, but must stay out of project grouping when persisted.
   */
  workspaceKind?: WorkspaceKind;
  /**
   * 远端目标 host id (`@cindy/maker-remote-ssh` ConnectionPool 里的 host alias)。
   * 设置后, agent 不在本机 spawn 进程, 改成通过 deps.getRemoteCodexTransport(id) 拿到
   * SSH-bridged transport 跟远端 codex daemon 通信。
   * workingDir 在 remote 场景下是 *远端机器上的绝对路径* (本地 fs 不存在也行)。
   *
   * 缺省 / undefined → 本地 spawn (历史行为)。
   * 目前仅 Codex 支持; Claude 不消费此字段 (会被忽略)。
   */
  remoteHostId?: string;
  /**
   * 设备托管:Agent 进程在本机运行(用本机的程序、登录、供应商与网络),任务、项目文件与
   * 命令执行在同账号的另一台电脑上。workingDir 是本机的影子目录(只放同步过来的项目说明,
   * 供 Agent 照常加载);文件与命令工具、Cindy 工具全部经 tunnel 回到任务所在电脑执行。
   * 与 remoteHostId 互斥。
   */
  deviceHosted?: DeviceHostedSession;
  model: string;
  /**
   * 本任务级工作上下文预算(tokens)。host 已按目录 `contextWindowMax` 与用户在同一
   * 路由上设过的模型级上限收敛,引擎只需直接采用;缺席 = 跟随 `resolveModelContextLimit`
   * / 目录默认(旧行为零变化)。
   */
  contextWindowBudget?: number;
  /**
   * 本次会话显式选择的供应商来源。maker-core 只用它推导子进程凭证形态;
   * 具体上游路由仍由 host 的 proxy / provider catalog 负责。
   */
  providerId?: string | null;
  effort?: Effort;
  /**
   * Codex Fast mode: true → app-server ServiceTier.Fast, false → explicit standard tier.
   * Undefined means do not override the agent/server default.
   */
  fastMode?: boolean | 'ultrafast';
  /** Trusted host restriction for this subscription run, including live policy changes. */
  fastModePolicy?: import('./shared/fast-mode-policy.js').FastModePolicy;
  /**
   * Host-owned live pricing variant for request-level usage segments.
   * Pi reads this at each provider request boundary so a mid-turn Fast toggle
   * prices already-started requests with the tariff they actually used.
   */
  getPriceVariant?: () => 'standard' | 'priority';
  /** Match completed proxy usage to its actual execution tariff, before preference-based pricing. */
  resolveUsagePriceVariant?: (usage: {
    threadId?: string;
    inputTokens: number;
    outputTokens: number;
    cacheReadTokens: number;
  }) => 'standard' | 'priority' | undefined;
  /** Pi + thinking-toggle 模型:false 时启动即关思考。缺省保持模型默认(开)。 */
  thinkingEnabled?: boolean;
  /**
   * 用户级 system prompt 追加段,跨 agent (claude-code / codex) 公用,
   * 拼接顺序最末(优先级最高),覆盖 engine 与 host 段。空串 / undefined 跳过。
   *
   * 来源:renderer 的 lib/userPromptStore(本地 localStorage,不上服务器)。
   * 每次 startSession 由 ChatInput 透传当前最新值,达成「实时跟随」语义 ——
   * 用户改 prompt 后,下一次新 session 立即生效,老 session 维持启动时快照。
   */
  userPrompt?: string;
  /**
   * Bot Profile runtime context, resolved by the main/DB authority at session
   * start. It is a startup system-prompt segment, not a per-turn user prefix.
   * Harness adapters place it before the user personalization segment.
   */
  botProfilePrompt?: string;
  /**
   * Stable profile-binding metadata rendered separately from the Bot SOUL.
   * Hermes keeps the active-profile marker outside the identity document so
   * profile metadata never mutates user-authored identity bytes.
   */
  botProfileContextPrompt?: string;
  /**
   * Hermes USER.md equivalent for a Bot Profile. This is frozen with the
   * Profile/runtime snapshot and belongs in the volatile prompt tier after
   * memory, not inside the Bot's SOUL identity.
   */
  botUserProfilePrompt?: string;
  /**
   * Native Bot capability snapshot resolved by the host before the harness
   * starts. Adapters must enforce this through their own Skill/MCP/tool config;
   * it must never be converted into natural-language capability claims.
   */
  botRuntimeProfile?: BotRuntimeProfile;
  /**
   * 是否启用 Maker Memory (本次 session 内). 跟 userPrompt 同模式 — renderer 启 session
   * 时透传当前 memoryMode='maker' → true, 'native' / 'off' → false。main 不持久化。
   *
   * 缺省 / undefined → fallback 到 runtimeConfig.makerMemoryEnabled (host 静态配置, 一般为
   * undefined / false), 实际效果就是不启用 maker memory。
   *
   * 启用时 agent.startSession 会:
   *   1. 拼 system prompt 时注入 memory rules + MEMORY.md 索引
   *   2. 创建 MemoryFlushController 监听 token usage
   * 共享 manager 的 enablement 由 host setting 控制,不由 session flag 改写。
   */
  makerMemoryEnabled?: boolean;
  /**
   * Stable host-owned Maker Memory scope. Cindy Bots use this to keep memory
   * isolated by Bot identity instead of sharing it with every task in a workdir.
   */
  makerMemoryScopeKey?: string;
  /**
   * Exact host-frozen memory bytes for this runtime start. When present the
   * harness must inject these bytes instead of re-reading MEMORY.md later in
   * startup, otherwise the persisted runtime snapshot and the actual prompt
   * can observe different memory generations.
   */
  makerMemoryIndexSnapshot?: string;
  /**
   * Host-owned Cindy Review policy. This is not a user permission preset:
   * adapters must keep the session local, fresh, memory-free and hard
   * read-only even if a later control request tries to widen permissions.
   */
  reviewMode?: true;
  /**
   * Exact local files or directories that a host-owned Review may inspect in
   * addition to workingDir. Adapters must treat files as exact grants and
   * directories as subtree grants; this is narrower than extraDirs, whose
   * parent-directory transport semantics are only used to make attachments
   * visible to the underlying harness.
   */
  reviewReadPaths?: string[];
  permissionMode?: PermissionMode;
  /**
   * 计划模式开关(与 permissionMode 正交,见 Capabilities.planMode)。
   * true → Claude 以 SDK plan mode 启动 / Codex turn 携带 collaborationMode plan。
   * 缺省 / undefined → 关闭。
   */
  planMode?: boolean;
  displayReasoning?: ReasoningDisplay;
  resumeSessionId?: string;
  /**
   * Maker 内部注入的 invalid-resume CAS 回调。Agent 只有在供应商明确报告
   * resumeSessionId 不存在时才调用;返回 false 表示持久化值已被并发更新,
   * 此时不得 fresh fallback 覆盖新会话。
   */
  onInvalidResumeSession?: (expectedSdkSessionId: string) => Promise<boolean>;
  /**
   * Codex-only: whether the resumed thread history already contains xdt-maker's
   * product developer prompt. `false` / `undefined` lets non-proxy resume restore
   * it once; `true` keeps Option A and avoids repeated developer messages.
   */
  codexHistoryHasProductPrompt?: boolean;
  /**
   * 附加只读引用目录列表(绝对路径)。Claude 透传到 SDK options.additionalDirectories;
   * Codex 透传到 app-server runtimeWorkspaceRoots,并用 permission profile 保持只读。
   * 跟 model/effort 同语义: 启动时快照 + 由 setExtraDirs 热更新 closure。
   */
  extraDirs?: string[];
  /** Current task library root, supplied only by the Host and included in extraDirs. */
  [LIBRARY_READ_ROOT]?: string | null;
  /**
   * 附加可读写目录列表(绝对路径)。这是用户逐目录授予的会话级权限,不能从
   * extraDirs 自动推导;启动时快照,并可由 setWritableDirs 热更新。
   */
  writableDirs?: string[];
  /**
   * vendor-specific 透传字段。等价于现有 VendorSessionOptions.vendorOptions。
   * 例如:Claude 的 forkSession / resumeSessionAt / source / onStderrLine ...
   */
  vendorOptions?: Record<string, unknown>;
}

/**
 * Main-only send metadata. Symbol keys cannot cross Electron/device-link
 * structured-clone boundaries, so Renderer-controlled send options cannot mint
 * this proof. Main dispatchers attach it only after authenticating the source.
 */
export const MAIN_OWNED_SEND_CONTEXT = Symbol('cindy.main-owned-send-context');
/** Optional question replies must never be queued for a later execution. */
export const ASYNC_QUESTION_ANSWER = Symbol('cindy.async-question-answer');

/** Call-local user content before Session replaces images with generated descriptions. */
export const AUTO_REVIEW_SOURCE_CONTENT = Symbol('cindy.auto-review-source-content');

/** Host-restored user authorization for this send; never accepted from wire options. */
export const AUTO_REVIEW_USER_INTENT = Symbol('cindy.auto-review-user-intent');

/** Main-attested continuation: retain initialized live intent, including an explicit empty reset. */
export const AUTO_REVIEW_DELEGATED_CONTINUATION = Symbol('autoReviewDelegatedContinuation');

/** Main-only selection from the original input for a retained-history continuation. */
export const INHERITED_CAPABILITY_SELECTION = Symbol('cindy.inherited-capability-selection');

/**
 * Main-attested Skill winner for this exact send. Symbol keys cannot cross the
 * Renderer/device-link boundary, so only a Host dispatcher can pin a path.
 */
export const PINNED_SKILL_INVOCATION = Symbol('cindy.pinned-skill-invocation');

export interface PinnedSkillInvocation {
  readonly name: string;
  readonly path: string;
}

export interface MainOwnedSendContext {
  readonly origin: TurnPermissionOrigin;
  /** Main-authenticated user text before channel/persona/context decoration. */
  readonly rawChannelText?: string;
  /**
   * Host-stamped content this channel message points at (reply/quote and attachment
   * counts). Auto-review shows it as third-party evidence beside, never inside, the
   * user's words; it cannot grant authority.
   */
  readonly autoReviewReferences?: AutoReviewUserReferences;
}

/**
 * Session.send / handle.send 的可选附加项。
 * 缺省 / 不识别字段必须安全忽略。
 */
export const PI_CACHE_RECOVERY_EXPECTATION = Symbol('pi-cache-recovery-expectation');

export interface SendOptions {
  readonly [PI_CACHE_RECOVERY_EXPECTATION]?: import('./pi/cache-compatibility.js').PiCacheCompatibility;
  readonly [ASYNC_QUESTION_ANSWER]?: true;
  readonly [AUTO_REVIEW_SOURCE_CONTENT]?: UserMessage['content'];
  readonly [AUTO_REVIEW_USER_INTENT]?: AutoReviewUserIntent;
  readonly [AUTO_REVIEW_DELEGATED_CONTINUATION]?: true;
  readonly [INHERITED_CAPABILITY_SELECTION]?: string;
  /** Exact Skill selected by a Host authorization check for this send. */
  readonly [PINNED_SKILL_INVOCATION]?: PinnedSkillInvocation;
  /** Host-authenticated metadata; never accept an equivalent string-keyed wire field. */
  readonly [MAIN_OWNED_SEND_CONTEXT]?: MainOwnedSendContext;
  /**
   * 当前 session 的展示 title (renderer / IPC 层在调 send 前查到的最新值)。
   * 仅用于在 SDK ▷ token usage 等诊断日志里多一行可读上下文,
   * 不参与任何业务逻辑; 长 session 跨 turn 之间允许变化 (auto-rename / 用户手改)。
   */
  logTitle?: string;
  /**
   * 调用方为这条 user 消息预先生成的 uuid。Claude SDK 会把它当作 file checkpoint
   * 的 snapshot messageId, rewind preview 反查 user uuid 调 rewindFiles dryRun
   * 也用同一个值。调用方应当**同时**:
   *   1. 落库时写进 messages.agent_meta.uuid (rewind preview/commit 反查锚点)
   *   2. 透传到这里 (本字段) 让 SDK 按这个 uuid 标 checkpoint
   * 缺省时 SDK 自己生成一个 (但调用方不知道, rewind 拿不到 → 走"老消息"兜底)。
   * Claude 端: agent 实现把它注入 inputQueue.push 的 SDKUserMessage.uuid;
   * Codex 端: 当前不消费 (Codex 无 file checkpointing 概念)。
   */
  messageUuid?: string;
  /**
   * Adapter 回报这条 user prompt 在原生 transcript 中的稳定 entry id。
   * Host 可把它补到已落库的 Cindy user 行,供后续原生分支重投影精确恢复附件。
   * 回调失败不得改变已经接受的 provider dispatch 结果。
   */
  onTranscriptUserEntry?: (entryId: string) => void | Promise<void>;
  /** Exact accepted Pi input replaced by a zero-output retry; never match by text. */
  retryTranscriptUserEntryId?: string;
  /**
   * 当前用户的展示名 (host / renderer 在调 send 时提供)。仅用于 turn-start 时
   * push status event 的文案 — agent 拼成 "<userName> Just Wait ..." 让 UI 个人化;
   * 缺省时 fallback "Just Wait ..."。不参与任何业务逻辑。
   */
  userName?: string;
  /**
   * 本条消息的计划模式意图快照(点击发送瞬间的勾选状态,随排队行透传)。
   *  - true  → 本 turn 以计划模式执行;若 agent 武装态仍在则一并消耗(emit
   *            plan_mode_changed),否则(排队后用户已改勾选)不动武装态。
   *  - false → 本 turn 显式普通执行,且**不**消耗武装态(用户可能是排队普通消息
   *            之后才重新勾选,意图留给未来消息)。
   *  - undefined → 旧语义:消耗 agent 当前武装态(IM / scheduler / goal 等
   *            不走 composer 的调用方)。
   * 背景:排队行的 createOpts 快照对已存活会话曾被忽略,drain 时按 agent 当时
   * 的武装态执行 —— 排队期间改勾选会丢失/误用计划意图(PR #494 review)。
   */
  planMode?: boolean;
  /**
   * 调用方要求 Codex turn/start 失败时 reject。普通 send 的历史契约是通过事件流
   * 上报失败,不 reject;但 desktop renderer 队列路径需要“agent 已接受才落库”的
   * 确定性语义,Codex 插话也需要知道 follow-up turn 是否真正启动。未知 agent 必须
   * 安全忽略。
   */
  throwOnStartFailure?: boolean;
  /**
   * Optional cancellation boundary for caller-owned transactions.
   *
   * This is not a user-facing "abort the model" primitive. It exists so main's
   * queue coordinator can cancel a pre-accept transaction (notably Codex
   * interrupt-then-follow-up steer) when Stop/close wins the race. Agent
   * implementations that cannot observe it must ignore it safely; callers still
   * rely on the agent's normal close/abort checks as the final guard.
   */
  signal?: AbortSignal;
  /**
   * 本次 send 的发起来源(产品层 turn origin)。Session 会记住它并打到这一轮
   * 的每个 AgentEvent.turnOrigin 上(见 session.ts 的 currentTurnOrigin),供
   * 共享 session 下区分自动任务 turn 与用户 turn。agent 子类不消费,透传无害。
   */
  origin?: SendOrigin;
  /** Host-owned per-turn correlation copied onto every AgentEvent for lifecycle settlement. */
  turnAttemptToken?: number;
  /**
   * Host-owned, per-turn permission policy. This is deliberately a callback
   * rather than prompt text: providers must enforce it at their pre-execution
   * approval boundary, before MCP auto-approval or permission-mode bypasses.
   */
  turnPermissionPolicy?: TurnPermissionPolicy;
  /** Host-owned text-only turn. Block every tool before execution, including reads and Full access. */
  toolsDisabled?: boolean;
}

export type TurnPermissionOrigin =
  | { kind: 'desktop' }
  | {
      kind: 'im';
      channel: 'feishu' | 'discord' | 'slack' | 'wechat' | 'telegram' | 'dingtalk' | 'wecom';
      taskId?: string;
    }
  | { kind: 'scheduler' }
  | { kind: 'hook'; source: string };

export interface TurnPermissionPolicy {
  /** Only the Host may supply this identity evidence; it is never parsed from message text. */
  readonly autoReviewContext?: AutoReviewRequest['authorizationContext'];
  readonly origin: TurnPermissionOrigin;
  readonly confirmationSurface: 'desktop' | 'channel';
  readonly confirmationTimeoutMs?: number;
  readonly onInteractionStateChange?: (
    state: 'waiting' | 'resolved' | 'cancelled',
  ) => void;
  forceConfirmToolCall(toolName: string, input: unknown): boolean;
}

export class TurnPermissionPolicyUnsupportedError extends Error {
  readonly code = 'TURN_PERMISSION_POLICY_UNSUPPORTED';

  constructor(
    readonly agentKind: AgentKind,
    readonly permissionMode: PermissionMode,
  ) {
    super(
      `Turn permission policy is not supported by ${agentKind} in permission mode ${permissionMode}`,
    );
    this.name = 'TurnPermissionPolicyUnsupportedError';
  }
}

/**
 * 会话内仍在运行的单个后台任务快照(listBackgroundTasks 的元素)。字段与
 * agent_task_update 事件同源:taskId 是 SDK task_id;toolUseId 是派生该任务的
 * 工具调用 id(renderer 用它对回消息流里的工具行);title 是 SDK description。
 */
export interface BackgroundTaskSnapshot {
  taskId: string;
  /** SDK task_type(local_bash / local_agent / local_workflow 等),缺失表示未知。 */
  taskType?: string;
  toolUseId?: string;
  title?: string;
  /**
   * Agent that produced this task. Renderer hydration must preserve it so a
   * durable Pi Subagent is not synthesized as claude-code after reload.
   * Omitted snapshots default to claude-code.
   */
  provider?: 'pi' | 'claude-code';
  /**
   * SDK 为该任务写入的输出文件(task_started 的 output_file)。主进程据此按
   * (会话, 任务) 读取后台命令的最近输出,调用方不能自带路径。
   */
  outputFile?: string;
}

/**
 * Provider-owned lifecycle of the turn boundary after a foreground `done`.
 *
 * `awaiting` means the provider has an automatic continuation queued or still
 * expected. `active` means that continuation has started. `cancelled` means
 * the continuation was explicitly stopped; observers may settle immediately,
 * while the provider appends an ordered terminal boundary for Session state.
 * Provider/session failure settles via the normal terminal error and
 * session-status paths instead.
 */
export type TurnContinuationState = 'awaiting' | 'active' | 'cancelled';

/**
 * Why a session handle is being torn down.
 *
 * This is a *lifecycle identity*, not a hint: adapters that own detached,
 * parent-independent resources (currently the Pi durable Subagent runners)
 * branch on it.
 *
 * - `navigation` — ordinary session close / agent switch. The account and its
 *   database stay the same, so detached work keeps running.
 * - `account-boundary` — logout or account switch. The owner database and
 *   gateway credentials are being replaced, so every detached child of the old
 *   owner must be stopped and its credential leases revoked immediately.
 * - `app-quit` — process shutdown. Detached children are stopped by the
 *   dedicated quit step; this reason exists so quit is never mistaken for an
 *   ownership change.
 *
 * Callers that cannot identify their boundary must omit the reason: teardown
 * then fails closed to `account-boundary`.
 */
export type AgentSessionTeardownReason = 'navigation' | 'account-boundary' | 'app-quit';

export interface AgentSessionTeardownOptions {
  readonly reason: AgentSessionTeardownReason;
}

/** Read-only native Codex capacity, separate from provider catalog specifications. */
export interface CodexContextWindowInfo {
  contextWindow: number;
  usableContextWindow: number;
  autoCompactTokenLimit: number;
  modelMaxContextWindow: number | null;
  source: 'runtime' | 'config';
  fallbackModel: boolean;
  /** No live CLI handle: these settings will be applied on the next send. */
  pendingApply?: boolean;
}

/**
 * 一个已启动的 agent 会话句柄。
 * 上层 Session 类持有此句柄并对外暴露 UI 友好的 API。
 */
export interface PiModelSwitchPreview {
  /** Existing Pi model snapshot can serve the target without a catalog mutation. */
  action: 'hot' | 'refresh' | 'rebuild' | 'unavailable';
  /** Target configuration's context capacity; null when not established. */
  targetContextWindow: number | null;
  /** Only true when the live Pi runtime has confirmed this exact target window. */
  windowVerified: boolean;
  /** Non-secret reason suitable for a host error; never include env values. */
  reason?: string;
}

/**
 * What the running engine reports for one MCP server in this session.
 * - `connected`: the engine lists tools for it (possibly none, when it says so).
 * - `no-tools`: the engine has the server but lists no tools and no state; it
 *   may have failed to start, still be starting, or expose no tools.
 * - `not-mounted`: the engine has no server by that name in this session.
 */
export type AgentMcpServerToolsState =
  | 'connected'
  | 'no-tools'
  | 'not-mounted'
  | 'failed'
  | 'needs-auth'
  | 'pending'
  | 'disabled';

export interface AgentMcpServerToolsReport {
  state: AgentMcpServerToolsState;
  /** Raw MCP tool names as the server declared them, not harness-qualified names. */
  tools: Array<{ name: string; description?: string }>;
}

export interface AgentSessionHandle {
  /** Canonical physical Skill identities frozen at native runtime startup. */
  readonly disabledSkillPaths?: readonly string[];
  getCodexContextWindowInfo?(): Promise<CodexContextWindowInfo | null>;
  /**
   * Read-only: ask the engine which tools it holds for one MCP server in this
   * session. Never starts a server or calls its tools. Absent, or null, when
   * the engine has no per-session MCP status entry.
   */
  readMcpServerTools?(serverName: string): Promise<AgentMcpServerToolsReport | null>;
  /** Native session identity safe for resume; may retain an unaccepted fork's source. */
  readonly id: string;
  /** Transient native request identity; hosts must not persist it as a resume id. */
  readonly requestSessionId?: string;
  readonly agentKind: AgentKind;
  readonly model: string;
  /** Pi-only, per-session runtime command catalog. Undefined for other agents. */
  getRuntimeCapabilities?(): PiRuntimeCapabilityManifest | undefined;
  /** Subscribe to Pi runtime catalog replacement; returns an idempotent disposer. */
  onRuntimeCapabilitiesChange?(
    listener: (manifest: PiRuntimeCapabilityManifest | undefined) => void,
  ): () => void;
  /** Codex-only: 当前会话绑定的 app-server host 是否经 loopback proxy 出口。 */
  readonly codexProxyActive?: boolean;
  /** Local runtime identity, never serialized to the remote wire protocol. */
  readonly codexHostKey?: string;
  /**
   * Codex-only: thread/start 或 thread/resume 响应确认的实际 model provider。
   * 这是 thread 级冻结身份,不随 thread/settings/update 的模型切换改变。
   */
  readonly codexThreadModelProviderId?: string;
  /** Codex-only: provider-owned proof that this thread has crossed a turn boundary. */
  readonly codexThreadMayHaveRollout?: boolean;
  /** Codex-only: 当前 host 的独立 Subagent 路由是否兼容 Cindy Codex 远程压缩。 */
  readonly codexCindyRemoteCompactionCompatible?: boolean;
  /**
   * Codex-only: start/resume 成功后,产品 prompt 这一次到底有没有进入
   * codex thread history。Maker 用这个事实更新 host 持久化 bit,避免再从
   * 全局 proxy 状态反推。其它 agent 不设置。
   */
  readonly codexProductPromptDelivery?: {
    readonly threadId: string;
    readonly historyHasProductPrompt: boolean;
  };

  /** 推送一条用户消息(流式输入) */
  send(message: UserMessage, opts?: SendOptions): Promise<void>;

  /**
   * Synchronous provider preflight called by Session after reserving the turn
   * and the optional `afterTurnReserved` state-preparation hook, but before any
   * durable `beforeProviderStart` / `onAccepted` side effect.
   * Direct handle callers are still validated again inside send().
   */
  validateSendOptions?(opts: SendOptions): void;

  /**
   * 把用户消息追加到当前 in-flight turn。
   *
   * 与 send() 的差别不是参数形态,而是状态语义:send() 开启新 turn 并重置
   * usage/status/tool-loop;steer() 只进入已有 turn 的输入通道,不能刷新这些
   * per-turn 状态。这里保留独立方法,避免调用方用 boolean 改写 send() 后踩到
   * 缓存率、计费和 UI 状态错乱的问题。
   */
  steer(message: UserMessage, opts?: SendOptions): Promise<void>;

  /** 中断当前 turn */
  abort(): Promise<void>;

  /**
   * 请求当前 turn 在 provider 的安全边界停止。
   *
   * 与 abort() 的产品语义不同:这里只发送 provider 原生的软中断请求,不得关闭
   * Query、transport 或子进程,也不得升级为 kill/rebuild。Session 层负责等到当前
   * 工具结果边界再调用,并对悬挂/失败做有界的 unconfirmed 降级。
   */
  requestGracefulStop?(opts?: { signal?: AbortSignal }): Promise<void>;

  /** Provider turn identity when the adapter exposes one (currently Codex). */
  getCurrentTurnId?(): string | null;

  /**
   * 停止会话内单个后台任务(SDK Query.stopTask 透传)。
   * 与 abort() 的区别:abort 是"用户 Stop"的全停语义(只连带 wake 型任务、并
   * 中断当前 turn);本方法精确停一个后台任务(含 local_bash —— 用户在 UI 上
   * 对着具体任务点停,不存在 abort 那种误杀 dev server 的顾虑),不碰当前 turn。
   * 幂等:任务已到终态时静默成功。不支持的 agent 留空(Session 层抛
   * NotSupportedError)。
   */
  stopBackgroundTask?(taskId: string): Promise<void>;

  /** Resume a terminal durable child on its existing provider session. */
  resumeBackgroundTask?(taskId: string, message: string, childId?: string): Promise<void>;

  /**
   * 当前仍在运行的后台任务快照(含 local_bash)。事件流(agent_task_update)是
   * 唯一实时源;本方法只服务「订阅者挂载/重载晚于任务启动」的存量补齐场景。
   * 不支持的 agent 留空(Session 层回退为空数组)。
   */
  listBackgroundTasks?(): BackgroundTaskSnapshot[];

  /**
   * 「任务已终态、wake turn 尚未启动或仍在跑」的 continuation claim 数
   * (awaiting + active,cancelled 不计)。listBackgroundTasks 在任务终态后
   * 立即不再包含该任务,空快照不能证明后续没有 wake turn —— renderer 的
   * 唤醒桥接对账以本计数为收口权威依据。不支持的 agent 留空(Session 层
   * 回退为 0,消费方按「信号不可用 → 不收口」保守处理)。
   */
  countPendingWakeContinuations?(): number;

  /**
   * 宿主发起的独占 RPC 操作(手动压缩 / rewind fork / 切模等)是否在途。
   * 这类操作不预约 turn、也不置 isStreaming;运行时回收必须能看见它们,
   * 不能把进程关在操作中间。不支持的 agent 留空(Session 层回退 false)。
   */
  hasPendingHostOperation?(): boolean;

  /**
   * Resolve the provider claim attached atomically to a specific `done` event.
   * Returns null when that event has no matching continuation boundary.
   */
  beginTurnContinuationWait?(continuationId?: number): TurnContinuationState | null;

  /**
   * Observe provider-owned continuation cancellation/start transitions. The
   * subscription is intentionally separate from task-card events: a stopped
   * wake task does not necessarily produce another provider `done`.
   */
  onTurnContinuationChange?(
    listener: (continuationId: number, state: TurnContinuationState) => void,
  ): () => void;

  /** 关闭会话,清理子进程 */
  close(opts?: AgentSessionTeardownOptions): Promise<void>;

  /**
   * Detach from a long-lived remote session without terminating the upstream
   * process. Agents without detach semantics leave this undefined.
   */
  detach?(opts?: AgentSessionTeardownOptions): Promise<void>;

  /** 事件流(streaming + 翻译后的统一事件) */
  events(): AsyncIterable<AgentEvent>;

  /** 当前 usage 快照 */
  getUsageSnapshot(): UsageSnapshot;

  /** Structured context usage breakdown. Only Claude Code implements this today. */
  getContextUsage?(): Promise<ContextUsageData>;

  /**
   * 设置统一的用户交互回调 —— permission/ask_user_question/plan_review 三种 kind
   * 通过同一个 resolver dispatch。host 侧根据 req.kind 弹不同 UI。
   */
  setInteractionResolver(resolver: InteractionResolver): void;

  /** Host tool approval uses the same live intent/model/scope as native tool approval. */
  reviewAutoPermissionAction?(action: ReviewableAction): Promise<AutoReviewDecision>;

  /** Actual runtime reviewer, not subscription availability. Only applies to harness-dispatched tools. */
  getAutoReviewOwner?(): 'native' | 'cindy';

  /** 运行时切换模型 —— 不支持时抛 NotSupportedError。
   * thinkingEnabled = 目标模型的思考开关意图(Pi 用它收敛切模后的 thinking level)。 */
  setModel?(
    model: string,
    opts?: {
      providerId?: string | null;
      effort?: Effort;
      thinkingEnabled?: boolean;
      /**
       * 本任务级工作上下文预算(tokens);host 已按目标路由的目录上限与模型级上限
       * 收敛。显式传 null / undefined 时保持当前预算不变(host 在预算变化时直接
       * 触发重建,不走热切)。
       */
      contextWindowBudget?: number | null;
    },
  ): Promise<void>;

  /** Read-only Pi preflight before the host changes its persisted route or context. */
  previewModelSwitch?(
    model: string,
    opts?: { providerId?: string | null; contextWindowBudget?: number | null },
  ): Promise<PiModelSwitchPreview>;

  /**
   * 当前 provider handle 是否必须先关闭、再由同一业务任务 cold resume 才能应用目标模型。
   * 缺省 false;用于 Codex 这类把部分模型配置冻结在 app-server spawn / thread resume
   * 边界的 adapter。调用方必须在任何 route store 写入前完成该预检。
   */
  requiresModelSwitchRebuild?(
    model: string,
    opts?: { providerId?: string | null },
  ): boolean | Promise<boolean>;

  /** 运行时切换 effort */
  setEffort?(effort: Effort): Promise<void>;

  /** 运行时切换 permission mode */
  setPermissionMode?(mode: PermissionMode): Promise<void>;

  /**
   * Vendor-native Auto reviewer became unavailable. Keep the product mode at
   * Auto, but route subsequent approvals through Cindy's lightweight reviewer.
   */
  useCindyAutoReviewFallback?(): Promise<void>;

  /**
   * 运行时开关计划模式(Capabilities.planMode 支持时实现)。
   * 开启:Claude 把 SDK 切到 plan mode;Codex 下一 turn 携带 collaborationMode plan。
   * 关闭:切回当前 permissionMode 对应的底层权限档 / collaborationMode default。
   * 计划批准后 agent 自行关闭时会 emit 'plan_mode_changed' 事件(host 负责持久化回写)。
   */
  setPlanMode?(enabled: boolean): Promise<void>;

  /** 当前 maker 进程内记录的计划模式状态;不支持的 agent 不实现。 */
  getPlanMode?(): boolean | null;

  /** Execution authority, including an active one-shot Plan turn after the UI toggle is consumed. */
  getExecutionPlanMode?(): boolean | null;

  /**
   * 把当前会话导出成 HTML 文件,返回写入的绝对路径。
   * `outputPath` 省略时由 agent 决定默认落盘位置。仅 Capabilities.sessionHtmlExport
   * 支持的 agent(pi)实现;不支持的 agent 不实现。
   */
  exportSessionHtml?(outputPath?: string): Promise<string>;

  /**
   * 手动压缩会话上下文(可带聚焦指令,由 agent 调 LLM 生成摘要,压缩边界经事件流
   * 上报 —— pi 为 compaction_start/end → compact_boundary)。仅
   * Capabilities.manualCompact 支持的 agent(pi)实现;不支持的 agent 不实现。
   */
  compactSession?(instructions?: string): Promise<ManualCompactResult>;

  /** 读取 / 切换同一 SDK session 内的原生分支树。 */
  getSessionTree?(): Promise<SessionTreeSnapshot>;
  navigateSessionTree?(
    entryId: string,
    options?: NavigateSessionTreeOptions,
  ): Promise<NavigateSessionTreeResult>;

  /** 运行时切换 Fast mode;不支持的 agent 不实现。 */
  setFastMode?(enabled: boolean | 'ultrafast'): Promise<void>;
  /** Pi thinking-toggle 模型:运行时开关思考。 */
  setThinkingEnabled?(enabled: boolean): Promise<void>;

  /**
   * 运行时增删 extraDirs(覆盖式)。Claude 与 Codex 都更新 closure,在下一 turn 生效。
   */
  setExtraDirs?(dirs: string[], libraryRoot?: string | null): Promise<void>;

  /** 运行时增删附加可读写目录(覆盖式),下一 turn 生效。 */
  setWritableDirs?(dirs: string[]): Promise<void>;

  /**
   * 运行时合并 vendorOptions(浅合并到内部闭包)。
   * 用于中途切换 session-specific 配置(例如 orcaRole='lead' 让 MCP provider
   * 的 isEnabled(ctx) 在下一 turn 立即返回 true / false)。
   * SDK 的 system prompt 不支持中途修改,这是唯一干净的"中途切换能力集"机制。
   * 不发起任何 SDK 调用,只改 closure;下一次 buildQuery / turn/start 自动用新值。
   */
  setVendorOptions?(patch: Record<string, unknown>): Promise<void>;

  /** 当前 maker 进程内记录的 Fast mode 状态;不支持的 agent 不实现。 */
  getFastMode?(): boolean | 'ultrafast';
  /** 当前 maker 进程内记录的思考强度;固定强度模型可返回 null。 */
  getEffort?(): Effort | null;

  // ── Rewind ────────────────────────────────────────────────────────────────
  // Claude 走 SDK message uuid + file checkpoint;Codex 走 app-server thread/rollback
  // 裁剪完整 turn,不做文件回滚。

  /**
   * dryRun: 问 SDK "如果回滚到这个 user 消息那一刻, 会动哪些文件"。
   * 不改任何状态, 调用方 (Dialog) 拿来给用户看 diff 列表。
   * SDK 软拒绝 (老 session 没开 checkpointing 等) 包成 {canRewind:false, error}。
   */
  previewRewindFiles?(userUuid: string): Promise<RewindFilesResult>;

  /**
   * 真执行 rewind:
   *   1. 立即把文件回滚到 target 时点 (q.rewindFiles dryRun:false)
   *   2. close 当前 SDK Query (释放 CLI 子进程)
   *   3. 内部标记 pendingRewindTo = priorAssistantUuid; 下一次 send 自动用
   *      resume + resumeSessionAt + forkSession 三件套重启 sdkQuery
   *
   * 失败语义: 文件回滚抛错 → warn + 继续 (forkSession=true 兜底); close 抛错 → warn。
   * DB 操作 (软删 messages / reset tokens) 由调用方负责, 不在 maker-core 范围。
   */
  commitRewindFiles?(
    userUuid: string,
    priorAssistantUuid: string,
    opts?: RewindCommitOptions,
  ): Promise<undefined | RewindCommitResult>;

  /**
   * 当前 turn 是否在跑 (rewind preview/commit 前置守卫用)。
   * true = SDK 在处理上一条 user 消息, false = 空闲。
   * 默认实现为 false (capability 缺失时 host 不该问)。
   */
  isTurnRunning?(): boolean;
  /** A provider-owned preparatory turn still precedes the accepted user input.
   * Host timeouts must not resume it with a generic CONTINUE. Read synchronously
   * before abort clears the provider's existing preparation state.
   */
  isPreparingUserTurn?(): boolean;
}

export abstract class BaseAgent {
  abstract readonly kind: AgentKind;
  abstract readonly capabilities: Capabilities;

  /**
   * 当前 host 对 memory 通道的覆盖意图。
   *  - undefined : 没人改过, 走 agent 自带默认
   *  - true/false: runtimeConfig.memoryEnabled 注入或被 setMemory 改过
   *
   * 子类的 startSession (CC: buildQuery options.settings; Codex: experimentalFeature/enablement/set)
   * 都从这里读, 保证 "构造期 runtimeConfig.memoryEnabled" 与 "运行时 setMemory" 是同一份事实。
   */
  protected memoryOverride: boolean | undefined;

  constructor(protected deps: AgentDeps) {
    if (!deps.binaryPath) {
      throw new Error(
        `${this.constructor.name}: binaryPath is required at construction (host must provision binary before instantiating agent)`,
      );
    }
    this.memoryOverride = deps.runtimeConfig.memoryEnabled;
  }

  /**
   * Build instance-level capabilities from an agent's built-in declaration plus
   * host additions. Agents keep ownership of their defaults; BaseAgent only owns
   * the shared append/merge mechanics.
   */
  protected buildCapabilities(base: Capabilities): Capabilities {
    const additions = this.deps.capabilityAdditions;
    return {
      ...base,
      availableModels: this.mergeCapabilityList(
        'availableModels',
        base.availableModels,
        additions?.availableModels,
      ),
      effortLevels: this.mergeCapabilityList(
        'effortLevels',
        base.effortLevels,
        additions?.effortLevels,
      ),
    };
  }

  private mergeCapabilityList<T extends { id: string }>(
    listName: 'availableModels' | 'effortLevels',
    builtIn: readonly T[],
    additions: readonly T[] | undefined,
  ): T[] {
    const merged = [...builtIn];
    if (!additions || additions.length === 0) return merged;

    const ids = new Set(merged.map((item) => item.id));
    for (const item of additions) {
      if (ids.has(item.id)) {
        this.deps.logger.warn('capability addition ignored duplicate id', {
          agentKind: this.kind,
          listName,
          id: item.id,
        });
        continue;
      }
      ids.add(item.id);
      merged.push(item);
    }
    return merged;
  }

  /**
   * Shared "allow for this session" semantics for permission prompts. Concrete
   * agents still translate the resulting decision into their vendor protocol.
   */
  protected createSessionPermissionUpdates(
    fields: Record<string, unknown> = {},
  ): SessionPermissionUpdate[] {
    return [createSessionPermissionUpdate(fields)];
  }

  /**
   * Vendor SDKs may suggest persistent updates. Maker's UI action is explicitly
   * session-scoped, so agents normalize those suggestions before exposing them.
   */
  protected normalizeSessionPermissionSuggestions(
    suggestions?: readonly unknown[] | null,
  ): SessionPermissionUpdate[] | undefined {
    const updates = coerceSessionPermissionUpdates(suggestions);
    return updates.length > 0 ? updates : undefined;
  }

  protected permissionDecisionRequestsSessionApproval(
    decision: Extract<InteractionDecision, { kind: 'permission' }>,
  ): boolean {
    return hasSessionPermissionUpdates(decision);
  }

  /**
   * 启动一个新会话或恢复已有会话。
   * 子类负责用 deps.binaryPath / auth / runtimeConfig 组装 env / spawn / 包装 SDK。
   */
  abstract startSession(opts: StartSessionOptions): Promise<AgentSessionHandle>;

  /**
   * Agent 内置 command 白名单 —— ChatInput `/` palette 的 'agent-builtin' 类目。
   *
   * 同步、半静态: 子类返回硬编码常量数组(见 claude-code/commands.ts)。
   * 不从 SDK 自动派生 —— 由开发者显式选择想暴露给用户的子集, SDK 支持
   * 但白名单未列出的命令不会进 palette。
   *
   * 执行方式: desktop 把 `/<name> [args]` 当 prompt 前缀直接 send 给当前会话,
   * 由 agent 自己识别处理。
   */
  listAgentCommands(): AgentBuiltinCommand[] {
    return [];
  }

  /** Filter only the palette projection; management discovery retains disabled sources. */
  filterActiveSkillCommands(result: ListAgentSkillsResult, remoteHostId?: string, snapshot?: readonly string[]): ListAgentSkillsResult {
    const disabled = remoteHostId ? [] : snapshot ?? this.deps.getDisabledSkillPaths?.() ?? [];
    if (disabled.length === 0) return result;
    return { ...result, skills: result.skills.filter((skill) => !skill.path || !(snapshot
      ? disabled.includes(canonicalSkillPath(skill.path)) : isSkillDisabled(skill.path, disabled))) };
  }


  /**
   * Agent 用户/项目目录扫描出的 skill 列表 —— ChatInput `/` palette 的
   * 'agent-skill' 类目。
   *
   * 异步、有 IO: Claude Code 扫 ~/.claude/{commands,skills}, Codex 走
   * app-server skills/list。子类自己负责缓存策略与未授权静默处理。
   * 默认无实现, 不暴露任何 skill。
   */

  async listAgentSkills(opts: ListAgentSkillsOptions): Promise<ListAgentSkillsResult> {
    void opts;
    return { skills: [] };
  }

  /** Runtime-accurate Skill discovery for host-side authorization checks. */
  async listRuntimeSkills(opts: ListRuntimeSkillsOptions): Promise<ListAgentSkillsResult> {
    return this.listAgentSkills(opts);
  }

  /**
   * ChatInput `@` palette entries for this agent kind.
   *
   * Default: workspace files/directories only. Agents can extend or replace this
   * when their native UX exposes additional @ resources.
   */
  async scanAtResources(opts: ScanAtResourcesOptions): Promise<ScanAtResourcesResult> {
    return scanWorkspaceFileResources(opts.workingDir, opts.cap, { query: opts.query });
  }

  /**
   * 列出本 agent 认识的所有本地 customization (skill / command / agent / ...)。
   *
   * 与 listSlashCommands 的关系:
   * - listSlashCommands 是 ChatInput `/` 菜单视图: 只取 enabled 的、扁平化、按 name 去重
   * - listCustomizations 是"原始全集": SkillHub 这类外部消费者要看到 disabled 的
   *   skill / 区分 command 和 skill / 拿 frontmatter 等元数据
   *
   * 实现约定:
   * - Claude Code 返回 kind ∈ {skill, command, agent}
   * - Codex 返回 kind = 'skill' (协议本身只有 skill 概念)
   * - 单个 source 失败 (目录读不了 / RPC 报错) 收集进 errors, 不整体抛
   *
   * 默认实现: 空数组 + 空 errors。子类按自家发现方式覆盖。
   */
  async listCustomizations(opts: ListCustomizationsOptions): Promise<ListCustomizationsResult> {
    void opts;
    return { items: [], errors: [] };
  }

  /**
   * 一次性 LLM 调用 —— 跑完即结束, 不开 session、不进事件流, 没有 turn 概念。
   *
   * 用途: 给会话起标题 / 合成 prompt 摘要 / commit msg 命名 等
   * "agent 自己说一句话" 类的辅助任务。
   *
   * 各 agent 选自家最便宜的可用模型实现, 鉴权 / API 路径与 startSession 同源
   * (确保 OAuth-only 用户也能用):
   *   - Claude → sdkQuery + haiku-4-5 + maxTurns:1
   *   - Codex  → Codex SDK startThread + gpt-5.4-mini
   * 调用方不关心用哪个模型, 只拿一个 string。
   *
   * 子类可选实现; 不实现时调到这里, 抛 NotSupportedError。
   */
  async oneShot(prompt: string, opts?: OneShotOptions): Promise<string> {
    void prompt; void opts;
    return this.throwNotSupported('oneShot', 'not-implemented');
  }

  /**
   * Fork 一条已有的 SDK session, 不依赖 live session。
   *
   * 调用语义:
   *   - 输入 sourceSdkSessionId + agent-specific 截断信息
   *   - 子类按各自协议 fork; Claude 额外返回 oldUuid → newUuid 映射
   *     (调用方拿来 remap agentMeta, 见 ForkSdkSessionResult)
   *   - 不动 maker 这边的 sessions / 不开 live session
   *
   * Claude / Codex 端各自实现;不支持的 agent 默认抛 NotSupportedError。
   */
  async forkSdkSession(opts: ForkSdkSessionOptions): Promise<ForkSdkSessionResult> {
    void opts;
    return this.throwNotSupported('forkSdkSession', 'sdk-missing');
  }

  async requiresCodexThreadHostTransfer(
    opts: Pick<StartSessionOptions, 'sessionId' | 'model' | 'providerId' | 'reviewMode' | 'remoteHostId'> & { threadId: string },
  ): Promise<boolean> {
    void opts;
    return false;
  }

  // ── Auth 透传到 deps.auth ────────────────────────────────────────────────
  // Maker 不直接访问 agent.deps (protected), 通过这层 thin façade 暴露给 host
  // 的 maker:auth:* IPC handler。BaseAgent 把"agent 的鉴权"作为一等公民,
  // 跟 startSession / oneShot / fork 同级 —— 调用方不需要知道底层 AuthAdapter。

  getAuthState() {
    return this.deps.auth.getState();
  }

  triggerLogin(opts?: AuthLoginOptions) {
    return this.deps.auth.triggerLogin(opts);
  }

  logout() {
    return this.deps.auth.logout();
  }

  /**
   * 刷新 agent 本机运行时暴露的模型清单。
   *
   * 默认无运行时发现能力,返回 false;Codex 覆盖后通过 app-server `model/list`
   * 拉完整分页快照。返回值表示快照是否仍属于当前 host 且已由宿主成功应用。
   */
  async refreshLocalModels(_options?: RefreshLocalModelsOptions): Promise<boolean> {
    return false;
  }

  /**
   * Read provider account rate limits without starting a model turn.
   * Codex implements this through the app-server control plane.
   */
  async readAccountRateLimits(_providerId?: string): Promise<AccountRateLimitsResponse> {
    return this.throwNotSupported('account:rate-limits:read', 'not-implemented');
  }

  /** Consume one banked provider reset credit without starting a model turn. */
  async consumeAccountRateLimitResetCredit(
    params: ConsumeAccountRateLimitResetCreditParams,
    _providerId?: string,
  ): Promise<ConsumeAccountRateLimitResetCreditResponse> {
    void params;
    return this.throwNotSupported('account:rate-limit-reset:consume', 'not-implemented');
  }

  /**
   * 取消正在进行的登录。
   * AuthAdapter 不实现 cancelLogin (Claude 是同步弹窗, 没东西可 cancel) 时此方法 no-op。
   */
  cancelLogin(): void {
    this.deps.auth.cancelLogin?.();
  }

  /** 同步取 binary path (host 注入时已存在, 构造期校验过)。供 maker:agent:status 用。 */
  getBinaryPath(): string {
    return this.deps.binaryPath;
  }

  // ── Memory 控制 (子类实现) ─────────────────────────────────────────────
  // 范围: 仅 agent "自动记忆" (Claude auto-memory / Codex experimental memories),
  // 不含手写的 CLAUDE.md / AGENTS.md 文档 (那些走 settingSources / project_doc_max_bytes)。
  // 详见 packages/maker-core/src/types/memory.ts。

  /**
   * 当前 memory 状态 + (可选) 用量元数据。
   *
   * 子类实现要点:
   *  - Claude: enabled = this.memoryOverride ?? true (SDK 默认 true);
   *            stats 可选, 扫 ~/.claude/projects/<sanitized-cwd>/memory/
   *  - Codex:  调 config/read 读 effective config 的 features.memories
   *
   * 默认实现抛 NotSupportedError, 让 capabilities.memory.supported 与方法实现保持一致 —
   * 不实现 = 不支持。
   */
  async getMemoryStatus(): Promise<MemoryStatus> {
    return this.throwNotSupported('memory:get', 'not-implemented');
  }

  /**
   * 改 memory 启用状态。
   *
   * 子类实现要点:
   *  - 必须更新 this.memoryOverride, 让后续 startSession 拿到一致的值
   *  - Claude: 当前实现只更新 memoryOverride, 不向 live SDK Query 传 applyFlagSettings
   *            (BaseAgent 不追踪 active sessions), 返 effective:'next-session'
   *  - Codex:  调 experimentalFeature/enablement/set { memories } RPC,
   *            server 端 in-memory enablement 覆盖 config.toml + 热重载所有 live thread,
   *            返 effective:'immediate'
   *
   * UI 看到 effective:'next-session' 应给用户提示 "需新会话生效"。
   */
  async setMemory(enabled: boolean): Promise<MemorySetResult> {
    void enabled;
    return this.throwNotSupported('memory:set', 'not-implemented');
  }

  /**
   * 清空 agent 已积累的所有自动记忆。**全局**, 不限当前 cwd
   * (跟 setMemory 的全局 toggle 语义对称)。
   *
   * 子类实现要点:
   *  - Claude: 遍历 ~/.claude/projects/*\/memory/ 全删 (per-cwd 子目录, 不动 *.jsonl 历史)
   *  - Codex:  调 memory/reset RPC, server 端清 <CODEX_HOME>/memories/ + sqlite stage 数据
   *
   * 失败抛错; 调用方决定 UI 怎么处理 (toast / dialog)。
   */
  async resetMemory(): Promise<MemoryResetResult> {
    return this.throwNotSupported('memory:reset', 'not-implemented');
  }

  /**
   * Agent 进程级资源回收 — app.before-quit 时由 Maker.shutdown() 调一次。
   *
   * Claude: SDK 自带 per-session lifecycle, 没 agent 级共享子进程, 默认 no-op。
   * Codex (路线 A shared app-server): 需要在这里 shutdown AppServerHost,
   *   否则 codex app-server 子进程在 Windows 上不会随父进程死, 成孤儿。
   *
   * 子类可选实现; 不实现 = no-op。**幂等**: 多次调用安全。
   */
  async dispose(): Promise<void> {
    // 默认 no-op
  }

  /**
   * 默认的"不支持"抛错助手。子类不实现某能力时调此方法。
   */
  protected throwNotSupported(capability: string, reason: 'sdk-missing' | 'not-implemented' | 'platform-limited' = 'sdk-missing', upstreamRef?: string): never {
    throw new NotSupportedError(capability, { supported: false, reason, upstreamRef });
  }
}