laohuang 0.3.2 → 0.4.0

package/README.md

@@ -1,27 +1,153 @@
-# laohuang
+# laoHuangCode
 
-This npm package provides the `laohuang` command for
-[laoHuangCode](https://github.com/hxr223/laoHuangCode).
+一个最小的 coding agent，基于 TypeScript/Node.js、官方 `openai` npm SDK 和
+Chat Completions 原生工具调用。
 
-It is a small Node.js launcher, not a second implementation of the agent. On
-first run it creates an isolated Python environment in the user cache and
-installs the bundled `laohuangcode` Python wheel. Python 3.11 or newer must
-already be available as `python3` or `python`. Third-party Python dependencies
-are downloaded by pip during this first launch.
+当前提供四个工具：`read`、`write`、`edit`、`bash`。所有工具均直接执行，当前原型
+暂不提供权限确认。
+
+同一次模型响应中的只读工具与多个 Bash 调用默认并发执行。实时事件按工具实际完成
+顺序发出，回传模型的 `tool` 消息保持原始调用顺序。只要一个批次包含 `write` 或
+`edit`，Agent 会保守地串行执行整个批次，避免读写或多次修改之间出现竞态。
+
+交互终端采用后台 AgentSession：模型回复和 Bash 的 stderr/状态会实时显示，stdout
+会保留在工具结果中但默认不刷到终端，
+Agent 运行时仍可继续输入。后续输入由事件路由器放入 pending/held 队列，并在安全点
+成批交给模型；当前任务可以通过 `/cancel` 或运行中的 `Ctrl+C` 协作式取消。
+连续重复的工具调用和 Token、耗时预算会触发安全保护；保护触发后
+Agent 会禁用工具并尝试基于已有信息完成一次最终回答。
+
+## 快速开始
+
+需要 Node.js 18+。面向普通用户的安装方式：
 
 ```bash
 npm install --global laohuang
-laohuang --version
 laohuang
 ```
 
-The first interactive launch asks for DeepSeek or OpenAI, reads the API key
-with hidden terminal input, and then asks which model to use. No API key
-environment variable is needed.
+首次启动会在终端中依次选择 DeepSeek 或 OpenAI、隐藏输入 API key、选择模型，
+不需要设置环境变量。配置完成后，进入任意项目目录直接运行 `laohuang`。
+
+从源码运行：
+
+```bash
+git clone https://github.com/hxr223/laoHuangCode.git
+cd laoHuangCode
+npm ci
+npm run build
+node dist/cli.js
+```
+
+## 模型配置
+
+首次运行时，终端会提供两个供应商：
+
+- DeepSeek：内置 `deepseek-v4-flash` 和 `deepseek-v4-pro`。
+- OpenAI：使用输入的 API key 动态读取账户可用模型，也可手动输入模型名。
+
+API key 使用隐藏输入，保存在独立的
+`~/.config/laohuang/credentials.json` 中。普通模型配置保存在同目录的
+`config.json`；两个文件均使用 `0600` 权限，目录使用 `0700` 权限。
+
+```text
+/model                              交互选择供应商和模型
+/model current                      查看当前模型
+/model deepseek deepseek-v4-pro     直接切换模型
+/model openai <model-name>          直接切换 OpenAI 模型
+/login                              交互选择供应商并登录
+/login deepseek                     输入或覆盖 DeepSeek API key
+/logout openai                      删除保存的 OpenAI 凭据
+/cancel                             取消当前运行任务
+/queue                              查看 pending/held/dead-letter 与估算 token
+/queue resume                       恢复取消后保留的消息
+/queue clear                        清空 pending/held/dead-letter
+/clear                              清空当前对话上下文
+```
+
+认证和模型选择相互独立：`/login`、`/logout` 管理凭据，`/model` 只切换模型。
+如果请求返回 401，Agent 会提示对应的 `/login <provider>` 命令。旧的
+`/apikey set`、`/apikey remove` 暂时保留为兼容别名。
+
+常用配置命令：
+
+```bash
+laohuang config list
+laohuang config use default
+laohuang doctor
+```
+
+完整规则见 [模型配置文档](docs/configuration.md)。
+
+## 运行
+
+进入希望 Agent 操作的项目目录后执行：
+
+```bash
+laohuang
+```
+
+输入任务，使用 `/help` 查看命令，使用 `/exit` 或 `Ctrl+D` 退出。通过 `/model`
+切换供应商或模型时会保留当前对话上下文。
+
+交互终端使用简洁的上下边框标识输入区域，不显示常驻状态或快捷键底栏。输入 `/` 会
+立即显示命令、说明和参数补全；`Tab`/`Enter` 可接受当前补全，`/model` 会按
+“供应商 → 模型”分层补全。终端还支持多行
+编辑和当前会话输入历史：
+
+- `Enter`：发送任务。
+- `Alt+Enter`：插入换行。
+- `↑` / `↓`：浏览历史输入。
+- Agent 运行中按 `Ctrl+C`：取消当前任务。
+- Agent 空闲时按 `Ctrl+C`：清空输入；500ms 内再按一次：退出。
+- `Ctrl+D`：退出。
+
+模型文本和 Bash stderr/状态采用 append-only inline 流式展示，工具输出按 tool call 分组；
+被取消或截断的半条模型回复会保留在屏幕上并标记“未加入上下文”。完整的逐轮事件仍可
+通过 Web 日志面板查看。输出被重定向或由程序调用 CLI 时，会自动回退到稳定的纯文本
+格式。
+
+### 验证交互终端
+
+1. 在真实 TTY 中运行 `laohuang`。
+2. 发送第一个问题并等待回答完成。
+3. 发送第二个问题；向上滚动确认第一个问题和回答仍保留且未被改写。
+4. 输入 `/` 和 `/e`，确认候选只占可见行数，`Tab` 可接受 `/exit`，继续编辑会移除补全层。
+5. 任务运行中按 `Ctrl+C` 取消；空闲且编辑器为空时按 `Ctrl+D` 退出。
+
+当前版本不会在工具执行前请求确认。请只在你信任的项目和环境中运行。
+
+### Web 日志面板
+
+```bash
+laohuang --web
+laohuang --web --web-port 9000
+```
+
+面板默认位于 <http://127.0.0.1:8765>，展示模型轮次、工具调用和最终
+回复。它只监听本机，数据只存在内存中，进程退出后清空。
+
+## 开发与发布检查
+
+```bash
+npm ci
+npm run build
+npm test
+```
+
+`npm run build` 通过 `tsc` 把 `src/` 编译到 `dist/`；`npm test` 使用 Node 自带的
+`node:test` 运行 `test/` 下的离线测试套件，不需要网络访问。发布流程见
+[发布流程](docs/publishing.md) 和 [npm 分发说明](docs/npm-distribution.md)。
+
+## 安全边界
+
+文件工具会限制在启动目录内并阻止符号链接逃逸；API key 不通过环境变量传递给
+Bash。但 `bash` **没有操作系统级沙箱**，执行后仍能访问项目外文件、网络和其他
+系统资源。公开使用前请阅读 [安全模型](docs/security.md)。
 
-The launcher accepts two advanced environment variables:
+架构说明见 [docs/architecture.md](docs/architecture.md)；设计文档归档在
+[docs/superpowers/specs/](docs/superpowers/specs/)。
 
-- `LAOHUANG_PYTHON`: run a specific Python executable and skip bootstrapping.
-- `LAOHUANG_CACHE_HOME`: override the launcher's cache root.
+## License
 
-See the main project README for model configuration and security details.
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,166 @@
+/**
+ * The model/tool loop at the heart of laoHuangCode.
+ *
+ * One user turn streams model completions through the provider-neutral
+ * adapter boundary (model-adapter.ts), commits
+ * only fully validated attempts to history (atomically, via the owning
+ * session's commit hooks when present), executes tool-call batches
+ * (read-only tools and multiple bash calls concurrently; any write/edit or
+ * sequential-mode tool makes the whole batch serial), and enforces the
+ * runtime guard rails: repeated-identical-tool-call detection plus token and
+ * duration budgets. A triggered guard disables tools and asks the model for
+ * one final answer from the information already gathered.
+ */
+import { CancelToken } from "./cancellation.ts";
+import { EventKind, EventSource, type EventBus } from "./events.ts";
+import { type ChatClientLike } from "./model-adapter.ts";
+import type { ToolDefinition, ToolExecutionContextLike, ToolExecutionMode, ToolResult, ToolSpec } from "./tools.ts";
+import { ProjectInstructionState } from "./project-instructions.ts";
+export declare const FORCED_FINAL_PROMPT = "Tool use has been stopped by the runtime safety guard.\nDo not call any tools. Give the user the best concise answer possible from the\ninformation already available. Clearly state any limitation caused by stopping\ntool use, but do not mention internal implementation details unless useful.";
+/** Raised when the model response cannot drive the agent loop. */
+export declare class AgentError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Raised when the active agent task is cooperatively cancelled. */
+export declare class AgentCancelled extends AgentError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export type AgentEventCallback = (eventType: string, payload: Record<string, unknown>) => void;
+export type ToolEventCallback = (name: string, args: Record<string, unknown>, result: ToolResult) => void;
+export type { ChatClientLike } from "./model-adapter.ts";
+/** Structural minimum of ToolRegistry (tools.ts) the agent relies on. */
+export interface AgentToolRegistry {
+    readonly definitions: readonly ToolDefinition[];
+    readonly orderedSpecs: readonly ToolSpec[];
+    executionMode(name: string): ToolExecutionMode | undefined;
+    execute(name: string, args: Record<string, unknown>, context?: ToolExecutionContextLike): Promise<ToolResult> | ToolResult;
+}
+/** Pending user input handed over at a session safe point. */
+export interface PendingInputBatchLike {
+    content?: string | undefined;
+    eventIds?: readonly string[] | undefined;
+}
+/** Options for the session-owned publish hook. */
+export interface AgentEventPublishOptions {
+    source: EventSource;
+    correlation_id: string | null;
+    payload: Record<string, unknown>;
+}
+/**
+ * Capabilities the owning session (session.ts) exposes to one agent run.
+ * Every member is optional; without a context the agent runs standalone and
+ * manages its own history commits and cancellation checks.
+ */
+export interface AgentContext {
+    readonly sessionId?: string | null;
+    readonly taskId?: string | null;
+    readonly cancelToken?: CancelToken | null;
+    readonly eventBus?: EventBus | null;
+    publish?(kind: EventKind, options: AgentEventPublishOptions): unknown;
+    /** Return false to cancel before the model request is sent. */
+    modelStarted?(): boolean | void;
+    /** Called once the SDK acknowledged the streaming request. */
+    modelRequestOpened?(): boolean | void;
+    toolsStarted?(): void;
+    safePoint?(): PendingInputBatchLike | null | undefined;
+    /** Atomically commit the user message; rollback undoes a failed commit. */
+    commitInput?(append: () => void, rollback: () => void): boolean;
+    commitPending?(batch: PendingInputBatchLike, append: () => void, rollback: () => void): boolean;
+    /** Atomically reject history commits once cancellation has won. */
+    commitIfActive?(callback: () => void): boolean;
+}
+export interface RunOptions {
+    cancelToken?: CancelToken | null;
+    requestId?: string | null;
+    isRequestActive?: ((requestId: string) => boolean) | null;
+}
+export interface CodingAgentOptions {
+    client: ChatClientLike;
+    model: string;
+    tools: AgentToolRegistry;
+    maxTotalTokens?: number;
+    maxElapsedSeconds?: number;
+    repeatedToolCallLimit?: number;
+    onToolEvent?: ToolEventCallback | null;
+    onAgentEvent?: AgentEventCallback | null;
+    provider?: string | null;
+    toolExecution?: ToolExecutionMode;
+    /**
+     * Project root used only for project-instruction loading (both this and
+     * `startupCwd` must be set; omit both to disable instruction injection).
+     */
+    projectRoot?: string | null;
+    /** Startup cwd for project-instruction discovery. */
+    startupCwd?: string | null;
+}
+/** Execution context handed to every tool call in a batch. */
+export interface AgentToolContext extends ToolExecutionContextLike {
+    readonly sessionId: string | null;
+    readonly taskId: string | null;
+    readonly toolCallId: string | null;
+    readonly cancelToken: CancelToken | null;
+}
+export declare class CodingAgent {
+    client: ChatClientLike;
+    model: string;
+    provider: string | null;
+    /** Provider-neutral model access; resolved from `provider`. */
+    private adapter;
+    readonly tools: AgentToolRegistry;
+    readonly maxTotalTokens: number;
+    readonly maxElapsedSeconds: number;
+    readonly repeatedToolCallLimit: number;
+    readonly toolExecution: ToolExecutionMode;
+    /** Conversation history in Chat Completions wire shape. */
+    messages: Array<Record<string, unknown>>;
+    private readonly onToolEvent;
+    private readonly onAgentEvent;
+    private readonly instructionRoot;
+    private readonly startupCwd;
+    private baselineInstructionsLoaded;
+    private instructionState;
+    private turn;
+    private activeContext;
+    private activeRequestId;
+    constructor(options: CodingAgentOptions);
+    /** Bookkeeping for loaded project instructions (never model-visible). */
+    get projectInstructionState(): ProjectInstructionState | null;
+    /** Swap the model client mid-conversation, keeping portable history. */
+    switchModel(options: {
+        client: unknown;
+        model: string;
+        provider: string;
+    }): void;
+    /** Run one user turn, committing only fully validated model attempts. */
+    run(userInput: string, context?: AgentContext | null, options?: RunOptions): Promise<string>;
+    private budgetGuardReason;
+    private guardPayload;
+    private recordRepeatedToolCalls;
+    private executeToolBatch;
+    private executeTool;
+    private finishToolEvent;
+    /**
+     * Append the rendered baseline project instructions once per session,
+     * right after the first direct user message and before the first model
+     * request. Append-only: the system prompt and committed history are never
+     * rebuilt, and nothing is appended when no instruction files exist.
+     */
+    private injectBaselineInstructions;
+    /**
+     * DSH-style dynamic descendant discovery: for every parent directory from
+     * the instruction root to each successfully touched path's directory,
+     * render instructions from scopes not already represented by the
+     * instruction state as one additional reminder message. Append-only and
+     * duplicate-suppressed by ProjectInstructionState; a no-op when
+     * instruction loading is not configured.
+     */
+    private discoverForTouchedPaths;
+    private commitContextMessage;
+    private emit;
+    private emitLegacy;
+    private publishRuntimeEvent;
+}