neoctl 0.2.29 → 0.2.31

package/README.md

@@ -262,15 +262,17 @@ REPL 当前注册的内置工具：
 
 ### 命令执行
 
-`exec_command` 根据平台和 `shell` 参数选择 PowerShell、cmd、bash 或 sh。命令启动后持续收集输出；首次等待期内结束则直接返回，仍在运行则返回 `session_id`，进程不会依赖当前模型轮次存活。
+`exec_command` 根据平台和 `shell` 参数选择 PowerShell、cmd、bash 或 sh。命令启动后持续收集输出；首次等待期内结束则直接返回，仍在运行则返回 `session_id`，进程不会依赖当前模型轮次存活。`timeout_ms` 约束命令进入后台前的前台阶段；一旦命令让出成为后台终端，超时计时器会被清除，任务将持续运行到自行退出、显式停止或宿主进程关闭。
 
 - `workdir`：命令工作目录。
-- `timeout_ms`：进程总生命周期上限。
+- `timeout_ms`：命令进入后台前的前台阶段超时上限；后台任务不设自动超时。
 - `yield_time_ms`：首次等待时间；到期后将仍在运行的命令交还为后台终端。
 - `max_output_chars`：分别限制每次待读取的 stdout/stderr，超限时保留开头和结尾。
 - `tty=true`：通过 PTY/ConPTY 运行需要真实终端语义的交互程序。
 
-`write_stdin` 使用 `session_id` 续接后台终端：空字符用于等待并读取新增输出，非空字符原样写入终端，也可发送 interrupt、terminate 或 kill。不同终端可并行执行，同一终端的交互按调用顺序串行处理。
+`stdout`、`stderr`、`output_chars` 和 `omitted_chars` 都是本次调用新消费的增量；调用方应追加保存，重复查询终态不会返回已经读取的输出。`duration_ms` 是进程实际运行时间，进入终态后保持不变。每个终态都通过 `termination_reason` 区分正常完成、非零退出、用户中断、用户终止、强制停止、超时、外部信号和启动错误。Windows TTY 优先返回终端进程 PID；底层无法提供时返回 PTY 宿主 PID，不返回 `0`。TTY 输出可能包含 ANSI/VT 控制序列，后端会原样保留供终端界面解释。
+
+`write_stdin` 使用 `session_id` 续接后台终端：空字符用于等待并读取新增输出，非空字符原样写入终端，也可发送 interrupt、terminate 或 kill。不同终端可并行执行，同一终端的交互按调用顺序串行处理。并行工具批次采用聚合返回语义：单个调用的 `yield_time_ms` 只约束该调用自身，不约束整批结果的交付时间；需要观察精确状态时序时应串行调用 `exec_command` 与 `write_stdin`。
 
 ## 上下文与压缩
 
@@ -284,7 +286,7 @@ REPL 当前注册的内置工具：
 压缩实现位于 `src/context/compaction.ts`：
 
 - `DeterministicCompactor` 提供可预测的 snip、microcompact、summary fallback。
-- 默认运行时使用 `ManualOnlyCompactor`，仅保留 manual compact 和 pure compact；显式注入其它 `Compactor` 时仍可用于测试或定制策略。
+- 默认运行时使用 `ModelDrivenCompactor`：达到上下文窗口阈值时主动压缩，模型返回上下文超限错误时执行响应式压缩并重试；如需仅允许手动压缩，可显式注入 `ManualOnlyCompactor`。
 - 当工具结果过大时，session 模式下 `FileToolResultMemory` 会把完整结果写入文件，仅把预览和路径留在上下文中。
 
 ## 会话持久化
@@ -404,6 +406,40 @@ const canUseTool = createSkillAwareCanUseTool(skills, parentCanUseTool);
 
 建议：开放 `skill_create`/`skill_update` 给模型时保持 approval；对 remote/plugin skill 使用只读 root；生产环境使用 `createSkillAwareCanUseTool()` 或父级权限系统强制 `allowedTools`。
 
+## 插件协议
+
+Core 提供 `neo-plugin/v1` 目录资源协议和 `loadNeoPlugins()` 动态加载器。Core 只定义协议、校验并加载资源，不内置任何外部插件实现。
+
+一个插件根目录可以包含多个直接子目录；每个插件目录必须包含 `neo-plugin.json`：
+
+```json
+{
+  "protocol": "neo-plugin/v1",
+  "id": "example",
+  "name": "Example",
+  "version": "1.0.0",
+  "entry": "index.mjs",
+  "defaultEnabled": true
+}
+```
+
+入口模块导出 `createPlugin(context)` 或默认工厂函数，返回以下能力之一或多项：
+
+- `tools`: 符合 Core `Tool` 协议的工具数组。
+- `promptSections`: 符合 `PromptSection` 协议的系统提示词段。
+- `route(req, res, url, helpers)`: 由嵌入后台托管的 HTTP 路由处理器。
+
+```ts
+import { loadNeoPlugins } from "neoctl";
+
+const plugins = await loadNeoPlugins({
+  directories: "/absolute/path/to/plugins",
+  appDataDir: "/absolute/path/to/app-data",
+});
+```
+
+加载器会校验清单版本、插件 id、入口边界、工具/提示词结构、插件 id 冲突和工具名冲突；不存在的插件根目录视为空目录。
+
 ## 作为库使用
 
 包入口会导出核心 agent 编排运行时、模型网关、上下文管理、任务/子代理、工具系统、session 与 safety 边界：

package/dist/context/compaction.d.ts

@@ -9,20 +9,36 @@ export interface ContextBudgetOptions {
     autoCompactTriggerRatio?: number;
     microCompactTriggerRatio?: number;
     snipCompactTriggerRatio?: number;
+    /** @deprecated Summary checkpoints preserve recent user messages by token budget instead. */
     keepRecentMessages?: number;
     keepRecentTokenBudget?: number;
     keepRecentToolResults?: number;
+    /** Character budget for deterministic fallback, snip, and pure summaries. Model summaries use compactMaxOutputTokens. */
     summaryMaxChars?: number;
+    /** @deprecated Checkpoint summaries serialize the complete pre-compaction window. */
+    compactInputMaxChars?: number;
     compactModel?: string;
     compactMaxOutputTokens?: number;
 }
 export type CompactionReason = "none" | "snip" | "microcompact" | "autocompact" | "reactive_compact" | "manualcompact" | "purecompact";
+export interface CompactionReport {
+    reason: Exclude<CompactionReason, "none">;
+    summary: string;
+    continuationState: string;
+    sourceMessages: number;
+    preservedUserMessages: number;
+    newWindowMessages: number;
+    charsFreed: number;
+    modelDriven: boolean;
+    imageCount: number;
+}
 export interface CompactionResult {
     messages: Message[];
     summary?: string;
     changed: boolean;
     reason?: CompactionReason;
     charsFreed?: number;
+    report?: CompactionReport;
     /** @deprecated Use charsFreed instead. Alias kept for backward compatibility. */
     tokensFreed?: number;
 }
@@ -41,13 +57,12 @@ export declare class DeterministicCompactor implements Compactor {
 }
 export declare class ModelDrivenCompactor implements Compactor {
     private readonly modelGateway;
-    private readonly fallback;
     constructor(modelGateway: ModelGateway);
     compact(messages: readonly Message[], options?: ContextBudgetOptions): Promise<CompactionResult>;
     manualCompact(messages: readonly Message[], options?: ContextBudgetOptions): Promise<CompactionResult>;
     pureCompact(messages: readonly Message[], options?: ContextBudgetOptions): Promise<CompactionResult>;
-    reactiveCompact(messages: readonly Message[], error: Error, options?: ContextBudgetOptions): Promise<CompactionResult>;
-    private modelAutoCompactIfNeeded;
+    reactiveCompact(messages: readonly Message[], _error: Error, options?: ContextBudgetOptions): Promise<CompactionResult>;
+    private createCheckpoint;
     private summarizeWithModel;
 }
 export declare class NoopCompactor implements Compactor {
@@ -67,7 +82,8 @@ export declare class ManualOnlyCompactor implements Compactor {
     pureCompact(messages: readonly Message[], options?: ContextBudgetOptions): Promise<CompactionResult>;
     reactiveCompact(messages: readonly Message[], _error: Error, _options?: ContextBudgetOptions): Promise<CompactionResult>;
 }
+export declare function withCompactionReport(result: CompactionResult, sourceMessages: number): CompactionResult;
 export declare function estimateMessagesChars(messages: readonly Message[]): number;
 export declare function snipCompactIfNeeded(messages: readonly Message[], options?: ContextBudgetOptions): CompactionResult;
 export declare function microCompactIfNeeded(messages: readonly Message[], options?: ContextBudgetOptions): CompactionResult;
-export declare function autoCompactIfNeeded(messages: readonly Message[], options?: ContextBudgetOptions): CompactionResult;
+export declare function autoCompactIfNeeded(messages: readonly Message[], options?: ContextBudgetOptions, sourceMessages?: readonly Message[]): CompactionResult;