@autopilot-agent/cli 0.0.0-stage → 0.1.0

package/dist/context-report.js

@@ -0,0 +1,174 @@
+/**
+ * Context Usage 安全报告格式化。
+ *
+ * 所有输入只来自 Core 白名单 ContextUsageView DTO；宿主只做展示转换，
+ * 不重算 token、不猜测窗口、不为非零分类强塞至少一格。
+ */
+/** Core 固定枚举到 CLI 稳定中文标签的映射；不携带动态名称。 */
+const CONTEXT_CATEGORY_LABELS = {
+    system: "系统",
+    instructions: "项目指令",
+    memory: "Memory",
+    skills: "Skills",
+    tools: "工具",
+    conversation: "对话",
+    other: "其他",
+    output_reserve: "输出预留",
+};
+/** Memory/Skills 以聚合行展示，不再出现在固定分类列表。 */
+const AGGREGATED_CATEGORY_KINDS = new Set(["memory", "skills"]);
+/** 1M 及以上窗口在相同列数下提供更细的网格分辨率。 */
+const HIGH_RESOLUTION_WINDOW_TOKENS = 1_000_000;
+/** 千分位数字格式；固定 locale 保证 Plain/JSONL/TUI 输出稳定。 */
+function formatTokens(tokens) {
+    return tokens.toLocaleString("en-US");
+}
+/** 百分比格式；usageRatio 不在 Core clamp，允许显示超过 100% 的真实值。 */
+function formatPercent(ratio) {
+    return `${(ratio * 100).toFixed(1)}%`;
+}
+/** 单条分类的稳定文本行；expanded 追加 projected 比例。 */
+function formatCategoryLine(category, expanded) {
+    const label = CONTEXT_CATEGORY_LABELS[category.kind];
+    const items = category.itemCount !== undefined ? ` · ${formatTokens(category.itemCount)} items` : "";
+    const reserved = category.measurement === "reserved" ? " (reserved)" : "";
+    const base = `${label}: ${formatTokens(category.tokens)} tokens${items} (${formatPercent(category.windowRatio)} window)${reserved}`;
+    return expanded ? `${base} · ${formatPercent(category.projectedRatio)} projected` : base;
+}
+/** Memory/Skills 聚合行；expanded 时补充 Core 已提供的窗口占比与 projected 占比。 */
+function formatAggregatedCategoryLine(category, expanded) {
+    const label = category.kind === "memory" ? "Memory files" : "Skills";
+    const items = category.itemCount !== undefined ? `${formatTokens(category.itemCount)} items · ` : "";
+    const base = `${label}: ${items}${formatTokens(category.tokens)} tokens`;
+    return expanded ? `${base} (${formatPercent(category.windowRatio)} window) · ${formatPercent(category.projectedRatio)} projected` : base;
+}
+/** 右侧信息区的稳定文本行；字段顺序固定，供 Plain/TUI/视口共用。 */
+function formatContextSummaryLines(usage, expanded) {
+    const lines = [
+        `model: ${usage.modelRef}`,
+        `projected: ${formatTokens(usage.projectedTokens)} / ${formatTokens(usage.contextWindowTokens)} tokens (${formatPercent(usage.usageRatio)} projected) · ${usage.measurement}`,
+        "usage by category (estimated):",
+    ];
+    for (const category of usage.breakdown.categories) {
+        if (AGGREGATED_CATEGORY_KINDS.has(category.kind))
+            continue;
+        lines.push(`  ${formatCategoryLine(category, expanded)}`);
+    }
+    lines.push(`Free space: ${formatTokens(usage.breakdown.freeTokens)} tokens (${formatPercent(usage.breakdown.freeRatio)})`, `Autocompact buffer: ${formatTokens(usage.breakdown.compactBufferTokens)} tokens (${formatPercent(usage.breakdown.compactBufferRatio)})`);
+    for (const category of usage.breakdown.categories) {
+        if (!AGGREGATED_CATEGORY_KINDS.has(category.kind))
+            continue;
+        const aggregated = formatAggregatedCategoryLine(category, expanded);
+        if (aggregated)
+            lines.push(aggregated);
+    }
+    return lines;
+}
+/** /context all 的安全展开块；只补充 DTO 已有字段，不生成派生结论。 */
+function formatContextDetailLines(usage) {
+    const lines = [
+        "Context usage details (all):",
+        `overall measurement: ${usage.measurement}`,
+        `breakdown measurement: ${usage.breakdown.measurement}`,
+        `provider measured: ${usage.providerMeasuredTokens !== undefined ? `${formatTokens(usage.providerMeasuredTokens)} tokens` : "not available"}`,
+        `estimated added: ${formatTokens(usage.estimatedAddedTokens)} tokens`,
+        `current context: ${formatTokens(usage.currentContextTokens)} tokens`,
+        `output reserve: ${formatTokens(usage.outputReserveTokens)} tokens`,
+        `compact trigger: ${formatTokens(usage.compactTriggerTokens)} tokens`,
+        `compact needed: ${usage.compactNeeded ? "yes" : "no"}`,
+        `free: ${formatTokens(usage.breakdown.freeTokens)} tokens (${formatPercent(usage.breakdown.freeRatio)})`,
+        `compact buffer: ${formatTokens(usage.breakdown.compactBufferTokens)} tokens (${formatPercent(usage.breakdown.compactBufferRatio)})`,
+        `over limit: ${formatTokens(usage.breakdown.overLimitTokens)} tokens (${formatPercent(usage.breakdown.overLimitRatio)})`,
+    ];
+    return lines;
+}
+/** 网格尺寸：窄屏降列数，>=1M 窗口提升行数（Plan 9.5）。 */
+function resolveGridShape(usage, columns) {
+    const highResolution = usage.contextWindowTokens >= HIGH_RESOLUTION_WINDOW_TOKENS;
+    if (columns < 80)
+        return { cols: 5, rows: highResolution ? 10 : 5 };
+    return { cols: highResolution ? 20 : 10, rows: 10 };
+}
+/** 用最大余数法把 window 分配到固定格子；零份额分类不保留格子。 */
+function allocateGridCells(shares, totalCells, windowTokens) {
+    const raw = shares.map(function toFraction(tokens) { return tokens / windowTokens * totalCells; });
+    const base = raw.map(function floorShare(value) { return Math.floor(value); });
+    let remaining = totalCells - base.reduce(function sumCells(total, cells) { return total + cells; }, 0);
+    const order = raw
+        .map(function toRemainder(value, index) { return { index, remainder: value - Math.floor(value) }; })
+        .sort(function byRemainderDesc(left, right) { return right.remainder - left.remainder || left.index - right.index; });
+    for (const item of order) {
+        if (remaining <= 0)
+            break;
+        base[item.index] += 1;
+        remaining -= 1;
+    }
+    return base;
+}
+/** 渲染网格行：已用/侵入 buffer/free/剩余 buffer 使用不同单格宽字符。 */
+function renderGridLines(usage, columns) {
+    const { cols, rows } = resolveGridShape(usage, columns);
+    const projected = Math.min(usage.projectedTokens, usage.contextWindowTokens);
+    const usedMain = Math.min(projected, usage.compactTriggerTokens);
+    const usedBuffer = Math.max(projected - usage.compactTriggerTokens, 0);
+    const free = Math.max(usage.breakdown.freeTokens, 0);
+    const bufferRemaining = Math.max(usage.breakdown.compactBufferTokens - usedBuffer, 0);
+    const counts = allocateGridCells([usedMain, usedBuffer, free, bufferRemaining], cols * rows, usage.contextWindowTokens);
+    const glyphs = ["█", "▓", "░", "▒"];
+    // 按份额顺序展开为每格字符；未分配格子保持空白。
+    const cellGlyphs = [];
+    counts.forEach(function expandCells(count, shareIndex) {
+        for (let index = 0; index < count; index += 1)
+            cellGlyphs.push(glyphs[shareIndex] ?? " ");
+    });
+    // Array.from 回调首参是 element，行号在第二参；用错会把行号算成 NaN 并全部回退空格。
+    return Array.from({ length: rows }, function buildRow(_element, rowIndex) {
+        let line = "";
+        for (let colIndex = 0; colIndex < cols; colIndex += 1) {
+            line += cellGlyphs[rowIndex * cols + colIndex] ?? " ";
+        }
+        return line;
+    });
+}
+/**
+ * 生成 Context 报告文本行。
+ * grid=false（Plain/screen reader/NO_COLOR）跳过装饰网格但保留完整文本；
+ * 列数不足以并排时整体改为上下堆叠。
+ */
+export function formatContextReportLines(usage, expanded, options) {
+    if (!usage)
+        return ["Context: unknown"];
+    const rightLines = formatContextSummaryLines(usage, expanded);
+    if (expanded)
+        rightLines.push(...formatContextDetailLines(usage));
+    if (!options.grid) {
+        return ["Context Usage", ...rightLines, "", "/context all to expand"];
+    }
+    const gridLines = renderGridLines(usage, options.columns);
+    const gridWidth = gridLines.reduce(function maxGridWidth(width, line) { return Math.max(width, line.length); }, 0);
+    const stackVertically = gridWidth + 2 + 30 > options.columns;
+    const rows = ["Context Usage"];
+    if (stackVertically) {
+        rows.push(...gridLines, ...rightLines);
+    }
+    else {
+        const height = Math.max(gridLines.length, rightLines.length);
+        for (let index = 0; index < height; index += 1) {
+            const gridLine = (gridLines[index] ?? "").padEnd(gridWidth, " ");
+            rows.push(`${gridLine}  ${rightLines[index] ?? ""}`.trimEnd());
+        }
+    }
+    rows.push("", "/context all to expand");
+    return rows;
+}
+/** Plain/非 TTY 的稳定文本报告；始终跳过装饰网格。 */
+export function formatPlainContextReport(usage, expanded) {
+    return formatContextReportLines(usage, expanded, { grid: false, columns: Number.MAX_SAFE_INTEGER });
+}
+/** 状态栏 Context 行的紧凑文本：`12.3% · measured` / `≈1.2% · estimated` / `unknown`。 */
+export function formatTuiContextStatus(usage) {
+    if (!usage)
+        return "unknown";
+    const percent = formatPercent(usage.usageRatio);
+    return `${usage.measurement === "measured" ? "" : "≈"}${percent} · ${usage.measurement}`;
+}

package/dist/controller.d.ts

@@ -0,0 +1,79 @@
+/**
+ * CLI Controller。
+ *
+ * Controller 是 Action 到 Core Runtime Public API 的唯一映射层；它不实现
+ * Session/Turn 状态机，审批只从当前安全 projection 取得 approvalId，绝不
+ * 生成 callId、toolName、normalizedInputHash 或冻结工具输入。
+ */
+import type { AgentEvent, ApprovalDecision, ContextUsageView } from "@autopilot-agent/core";
+import type { CliAction, CliCommand, CliEffortOption, CliExitCode, CliEventListener, CliJobView, CliQueuedInputStartedListener, CliModelOption, CliPermissionOption, CliProjection, CliRenderer, CliRuntimeStatusDefaults, CliSkillCatalogLister, CliSkillResolver, CliSkillSummary, CliStatusView, CliRuntime } from "./types.js";
+/** 为当前 Controller 注入的审批提交回调；四字段之外不允许宿主提供凭证。 */
+export type CliApprovalSubmit = (input: {
+    sessionId: string;
+    turnId: string;
+    approvalId: string;
+    decision: "allow_once" | "allow_session" | "allow_workspace" | "deny";
+}) => Promise<ApprovalDecision>;
+/** Controller 输出结果；lines 由 Main 统一写入 stdout/stderr。 */
+export interface CliControllerResult {
+    kind: "ok" | "exit" | "error" | "unavailable";
+    exitCode: CliExitCode;
+    lines: string[];
+    message?: string;
+    skillOptions?: CliSkillSummary[];
+    /** 交互 TTY 用于打开权限 picker；Plain 模式使用同一结果中的稳定 lines。 */
+    permissionOptions?: CliPermissionOption[];
+    /** 交互 TTY 用于打开模型 picker；Plain 模式使用同一结果中的稳定 lines。 */
+    modelOptions?: CliModelOption[];
+    /** 交互 TTY 用于打开推理强度 picker；Plain 模式使用同一结果中的稳定 lines。 */
+    effortOptions?: CliEffortOption[];
+    /** 当前 Session 的后台任务列表或详情；TUI 直接消费安全 DTO。 */
+    jobView?: CliJobView;
+    /** 状态栏使用的安全配置视图。 */
+    statusView?: CliStatusView;
+    /** /context 的专用安全报告；TUI 渲染为静态 transcript item，Plain/JSONL 消费 lines。 */
+    contextView?: {
+        usage: ContextUsageView | null;
+        expanded: boolean;
+    };
+    /** 运行中输入成功写入 durable inbox 后，供 TUI 标识等待中的引导或排队消息。 */
+    submittedInput?: {
+        inputId: string;
+        delivery: "steer" | "queue";
+    };
+    projection: CliProjection;
+}
+/** Controller 创建参数。 */
+export interface CreateCliControllerOptions {
+    runtime?: CliRuntime;
+    renderer: CliRenderer;
+    sessionId?: string;
+    approvalSubmit?: CliApprovalSubmit;
+    listSkills?: CliSkillCatalogLister;
+    resolveSkill?: CliSkillResolver;
+    /** Composition Root 传入的 canonical workspaceRoot，只用于安全状态栏展示。 */
+    workspaceRoot?: string;
+    /** 读取已热更新的安全 Runtime 默认值；仅用于 idle/Completed 状态栏，不参与 Turn 冻结。 */
+    getRuntimeStatusDefaults?: () => CliRuntimeStatusDefaults;
+    onEvent?: CliEventListener;
+    /** 自动启动 queue Turn 前通知交互 TUI，避免等待 prompt 残留在底部。 */
+    onQueuedInputStarted?: CliQueuedInputStartedListener;
+    now?: () => Date;
+}
+/** CLI Controller 对外接口。 */
+export interface CliController {
+    dispatch(action: CliAction): Promise<CliControllerResult>;
+    consume(events: AsyncIterable<AgentEvent>): Promise<CliControllerResult>;
+    resume(): Promise<CliControllerResult>;
+    getProjection(): CliProjection;
+    /** 读取当前 Session 默认或活动 Turn frozen 的脱敏状态栏视图。 */
+    getStatusView?(): Promise<CliStatusView>;
+    setSession(sessionId: string): void;
+    setEventListener(listener?: import("./types.js").CliEventListener): void;
+    /** 绑定 queue Turn 启动通知；Plain 宿主不需要注册。 */
+    setQueuedInputListener?(listener?: CliQueuedInputStartedListener): void;
+}
+/** 创建无 React 依赖的 Controller；Renderer 和 Runtime 均通过参数注入。 */
+export declare function createCliController(options: CreateCliControllerOptions): CliController;
+/** 将 argv 命令转换为 Step 5.2 可执行范围内的 Controller Action。 */
+export declare function commandToAction(command: CliCommand): CliAction | undefined;