@armadra/agent 0.0.0-stage → 0.3.0

package/dist/cli/compose-session.js

@@ -0,0 +1,370 @@
+/**
+ * 组装根：`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 { readFileSync } from "node:fs";
+import { AgentSessionImpl } from "../agent/session.js";
+import { WARMING_MODES } from "../ai/cache/types.js";
+import { isOverflowErrorText } from "../ai/overflow.js";
+import { CACHE_RETENTIONS } from "../config/types.js";
+import { AmaError, StartupError } from "../errors.js";
+import { ApprovalBrokerChain, DEFAULT_APPROVAL_TIMEOUT_MS } from "../permissions/broker.js";
+import { PermissionPipeline } from "../permissions/pipeline.js";
+import { SessionManager } from "../session/manager.js";
+import { sessionDirForCwd } from "../session/store.js";
+import { expandSkillCommand } from "../skills/expand.js";
+import { formatSkillIndex } from "../skills/index-prompt.js";
+import { expandPromptCommand } from "../skills/templates.js";
+import { PresetToolRegistry } from "../tools/presets.js";
+import { openSession } from "./compose-store.js";
+import { ExitCode } from "./exit-codes.js";
+export function emptyComposeState() {
+    return { skills: [], templates: [], warnings: [], session: undefined };
+}
+const records = new WeakMap();
+const LOG_LEVELS = ["debug", "info", "warn", "error"];
+/** `AMA_LOG=debug|info|warn|error`（缺省 warn）过滤后写 stderr。 */
+export function stderrLog(env = process.env) {
+    const wanted = LOG_LEVELS.indexOf((env["AMA_LOG"] ?? "warn"));
+    const min = wanted < 0 ? 2 : wanted;
+    return (level, message) => {
+        if (LOG_LEVELS.indexOf(level) >= min)
+            process.stderr.write(`ama: [${level}] ${message}\n`);
+    };
+}
+function approvalTimeout(options) {
+    const fromEnv = Number(process.env["AMA_APPROVAL_TIMEOUT_MS"]);
+    if (Number.isFinite(fromEnv) && fromEnv > 0)
+        return fromEnv;
+    return options.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS;
+}
+function sourceText(source, cache, log) {
+    if (source.kind === "text")
+        return source.text;
+    const cached = cache.get(source.path);
+    if (cached !== undefined)
+        return cached;
+    let text = "";
+    try {
+        text = readFileSync(source.path, "utf8");
+    }
+    catch (error) {
+        log("warn", `读取指令文件失败：${source.path}：${error.message}`);
+    }
+    cache.set(source.path, text);
+    return text;
+}
+function hostInstructions(record) {
+    return record.assembly.host.instructions
+        .map((s) => sourceText(s, record.hostTexts, record.log))
+        .filter((t) => t.trim() !== "");
+}
+/** `--instructions` 文件追加在 AGENTS.md 之后（project_context 节，实施计划表 B17）。 */
+function contextFiles(record) {
+    const { resources } = record.assembly;
+    const extra = resources.instructions.map((s) => ({
+        path: s.kind === "file" ? s.path : (s.name ?? "instructions"),
+        content: sourceText(s, record.hostTexts, record.log),
+    }));
+    return [...resources.contextFiles, ...extra.filter((f) => f.content.trim() !== "")];
+}
+function systemInput(record, active) {
+    const system = { contextFiles: contextFiles(record) };
+    const index = formatSkillIndex(record.state.skills, {
+        hasSkillTool: false,
+        hasReadTool: active.includes("read"),
+    });
+    if (index !== "")
+        system.skillsIndex = index;
+    const host = hostInstructions(record);
+    if (host.length > 0)
+        system.hostInstructions = host;
+    const hookContext = record.hookContext();
+    if (hookContext !== undefined && hookContext !== "")
+        system.hookContext = hookContext;
+    return system;
+}
+/** 提示展开前刷新会晚到的系统提示材料（值不变则不产生补丁）。 */
+function refreshSystem(record, session) {
+    const patch = {};
+    const hookContext = record.hookContext();
+    if (hookContext !== undefined && hookContext !== "")
+        patch.hookContext = hookContext;
+    const host = hostInstructions(record);
+    if (host.length > 0)
+        patch.hostInstructions = host;
+    if (Object.keys(patch).length > 0)
+        session.updateSystem(patch);
+}
+async function expandPrompt(record, session, text) {
+    refreshSystem(record, session);
+    const skill = await expandSkillCommand(text, record.state.skills);
+    if (skill?.kind === "unknown") {
+        const hint = skill.available.length > 0 ? `（可用：${skill.available.join(", ")}）` : "";
+        throw new AmaError("skill_not_found", `未知 Skill：${skill.name}${hint}`);
+    }
+    if (skill?.kind === "expanded")
+        return { text: skill.text };
+    const template = await expandPromptCommand(text, record.state.templates);
+    return { text: template?.text ?? text };
+}
+/** config `cache` 段 + 环境变量 → 会话缓存设置；非法的环境变量值忽略并 warning。 */
+export function cacheSettingsFrom(config, env = process.env, warn = () => undefined) {
+    const settings = {};
+    for (const [key, value] of Object.entries(config.cache ?? {})) {
+        if (value !== undefined)
+            settings[key] = value;
+    }
+    const warming = env["AMA_CACHE_WARMING"];
+    if (warming !== undefined && warming !== "") {
+        if (WARMING_MODES.includes(warming))
+            settings.warming = warming;
+        else
+            warn(`AMA_CACHE_WARMING=${warming} 无效（off | streaming | idle），已忽略`);
+    }
+    const retention = env["AMA_CACHE_RETENTION"];
+    if (retention !== undefined && retention !== "") {
+        const value = retention;
+        if (CACHE_RETENTIONS.includes(value))
+            settings.retention = value;
+        else
+            warn(`AMA_CACHE_RETENTION=${retention} 无效（none | short | long），已忽略`);
+    }
+    return settings;
+}
+/** §1.4：SessionEvent → AgentEvents。 */
+export function bridgeEvent(event, bus) {
+    switch (event.type) {
+        case "before_agent_start":
+            void bus.emit("before_agent_start", { prompt: event.prompt });
+            return;
+        case "agent_start":
+        case "turn_start":
+        case "turn_end":
+        case "agent_before_settle":
+            void bus.emit(event.type, {});
+            return;
+        case "agent_end":
+            void bus.emit("agent_end", { stopReason: event.stopReason, willRetry: event.willRetry });
+            return;
+        case "agent_settled":
+            void bus.emit("agent_settled", event.warning === undefined ? {} : { warning: event.warning });
+            return;
+        case "tool_execution_start":
+            void bus.emit("tool_call", {
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                input: event.args,
+            });
+            return;
+        case "tool_execution_end":
+            void bus.emit("tool_result", {
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                isError: event.isError,
+            });
+            return;
+        case "permission_request":
+            void bus.emit("tool_approval_requested", {
+                requestId: event.requestId,
+                toolName: event.toolName,
+            });
+            return;
+        case "permission_resolved":
+            void bus.emit("tool_approval_resolved", {
+                requestId: event.requestId,
+                decision: event.decision,
+            });
+            return;
+        case "compaction_end":
+            if (event.result !== undefined)
+                void bus.emit("session_compact", { tokensBefore: event.result.tokensBefore });
+            return;
+        case "model_changed":
+            void bus.emit("model_select", { model: event.model });
+            return;
+        case "cache_miss": {
+            const { type: _type, ...miss } = event;
+            void bus.emit("cache_miss", miss);
+            return;
+        }
+        case "context_pressure": {
+            const { type: _type, ...pressure } = event;
+            void bus.emit("context_pressure", pressure);
+            return;
+        }
+        default:
+            return;
+    }
+}
+function buildSession(record, manager, model, thinkingLevel) {
+    const { assembly } = record;
+    const registry = assembly.tools;
+    const all = registry
+        .list()
+        .map((name) => registry.get(name))
+        .filter((tool) => tool !== undefined);
+    const active = registry.active().map((tool) => tool.name);
+    const config = assembly.config;
+    let session;
+    const options = {
+        sessionManager: manager,
+        providers: assembly.providers,
+        model,
+        thinkingLevel,
+        tools: all,
+        activeTools: active,
+        permission: assembly.permission,
+        brokers: [record.chain],
+        unattended: assembly.unattended,
+        approvalTimeoutMs: approvalTimeout(record.options),
+        hooks: assembly.hooks,
+        system: systemInput(record, active),
+        compaction: { ...config.compaction },
+        retry: { ...config.retry },
+        expandPrompt: (text) => expandPrompt(record, session, text),
+        isContextOverflow: isOverflowErrorText,
+        subagents: registry.get("task") === undefined ? false : { maxConcurrent: 4 },
+        log: record.log,
+        cache: cacheSettingsFrom(config, process.env, (message) => record.log("warn", message)),
+        warmingDecider: () => assembly.host.warmingDecider?.(),
+    };
+    const maxChars = config.tools?.maxToolResultChars;
+    if (maxChars !== undefined)
+        options.maxToolResultChars = maxChars;
+    const hostId = assembly.host.handle?.adapter.id;
+    if (hostId !== undefined)
+        options.hostId = hostId;
+    session = new AgentSessionImpl(options);
+    session.subscribe((event) => bridgeEvent(event, assembly.events));
+    records.set(session, record);
+    record.state.session = session;
+    return session;
+}
+/** 第 14 步：组装主会话。 */
+export function composeSession(assembly, state = emptyComposeState(), options = {}) {
+    const manager = assembly.sessionManager;
+    if (!(manager instanceof SessionManager)) {
+        throw new AmaError("invalid_arguments", "组装根只接受 SessionManager 实例（由 sessions.open 创建）");
+    }
+    const { model } = assembly;
+    if (assembly.providers.getApi(model.api) === undefined) {
+        const via = model.api === "google-generative-ai" ? "；过渡期请经 openrouter 调用" : "";
+        throw new StartupError("provider_not_found", `模型 ${model.provider}/${model.id} 的协议 ${model.api} 尚未实现${via}`, ExitCode.NoModel);
+    }
+    for (const warning of state.warnings.splice(0))
+        assembly.warn(warning);
+    const timeoutMs = approvalTimeout(options);
+    const chain = new ApprovalBrokerChain({ timeoutMs });
+    chain.setHostBroker({
+        ask: (request, signal) => assembly.host.broker()?.ask(request, signal) ?? Promise.resolve(undefined),
+    });
+    chain.setUiBroker({
+        ask: (request, signal) => assembly.uiBroker()?.ask(request, signal) ?? Promise.resolve(undefined),
+    });
+    const record = {
+        assembly,
+        state,
+        options,
+        chain,
+        hookContext: () => assembly.sessionStartContext(),
+        hostTexts: new Map(),
+        log: options.log ?? stderrLog(),
+    };
+    const session = buildSession(record, manager, model, assembly.thinkingLevel);
+    record.current = session;
+    const registry = assembly.tools;
+    if (registry instanceof PresetToolRegistry) {
+        // 宿主在会话创建之后注册的工具：追加进当前会话，下次请求以 system 补丁声明（只在末尾追加）。
+        registry.onRegister((tool) => {
+            const active = registry.active().some((t) => t.name === tool.name);
+            try {
+                record.current.addTool(tool, active);
+            }
+            catch (error) {
+                record.log("warn", `追加工具 ${tool.name} 失败：${error.message}`);
+            }
+        });
+    }
+    return session;
+}
+function recordOf(target) {
+    const key = "sessionManager" in target && "paths" in target ? target.session : target;
+    return records.get(key);
+}
+/** 模式层当前应操作的会话（`switchSession` 之后不再是 `Runtime.session`）。 */
+export function currentSession(target) {
+    const record = recordOf(target);
+    if (record !== undefined)
+        return record.current;
+    return "paths" in target && "sessionManager" in target ? target.session : target;
+}
+/**
+ * `/new`、`/resume`、`/fork`、RPC `new_session / switch_session / fork`：旧会话发 SessionEnd 后
+ * dispose，新会话复用装配材料，宿主总线发 session_start，再跑 SessionStart Hook。
+ */
+export async function switchSession(target, request) {
+    const record = recordOf(target);
+    if (record === undefined)
+        throw new AmaError("not_implemented", "该会话不是由组装根创建的，不能切换");
+    const old = record.current;
+    if (old.state.isStreaming)
+        throw new AmaError("busy", "运行中不能切换会话");
+    const { assembly } = record;
+    const sessionDir = assembly.paths.sessionDir;
+    let manager;
+    let source;
+    switch (request.kind) {
+        case "new":
+            manager = SessionManager.create(sessionDirForCwd(sessionDir, old.cwd), old.cwd);
+            source = "new";
+            break;
+        case "open":
+            manager = SessionManager.open(request.file);
+            source = "resume";
+            break;
+        case "resume":
+            manager = openSession({ kind: "resume", id: request.id }, { sessionDir, cwd: old.cwd });
+            source = "resume";
+            break;
+        case "fork":
+            manager = old.manager.fork(request.entryId);
+            source = "fork";
+            break;
+    }
+    await assembly.hooks
+        .run("SessionEnd", { reason: request.kind === "new" ? "new" : "switch" })
+        .catch(() => undefined);
+    await old.dispose();
+    if (assembly.permission instanceof PermissionPipeline)
+        assembly.permission.clearSessionGrants();
+    let hookContext;
+    record.hookContext = () => hookContext;
+    const next = buildSession(record, manager, old.model(), old.thinkingLevel());
+    record.current = next;
+    assembly.onSessionReplaced(next);
+    const file = next.state.sessionFile;
+    await assembly.events.emit("session_start", {
+        sessionId: next.state.sessionId,
+        ...(file !== undefined ? { sessionFile: file } : {}),
+        cwd: next.cwd,
+        reason: source,
+    });
+    const outcome = await assembly.hooks.run("SessionStart", { source }).catch(() => undefined);
+    hookContext = outcome?.additionalContext;
+    // 会话自身的 session_start 由模式在重新订阅之后调 `announceStart` 发（否则订阅者收不到）。
+    return next;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * 组装根：会话存储（实施计划 §1.1 `sessions.*`）。[B6]
+ *
+ * 会话根目录 `sessionDir` 下按 cwd 分子目录（`sessionDirForCwd`）。
+ * - `new` → 延迟落盘新建；`continue` → 本目录最近一条（没有则新建）；
+ * - `resume{id}` / `fork{id}`：先在本目录、再在全部子目录里按 id 或唯一前缀找文件；找不到 →
+ *   `session_not_found`，前缀不唯一 → `invalid_arguments` 并列出候选；
+ * - `session-id{id}`：找到则打开，否则以该 id 新建；
+ * - `fork{id}`：打开后从叶子复制出新文件，原会话立即关闭（释放锁）。
+ */
+import { SessionManager } from "../session/manager.js";
+import type { SessionListItem } from "../session/types.js";
+import type { RuntimeDeps, SessionRequest } from "./deps.js";
+/** 按 id / 唯一前缀找会话文件；本 cwd 目录优先。 */
+export declare function findSessionFile(root: string, id: string, cwd?: string): string | undefined;
+export declare function openSession(request: SessionRequest, context: {
+    sessionDir: string;
+    cwd: string;
+}): SessionManager;
+export declare function listSessions(context: {
+    sessionDir: string;
+    cwd?: string;
+}): SessionListItem[];
+export declare function createSessionStore(): RuntimeDeps["sessions"];

package/dist/cli/compose-store.js

@@ -0,0 +1,125 @@
+/**
+ * 组装根：会话存储（实施计划 §1.1 `sessions.*`）。[B6]
+ *
+ * 会话根目录 `sessionDir` 下按 cwd 分子目录（`sessionDirForCwd`）。
+ * - `new` → 延迟落盘新建；`continue` → 本目录最近一条（没有则新建）；
+ * - `resume{id}` / `fork{id}`：先在本目录、再在全部子目录里按 id 或唯一前缀找文件；找不到 →
+ *   `session_not_found`，前缀不唯一 → `invalid_arguments` 并列出候选；
+ * - `session-id{id}`：找到则打开，否则以该 id 新建；
+ * - `fork{id}`：打开后从叶子复制出新文件，原会话立即关闭（释放锁）。
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { AmaError } from "../errors.js";
+import { SessionManager } from "../session/manager.js";
+import { migrateSessionLines } from "../session/migrate.js";
+import { TRASH_DIR_NAME, listSessionFiles, purgeTrash, readSessionLines, sessionDirForCwd, sessionIdFromFileName, trashSession, } from "../session/store.js";
+/** 根目录下全部 cwd 子目录（不含 trash）。 */
+function cwdDirs(root) {
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root)
+        .filter((name) => name !== TRASH_DIR_NAME)
+        .map((name) => join(root, name))
+        .filter((dir) => {
+        try {
+            return statSync(dir).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** 按 id / 唯一前缀找会话文件；本 cwd 目录优先。 */
+export function findSessionFile(root, id, cwd) {
+    const dirs = cwd === undefined ? cwdDirs(root) : [sessionDirForCwd(root, cwd), ...cwdDirs(root)];
+    const seen = new Set();
+    const prefix = [];
+    for (const dir of dirs) {
+        for (const file of listSessionFiles(dir)) {
+            if (seen.has(file))
+                continue;
+            seen.add(file);
+            const fileId = sessionIdFromFileName(file);
+            if (fileId === id)
+                return file;
+            if (fileId?.startsWith(id) === true)
+                prefix.push(file);
+        }
+    }
+    if (prefix.length > 1) {
+        const ids = prefix.map((f) => sessionIdFromFileName(f) ?? f).slice(0, 10);
+        throw new AmaError("invalid_arguments", `会话 id 前缀 ${id} 不唯一，候选：${ids.join(", ")}`, {
+            exitCode: 5,
+        });
+    }
+    return prefix[0];
+}
+function requireFile(root, id, cwd) {
+    const file = findSessionFile(root, id, cwd);
+    if (file === undefined)
+        throw new AmaError("session_not_found", `会话不存在：${id}`);
+    return file;
+}
+export function openSession(request, context) {
+    const { sessionDir: root, cwd } = context;
+    const dir = sessionDirForCwd(root, cwd);
+    switch (request.kind) {
+        case "new":
+            return SessionManager.create(dir, cwd);
+        case "continue":
+            return SessionManager.continueRecent(dir, cwd);
+        case "resume":
+            return SessionManager.open(requireFile(root, request.id, cwd));
+        case "session-id": {
+            const file = findSessionFile(root, request.id, cwd);
+            return file === undefined
+                ? SessionManager.create(dir, cwd, { id: request.id })
+                : SessionManager.open(file);
+        }
+        case "fork": {
+            const source = SessionManager.open(requireFile(root, request.id, cwd));
+            try {
+                const leaf = source.leafId();
+                if (leaf === null)
+                    throw new AmaError("session_corrupt", `会话 ${request.id} 没有条目`);
+                return source.fork(leaf);
+            }
+            finally {
+                source.close();
+            }
+        }
+    }
+}
+export function listSessions(context) {
+    const dirs = context.cwd === undefined
+        ? cwdDirs(context.sessionDir)
+        : [sessionDirForCwd(context.sessionDir, context.cwd)];
+    return dirs
+        .flatMap((dir) => SessionManager.list(dir))
+        .sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
+}
+export function createSessionStore() {
+    return {
+        open: (request, context) => openSession(request, context),
+        list: async (context) => listSessions(context),
+        show: async (id, context) => {
+            const file = requireFile(context.sessionDir, id);
+            const item = SessionManager.list(join(file, "..")).find((i) => i.file === file);
+            if (item === undefined)
+                throw new AmaError("session_corrupt", `会话文件无法读取：${file}`);
+            const { entries } = migrateSessionLines(readSessionLines(file).lines, file);
+            return { item, entries };
+        },
+        prune: async (context) => {
+            const cutoff = Date.now() - context.olderThanDays * 24 * 60 * 60 * 1000;
+            const old = listSessions(context).filter((i) => Date.parse(i.modifiedAt) < cutoff);
+            if (context.dryRun)
+                return { moved: old.map((i) => i.file) };
+            for (const item of old)
+                trashSession(item.file, context.sessionDir);
+            purgeTrash(context.sessionDir);
+            return { moved: old.map((i) => i.file) };
+        },
+    };
+}

package/dist/cli/compose.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 组装根（composition root，实施计划 §1）：`createRuntimeDeps()` 把各批次的实现装成 bootstrap 要的
+ * `RuntimeDeps`。CLI（main.ts 动态 import）与 SDK（sdk.ts）共用。[B6]
+ *
+ * | 字段                 | 实现                                                                 |
+ * | -------------------- | -------------------------------------------------------------------- |
+ * | providers.create     | compose-providers.ts（ProviderRegistry + auth + 零配置本地探测）     |
+ * | sessions.*           | compose-store.ts（SessionManager 五种请求、list / show / prune）     |
+ * | tools.create         | PresetToolRegistry：内置 + 工具工厂 + extraTools，按预设定活动集     |
+ * | permissions.create   | 内置 deny（按 builtinDeny 过滤）+ 逐条 parseRule → PermissionPipeline |
+ * | resources.discover   | skills / 提示模板发现，完整对象存进闭包状态                          |
+ * | session.create       | compose-session.ts                                                   |
+ * | modes                | line / print / rpc 懒加载；interactive 在 B7 之前回落到 line         |
+ * | ui                   | 传了 io 时：终端 → 迷你 TUI（懒加载），否则文本问答；stdin 非 TTY 不问 |
+ *
+ * **跨步骤状态走闭包（表 B·B13，有意保留）**：`RuntimeDeps.tools.create` 的入参没有 skills / 提示模板，
+ * 第 13 步 `resources.discover` 把完整对象存进 `ComposeState`，组装会话时（compose-session.ts 的技能
+ * 索引与 `/skill:` 展开）再取。不为此扩契约：两步都在同一个 `createRuntimeDeps()` 闭包里，顺序由
+ * bootstrap 固定。
+ *
+ * **工具注册点（给 B10 等）**：`ComposeOptions.toolFactories` 与 `DEFAULT_TOOL_FACTORIES`。工厂在
+ * 第 12 步建注册表时调用，产物以 `builtin` 来源注册（受预设管理）；工厂拿不到会话对象本身，执行期
+ * 需要会话时用 `ctx.session()`，嵌套调用其它工具用 `ToolContext.tools.executeTool`（走完整门禁）。
+ */
+import type { ApiRegistry } from "../ai/apis/api.js";
+import type { ModelRef, ProviderData } from "../ai/types.js";
+import type { AgentSession } from "../agent/types.js";
+import type { AmaConfig } from "../config/types.js";
+import type { Rule } from "../permissions/types.js";
+import { PresetToolRegistry } from "../tools/presets.js";
+import type { ToolDefinition, ToolRegistryApi } from "../tools/types.js";
+import { type ComposeState, type LogFn } from "./compose-session.js";
+import type { CliIo, InteractiveUi, ModeRunner, RuntimeDeps } from "./deps.js";
+import type { RuntimeMode } from "./runtime.js";
+import type { StartupUiOptions } from "../modes/interactive/startup-ui.js";
+import type { TextUiIo } from "../modes/startup-ui-text.js";
+export interface ToolFactoryContext {
+    config: AmaConfig;
+    cwd: string;
+    mode: RuntimeMode;
+    registry: ToolRegistryApi;
+    /** 会话组装之后才有值；工具执行期取用。 */
+    session(): AgentSession | undefined;
+    /** 组装期 warning（组装会话时交给 assembly.warn）。 */
+    warn(message: string): void;
+}
+/** 返回 undefined = 本次不注册（例如配置关闭）。 */
+export type ToolFactory = (ctx: ToolFactoryContext) => ToolDefinition | undefined;
+/** 缺省工具工厂：codemode（`codemode.mode` 生效值为 off 时不注册）。 */
+export declare const DEFAULT_TOOL_FACTORIES: readonly ToolFactory[];
+export interface ComposeOptions {
+    /** 追加 / 覆盖供应商（SDK）。 */
+    providers?: ProviderData[];
+    apis?: ApiRegistry;
+    /** SDK 追加的工具（来源 sdk，总在活动集里）。 */
+    extraTools?: ToolDefinition[];
+    /** 缺省 DEFAULT_TOOL_FACTORIES。 */
+    toolFactories?: readonly ToolFactory[];
+    /** 覆盖启动期问答；缺省见 `defaultStartupUi`。 */
+    ui?: InteractiveUi;
+    modes?: Partial<Record<RuntimeMode, ModeRunner>>;
+    /** key 发现用的环境（缺省 process.env）。 */
+    env?: NodeJS.ProcessEnv;
+    approvalTimeoutMs?: number;
+    /** 零配置时探测本地 ollama / lmstudio（缺省 true，`AMA_NO_LOCAL_PROBE=1` 关闭）。 */
+    probeLocal?: boolean;
+    includeFake?: boolean;
+    log?: LogFn;
+}
+export declare function lazyMode(load: () => Promise<ModeRunner>): ModeRunner;
+/** 缺省模式（懒加载：子命令与 --version 不加载模式实现）。 */
+export declare const DEFAULT_MODES: Readonly<Partial<Record<RuntimeMode, ModeRunner>>>;
+/**
+ * 第 12 步：内置工具 + 工厂 + extraTools，按预设定活动集；warning 留给组装会话时报告。
+ *
+ * 先跑工厂（产物暂不注册）再解析预设：codemode 是否可用决定预设与模式；`on` 模式下注册时给
+ * 其它工具的描述追加 codemode 提示，`only` 模式活动集独占（codemode/modes.ts）。工厂拿到的
+ * `registry` 在执行期才读，此时已登记完全部工具。
+ */
+export declare function createTools(input: {
+    config: AmaConfig;
+    cwd: string;
+    mode: RuntimeMode;
+}, options: ComposeOptions, state: ComposeState): PresetToolRegistry;
+/** 当前模型是否收图片（read 工具用）；查不到模型时按收（交给协议层过滤）。 */
+export declare function modelAcceptsImages(state: ComposeState, model: ModelRef | undefined): boolean;
+/** 第 14 步前：内置 deny（builtinDeny 过滤）+ 用户规则；非法规则 warning 后跳过。 */
+export declare function buildRules(specs: readonly {
+    effect: "allow" | "deny";
+    raw: string;
+    source: Rule["source"];
+}[], builtinDeny: boolean | readonly string[] | undefined, warn: (message: string) => void): Rule[];
+type UiIo = Pick<CliIo, "stdinIsTTY" | "stdoutIsTTY" | "env">;
+/**
+ * CLI 缺省的启动期问答（第 7 / 8 / 11 步，只在 interactive / line 模式被调用）：
+ * stdin 非 TTY 时不问（管道里的输入留给行式界面，保持非交互分支）；stdout 也是终端、
+ * `TERM` 不是 dumb 且没有 `--no-tui` 时用迷你 TUI，否则写 stderr、从 stdin 读一行。
+ */
+export declare function defaultStartupUi(io: UiIo, options?: {
+    noTui?: boolean | undefined;
+    tui?: StartupUiOptions;
+    text?: TextUiIo;
+}): InteractiveUi | undefined;
+export declare function createRuntimeDeps(options?: ComposeOptions & {
+    io?: UiIo;
+    noTui?: boolean | undefined;
+}): RuntimeDeps;
+export {};