@armadra/agent 0.3.0 → 0.5.0

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

@@ -16,6 +16,7 @@
  *   让宿主访问、Hook 公共字段与退出 dispose 跟随新会话。
  */
 import type { ProviderRegistryApi } from "../ai/types.js";
+import type { BashSandbox } from "../sandbox/bash.js";
 import { AgentSessionImpl } from "../agent/session.js";
 import type { AgentSession, CacheSettings, SessionEvent } from "../agent/types.js";
 import { type AmaConfig } from "../config/types.js";
@@ -35,6 +36,8 @@ export interface ComposeState {
     session: AgentSession | undefined;
     /** 第 11 步建好的供应商注册表（read 工具判断当前模型收不收图片）。 */
     providers?: ProviderRegistryApi;
+    /** [S2] tools.create 算出的 bash 沙箱设定，permissions.create 用同一份。 */
+    bashSandbox?: BashSandbox;
 }
 export declare function emptyComposeState(): ComposeState;
 export type LogFn = (level: "debug" | "info" | "warn" | "error", message: string) => void;
@@ -47,6 +50,11 @@ export interface SessionComposeOptions {
 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>;
+/**
+ * 模型请求的空闲超时：`AMA_IDLE_TIMEOUT_MS` > config `request.idleTimeoutMs`；都没有 → undefined
+ * （协议层取缺省 300 000）。0 关闭；非法的环境变量值忽略并 warning。
+ */
+export declare function idleTimeoutFrom(config: Pick<AmaConfig, "request">, env?: NodeJS.ProcessEnv, warn?: (message: string) => void): number | undefined;
 /** §1.4：SessionEvent → AgentEvents。 */
 export declare function bridgeEvent(event: SessionEvent, bus: AgentEventBus): void;
 /** 第 14 步：组装主会话。 */

package/dist/cli/compose-session.js

@@ -16,7 +16,9 @@
  *   让宿主访问、Hook 公共字段与退出 dispose 跟随新会话。
  */
 import { readFileSync } from "node:fs";
+import { resolveLimits } from "../agent/limits.js";
 import { AgentSessionImpl } from "../agent/session.js";
+import { DEFAULT_SUBAGENT_CONCURRENCY } from "../agent/session-subagent.js";
 import { WARMING_MODES } from "../ai/cache/types.js";
 import { isOverflowErrorText } from "../ai/overflow.js";
 import { CACHE_RETENTIONS } from "../config/types.js";
@@ -25,11 +27,13 @@ import { ApprovalBrokerChain, DEFAULT_APPROVAL_TIMEOUT_MS } from "../permissions
 import { PermissionPipeline } from "../permissions/pipeline.js";
 import { SessionManager } from "../session/manager.js";
 import { sessionDirForCwd } from "../session/store.js";
+import { createCheckpointBackendFactory, resolveCheckpointSettings } from "../checkpoints/index.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 { composeExtensions } from "./compose-extensions.js";
 import { ExitCode } from "./exit-codes.js";
 export function emptyComposeState() {
     return { skills: [], templates: [], warnings: [], session: undefined };
@@ -83,6 +87,11 @@ function contextFiles(record) {
 }
 function systemInput(record, active) {
     const system = { contextFiles: contextFiles(record) };
+    const override = record.assembly.overrides?.systemPrompt;
+    if (override?.mode === "replace")
+        system.preamble = override.text;
+    else if (override !== undefined)
+        system.extraRules = [override.text];
     const index = formatSkillIndex(record.state.skills, {
         hasSkillTool: false,
         hasReadTool: active.includes("read"),
@@ -145,6 +154,20 @@ export function cacheSettingsFrom(config, env = process.env, warn = () => undefi
     }
     return settings;
 }
+/**
+ * 模型请求的空闲超时：`AMA_IDLE_TIMEOUT_MS` > config `request.idleTimeoutMs`；都没有 → undefined
+ * （协议层取缺省 300 000）。0 关闭；非法的环境变量值忽略并 warning。
+ */
+export function idleTimeoutFrom(config, env = process.env, warn = () => undefined) {
+    const raw = env["AMA_IDLE_TIMEOUT_MS"];
+    if (raw !== undefined && raw.trim() !== "") {
+        const value = Number(raw);
+        if (Number.isFinite(value) && value >= 0)
+            return value;
+        warn(`AMA_IDLE_TIMEOUT_MS=${raw} 无效（应为不小于 0 的毫秒数），已忽略`);
+    }
+    return config.request?.idleTimeoutMs;
+}
 /** §1.4：SessionEvent → AgentEvents。 */
 export function bridgeEvent(event, bus) {
     switch (event.type) {
@@ -206,6 +229,27 @@ export function bridgeEvent(event, bus) {
             void bus.emit("context_pressure", pressure);
             return;
         }
+        // [W5-C0] 子 Agent 与计划事件
+        case "subagent_start": {
+            const { type: _type, ...payload } = event;
+            void bus.emit("subagent_start", payload);
+            return;
+        }
+        case "subagent_end": {
+            const { type: _type, ...payload } = event;
+            void bus.emit("subagent_end", payload);
+            return;
+        }
+        case "plan_proposed": {
+            const { type: _type, ...payload } = event;
+            void bus.emit("plan_proposed", payload);
+            return;
+        }
+        case "plan_resolved": {
+            const { type: _type, ...payload } = event;
+            void bus.emit("plan_resolved", payload);
+            return;
+        }
         default:
             return;
     }
@@ -237,17 +281,44 @@ function buildSession(record, manager, model, thinkingLevel) {
         retry: { ...config.retry },
         expandPrompt: (text) => expandPrompt(record, session, text),
         isContextOverflow: isOverflowErrorText,
-        subagents: registry.get("task") === undefined ? false : { maxConcurrent: 4 },
+        subagents: registry.get("task") === undefined
+            ? false
+            : { maxConcurrent: config.subagents?.maxConcurrent ?? DEFAULT_SUBAGENT_CONCURRENCY },
         log: record.log,
         cache: cacheSettingsFrom(config, process.env, (message) => record.log("warn", message)),
         warmingDecider: () => assembly.host.warmingDecider?.(),
+        // [W5-C0] 会话扩展（组装表在 compose-extensions.ts）
+        extensions: composeExtensions({ assembly, env: process.env, log: record.log }),
     };
+    // [W5-H2] 预算：--max-turns / --max-cost 覆盖 config limits.*，由 limits 扩展执行（agent/limits.ts）
+    const limits = resolveLimits(config.limits, {
+        maxTurns: assembly.overrides?.maxTurns,
+        maxCostUsd: assembly.overrides?.maxCostUsd,
+    });
+    if (limits !== undefined)
+        options.limits = limits;
+    if (config.fallbackModel !== undefined)
+        options.fallbackModel = config.fallbackModel;
+    const idle = idleTimeoutFrom(config, process.env, (message) => record.log("warn", message));
+    if (idle !== undefined)
+        options.idleTimeoutMs = idle;
+    const autoModel = config.permission?.autoModel;
+    if (autoModel !== undefined)
+        options.permissionClassifier = { model: autoModel };
     const maxChars = config.tools?.maxToolResultChars;
     if (maxChars !== undefined)
         options.maxToolResultChars = maxChars;
     const hostId = assembly.host.handle?.adapter.id;
     if (hostId !== undefined)
         options.hostId = hostId;
+    // [RW-B] 回滚：中断即撤回与检查点后端（内存会话不调工厂；mode off 时工厂返回 undefined）
+    if (config.ui?.restoreOnCancel === false)
+        options.restoreOnCancel = false;
+    options.checkpoints = createCheckpointBackendFactory({
+        ...resolveCheckpointSettings(config, process.env, (message) => record.log("warn", message)),
+        dataDir: assembly.paths.dataDir,
+        sessionsRoot: assembly.paths.sessionDir,
+    });
     session = new AgentSessionImpl(options);
     session.subscribe((event) => bridgeEvent(event, assembly.events));
     records.set(session, record);
@@ -329,7 +400,10 @@ export async function switchSession(target, request) {
     let source;
     switch (request.kind) {
         case "new":
-            manager = SessionManager.create(sessionDirForCwd(sessionDir, old.cwd), old.cwd);
+            manager =
+                assembly.overrides?.noSession === true
+                    ? SessionManager.inMemory(old.cwd)
+                    : SessionManager.create(sessionDirForCwd(sessionDir, old.cwd), old.cwd);
             source = "new";
             break;
         case "open":

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

@@ -2,7 +2,7 @@
  * 组装根：会话存储（实施计划 §1.1 `sessions.*`）。[B6]
  *
  * 会话根目录 `sessionDir` 下按 cwd 分子目录（`sessionDirForCwd`）。
- * - `new` → 延迟落盘新建；`continue` → 本目录最近一条（没有则新建）；
+ * - `new` → 延迟落盘新建；`memory`（`--no-session`）→ 内存会话，从不落盘；`continue` → 本目录最近一条（没有则新建）；
  * - `resume{id}` / `fork{id}`：先在本目录、再在全部子目录里按 id 或唯一前缀找文件；找不到 →
  *   `session_not_found`，前缀不唯一 → `invalid_arguments` 并列出候选；
  * - `session-id{id}`：找到则打开，否则以该 id 新建；

package/dist/cli/compose-store.js

@@ -2,7 +2,7 @@
  * 组装根：会话存储（实施计划 §1.1 `sessions.*`）。[B6]
  *
  * 会话根目录 `sessionDir` 下按 cwd 分子目录（`sessionDirForCwd`）。
- * - `new` → 延迟落盘新建；`continue` → 本目录最近一条（没有则新建）；
+ * - `new` → 延迟落盘新建；`memory`（`--no-session`）→ 内存会话，从不落盘；`continue` → 本目录最近一条（没有则新建）；
  * - `resume{id}` / `fork{id}`：先在本目录、再在全部子目录里按 id 或唯一前缀找文件；找不到 →
  *   `session_not_found`，前缀不唯一 → `invalid_arguments` 并列出候选；
  * - `session-id{id}`：找到则打开，否则以该 id 新建；
@@ -67,6 +67,8 @@ export function openSession(request, context) {
     switch (request.kind) {
         case "new":
             return SessionManager.create(dir, cwd);
+        case "memory":
+            return SessionManager.inMemory(cwd);
         case "continue":
             return SessionManager.continueRecent(dir, cwd);
         case "resume":

package/dist/cli/compose.d.ts

@@ -27,6 +27,8 @@ 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 { type SandboxCapability } from "../codemode/capability.js";
+import { type BashSandbox } from "../sandbox/bash.js";
 import { PresetToolRegistry } from "../tools/presets.js";
 import type { ToolDefinition, ToolRegistryApi } from "../tools/types.js";
 import { type ComposeState, type LogFn } from "./compose-session.js";
@@ -46,7 +48,7 @@ export interface ToolFactoryContext {
 }
 /** 返回 undefined = 本次不注册（例如配置关闭）。 */
 export type ToolFactory = (ctx: ToolFactoryContext) => ToolDefinition | undefined;
-/** 缺省工具工厂：codemode（`codemode.mode` 生效值为 off 时不注册）。 */
+/** 缺省工具工厂：codemode（生效模式为 off 时不注册；缺省跟随预设，见 tools/presets.ts）。 */
 export declare const DEFAULT_TOOL_FACTORIES: readonly ToolFactory[];
 export interface ComposeOptions {
     /** 追加 / 覆盖供应商（SDK）。 */
@@ -56,6 +58,13 @@ export interface ComposeOptions {
     extraTools?: ToolDefinition[];
     /** 缺省 DEFAULT_TOOL_FACTORIES。 */
     toolFactories?: readonly ToolFactory[];
+    /**
+     * 沙箱能力（缺省按运行时 Node 探测）。决定 default 预设是否开 codemode；给了且没给
+     * `toolFactories` 时 codemode 工厂也用它（测试据此不随 Node 版本变化）。
+     */
+    sandboxCapability?: SandboxCapability;
+    /** [S2] bash 的 OS 沙箱设定（缺省按 `sandbox.*` 配置与本机探测；测试注入）。 */
+    bashSandbox?: BashSandbox;
     /** 覆盖启动期问答；缺省见 `defaultStartupUi`。 */
     ui?: InteractiveUi;
     modes?: Partial<Record<RuntimeMode, ModeRunner>>;
@@ -73,14 +82,18 @@ export declare const DEFAULT_MODES: Readonly<Partial<Record<RuntimeMode, ModeRun
 /**
  * 第 12 步：内置工具 + 工厂 + extraTools，按预设定活动集；warning 留给组装会话时报告。
  *
- * 先跑工厂（产物暂不注册）再解析预设：codemode 是否可用决定预设与模式；`on` 模式下注册时给
- * 其它工具的描述追加 codemode 提示，`only` 模式活动集独占（codemode/modes.ts）。工厂拿到的
- * `registry` 在执行期才读，此时已登记完全部工具。
+ * 先跑工厂（产物暂不注册）再解析预设：codemode 是否可用决定预设与模式；`only` 模式活动集独占
+ * （codemode/modes.ts）。工厂拿到的 `registry` 在执行期才读，此时已登记完全部工具。default 预设
+ * 跟随预设而 codemode 缺省关闭时（非 strict 运行时）提示一次（cli/codemode-notice.ts）。
  */
 export declare function createTools(input: {
     config: AmaConfig;
     cwd: string;
     mode: RuntimeMode;
+    paths?: {
+        configDir: string;
+        dataDir: string;
+    } | undefined;
 }, options: ComposeOptions, state: ComposeState): PresetToolRegistry;
 /** 当前模型是否收图片（read 工具用）；查不到模型时按收（交给协议层过滤）。 */
 export declare function modelAcceptsImages(state: ComposeState, model: ModelRef | undefined): boolean;

package/dist/cli/compose.js

@@ -25,17 +25,25 @@
 import { formatModelRef } from "../ai/providers/channels.js";
 import { PermissionPipeline } from "../permissions/pipeline.js";
 import { BUILTIN_DENY_RULES, parseRule } from "../permissions/rules.js";
+import { withBuiltinSkills } from "../skills/builtin.js";
 import { discoverSkills, skillSources } from "../skills/discover.js";
 import { discoverPromptTemplates, promptSources } from "../skills/templates.js";
-import { applyCodemodeMode, decorateForMode } from "../codemode/modes.js";
+import { applyCodemodeMode } from "../codemode/modes.js";
+import { sandboxCapabilityFor } from "../codemode/capability.js";
 import { codemodeToolFactory } from "../codemode/tool.js";
+import { configureOsSandbox } from "../sandbox/detect.js";
+import { resolveBashSandbox } from "../sandbox/bash.js";
+import { join } from "node:path";
+import { AUTH_FILE } from "../config/paths.js";
 import { PresetToolRegistry, resolvePreset } from "../tools/presets.js";
 import { builtinTools } from "../tools/registry.js";
+import { takeCodemodeNotice } from "./codemode-notice.js";
 import { buildProviderRegistry } from "./compose-providers.js";
 import { composeSession, emptyComposeState, } from "./compose-session.js";
 import { createSessionStore } from "./compose-store.js";
 import { defaultSendUser } from "./startup-steps.js";
-/** 缺省工具工厂：codemode（`codemode.mode` 生效值为 off 时不注册）。 */
+import { imageFitOptionsFor } from "../modes/image-input.js";
+/** 缺省工具工厂：codemode（生效模式为 off 时不注册；缺省跟随预设，见 tools/presets.ts）。 */
 export const DEFAULT_TOOL_FACTORIES = [codemodeToolFactory()];
 export function lazyMode(load) {
     return async (runtime, context) => (await load())(runtime, context);
@@ -50,18 +58,38 @@ export const DEFAULT_MODES = {
 /**
  * 第 12 步：内置工具 + 工厂 + extraTools，按预设定活动集；warning 留给组装会话时报告。
  *
- * 先跑工厂（产物暂不注册）再解析预设：codemode 是否可用决定预设与模式；`on` 模式下注册时给
- * 其它工具的描述追加 codemode 提示，`only` 模式活动集独占（codemode/modes.ts）。工厂拿到的
- * `registry` 在执行期才读，此时已登记完全部工具。
+ * 先跑工厂（产物暂不注册）再解析预设：codemode 是否可用决定预设与模式；`only` 模式活动集独占
+ * （codemode/modes.ts）。工厂拿到的 `registry` 在执行期才读，此时已登记完全部工具。default 预设
+ * 跟随预设而 codemode 缺省关闭时（非 strict 运行时）提示一次（cli/codemode-notice.ts）。
  */
 export function createTools(input, options, state) {
     const registry = new PresetToolRegistry();
-    const bash = input.config.tools?.bashTimeoutMs !== undefined
-        ? { defaultTimeoutMs: input.config.tools.bashTimeoutMs }
-        : {};
+    // 记下 sandbox.enabled：拿不到配置的只读调用方（状态栏）与这里得到同一结论。
+    const osStatus = configureOsSandbox(input.config.sandbox?.enabled);
+    // [S2] bash 沙箱：工具与权限管线用同一份设定（tools.create 先于 permissions.create）
+    const bashSandbox = options.bashSandbox ??
+        resolveBashSandbox(input.config.sandbox, {
+            status: osStatus,
+            ...(input.paths === undefined ? {} : { hidden: [join(input.paths.configDir, AUTH_FILE)] }),
+        });
+    state.bashSandbox = bashSandbox;
+    const capability = options.sandboxCapability ?? sandboxCapabilityFor(input.config);
+    const factories = options.toolFactories ??
+        (options.sandboxCapability !== undefined
+            ? [codemodeToolFactory({ capability })]
+            : DEFAULT_TOOL_FACTORIES);
+    const bash = {
+        ...(input.config.tools?.bashTimeoutMs !== undefined
+            ? { defaultTimeoutMs: input.config.tools.bashTimeoutMs }
+            : {}),
+        ...(bashSandbox.active ? { sandbox: bashSandbox } : {}),
+    };
     const builtins = builtinTools({
         bash,
-        read: { supportsImages: (ctx) => modelAcceptsImages(state, ctx.model) },
+        read: {
+            supportsImages: (ctx) => modelAcceptsImages(state, ctx.model),
+            imageOptions: (ctx) => imageFitOptionsFor(state.providers, ctx.model, input.config.images),
+        },
     });
     const ctx = {
         ...input,
@@ -70,7 +98,7 @@ export function createTools(input, options, state) {
         warn: (message) => state.warnings.push(message),
     };
     const produced = [];
-    for (const factory of options.toolFactories ?? DEFAULT_TOOL_FACTORIES) {
+    for (const factory of factories) {
         try {
             const tool = factory(ctx);
             if (tool !== undefined)
@@ -82,20 +110,29 @@ export function createTools(input, options, state) {
     }
     const extra = options.extraTools ?? [];
     const names = new Set([...builtins, ...produced, ...extra].map((tool) => tool.name));
-    const preset = resolvePreset({ config: input.config, available: (name) => names.has(name) });
-    const decorate = decorateForMode(preset.codemode);
+    const preset = resolvePreset({
+        config: input.config,
+        available: (name) => names.has(name),
+        strict: capability.strict,
+    });
     for (const tool of [...builtins, ...produced]) {
         try {
-            registry.register(decorate(tool), "builtin");
+            registry.register(tool, "builtin");
         }
         catch (error) {
             state.warnings.push(`工具 ${tool.name} 注册失败：${error.message}`);
         }
     }
     for (const tool of extra)
-        registry.register(decorate(tool), "sdk");
+        registry.register(tool, "sdk");
     applyCodemodeMode(registry, preset);
     state.warnings.push(...preset.warnings);
+    // 一次性提示只给有人看的界面（交互 / 行式）；-p 与 RPC 的 stderr 常被脚本解析，不打扰。
+    if (input.paths !== undefined && (input.mode === "interactive" || input.mode === "line")) {
+        const notice = takeCodemodeNotice({ config: input.config, capability, ...input.paths });
+        if (notice !== undefined)
+            state.warnings.push(notice);
+    }
     return registry;
 }
 /** 当前模型是否收图片（read 工具用）；查不到模型时按收（交给协议层过滤）。 */
@@ -173,6 +210,10 @@ export function createRuntimeDeps(options = {}) {
                 mode: input.mode,
                 rules: buildRules(input.rules, input.builtinDeny, (m) => state.warnings.push(m)),
                 cwd: input.cwd,
+                ...(input.autoSafeCommands !== undefined
+                    ? { autoSafeCommands: input.autoSafeCommands }
+                    : {}),
+                ...(state.bashSandbox?.active === true ? { bashSandbox: state.bashSandbox } : {}),
             }),
         },
         resources: {
@@ -182,6 +223,11 @@ export function createRuntimeDeps(options = {}) {
                     configDir: input.configDir,
                     cliDirs: input.extraSkillDirs,
                 }), { trusted: input.trusted });
+                if (input.dataDir !== undefined) {
+                    const builtin = await withBuiltinSkills(skills.skills, input.dataDir);
+                    skills.skills = builtin.skills;
+                    skills.warnings.push(...builtin.warnings);
+                }
                 const prompts = await discoverPromptTemplates(promptSources({
                     cwd: input.cwd,
                     configDir: input.configDir,

package/dist/cli/default-model.d.ts

@@ -1,16 +1,53 @@
 /**
  * 零配置选模型（设计 §10.0、§11.1 第 11 步）：没有 `--model`、续会话的 model_change 与
- * `config.defaultModel` 时，按内置供应商顺序（§3.3）选第一个**可用**供应商的缺省模型（目录首条）。
+ * `config.defaultModel` 时，按供应商顺序（内置 §3.3 在前，config 里的自定义供应商在后）选第一个
+ * **可用**供应商，再在它的模型里挑一个：
+ *
+ * - 内置供应商：目录首条（目录按推荐顺序整理过）；
+ * - 自定义供应商（中转站，模型表是上游 /v1/models 的顺序）：按 `pickByPrice` 的规则挑——
+ *   models.dev 有价格（输入价 > 0）且支持工具调用、上下文 ≥ 64k 的模型里输入价最低的；同价取上下文
+ *   大的，再同取列表靠前的。没有满足条件的才退回列表首条。`ama providers add` 写 defaultModel 用同一规则。
  *
  * 可用 = 有 key（`requiresApiKey`）或本地服务已探测到模型（ollama / lmstudio，组装根在
  * 无 key 时探测）。跳过 `fake`（测试供应商只能显式 `--model fake/…`）与协议尚未实现的供应商。
  */
 import type { Model, ProviderData, ProviderRegistryApi } from "../ai/types.js";
+/** 缺省模型的最小上下文（token）。 */
+export declare const MIN_DEFAULT_CONTEXT = 64000;
+export interface PriceCandidate {
+    id: string;
+    contextWindow?: number | undefined;
+    /** $/M 输入 token。 */
+    inputCost?: number | undefined;
+    /** models.dev 的 tool_call。 */
+    toolCall?: boolean | undefined;
+}
+export interface PricePick {
+    id: string;
+    /** 为什么选它（一句话）。 */
+    reason: string;
+}
+/** 规则说明（帮助与输出共用）。 */
+export declare const PRICE_RULE = "\u652F\u6301\u5DE5\u5177\u8C03\u7528\u3001\u4E0A\u4E0B\u6587 \u2265 64k \u4E14\u6709\u4EF7\u683C\u7684\u6A21\u578B\u91CC\u8F93\u5165\u4EF7\u6700\u4F4E";
+/** 按价格挑缺省模型；没有满足条件的返回 undefined（规则见文件头）。 */
+export declare function pickByPrice(candidates: readonly PriceCandidate[]): PricePick | undefined;
 export interface DefaultModelChoice {
     model: Model;
     provider: ProviderData;
     /** 选中原因：`key`（有 key，来源见 keySource）或 `local`（本地服务）。 */
     via: "key" | "local";
     keySource?: string;
+    /** 为什么是这个模型（内置目录首条 / 价格规则 / 列表首条）。 */
+    rule: string;
 }
+/** 供应商内挑模型：内置取目录首条；自定义按价格规则，挑不出再取首条。 */
+export declare function pickProviderModel(registry: ProviderRegistryApi, provider: ProviderData): {
+    model: Model;
+    rule: string;
+} | undefined;
 export declare function pickDefaultModel(registry: ProviderRegistryApi): Promise<DefaultModelChoice | undefined>;
+/**
+ * 没有可用模型时的引导（一行，选择器的说明行与报错共用）：列出前几个内置供应商的 key 环境变量，
+ * 以及 `ama auth set` / `ama providers add`。
+ */
+export declare function noModelGuidance(registry: Pick<ProviderRegistryApi, "list">): string;

package/dist/cli/default-model.js

@@ -1,24 +1,111 @@
 /**
  * 零配置选模型（设计 §10.0、§11.1 第 11 步）：没有 `--model`、续会话的 model_change 与
- * `config.defaultModel` 时，按内置供应商顺序（§3.3）选第一个**可用**供应商的缺省模型（目录首条）。
+ * `config.defaultModel` 时，按供应商顺序（内置 §3.3 在前，config 里的自定义供应商在后）选第一个
+ * **可用**供应商，再在它的模型里挑一个：
+ *
+ * - 内置供应商：目录首条（目录按推荐顺序整理过）；
+ * - 自定义供应商（中转站，模型表是上游 /v1/models 的顺序）：按 `pickByPrice` 的规则挑——
+ *   models.dev 有价格（输入价 > 0）且支持工具调用、上下文 ≥ 64k 的模型里输入价最低的；同价取上下文
+ *   大的，再同取列表靠前的。没有满足条件的才退回列表首条。`ama providers add` 写 defaultModel 用同一规则。
  *
  * 可用 = 有 key（`requiresApiKey`）或本地服务已探测到模型（ollama / lmstudio，组装根在
  * 无 key 时探测）。跳过 `fake`（测试供应商只能显式 `--model fake/…`）与协议尚未实现的供应商。
  */
+import { compactTokens, metadataOf } from "./subcommands/model-meta.js";
+/** 缺省模型的最小上下文（token）。 */
+export const MIN_DEFAULT_CONTEXT = 64_000;
+/** 规则说明（帮助与输出共用）。 */
+export const PRICE_RULE = "支持工具调用、上下文 ≥ 64k 且有价格的模型里输入价最低";
+/** 按价格挑缺省模型；没有满足条件的返回 undefined（规则见文件头）。 */
+export function pickByPrice(candidates) {
+    let best;
+    candidates.forEach((c, index) => {
+        if (c.toolCall !== true)
+            return;
+        if (c.inputCost === undefined || !(c.inputCost > 0))
+            return;
+        if ((c.contextWindow ?? 0) < MIN_DEFAULT_CONTEXT)
+            return;
+        if (best === undefined) {
+            best = { c, index };
+            return;
+        }
+        const a = best.c;
+        const cheaper = c.inputCost < a.inputCost;
+        const same = c.inputCost === a.inputCost;
+        if (cheaper || (same && (c.contextWindow ?? 0) > (a.contextWindow ?? 0)))
+            best = { c, index };
+    });
+    if (best === undefined)
+        return undefined;
+    const { c } = best;
+    return {
+        id: c.id,
+        reason: `${PRICE_RULE}（$${c.inputCost}/M 输入，上下文 ${compactTokens(c.contextWindow)}）`,
+    };
+}
+/** 供应商内挑模型：内置取目录首条；自定义按价格规则，挑不出再取首条。 */
+export function pickProviderModel(registry, provider) {
+    const usable = provider.models.filter((m) => registry.getApi(m.api) !== undefined);
+    const first = usable[0];
+    if (first === undefined)
+        return undefined;
+    if (provider.builtin)
+        return { model: first, rule: "内置目录推荐的首个模型" };
+    const picked = pickByPrice(usable.map((m) => ({
+        id: m.id,
+        contextWindow: m.contextWindow,
+        inputCost: m.cost?.input,
+        toolCall: metadataOf(registry, provider.id, m.id)?.toolCall,
+    })));
+    const model = picked === undefined ? undefined : usable.find((m) => m.id === picked.id);
+    if (picked !== undefined && model !== undefined)
+        return { model, rule: picked.reason };
+    return {
+        model: first,
+        rule: "列表首个模型（没有同时支持工具调用、上下文 ≥ 64k 且有价格的模型）",
+    };
+}
 export async function pickDefaultModel(registry) {
     for (const provider of registry.list()) {
         if (provider.id === "fake" && !provider.requiresApiKey)
             continue;
-        const model = provider.models[0];
-        if (model === undefined)
+        const head = provider.models[0];
+        if (head === undefined)
+            continue;
+        if (registry.getApi(head.api) === undefined)
             continue;
-        if (registry.getApi(model.api) === undefined)
+        let via = "local";
+        let keySource;
+        if (provider.requiresApiKey) {
+            const key = await registry.resolveApiKey(provider.id);
+            if (key.apiKey === undefined)
+                continue;
+            via = "key";
+            keySource = key.source;
+        }
+        const picked = pickProviderModel(registry, provider);
+        if (picked === undefined)
             continue;
-        if (!provider.requiresApiKey)
-            return { model, provider, via: "local" };
-        const key = await registry.resolveApiKey(provider.id);
-        if (key.apiKey !== undefined)
-            return { model, provider, via: "key", keySource: key.source };
+        const choice = { model: picked.model, provider, via, rule: picked.rule };
+        if (keySource !== undefined)
+            choice.keySource = keySource;
+        return choice;
     }
     return undefined;
 }
+/**
+ * 没有可用模型时的引导（一行，选择器的说明行与报错共用）：列出前几个内置供应商的 key 环境变量，
+ * 以及 `ama auth set` / `ama providers add`。
+ */
+export function noModelGuidance(registry) {
+    const envs = registry
+        .list()
+        .filter((p) => p.builtin && p.requiresApiKey && p.id !== "fake")
+        .map((p) => p.envKeys[0])
+        .filter((name) => name !== undefined);
+    const shown = envs.slice(0, 3).join(" / ");
+    const more = envs.length > 3 ? " 等" : "";
+    return (`没有可用模型：设置 ${shown}${more}环境变量，或 \`ama auth set <provider>\` 保存 key，` +
+        "或 `ama providers add <id> --base-url <url>` 接入中转站（也可 --model 指定）");
+}

package/dist/cli/deps.d.ts

@@ -37,6 +37,10 @@ export type SessionRequest = {
 } | {
     kind: "fork";
     id: string;
+}
+/** `--no-session`：内存会话，从不落盘。 */
+ | {
+    kind: "memory";
 };
 export interface ProviderBuildInput {
     config: AmaConfig;
@@ -61,6 +65,8 @@ export interface ResourceDiscoveryInput {
     /** 按 §5.3 顺序：`--skill-dir` → profile.skillDirs → config.skills.dirs。 */
     extraSkillDirs: readonly string[];
     promptDirs: readonly string[];
+    /** 数据目录：内置 Skill 的正文写在 `<dataDir>/builtin/`；缺省不加内置 Skill。 */
+    dataDir?: string;
 }
 export interface ResourceDiscoveryResult {
     skills: LoadedResources["skills"];
@@ -107,8 +113,26 @@ export interface SessionAssembly {
     sessionStartContext(): string | undefined;
     /** print：ask → deny。 */
     unattended: boolean;
+    /** 命令行对会话的覆盖（W4-C）：`-p --max-turns`、`--system-prompt`、`--no-session`。 */
+    overrides?: SessionOverrides;
     warn(message: string): void;
 }
+export interface SessionOverrides {
+    /** 一次运行（prompt）的回合上限。 */
+    maxTurns?: number;
+    /** [W5-C0] `--max-cost`：并入会话 `limits.maxCostUsd`（W5-H2 实现）。 */
+    maxCostUsd?: number;
+    /** `--system-prompt`：追加进 rules 节，或替换 preamble。 */
+    systemPrompt?: SystemPromptOverride;
+    /** `--no-session`：`/new` 等切换出的新会话也只在内存里。 */
+    noSession?: boolean;
+    /** [W5-G] `--agent-dir`（可重复）与 profile `agentDirs`，按此顺序：子 Agent 定义目录。 */
+    agentDirs?: string[];
+}
+export interface SystemPromptOverride {
+    text: string;
+    mode: "append" | "replace";
+}
 export interface ModeContext {
     args: ParsedArgs;
     /** 位置参数拼成的首条提示。 */
@@ -166,6 +190,11 @@ export interface RuntimeDeps {
             config: AmaConfig;
             cwd: string;
             mode: RuntimeMode;
+            /** CLI 启动时给出（一次性提示记在数据目录）；SDK 不给。 */
+            paths?: {
+                configDir: string;
+                dataDir: string;
+            };
         }): ToolRegistryApi;
     };
     /** B3：权限管线。 */
@@ -178,6 +207,8 @@ export interface RuntimeDeps {
             cwd: string;
             /** config `permission.builtinDeny`（只来自用户级 / profile）；缺省 = 启用全部内置 deny。 */
             builtinDeny?: boolean | string[];
+            /** config `permission.autoSafeCommands`（auto 模式安全名单追加）。 */
+            autoSafeCommands?: string[];
         }): PermissionPipelineApi;
     };
     /** B3：skills / prompts 发现；缺省为空。 */
@@ -204,4 +235,15 @@ export interface CliIo {
     cwd: string;
     /** 读取 stdin 全部内容（auth set）。 */
     readStdin(): Promise<string>;
+    /**
+     * 等首字节至多 `timeoutMs`：期间没有任何字节 → undefined（停止读取，不再占着 stdin）；收到首字节
+     * 后读到 EOF（不再超时）；期间就 EOF → 已读到的内容。缺省实现见 cli/main.ts。
+     */
+    readStdinFirstByte?(timeoutMs: number): Promise<string | undefined>;
+    /**
+     * stdin 的类型（`-p` 据此决定读不读）：`file` / `null`（/dev/null 等字符设备）读了不会卡；
+     * `fifo` 是 shell 管道；`socket` 多为父进程 spawn 时留的管道。未提供时按 `other` 处理（不读、不提示）。
+     */
+    stdinKind?(): StdinKind;
 }
+export type StdinKind = "tty" | "file" | "null" | "fifo" | "socket" | "other";