@armadra/agent 0.0.0-stage → 0.2.1

package/dist/cli/bootstrap.js

@@ -0,0 +1,398 @@
+/**
+ * 启动序列编排（设计 §11.1 第 3–16 步、§11.2）。[B5]
+ *
+ * `bootstrap(args, deps, io)` 跑第 3–14 步并返回 Runtime（SDK `createRuntime()` 复用）；
+ * `runCli(argv, deps, io)` 在其前后加上第 2 步（参数）与第 15–16 步（模式分派），返回退出码。
+ * 每步失败抛 `StartupError{exitCode}`；具体实现经 RuntimeDeps 注入（见 cli/deps.ts）。
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { defaultAuthFilePath } from "../config/auth-file.js";
+import { findContextFiles } from "../config/context-files.js";
+import { loadConfigFile } from "../config/load.js";
+import { mergeBaseLayers, mergeProjectAndCli } from "../config/merge.js";
+import { CONFIG_FILE, ensurePaths, projectFile, resolvePaths, userFile } from "../config/paths.js";
+import { loadProfile } from "../config/profile.js";
+import { decideTrust } from "../config/trust.js";
+import { AmaError, StartupError, isAmaError } from "../errors.js";
+import { loadHookConfigs } from "../hooks/config.js";
+import { HookDispatcher } from "../hooks/dispatcher.js";
+import { AgentEventBus, createHostApi } from "../host/api-impl.js";
+import { activateHost, disposeHost } from "../host/loader.js";
+import { HELP_TEXT, parseArgs, UsageError } from "./args.js";
+import { ExitCode } from "./exit-codes.js";
+import { applyProfile, applyToolFilters, decideMode, defaultSendUser, instructionSources, resolveModel, sessionRequestOf, sourceOf, step, thinkingOf, toStartupError, } from "./startup-steps.js";
+/** §11.1 第 3–14 步。 */
+export async function bootstrap(argsIn, deps, io) {
+    const warnings = [];
+    const warn = (message) => {
+        warnings.push(message);
+    };
+    // 3. profile
+    let args = argsIn;
+    let profile;
+    if (args.profile !== undefined) {
+        const profilePath = args.profile;
+        profile = await step(ExitCode.Config, "profile", () => loadProfile(profilePath, io.cwd));
+        warnings.push(...profile.warnings);
+        args = applyProfile(args, profile);
+    }
+    // 4. 模式
+    const mode = decideMode(args, io);
+    const interactive = mode === "interactive" || mode === "line";
+    // 5. 目录
+    const paths = await step(ExitCode.Config, "目录", () => {
+        const resolved = resolvePaths({ env: io.env, cwd: io.cwd, sessionDirFlag: args.sessionDir });
+        ensurePaths(resolved);
+        return resolved;
+    });
+    // 6. 用户级 + profile.config
+    const base = await step(ExitCode.Config, "配置", () => {
+        const user = loadConfigFile("config", userFile(paths, CONFIG_FILE));
+        if (user !== undefined)
+            warnings.push(...user.warnings);
+        return mergeBaseLayers({
+            user: user?.value,
+            profile: profile?.config,
+            hasProfile: profile !== undefined,
+        });
+    });
+    // 7. 会话
+    let request = sessionRequestOf(args);
+    if (request === "pick") {
+        if (!interactive || deps.ui?.pickSession === undefined || deps.sessions.list === undefined) {
+            throw new UsageError("--resume 在非交互模式下需要会话 id");
+        }
+        const items = await step(ExitCode.Session, "会话列表", () => deps.sessions.list?.({ sessionDir: paths.sessionDir, cwd: paths.cwd }) ?? []);
+        const id = await deps.ui.pickSession(items);
+        if (id === undefined)
+            throw new StartupError("session_not_found", "未选择会话", ExitCode.Session);
+        request = { kind: "resume", id };
+    }
+    const sessionRequest = request;
+    const sessionManager = await step(ExitCode.Session, "会话", () => deps.sessions.open(sessionRequest, { sessionDir: paths.sessionDir, cwd: paths.cwd }));
+    let sessionCwd = sessionManager.cwd;
+    if (!existsSync(sessionCwd)) {
+        const replacement = interactive ? await deps.ui?.askCwd?.(sessionCwd) : undefined;
+        if (replacement === undefined) {
+            throw new StartupError("session_corrupt", `会话的工作目录不存在：${sessionCwd}`, ExitCode.Session);
+        }
+        sessionCwd = resolve(replacement);
+    }
+    const runtimePaths = { ...paths, cwd: sessionCwd };
+    // 8. 信任（以会话 cwd 为准）
+    const trust = await step(ExitCode.Config, "信任", () => decideTrust({
+        cwd: sessionCwd,
+        configDir: paths.configDir,
+        flag: args.trust,
+        profileTrust: profile?.trustProject,
+        interactive,
+        prompt: deps.ui?.promptTrust,
+    }));
+    // 9. 项目级配置（只能收紧）+ 命令行
+    const merged = await step(ExitCode.Config, "项目配置", () => {
+        const project = loadConfigFile("config", projectFile(sessionCwd, CONFIG_FILE));
+        if (project !== undefined)
+            warnings.push(...project.warnings);
+        return mergeProjectAndCli(base, project?.value, {
+            thinkingLevel: args.thinking,
+            permissionMode: args.permissionMode,
+            allow: args.allow,
+            deny: args.deny,
+            quietStartup: args.quietStartup,
+            tuiMode: args.tuiMode,
+            toolsPreset: args.toolsPreset,
+            codemode: args.codemode,
+        });
+    });
+    warnings.push(...merged.warnings);
+    const config = merged.config;
+    // 10. 资源发现
+    const context = findContextFiles({ cwd: sessionCwd, configDir: paths.configDir });
+    warnings.push(...context.warnings);
+    const discovered = deps.resources === undefined
+        ? { skills: [], prompts: [], warnings: [] }
+        : await step(ExitCode.Config, "Skill 发现", () => deps.resources?.discover({
+            cwd: sessionCwd,
+            configDir: paths.configDir,
+            trusted: trust.trusted,
+            extraSkillDirs: [...args.skillDirs, ...(config.skills?.dirs ?? [])],
+            promptDirs: profile?.promptDirs ?? [],
+        }) ?? { skills: [], prompts: [], warnings: [] });
+    warnings.push(...discovered.warnings);
+    const hookConfig = await step(ExitCode.Config, "hooks.json", () => loadHookConfigs({
+        configDir: paths.configDir,
+        cwd: sessionCwd,
+        profileHooksFile: profile?.hooksFile,
+        trusted: trust.trusted,
+        defaultTimeoutMs: config.hooks?.timeoutMs,
+    }));
+    warnings.push(...hookConfig.warnings);
+    const instructions = instructionSources(args.instructions, io.cwd);
+    const resources = {
+        contextFiles: context.files.map((f) => ({ path: f.path, content: f.content })),
+        skills: discovered.skills,
+        prompts: discovered.prompts,
+        instructions,
+    };
+    // 11. 供应商与模型
+    const providers = await step(ExitCode.Config, "供应商", () => deps.providers.create({
+        config,
+        cwd: sessionCwd,
+        authFile: args.authFile !== undefined
+            ? resolve(io.cwd, args.authFile)
+            : defaultAuthFilePath(paths.configDir),
+        authEnv: profile?.authEnv ?? true,
+        ...(args.apiKey !== undefined && args.model !== undefined
+            ? {
+                cliApiKey: {
+                    apiKey: args.apiKey,
+                    modelRef: args.model,
+                    ...(args.provider !== undefined ? { provider: args.provider } : {}),
+                },
+            }
+            : {}),
+    }));
+    const { model, provider } = await step(ExitCode.NoModel, "模型", () => resolveModel(args, providers, sessionManager, config.defaultModel, deps, interactive));
+    const thinkingLevel = thinkingOf(args, sessionManager, config.thinkingLevel);
+    // 12. 工具注册表
+    const tools = await step(ExitCode.RuntimeError, "工具", () => deps.tools.create({ config, cwd: sessionCwd, mode }));
+    for (const name of config.tools?.disabled ?? []) {
+        if (tools.get(name) === undefined)
+            warn(`config tools.disabled：未知工具 ${name}，已忽略`);
+        else
+            tools.disable(name);
+    }
+    // 13. 宿主适配器
+    let session;
+    const events = new AgentEventBus((level, message, detail) => {
+        if (level === "warn" || level === "error")
+            warn(`${message}${detail instanceof Error ? `：${detail.message}` : ""}`);
+    });
+    const binding = createHostApi({
+        mode,
+        env: io.env,
+        session: {
+            id: () => session?.state.sessionId ?? sessionManager.id,
+            file: () => (session !== undefined ? session.state.sessionFile : sessionManager.file()),
+            cwd: () => session?.state.cwd ?? sessionCwd,
+            model: () => session?.state.model ?? { provider: model.provider, id: model.id },
+        },
+        tools,
+        bus: events,
+        sendUser: (text, origin) => {
+            if (session === undefined)
+                return Promise.reject(new AmaError("busy", "会话尚未就绪"));
+            return (deps.sendUser ?? defaultSendUser)(session, text, origin);
+        },
+        stderr: io.stderr,
+    });
+    let uiBroker;
+    const hostSpec = args.host;
+    let host;
+    if (hostSpec !== undefined) {
+        host = await step(ExitCode.HostOrHook, "宿主适配器", () => activateHost({ module: hostSpec, binding, cwd: io.cwd }));
+    }
+    let shutdown;
+    try {
+        applyToolFilters(args, tools);
+        // 14. 组装 AgentSession、session_start、SessionStart Hook
+        const unattended = mode === "print";
+        const builtinDeny = config.permission?.builtinDeny;
+        const permission = await step(ExitCode.Config, "权限", () => deps.permissions.create({
+            mode: config.permission?.mode ?? "default",
+            rules: merged.ruleSpecs,
+            unattended,
+            cwd: sessionCwd,
+            ...(builtinDeny !== undefined ? { builtinDeny } : {}),
+        }));
+        const hooks = new HookDispatcher({
+            hooks: hookConfig.hooks,
+            context: () => ({
+                sessionId: session?.state.sessionId ?? sessionManager.id,
+                ...((session?.state.sessionFile ?? sessionManager.file()) !== undefined
+                    ? { sessionFile: (session?.state.sessionFile ?? sessionManager.file()) }
+                    : {}),
+                cwd: session?.state.cwd ?? sessionCwd,
+                model: session?.state.model ?? { provider: model.provider, id: model.id },
+                permissionMode: session?.state.permissionMode ?? permission.mode,
+                depth: 0,
+                ...(host !== undefined ? { host: host.adapter.id } : {}),
+            }),
+            onExecuted: (r) => void events.emit("hook_executed", {
+                event: r.event,
+                command: r.command,
+                exitCode: r.exitCode,
+                durationMs: r.durationMs,
+            }),
+            onWarning: warn,
+        });
+        let sessionStartContext;
+        const source = sourceOf(sessionRequest, sessionManager);
+        const assembly = {
+            mode,
+            paths: runtimePaths,
+            config,
+            trust,
+            resources,
+            providers,
+            model,
+            provider,
+            thinkingLevel,
+            sessionManager,
+            source,
+            hooks,
+            permission,
+            tools,
+            events,
+            host: {
+                handle: host,
+                broker: binding.broker,
+                instructions: binding.instructions,
+                warmingDecider: binding.warmingDecider,
+            },
+            uiBroker: () => uiBroker,
+            onSessionReplaced: (next) => {
+                session = next;
+            },
+            sessionStartContext: () => sessionStartContext,
+            unattended,
+            warn,
+        };
+        session = await step(ExitCode.RuntimeError, "会话组装", () => deps.session.create(assembly));
+        const active = session;
+        let disposed;
+        shutdown = (reason) => {
+            disposed ??= (async () => {
+                await events.emit("session_shutdown", {});
+                await hooks.run("SessionEnd", { reason }).catch(() => undefined);
+                await disposeHost(host, (e) => warn(`宿主适配器 dispose 失败：${String(e)}`));
+                // 会话被替换过时 dispose 当前那个（旧会话由替换方负责）
+                await (session ?? active).dispose();
+            })();
+            return disposed;
+        };
+        await events.emit("session_start", {
+            sessionId: active.state.sessionId,
+            ...(active.state.sessionFile !== undefined ? { sessionFile: active.state.sessionFile } : {}),
+            cwd: active.state.cwd,
+            reason: source,
+        });
+        const outcome = await hooks.run("SessionStart", { source });
+        if (outcome.decision === "block") {
+            throw new StartupError("hook_failed", `SessionStart Hook 阻止启动：${outcome.reason ?? "（无原因）"}`, ExitCode.HostOrHook);
+        }
+        sessionStartContext = outcome.additionalContext;
+        const finalShutdown = shutdown;
+        return {
+            mode,
+            paths: runtimePaths,
+            config,
+            trust,
+            resources,
+            providers,
+            model,
+            thinkingLevel,
+            sessionManager,
+            session: active,
+            hooks,
+            host,
+            permission,
+            tools,
+            approvals: {
+                setUiBroker: (broker) => {
+                    uiBroker = broker;
+                },
+            },
+            notifier: { set: (fn) => binding.setNotify(fn) },
+            warnings,
+            dispose: (reason = "exit") => finalShutdown(reason),
+        };
+    }
+    catch (error) {
+        if (shutdown !== undefined)
+            await shutdown("exit").catch(() => undefined);
+        else
+            await disposeHost(host);
+        throw toStartupError(error, ExitCode.RuntimeError, "启动");
+    }
+}
+/** 非交互模式接管 stdout：console.log / info / debug 改写到 stderr；返回还原函数。 */
+export function takeOverStdout() {
+    const saved = { log: console.log, info: console.info, debug: console.debug };
+    console.log = console.info = console.debug = (...items) => console.error(...items);
+    return () => {
+        console.log = saved.log;
+        console.info = saved.info;
+        console.debug = saved.debug;
+    };
+}
+export function isTerminalInitError(error) {
+    return isAmaError(error) && error.code === "terminal_init_failed";
+}
+/** 第 2–16 步：参数 → bootstrap → 模式；返回退出码（不含子命令）。 */
+export async function runCli(argv, deps, io) {
+    let args;
+    try {
+        const parsed = parseArgs(argv);
+        if (parsed.kind !== "run")
+            throw new UsageError("子命令应由 main 分派");
+        args = parsed.args;
+    }
+    catch (error) {
+        return reportError(error, io);
+    }
+    if (args.help) {
+        io.stdout(HELP_TEXT);
+        return ExitCode.Ok;
+    }
+    if (deps === undefined) {
+        io.stderr("ama: 运行时尚未装配（集成批次通过 registerRuntimeDeps 注入实现）\n");
+        return ExitCode.RuntimeError;
+    }
+    let runtime;
+    try {
+        runtime = await bootstrap(args, deps, io);
+    }
+    catch (error) {
+        return reportError(error, io);
+    }
+    const restore = runtime.mode === "print" || runtime.mode === "rpc" ? takeOverStdout() : () => undefined;
+    try {
+        if (runtime.mode !== "interactive")
+            for (const w of runtime.warnings)
+                io.stderr(`ama: 警告：${w}\n`);
+        const context = { args, prompt: args.prompt, io };
+        const runner = deps.modes[runtime.mode];
+        if (runner === undefined)
+            throw new AmaError("not_implemented", `模式 ${runtime.mode} 尚未装配`, { exitCode: 1 });
+        try {
+            return await runner(runtime, context);
+        }
+        catch (error) {
+            const line = deps.modes.line;
+            if (runtime.mode !== "interactive" || !isTerminalInitError(error) || line === undefined)
+                throw error;
+            io.stderr(`ama: 警告：终端初始化失败，降级为行式界面（${error.message}）\n`);
+            return await line(runtime, context);
+        }
+    }
+    catch (error) {
+        return reportError(error, io, ExitCode.RuntimeError);
+    }
+    finally {
+        await runtime.dispose("exit").catch(() => undefined);
+        restore();
+    }
+}
+export function reportError(error, io, fallback = ExitCode.RuntimeError) {
+    if (error instanceof UsageError) {
+        io.stderr(`ama: ${error.message}\n（ama --help 查看用法）\n`);
+        return ExitCode.Usage;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    io.stderr(`ama: ${message}\n`);
+    if (isAmaError(error) && error.exitCode !== undefined)
+        return error.exitCode;
+    return fallback;
+}

package/dist/cli/compose-providers.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 组装根：供应商注册表（实施计划 §1.1 `providers.create`）。[B6]
+ *
+ * - `ProviderBuildInput` → `ProviderRegistry`：auth.json（`--auth-file` 或用户级缺省，已由 bootstrap
+ *   解析成一个路径，所以 `userAuthFile: null`）、环境变量开关、`--api-key` 只作用于 `--model` 所属的
+ *   供应商（无斜杠的模型名先用一个不带 cli key 的注册表解析出供应商）。
+ * - `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL`（第三波 §2.3）：与 key 同一份 `env`、同一个 `authEnv`
+ *   开关进注册表，内置 openai / anthropic 指向中转站；profile.authEnv=false 时一并不读。
+ * - SDK 追加的供应商（`ProviderData[]`）折成 `config.providers` 条目，走同一条合并路径。
+ * - 零配置（设计 §10.0）：没有 `defaultModel`、也没有任何需要 key 的供应商配了 key 时，探测本地
+ *   ollama / lmstudio（短超时），把枚举到的模型加进注册表，供 `pickDefaultModel` 选用。
+ */
+import type { ApiRegistry } from "../ai/apis/api.js";
+import { ProviderRegistry } from "../ai/providers/registry.js";
+import type { ProviderData } from "../ai/types.js";
+import type { AmaConfig, ProviderConfig } from "../config/types.js";
+import type { ProviderBuildInput } from "./deps.js";
+export declare const LOCAL_PROBE_TIMEOUT_MS = 300;
+export declare const NO_LOCAL_PROBE_ENV = "AMA_NO_LOCAL_PROBE";
+export interface ProviderComposeOptions {
+    /** 追加 / 覆盖的供应商（SDK）。 */
+    providers?: readonly ProviderData[] | undefined;
+    apis?: ApiRegistry | undefined;
+    /** key 发现用的环境（缺省 process.env）。 */
+    env?: NodeJS.ProcessEnv | undefined;
+    /** 注册 fake 供应商（缺省 true：测试与 `--model fake/echo` 依赖）。 */
+    includeFake?: boolean | undefined;
+    /** 零配置时探测本地服务（缺省 true；`AMA_NO_LOCAL_PROBE=1` 关闭）。 */
+    probeLocal?: boolean | undefined;
+    probeTimeoutMs?: number | undefined;
+    warn?: ((message: string) => void) | undefined;
+}
+export declare function providerConfigOf(provider: ProviderData): ProviderConfig;
+export declare function withExtraProviders(config: AmaConfig, providers: readonly ProviderData[] | undefined): AmaConfig;
+export declare function buildProviderRegistry(input: ProviderBuildInput, options?: ProviderComposeOptions): Promise<ProviderRegistry>;
+/** 本地服务（无需 key、模型表为空）的模型枚举；连不上静默跳过。 */
+export declare function probeLocalProviders(registry: ProviderRegistry, timeoutMs?: number): Promise<string[]>;

package/dist/cli/compose-providers.js

@@ -0,0 +1,104 @@
+/**
+ * 组装根：供应商注册表（实施计划 §1.1 `providers.create`）。[B6]
+ *
+ * - `ProviderBuildInput` → `ProviderRegistry`：auth.json（`--auth-file` 或用户级缺省，已由 bootstrap
+ *   解析成一个路径，所以 `userAuthFile: null`）、环境变量开关、`--api-key` 只作用于 `--model` 所属的
+ *   供应商（无斜杠的模型名先用一个不带 cli key 的注册表解析出供应商）。
+ * - `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL`（第三波 §2.3）：与 key 同一份 `env`、同一个 `authEnv`
+ *   开关进注册表，内置 openai / anthropic 指向中转站；profile.authEnv=false 时一并不读。
+ * - SDK 追加的供应商（`ProviderData[]`）折成 `config.providers` 条目，走同一条合并路径。
+ * - 零配置（设计 §10.0）：没有 `defaultModel`、也没有任何需要 key 的供应商配了 key 时，探测本地
+ *   ollama / lmstudio（短超时），把枚举到的模型加进注册表，供 `pickDefaultModel` 选用。
+ */
+import { ProviderRegistry, discoverLocalModels } from "../ai/providers/registry.js";
+export const LOCAL_PROBE_TIMEOUT_MS = 300;
+export const NO_LOCAL_PROBE_ENV = "AMA_NO_LOCAL_PROBE";
+/** 模型协议与供应商不同时保留模型级 `api`（同一中转下的模型可走不同协议）。 */
+function modelConfigOf(model, providerApi) {
+    const { provider: _p, api, ...rest } = model;
+    return api !== providerApi ? { ...rest, api } : rest;
+}
+export function providerConfigOf(provider) {
+    const config = {
+        name: provider.name,
+        api: provider.api,
+        baseUrl: provider.baseUrl,
+        envKeys: [...provider.envKeys],
+        requiresApiKey: provider.requiresApiKey,
+        models: provider.models.map((model) => modelConfigOf(model, provider.api)),
+    };
+    if (provider.authHeader !== undefined)
+        config.authHeader = provider.authHeader;
+    if (provider.headers !== undefined)
+        config.headers = { ...provider.headers };
+    if (provider.compat !== undefined)
+        config.compat = { ...provider.compat };
+    return config;
+}
+export function withExtraProviders(config, providers) {
+    if (providers === undefined || providers.length === 0)
+        return config;
+    const merged = { ...(config.providers ?? {}) };
+    for (const provider of providers)
+        merged[provider.id] = providerConfigOf(provider);
+    return { ...config, providers: merged };
+}
+export async function buildProviderRegistry(input, options = {}) {
+    const config = withExtraProviders(input.config, options.providers);
+    const make = (cliApiKey) => new ProviderRegistry({
+        config,
+        apis: options.apis,
+        includeFake: options.includeFake ?? true,
+        keys: {
+            cliApiKey,
+            authFile: input.authFile,
+            userAuthFile: null,
+            useEnv: input.authEnv,
+            env: options.env,
+        },
+        onWarning: options.warn,
+    });
+    let registry = make();
+    const cli = input.cliApiKey;
+    if (cli !== undefined) {
+        let provider = cli.provider;
+        if (provider === undefined) {
+            const found = registry.findModel(cli.modelRef);
+            if (found.ok)
+                provider = found.provider.id;
+        }
+        if (provider !== undefined)
+            registry = make({ provider, apiKey: cli.apiKey });
+    }
+    const env = options.env ?? process.env;
+    const probe = options.probeLocal ?? env[NO_LOCAL_PROBE_ENV] !== "1";
+    if (probe && config.defaultModel === undefined && !anyKeyConfigured(registry)) {
+        await probeLocalProviders(registry, options.probeTimeoutMs ?? LOCAL_PROBE_TIMEOUT_MS);
+    }
+    return registry;
+}
+function anyKeyConfigured(registry) {
+    return registry
+        .list()
+        .some((provider) => provider.requiresApiKey && registry.hasConfiguredKey(provider.id));
+}
+/** 本地服务（无需 key、模型表为空）的模型枚举；连不上静默跳过。 */
+export async function probeLocalProviders(registry, timeoutMs = LOCAL_PROBE_TIMEOUT_MS) {
+    const local = registry
+        .list()
+        .filter((p) => !p.requiresApiKey && p.id !== "fake" && p.models.length === 0);
+    const found = [];
+    await Promise.all(local.map(async (provider) => {
+        try {
+            const models = await discoverLocalModels(provider, { timeoutMs });
+            if (models.length === 0)
+                return;
+            registry.addModels(provider.id, models);
+            found.push(provider.id);
+        }
+        catch {
+            // 本地服务未运行：不是错误
+        }
+    }));
+    return found;
+}

package/dist/cli/compose-session.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 组装根：`SessionAssembly` → `AgentSessionImpl`（实施计划 §1.2、§1.4）。[B6]
+ *
+ * - 审批：一个 `ApprovalBrokerChain`（串行队列）作 B2 `brokers` 的唯一元素；链首代理宿主 broker
+ *   （`assembly.host.broker()` 每次现取，宿主可在任意时刻 `setBroker`），链尾代理模式层经
+ *   `Runtime.approvals.setUiBroker` 晚绑定的 UI broker。子 Agent 的请求由 B2 包上 `context.depth`
+ *   后进同一条链，排在父对话框之后。
+ * - 系统提示：AGENTS.md + `--instructions` 文件（project_context 节）、Skill 索引（read 读取）、
+ *   宿主 instructions（host 节，读成文本）。SessionStart Hook 的 additionalContext 与宿主后加的
+ *   指令在每次提示展开前 `updateSystem`——值不变时不产生补丁，前缀保持逐字节稳定（§9.1）。
+ * - 事件：`SessionEvent` 桥接到宿主 `AgentEventBus`（§1.4 表；hook_executed、session_start /
+ *   session_shutdown 由 bootstrap 发，不桥接）；第三波加 `cache_miss` / `context_pressure`。
+ * - 缓存（第三波 §1.12）：config `cache` 段（项目级已在合并时忽略）+ `AMA_CACHE_WARMING` /
+ *   `AMA_CACHE_RETENTION` 覆盖 → 会话的 `cache` 设置；宿主 `cache.onWarmingDecision` 每次现取。
+ * - 会话切换：`switchSession()` 复用同一份装配材料建新会话，`assembly.onSessionReplaced(next)`
+ *   让宿主访问、Hook 公共字段与退出 dispose 跟随新会话。
+ */
+import { AgentSessionImpl } from "../agent/session.js";
+import type { AgentSession, CacheSettings, SessionEvent } from "../agent/types.js";
+import { type AmaConfig } from "../config/types.js";
+import type { AgentEventBus } from "../host/api-impl.js";
+import type { Skill } from "../skills/discover.js";
+import { type PromptTemplate } from "../skills/templates.js";
+import type { SessionAssembly } from "./deps.js";
+import type { Runtime } from "./runtime.js";
+/** createRuntimeDeps 闭包里跨步骤共享的状态。 */
+export interface ComposeState {
+    /** 第 10 步发现的完整 Skill（`/skill:` 展开与索引用）。 */
+    skills: Skill[];
+    templates: PromptTemplate[];
+    /** 没有 warn 通道的步骤（tools.create 等）留下的 warning，组装会话时交给 assembly.warn。 */
+    warnings: string[];
+    /** 当前会话（工具工厂的 `session()`）。 */
+    session: AgentSession | undefined;
+}
+export declare function emptyComposeState(): ComposeState;
+export type LogFn = (level: "debug" | "info" | "warn" | "error", message: string) => void;
+export interface SessionComposeOptions {
+    /** 审批超时（缺省 10 分钟）；`AMA_APPROVAL_TIMEOUT_MS` 覆盖。 */
+    approvalTimeoutMs?: number | undefined;
+    log?: LogFn | undefined;
+}
+/** `AMA_LOG=debug|info|warn|error`（缺省 warn）过滤后写 stderr。 */
+export declare function stderrLog(env?: NodeJS.ProcessEnv): LogFn;
+/** config `cache` 段 + 环境变量 → 会话缓存设置；非法的环境变量值忽略并 warning。 */
+export declare function cacheSettingsFrom(config: Pick<AmaConfig, "cache">, env?: NodeJS.ProcessEnv, warn?: (message: string) => void): Partial<CacheSettings>;
+/** §1.4：SessionEvent → AgentEvents。 */
+export declare function bridgeEvent(event: SessionEvent, bus: AgentEventBus): void;
+/** 第 14 步：组装主会话。 */
+export declare function composeSession(assembly: SessionAssembly, state?: ComposeState, options?: SessionComposeOptions): AgentSessionImpl;
+/** 模式层当前应操作的会话（`switchSession` 之后不再是 `Runtime.session`）。 */
+export declare function currentSession(target: Runtime | AgentSession): AgentSession;
+export type SwitchRequest = {
+    kind: "new";
+} | {
+    kind: "open";
+    file: string;
+} | {
+    kind: "resume";
+    id: string;
+} | {
+    kind: "fork";
+    entryId: string;
+};
+/**
+ * `/new`、`/resume`、`/fork`、RPC `new_session / switch_session / fork`：旧会话发 SessionEnd 后
+ * dispose，新会话复用装配材料，宿主总线发 session_start，再跑 SessionStart Hook。
+ */
+export declare function switchSession(target: Runtime | AgentSession, request: SwitchRequest): Promise<AgentSessionImpl>;