@armadra/agent 0.0.0-stage → 0.2.1

package/dist/permissions/rules.js

@@ -0,0 +1,249 @@
+/**
+ * 权限规则（设计 §7.2、§5.2「通用安全」）。[B3]
+ *
+ * 语法：`tool` 或 `tool(pattern)`；`tool` 是工具名 glob（`canvas_*`、`*`）；pattern：
+ * - bash：对命令文本做通配（`*` 任意字符含空格与 `/`，`?` 单字符），命令先折叠空白；
+ * - 带 `path` 的工具（read / write / edit / ls / grep / glob 及宿主工具）：对路径做 glob（`**`）。
+ *   相对模式匹配 cwd 内的相对路径；以 `**` 开头的模式也匹配绝对路径（例如 .ssh 目录规则命中 ~/.ssh 下的文件）；
+ *   绝对模式（`/…`、`~/…`）匹配绝对路径。缺 path 的调用以 cwd 为路径。
+ * - 其它工具带 pattern 的规则不匹配（无可比对的对象）。
+ *
+ * bash 复合命令：deny 规则命中整条或**任一**段即生效；allow 规则要求**每一**段都被某条 allow 覆盖，
+ * 且命令里没有 `$(…)` / 反引号替换——否则 allow 不生效（回到「问」）。
+ *
+ * 来源约束（§7.2）：项目级只能收紧——allow 被忽略、mode 只能更严，均产生 warning。
+ */
+import { isAbsolute, relative, resolve } from "node:path";
+import { AmaError } from "../errors.js";
+import { PERMISSION_MODES_STRICT_FIRST } from "./types.js";
+import { globBody } from "../tools/glob.js";
+import { expandHome, resolvePath, toPosix } from "../tools/paths.js";
+/** 内置缺省 deny 表（用户可经 `builtinDeny` 选项移除）。 */
+export const BUILTIN_DENY_RULES = [
+    "write(**/.git/**)",
+    "edit(**/.git/**)",
+    "read(**/.ssh/**)",
+    "write(**/.ssh/**)",
+    "edit(**/.ssh/**)",
+];
+const RULE_RE = /^([A-Za-z0-9_*?]+)(?:\((.*)\))?$/s;
+export function parseRule(raw, effect, source) {
+    const text = raw.trim();
+    const m = RULE_RE.exec(text);
+    if (!m || (m[2] !== undefined && m[2].trim() === "")) {
+        throw new AmaError("invalid_arguments", `Invalid permission rule "${raw}"`);
+    }
+    const rule = { effect, tool: m[1], source, raw: text };
+    if (m[2] !== undefined)
+        rule.pattern = m[2].trim();
+    return rule;
+}
+export function wildcardToRegExp(pattern) {
+    let out = "";
+    for (const ch of pattern) {
+        if (ch === "*")
+            out += "[\\s\\S]*";
+        else if (ch === "?")
+            out += "[\\s\\S]";
+        else
+            out += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${out}$`);
+}
+export function toolNameMatches(ruleTool, toolName) {
+    return ruleTool === toolName || wildcardToRegExp(ruleTool).test(toolName);
+}
+export function normalizeCommand(command) {
+    return command.trim().replace(/\s+/g, " ");
+}
+/**
+ * 按 `&&`、`||`、`;`、`|`、`&`、换行切分（引号内不切），每段 trim 后返回非空段。
+ */
+export function splitShellSegments(command) {
+    const out = [];
+    let cur = "";
+    let quote;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote) {
+            cur += ch;
+            if (ch === "\\" && quote === '"' && i + 1 < command.length)
+                cur += command[++i];
+            else if (ch === quote)
+                quote = undefined;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            quote = ch;
+            cur += ch;
+        }
+        else if (ch === "\\" && i + 1 < command.length) {
+            cur += ch + command[++i];
+        }
+        else if (ch === ";" || ch === "\n" || ch === "|" || ch === "&") {
+            // `>&2`、`2>&1`、`&>` 是重定向不是分隔。
+            if (ch === "&" && (command[i - 1] === ">" || command[i + 1] === ">")) {
+                cur += ch;
+                continue;
+            }
+            out.push(cur);
+            cur = "";
+            if ((ch === "|" || ch === "&") && command[i + 1] === ch)
+                i++;
+        }
+        else {
+            cur += ch;
+        }
+    }
+    out.push(cur);
+    return out.map((s) => normalizeCommand(s)).filter((s) => s !== "");
+}
+export function hasCommandSubstitution(command) {
+    return /\$\(|`|<\(|>\(/.test(command);
+}
+function pathGlob(pattern) {
+    return new RegExp(`^${globBody(pattern, { braces: true })}$`);
+}
+/** 输入里的路径（绝对）；没有 path 字段的工具返回 undefined。 */
+export function inputPath(toolName, input, cwd) {
+    const raw = typeof input === "object" && input !== null
+        ? input["path"]
+        : undefined;
+    if (typeof raw === "string") {
+        try {
+            return resolvePath(raw, cwd);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (["read", "write", "edit", "ls", "grep", "glob"].includes(toolName))
+        return resolvePath(".", cwd);
+    return undefined;
+}
+export function inputCommand(input) {
+    const raw = typeof input === "object" && input !== null
+        ? input["command"]
+        : undefined;
+    return typeof raw === "string" ? raw : undefined;
+}
+export function pathMatches(pattern, absPath, cwd) {
+    const absPosix = toPosix(absPath);
+    const expanded = expandHome(pattern);
+    if (isAbsolute(expanded))
+        return pathGlob(toPosix(resolve(expanded))).test(absPosix);
+    const regex = pathGlob(pattern.replace(/^\.\//, ""));
+    const rel = relative(cwd, absPath);
+    const inside = rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+    if (inside && regex.test(toPosix(rel)))
+        return true;
+    if (rel === "" && (pattern === "**" || pattern === "*" || pattern === "."))
+        return true;
+    return pattern.startsWith("**") && regex.test(absPosix.replace(/^\/+/, ""));
+}
+/** 单条规则对一个（非复合）对象是否命中。 */
+function matchesSubject(rule, toolName, input, cwd, command) {
+    if (!toolNameMatches(rule.tool, toolName))
+        return false;
+    if (rule.pattern === undefined)
+        return true;
+    if (command !== undefined)
+        return wildcardToRegExp(rule.pattern).test(command);
+    const abs = inputPath(toolName, input, cwd);
+    return abs !== undefined && pathMatches(rule.pattern, abs, cwd);
+}
+/** 第一条命中的 deny 规则。 */
+export function findDenyRule(rules, toolName, input, cwd) {
+    const command = inputCommand(input);
+    for (const rule of rules) {
+        if (rule.effect !== "deny")
+            continue;
+        if (command === undefined || rule.pattern === undefined) {
+            if (matchesSubject(rule, toolName, input, cwd))
+                return rule;
+            continue;
+        }
+        const subjects = [normalizeCommand(command), ...splitShellSegments(command)];
+        if (subjects.some((s) => matchesSubject(rule, toolName, input, cwd, s)))
+            return rule;
+    }
+    return undefined;
+}
+/** 覆盖本次调用的 allow 规则（复合命令返回第一段的覆盖者）；不覆盖返回 undefined。 */
+export function findAllowRule(rules, toolName, input, cwd) {
+    const allows = rules.filter((r) => r.effect === "allow");
+    const command = inputCommand(input);
+    if (command === undefined)
+        return allows.find((r) => matchesSubject(r, toolName, input, cwd));
+    const unconditional = allows.find((r) => r.pattern === undefined && toolNameMatches(r.tool, toolName));
+    if (unconditional)
+        return unconditional;
+    if (hasCommandSubstitution(command))
+        return undefined;
+    const segments = splitShellSegments(command);
+    if (segments.length === 0)
+        return undefined;
+    let first;
+    for (const seg of segments) {
+        const hit = allows.find((r) => matchesSubject(r, toolName, input, cwd, seg));
+        if (!hit)
+            return undefined;
+        first ??= hit;
+    }
+    return first;
+}
+// ---------------------------------------------------------------------------
+// 来源合并与收紧校验
+// ---------------------------------------------------------------------------
+/** a 是否比 b 更严（或相等）。 */
+export function isAtLeastAsStrict(a, b) {
+    return PERMISSION_MODES_STRICT_FIRST.indexOf(a) <= PERMISSION_MODES_STRICT_FIRST.indexOf(b);
+}
+/**
+ * 按给定顺序（调用方排好：用户级 → profile → 项目级 → 命令行）合并。项目级只能收紧。
+ * 不合法的规则文本记 warning 并跳过。
+ */
+export function resolvePermissionLayers(layers, options = {}) {
+    const warnings = [];
+    const rules = [];
+    const removed = options.builtinDeny;
+    if (removed !== false) {
+        for (const raw of BUILTIN_DENY_RULES) {
+            if (Array.isArray(removed) && removed.includes(raw))
+                continue;
+            rules.push(parseRule(raw, "deny", "builtin"));
+        }
+    }
+    let mode = options.defaultMode ?? "default";
+    const add = (raw, effect, source) => {
+        try {
+            rules.push(parseRule(raw, effect, source));
+        }
+        catch (err) {
+            warnings.push(`${source}: ${err.message}`);
+        }
+    };
+    for (const layer of layers) {
+        const restricted = layer.source === "project";
+        if (layer.mode !== undefined) {
+            if (!PERMISSION_MODES_STRICT_FIRST.includes(layer.mode)) {
+                warnings.push(`${layer.source}: unknown permission mode "${String(layer.mode)}"`);
+            }
+            else if (restricted && !isAtLeastAsStrict(layer.mode, mode)) {
+                warnings.push(`project config cannot relax permission mode from "${mode}" to "${layer.mode}"; ignored`);
+            }
+            else {
+                mode = layer.mode;
+            }
+        }
+        for (const raw of layer.deny ?? [])
+            add(raw, "deny", layer.source);
+        for (const raw of layer.allow ?? []) {
+            if (restricted)
+                warnings.push(`project config cannot add allow rule "${raw}"; ignored`);
+            else
+                add(raw, "allow", layer.source);
+        }
+    }
+    return { mode, rules, warnings };
+}

package/dist/permissions/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 权限契约（设计 §6.2–§6.3、§7）。[B0] 契约文件，实现归 B3。
+ *
+ * 补全与偏差：
+ * - `ApprovalRequest / ApprovalDecision / ApprovalBroker` 在设计 §6.2 写在 host 契约里，
+ *   §1.2 又把 ApprovalRequest 列在本文件。统一定义在这里，host/types.ts 再导出。
+ * - 设计只写了 `Rule、Mode、Decision`；补全 `RuleSource`、`PermissionCheckInput`、
+ *   `PermissionVerdict`（带决定来自哪一步）与 Runtime 需要的 `PermissionPipelineApi`。
+ * - （W3-C0）执行前预览（第三波 §2.2）：`ActionPreview` 定义在这里，`ApprovalRequest.preview`
+ *   与 `permission_request` 事件携带；`ApprovalRequestContext.readFiles` 供 write 预览判断
+ *   「覆盖未读过的文件」。`previewAction()` 实现归 W3-B9a-2。
+ */
+import type { ToolPermission } from "../tools/types.js";
+/** 严格程度：plan > default > auto-edit > full-auto（项目级只能往左收紧，§7.2）。 */
+export type PermissionMode = "plan" | "default" | "auto-edit" | "full-auto";
+export declare const PERMISSION_MODES_STRICT_FIRST: readonly PermissionMode[];
+export type Decision = "allow" | "ask" | "deny";
+export type RuleSource = "builtin" | "user" | "profile" | "project" | "cli" | "sdk";
+/** `bash(git push*)`、`write(src/**)`、`read(**)`、`canvas_*` 解析结果。 */
+export interface Rule {
+    effect: "allow" | "deny";
+    /** 工具名 glob。 */
+    tool: string;
+    /** 括号内的 glob：bash 对命令文本，文件工具对路径；缺省匹配全部。 */
+    pattern?: string;
+    source: RuleSource;
+    /** 原始文本，用于诊断。 */
+    raw: string;
+}
+export type ApprovalReason = "mode" | "dangerous" | "hook";
+export interface ApprovalRequest {
+    requestId: string;
+    toolName: string;
+    input: unknown;
+    reason: ApprovalReason;
+    hookReason?: string;
+    /** [W3-C0] 执行前预览（只读、有上限）；预览超时或未实现时缺省。 */
+    preview?: ActionPreview;
+    /**
+     * 发起方上下文：`depth > 0` 表示来自 `task` 子 Agent（对话框标 `[task]`）；codemode 内层
+     * 调用带外层调用的 `parentToolCallId`。由子会话包装的 broker 填入，缺省视为主会话。
+     */
+    context?: ApprovalRequestContext;
+}
+export interface ApprovalRequestContext {
+    depth: number;
+    parentToolCallId?: string;
+    /** [W3-C0] 本会话已 read 过的路径（`ToolContext.readFiles`），由 `gateToolCall` 填入。 */
+    readFiles?: ReadonlySet<string>;
+}
+/** [W3-C0] 预览涉及的路径（bash 的 rm / mv / 重定向目标，write / edit 的目标文件）。 */
+export interface ActionPreviewTarget {
+    path: string;
+    exists: boolean;
+    bytes?: number;
+    /** 目录递归计数（上限外不再计）。 */
+    files?: number;
+}
+/** [W3-C0] 审批时「这一步会碰到什么」（第三波 §2.2）。线上形状，可 JSON 序列化。 */
+export interface ActionPreview {
+    kind: "bash" | "write" | "edit" | "other";
+    /** 已排好的人读文本（不含颜色）。 */
+    lines: string[];
+    severity: "info" | "warn" | "danger";
+    affected?: ActionPreviewTarget[];
+}
+export type ApprovalDecision = "allow" | "deny" | "allow_session";
+/** 返回 undefined 表示交给链上下一个回答者（宿主 → UI → 无人值守 deny）。 */
+export interface ApprovalBroker {
+    ask(request: ApprovalRequest, signal: AbortSignal): Promise<ApprovalDecision | undefined>;
+}
+export interface PermissionCheckInput {
+    toolName: string;
+    permission: ToolPermission;
+    input: unknown;
+    /** 命令式 Hook PreToolUse 合并后的决策（§6.3 第 2 步）；无决策为 undefined。 */
+    hookDecision?: Decision;
+    hookReason?: string;
+    /** 无人值守：ask → deny。 */
+    unattended: boolean;
+}
+/** 管线哪一步做出了最终决定。 */
+export type PermissionStep = "deny-rule" | "hook-deny" | "dangerous" | "mode" | "allow-rule" | "hook" | "session";
+export interface PermissionVerdict {
+    decision: Decision;
+    step: PermissionStep;
+    /** decision 为 ask 时给 broker 的 reason。 */
+    approvalReason?: ApprovalReason;
+    rule?: Rule;
+    /** 给模型 / 用户看的说明（deny 时写进 tool_result）。 */
+    message?: string;
+}
+export interface PermissionPipelineApi {
+    readonly mode: PermissionMode;
+    setMode(mode: PermissionMode): void;
+    readonly rules: readonly Rule[];
+    check(input: PermissionCheckInput): PermissionVerdict;
+    /** allow_session：内存记住 toolName + 归一化输入前缀，不落盘。 */
+    rememberForSession(toolName: string, input: unknown): void;
+}

package/dist/permissions/types.js

@@ -0,0 +1,18 @@
+/**
+ * 权限契约（设计 §6.2–§6.3、§7）。[B0] 契约文件，实现归 B3。
+ *
+ * 补全与偏差：
+ * - `ApprovalRequest / ApprovalDecision / ApprovalBroker` 在设计 §6.2 写在 host 契约里，
+ *   §1.2 又把 ApprovalRequest 列在本文件。统一定义在这里，host/types.ts 再导出。
+ * - 设计只写了 `Rule、Mode、Decision`；补全 `RuleSource`、`PermissionCheckInput`、
+ *   `PermissionVerdict`（带决定来自哪一步）与 Runtime 需要的 `PermissionPipelineApi`。
+ * - （W3-C0）执行前预览（第三波 §2.2）：`ActionPreview` 定义在这里，`ApprovalRequest.preview`
+ *   与 `permission_request` 事件携带；`ApprovalRequestContext.readFiles` 供 write 预览判断
+ *   「覆盖未读过的文件」。`previewAction()` 实现归 W3-B9a-2。
+ */
+export const PERMISSION_MODES_STRICT_FIRST = [
+    "plan",
+    "default",
+    "auto-edit",
+    "full-auto",
+];

package/dist/rpc.d.ts

@@ -0,0 +1,171 @@
+/**
+ * `@armadra/agent/rpc`：RPC（stdio JSONL，`--mode rpc`）命令 / 响应 / 事件类型（设计 §13.2，
+ * 框架沿用 v1 §8.4）。[B0] 契约文件，实现归 B6（modes/rpc/、modes/print/json-event.ts）。
+ *
+ * 补全与偏差：
+ * - 设计只列了命令名；参数形状按 v1 §8.4 补全，新增命令（get_available_thinking_levels、
+ *   set_auto_retry、abort_retry、get_fork_messages、set_permission_mode、get_commands、
+ *   get_skills）按名字含义补全。
+ * - 线上事件 = 进程内 `SessionEvent`，但 `message_update` 换成纯增量（去掉 partial / 累计消息，
+ *   附最新 usage）；stream-json 输出同一形状。
+ * - 类型定义直接放在本文件（B6 实现 import 它），避免子路径入口依赖实现文件。
+ */
+import type { AssistantEvent, ImageBlock, ModelThinkingLevel, Usage } from "./ai/types.js";
+import type { QueueMode, SessionEvent } from "./agent/types.js";
+import type { ApprovalDecision, PermissionMode } from "./permissions/types.js";
+export type { SessionEvent } from "./agent/types.js";
+export declare const RPC_PROTOCOL_VERSION: 1;
+export type RpcCapability = "approvals" | "images" | "hooks";
+export interface RpcHello {
+    type: "hello";
+    protocolVersion: typeof RPC_PROTOCOL_VERSION;
+    agent: "ama";
+    version: string;
+    capabilities: RpcCapability[];
+}
+/** 无参数命令。 */
+export type NoParams = Record<never, never>;
+export interface RpcCommandMap {
+    prompt: {
+        message: string;
+        images?: ImageBlock[];
+        streamingBehavior?: "steer" | "followUp";
+    };
+    steer: {
+        message: string;
+        images?: ImageBlock[];
+    };
+    follow_up: {
+        message: string;
+        images?: ImageBlock[];
+    };
+    abort: NoParams;
+    clear_queue: NoParams;
+    get_state: NoParams;
+    get_messages: NoParams;
+    get_last_assistant_text: NoParams;
+    get_session_stats: NoParams;
+    set_model: {
+        provider: string;
+        modelId: string;
+    };
+    get_available_models: NoParams;
+    set_thinking_level: {
+        level: ModelThinkingLevel;
+    };
+    get_available_thinking_levels: NoParams;
+    set_steering_mode: {
+        mode: QueueMode;
+    };
+    set_follow_up_mode: {
+        mode: QueueMode;
+    };
+    compact: {
+        customInstructions?: string;
+    };
+    set_auto_compaction: {
+        enabled: boolean;
+    };
+    set_auto_retry: {
+        enabled: boolean;
+    };
+    abort_retry: NoParams;
+    new_session: {
+        parentSession?: string;
+    };
+    switch_session: {
+        sessionPath: string;
+    };
+    fork: {
+        entryId: string;
+    };
+    get_entries: {
+        since?: string;
+    };
+    get_tree: NoParams;
+    set_session_name: {
+        name: string;
+    };
+    get_fork_messages: NoParams;
+    set_client_capabilities: {
+        capabilities: RpcCapability[];
+    };
+    permission_response: {
+        requestId: string;
+        decision: ApprovalDecision;
+    };
+    get_tools: NoParams;
+    set_active_tools: {
+        names: string[];
+    };
+    set_permission_mode: {
+        mode: PermissionMode;
+    };
+    get_commands: NoParams;
+    get_skills: NoParams;
+}
+export type RpcCommandType = keyof RpcCommandMap;
+/** `{ id?, type, ...参数 }`。 */
+export type RpcCommand = {
+    [K in RpcCommandType]: {
+        id?: string;
+        type: K;
+    } & RpcCommandMap[K];
+}[RpcCommandType];
+export type RpcCommandOf<K extends RpcCommandType> = Extract<RpcCommand, {
+    type: K;
+}>;
+export interface RpcModelInfo {
+    provider: string;
+    id: string;
+    name: string;
+    /** 只报有无，不回密钥。 */
+    hasKey: boolean;
+    keySource: "cli" | "auth-file" | "config" | "env" | "none";
+    contextWindow?: number;
+    maxTokens: number;
+    reasoning: boolean;
+    input: ("text" | "image")[];
+}
+export interface RpcCommandInfo {
+    name: string;
+    description?: string;
+    source: "builtin" | "template" | "skill";
+}
+export interface RpcSuccessResponse<D = unknown> {
+    id?: string;
+    type: "response";
+    command: RpcCommandType;
+    success: true;
+    data?: D;
+}
+export interface RpcErrorResponse {
+    id?: string;
+    type: "response";
+    /** JSON 解析失败时为 "parse" 且无 id。 */
+    command: RpcCommandType | "parse";
+    success: false;
+    error: string;
+    /** AmaError.code（若有）。 */
+    code?: string;
+}
+export type RpcResponse<D = unknown> = RpcSuccessResponse<D> | RpcErrorResponse;
+/** prompt / steer / follow_up 的 data。 */
+export interface RpcPromptData {
+    disposition: "started" | "queued" | "handled";
+}
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/** 线上助手事件：去掉 partial；done / error 仍带最终 message。 */
+export type WireAssistantEvent = DistributiveOmit<AssistantEvent, "partial">;
+export interface WireMessageUpdate {
+    type: "message_update";
+    assistantMessageEvent: WireAssistantEvent;
+    /** 最新 usage（供应商流中可得时）。 */
+    usage?: Usage;
+}
+export type RpcEvent = Exclude<SessionEvent, {
+    type: "message_update";
+}> | WireMessageUpdate;
+export type RpcEventType = RpcEvent["type"];
+/** stdout 上的一行。 */
+export type RpcOutbound = RpcHello | RpcResponse | RpcEvent;

package/dist/rpc.js

@@ -0,0 +1,13 @@
+/**
+ * `@armadra/agent/rpc`：RPC（stdio JSONL，`--mode rpc`）命令 / 响应 / 事件类型（设计 §13.2，
+ * 框架沿用 v1 §8.4）。[B0] 契约文件，实现归 B6（modes/rpc/、modes/print/json-event.ts）。
+ *
+ * 补全与偏差：
+ * - 设计只列了命令名；参数形状按 v1 §8.4 补全，新增命令（get_available_thinking_levels、
+ *   set_auto_retry、abort_retry、get_fork_messages、set_permission_mode、get_commands、
+ *   get_skills）按名字含义补全。
+ * - 线上事件 = 进程内 `SessionEvent`，但 `message_update` 换成纯增量（去掉 partial / 累计消息，
+ *   附最新 usage）；stream-json 输出同一形状。
+ * - 类型定义直接放在本文件（B6 实现 import 它），避免子路径入口依赖实现文件。
+ */
+export const RPC_PROTOCOL_VERSION = 1;

package/dist/sdk.d.ts

@@ -0,0 +1,98 @@
+/**
+ * SDK（设计 §13.1、实施计划 §1.3 C2）。[B6]
+ *
+ * - `createRuntime(options)`：与 CLI 同一条启动序列（bootstrap 第 3–14 步 + 组装根），读用户级 /
+ *   项目级配置、AGENTS.md、Skill、hooks.json、auth.json；不进入任何模式。参数可以写成字段，
+ *   也可以直接给 `argv`（与 `ama` 命令行同语法）。
+ * - `createAgentSession(options)`：不读文件系统配置的轻量装配——内存会话（或传入的
+ *   SessionManager）、选定的工具、规则与回调审批，直接返回 `AgentSessionImpl`
+ *   （含 `addTool / updateSystem / navigate` 等扩展方法）。
+ *
+ * 两者共用组装根（cli/compose*.ts），审批链、系统提示装配、工具预设与缓存行为与 CLI 一致。
+ */
+import type { ApiRegistry } from "./ai/apis/api.js";
+import type { ModelThinkingLevel, ProviderData } from "./ai/types.js";
+import type { AgentSessionImpl } from "./agent/session.js";
+import { type LogFn } from "./cli/compose-session.js";
+import { type ComposeOptions } from "./cli/compose.js";
+import type { Runtime } from "./cli/runtime.js";
+import type { AmaConfig, ToolsPreset } from "./config/types.js";
+import type { HookConfig } from "./hooks/types.js";
+import type { InstructionSource } from "./host/types.js";
+import type { ApprovalDecision, ApprovalRequest, PermissionMode } from "./permissions/types.js";
+import { SessionManager } from "./session/manager.js";
+import type { ToolDefinition } from "./tools/types.js";
+/** [W3-C2] 统计类型：`session.getStats()`、RPC `get_session_stats`、`-p --output-format json` 的 `cache`。 */
+export type { SessionCacheStats, SessionStats } from "./agent/types.js";
+export type { CacheMiss, CacheMissReason, CacheReporting, WarmerStatus, WarmingMode, } from "./ai/cache/types.js";
+export interface RuntimeOptions {
+    cwd?: string;
+    /** 与 `ama` 命令行同语法的参数（字段优先于这里的同名参数）。 */
+    argv?: string[];
+    model?: string;
+    thinkingLevel?: ModelThinkingLevel;
+    permissionMode?: PermissionMode;
+    toolsPreset?: ToolsPreset;
+    /** 信任项目（项目级 Hook / Skill / 提示模板）。 */
+    trust?: boolean;
+    sessionDir?: string;
+    profile?: string;
+    /** true：无人值守（ask → deny），同 `ama -p`。 */
+    unattended?: boolean;
+    env?: NodeJS.ProcessEnv;
+    stderr?: (text: string) => void;
+    /** 组装根选项：追加供应商 / 协议 / 工具 / 工具工厂。 */
+    compose?: ComposeOptions;
+}
+export declare function createRuntime(options?: RuntimeOptions): Promise<Runtime>;
+export type SessionAuth = {
+    kind: "file";
+    path: string;
+} | {
+    kind: "env";
+} | {
+    kind: "inline";
+    keys: Record<string, string>;
+} | {
+    kind: "none";
+};
+export interface CreateSessionOptions {
+    cwd?: string;
+    /** `provider/model-id`；缺省 config.defaultModel，再缺省零配置选择（第一个有 key 的供应商）。 */
+    model?: string | {
+        provider: string;
+        id: string;
+    };
+    thinkingLevel?: ModelThinkingLevel;
+    /** 缺省：用户级 auth.json + 环境变量。 */
+    auth?: SessionAuth;
+    /** 追加 / 覆盖的供应商（fake 总是可用）。 */
+    providers?: ProviderData[];
+    apis?: ApiRegistry;
+    /** 缺省内存会话。 */
+    sessionManager?: SessionManager;
+    /** `default`（缺省，按预设）/ `none` / 指定工具全集。 */
+    tools?: "default" | "none" | ToolDefinition[];
+    toolsPreset?: ToolsPreset;
+    extraTools?: ToolDefinition[];
+    disableTools?: string[];
+    /** 进系统提示 host 节。 */
+    instructions?: InstructionSource[];
+    skillDirs?: string[];
+    /** 读 AGENTS.md（缺省 false）。 */
+    contextFiles?: boolean;
+    permission?: {
+        mode?: PermissionMode;
+        allow?: string[];
+        deny?: string[];
+        /** 审批回调；缺省无人作答 → deny。 */
+        ask?(request: ApprovalRequest, signal: AbortSignal): Promise<ApprovalDecision>;
+    };
+    /** 命令式 Hook（缺省不加载文件系统里的 hooks.json）。 */
+    hooks?: HookConfig | false;
+    config?: Partial<AmaConfig>;
+    unattended?: boolean;
+    onWarning?: (message: string) => void;
+    log?: LogFn;
+}
+export declare function createAgentSession(options?: CreateSessionOptions): Promise<AgentSessionImpl>;