goatchain 0.0.7 → 0.0.9

package/README.md

@@ -62,77 +62,51 @@ for await (const event of session.receive()) {
 
 ## 🧰 CLI
 
-After installing `goatchain-cli` globally (or using `pnpm -s cli` in this repo), run:
+GoatChain CLI is a terminal UI (TUI) built on `@simon_he/vue-tui`.
+
+### Installation
+
+**Global installation (recommended):**
+
+```bash
+npm install -g goatchain-cli@latest
+```
+
+**Or use npx without installation:**
+
+```bash
+npx goatchain-cli@latest
+```
+
+### Usage
+
+After installation, simply run:
 
 ```bash
 goatchain
 ```
 
-Common options:
-
-- `-k, --api-key <key>` (or set `OPENAI_API_KEY`)
-- `-m, --model <id>`
-- `--base-url <url>`
-- `--max-tokens <n>`
-- `--temperature <n>`
-
-Commands:
-
-- `/help` help
-- `/model <id>` switch model id (OpenAI)
-- `/plan [on|off|toggle]` toggle plan mode (plan → confirm → execute)
-- `/approvals` select approval mode (interactive)
-- `/set <k> <v>` set request params (e.g. `temperature`, `maxTokens`)
-- `/unset <k>` clear a request param
-- `/params` show current request params
-- `/base-url <url>` set base URL
-- `/api-key <key>` set API key (not printed)
-- `/web-search-key <key>` set Serper API key for WebSearch tool (not printed)
-- `/tools` list enabled tools (Read/Write/Edit/Glob/Grep/WebSearch*)
-- `/sessions` list and pick a saved session
-- `/use <sessionId>` restore a saved session (prints recent history)
-- `/save` persist current config/session
-- `/status` show current model/session info
-- `/new` start a new conversation (clears history)
-
-Requires `OPENAI_API_KEY` in the environment.
-
-Web search (optional):
-
-- Set `SERPER_API_KEY` (or `GOATCHAIN_SERPER_API_KEY`) to enable the builtin `WebSearch` tool for up-to-date info like weather.
-- In interactive mode, you can also run `/web-search-key <key>` to persist the key into the workspace config.
-- You can also set it in `./.goatchain/config.json` (workspace-scoped, gitignored):
-  - `{"tools":{"webSearch":{"apiKey":"...","apiEndpoint":"...","numResults":10}}}`
-
-Plan mode (interactive planning):
-
-- Enable with `/plan on` to enter a plan-first workflow:
-  1. Agent explores the codebase and researches your request
-  2. Agent may ask clarifying questions using the `AskUserQuestion` tool to understand your preferences (e.g., library choices, architectural decisions)
-  3. Agent creates a structured plan using `TodoPlan` (3-8 steps)
-  4. You review and approve the plan
-  5. Agent executes the approved plan
-- During planning, file modifications are blocked (read-only phase)
-- Set `GOATCHAIN_PLAN_MODE=1` or configure in `.goatchain/config.json` to enable by default
-
-Local persistence (workspace-scoped):
-
-- Config and sessions are saved under `./.goatchain/` (auto-created).
-- `.goatchain/` is gitignored to avoid accidentally committing secrets.
-
-DeepSeek thinking mode compatibility:
-
-- Some OpenAI-compatible gateways (e.g. DeepSeek thinking mode) require `reasoning_content` to be present on assistant messages that contain `tool_calls` (and may reject empty strings). GoatChain will attach the accumulated thinking content when available.
-- If you use DeepSeek via a proxy where GoatChain can't detect it from `baseUrl`/`modelId`, you can enable this explicitly:
-  - Interactive: Run `/settings` and toggle "Interleaved Thinking"
-  - Config file: Set `openai.compat.interleavedThinking=true` in `./.goatchain/config.json`
+Inside the TUI:
+
+- `Ctrl+P` opens the command palette (Sessions / New Session / Settings / Tool Approvals; Chat also has Theme)
+- Slash commands in the input: `/settings`, `/approvals`, `/sessions`, `/new` (Chat also supports `/redo`)
+
+### Development
+
+Run it from this repo:
+
+```bash
+bun run cli
+```
+
+See `docs/cli.md` for the full feature list and flowcharts.
 
 ## 🔌 ACP Server
 
 GoatChain can be exposed as an ACP (Agent Client Protocol) server for integration with editors like Zed.
 
 ```bash
-pnpm acp-server
+bun run acp-server
 ```
 
 **Configuration for Zed** (`settings.json`):
@@ -190,7 +164,6 @@ classDiagram
 
     class StateStore {
         <<interface>>
-        +savePoint: string
         +deleteOnComplete: boolean
         +saveCheckpoint(checkpoint): Promise~void~
         +loadCheckpoint(sessionId): Promise~AgentLoopCheckpoint~
@@ -404,7 +377,6 @@ import { Agent, FileStateStore } from 'goatchain'
 // Create state store with configuration
 const stateStore = new FileStateStore({
   dir: './checkpoints',
-  savePoint: 'before', // Save before each iteration
   deleteOnComplete: true, // Clean up after successful completion
 })
 

package/README.zh.md

@@ -0,0 +1,39 @@
+# GoatChain（中文）
+
+GoatChain 是一个轻量、可扩展的 TypeScript Agent SDK，包含一个基于终端 UI 的 CLI（TUI）。
+
+- CLI（TUI）能力说明与流程图：`docs/cli.md`
+- 英文 README：`README.md`
+
+## CLI 安装和使用
+
+### 安装
+
+**全局安装（推荐）：**
+
+```bash
+npm install -g goatchain-cli@latest
+```
+
+**或使用 npx（无需安装）：**
+
+```bash
+npx goatchain-cli@latest
+```
+
+### 使用
+
+安装完成后，直接运行：
+
+```bash
+goatchain
+```
+
+### TUI 快捷键
+
+- `Ctrl+P` 打开命令面板（会话 / 新建会话 / 设置 / 工具批准；聊天界面还有主题）
+- 输入框中的斜杠命令：`/settings`、`/approvals`、`/sessions`、`/new`（聊天界面还支持 `/redo`）
+
+详细功能列表和流程图请查看 [docs/cli.md](./docs/cli.md)。
+
+

package/dist/acp-adapter/types.d.ts

@@ -39,6 +39,7 @@ export interface ACPMessage {
  */
 export interface ACPMetadata {
     session_id?: string;
+    signal?: AbortSignal;
     [key: string]: unknown;
 }
 /**

package/dist/agent/agent.d.ts

@@ -26,7 +26,25 @@ export declare class Agent {
     private _middlewares;
     private _middlewareCounter;
     private _middlewareTools;
+    private _enableLogging;
+    private _initializationPromise;
+    private _initialized;
     constructor(options: AgentOptions);
+    /**
+     * Initialize middleware asynchronously (internal helper for constructor)
+     * @private
+     */
+    private _initializeMiddleware;
+    /**
+     * Ensure agent is initialized (all middleware registered)
+     * @private
+     */
+    private _ensureInitialized;
+    /**
+     * Internal logging method
+     * @private
+     */
+    private _log;
     /**
      * Get the model client
      */
@@ -42,10 +60,6 @@ export declare class Agent {
      * - Otherwise, returns the model client's default `modelRef` (if supported).
      */
     get modelRef(): ModelRef | undefined;
-    /**
-     * Get the available model references (e.g. routing fallback order), if supported by the model client.
-     */
-    get modelRefs(): ModelRef[];
     /**
      * Get the tool registry
      */
@@ -85,7 +99,7 @@ export declare class Agent {
      * @example
      * ```ts
      * // Named middleware (recommended)
-     * agent.use(async (state, next) => {
+     * await agent.use(async (state, next) => {
      *   console.log('Before iteration', state.iteration);
      *   const result = await next(state);
      *   console.log('After iteration', state.iteration);
@@ -93,20 +107,20 @@ export declare class Agent {
      * }, 'logging');
      *
      * // Built-in middleware with default name
-     * agent.use(createContextCompressionMiddleware({ ... })); // auto-named 'context-compression'
+     * await agent.use(createContextCompressionMiddleware({ ... })); // auto-named 'context-compression'
      *
      * // Override default name
-     * agent.use(createPlanModeMiddleware(), 'my-plan-mode');
+     * await agent.use(createPlanModeMiddleware(), 'my-plan-mode');
      *
      * // Middleware with tools (auto-registers tools with namespace)
      * const middleware: Middleware = async (state, next) => next(state);
      * middleware.__middlewareName = 'plan-mode';
-     * middleware.__createTools = () => [new EnterPlanModeTool()];
-     * agent.use(middleware);
+     * middleware.__createTools = async () => [new EnterPlanModeTool()];
+     * await agent.use(middleware);
      * // Tool registered as: 'plan-mode_EnterPlanMode'
      *
      * // Anonymous middleware (auto-named)
-     * const unsubscribe = agent.use(async (state, next) => {
+     * const unsubscribe = await agent.use(async (state, next) => {
      *   const compressed = { ...state, messages: compress(state.messages) };
      *   return next(compressed);
      * });
@@ -115,7 +129,7 @@ export declare class Agent {
      * unsubscribe();
      * ```
      */
-    use(fn: Middleware<AgentLoopState>, name?: string): () => void;
+    use(fn: Middleware<AgentLoopState>, name?: string): Promise<() => void>;
     /**
      * Remove a specific middleware from the agent by name or function reference.
      *

package/dist/agent/index.d.ts

@@ -1,4 +1,4 @@
-export { fromLoopCheckpoint, toLoopCheckpoint } from '../middleware/checkpointMiddleware';
+export { extractPersistentMetadata, extractPersistentState, fromLoopCheckpoint, toLoopCheckpoint, } from '../middleware/checkpointMiddleware';
 export type { ToCheckpointOptions } from '../middleware/checkpointMiddleware';
 export { compressSessionManually, createContextCompressionMiddleware } from '../middleware/contextCompressionMiddleware';
 export type { ManualCompressionOptions, ManualCompressionResult } from '../middleware/contextCompressionMiddleware';

package/dist/agent/middleware.d.ts

@@ -54,6 +54,8 @@ export interface Middleware<State = AgentLoopState> {
      * Tools will be namespaced as: `<middlewareName>_<toolName>`
      * When the middleware is removed, all associated tools are automatically unregistered.
      *
+     * Can be synchronous or asynchronous to support dynamic tool creation.
+     *
      * @example
      * ```ts
      * const middleware: Middleware = async (state, next) => {
@@ -67,7 +69,7 @@ export interface Middleware<State = AgentLoopState> {
      * ];
      * ```
      */
-    __createTools?: () => BaseTool[];
+    __createTools?: () => BaseTool[] | Promise<BaseTool[]>;
     /**
      * Optional function that returns a list of tool names to block for the given state.
      * This allows middleware to dynamically control which tools should be unavailable

package/dist/agent/types.d.ts

@@ -143,10 +143,21 @@ export interface AgentOptions {
      * A SessionManager is automatically created to manage sessions.
      * Sessions will be stored in the StateStore.
      *
-     * The state store contains its own configuration for when to save
-     * (savePoint) and whether to delete on completion (deleteOnComplete).
+     * The state store can be configured with deleteOnComplete to control
+     * whether checkpoints are deleted after successful completion.
      */
     stateStore?: StateStore;
+    /**
+     * Enable console logging for debugging (default: false).
+     *
+     * When enabled, the agent will output logs for key operations:
+     * - Agent and session creation
+     * - Message sending and receiving
+     * - Model calls and responses
+     * - Tool executions
+     * - Middleware execution
+     */
+    enableLogging?: boolean;
 }
 /**
  * Input for agent execution
@@ -239,10 +250,6 @@ export interface CreateSessionOptions extends SessionHandleOptions {
     maxIterations?: number;
 }
 export interface SendOptions {
-    /**
-     * AbortSignal for cancellation support
-     */
-    signal?: AbortSignal;
     /**
      * Optional tool execution context input
      */

package/dist/index.d.ts

@@ -1,12 +1,19 @@
-export { Agent, AgentAbortError, AgentMaxIterationsError, compose, compressSessionManually, createContextCompressionMiddleware, createInitialLoopState, ensureNotAborted, fromLoopCheckpoint, HookManager, toLoopCheckpoint, } from './agent';
+export { Agent, AgentAbortError, AgentMaxIterationsError, compose, compressSessionManually, createContextCompressionMiddleware, createInitialLoopState, ensureNotAborted, extractPersistentMetadata, extractPersistentState, fromLoopCheckpoint, HookManager, toLoopCheckpoint, } from './agent';
 export type { AgentInput, AgentLoopState, AgentOptions, CompressionStats, ContextCompressionOptions, CreateSessionOptions, HookContext, ManualCompressionOptions, ManualCompressionResult, Middleware, NextFunction, PostToolUseFailureHook, PostToolUseHook, PreToolUseHook, PreToolUseResult, SendOptions, SessionHandleOptions, ToCheckpointOptions, ToolCallWithResult, ToolHooks, } from './agent';
+export { createAgentRulesMiddleware } from './middleware/agentRulesMiddleware';
+export type { AgentRulesMiddlewareOptions } from './middleware/agentRulesMiddleware';
 export { createCommitModeMiddleware } from './middleware/commitModeMiddleware';
 export type { CommitModeMiddlewareOptions } from './middleware/commitModeMiddleware';
+export { createEnvInfoMiddleware } from './middleware/envInfoMiddleware';
+export type { EnvInfoMiddlewareOptions } from './middleware/envInfoMiddleware';
 export { createPlanModeMiddleware } from './middleware/planModeMiddleware';
 export type { PlanModeMiddlewareOptions } from './middleware/planModeMiddleware';
 export { createParallelSubagentMiddleware } from './middleware/parallelSubagentMiddleware';
 export type { ParallelSubagentMiddlewareOptions } from './middleware/parallelSubagentMiddleware';
-export { injectSystemReminderToLastUserMessage } from './middleware/utils';
+export { createSkillsMiddleware, parseSkillFile, scanMultipleSkillsDirectories, scanSkillsDirectory } from './middleware/skillsMiddleware';
+export type { ParsedSkill, SkillsMiddlewareOptions } from './middleware/skillsMiddleware';
+export { createMessageSnapshot, injectSystemReminderToLastUserMessage, restoreMessageAt, restoreMessages, snapshotMessageByRole, } from './middleware/utils';
+export type { MessageRestoration } from './middleware/utils';
 export * from './subagent';
 export * from './acp-adapter';
 export { runAcpServer } from './acp-server';