ikie-cli 0.1.32 → 0.1.34

package/README.md

@@ -1,43 +1,206 @@
-# ikie
+# Ikie
 
-**Agentic coding CLI** — your terminal AI pair programmer.
+**Agentic coding CLI — your AI pair programmer in the terminal.**
+
+Ikie reads, writes, and refactors code, runs commands, searches the web, and
+drives multi-step engineering tasks autonomously — all from your shell, with a
+polished interactive REPL and a one-shot mode for quick jobs.
 
 ```bash
 npm install -g ikie-cli
 ikie login
-ikie "write a rust web server"
+ikie "write a rust web server with graceful shutdown"
 ```
 
-## Features
+---
+
+## Highlights
+
+- **Autonomous agent loop** — Ikie plans, edits files, runs builds/tests, reads
+  the errors, and self-corrects until the task is done.
+- **Plan mode & agent mode** — research read-only and propose a plan, or execute
+  with full tool access. Toggle live with **Shift+Tab**.
+- **28 built-in tools** — files, shell, search, git, web, memory, sub-agents.
+- **Skills** — installable instruction packs that give Ikie expert knowledge for
+  a specific kind of task (UI/UX, research, framework conventions, …).
+- **MCP support** — extend Ikie with Model Context Protocol servers (GitHub,
+  databases, browser automation, and any custom MCP).
+- **Polished terminal UX** — markdown rendering, slash-command menu, 7 color
+  themes, image paste (Ctrl+V), session save/load, and live token/usage tracking.
+- **Safe by default** — mutating actions ask for permission once (press `a` to
+  always-allow for the session); reads of secret files (`.env`, keys) are guarded.
 
-- 12 built-in tools: read/write/edit files, bash, search, grep, memory, agent spawn, web fetch & search
-- Interactive REPL with slash commands, markdown rendering, and session management
-- One-shot mode: `ikie "your prompt"`
-- Image paste support (Ctrl+V)
-- Theming (7 color schemes)
+---
 
 ## Quick start
 
 ```bash
-# Install
-npm install -g ikie
+# 1. Install globally
+npm install -g ikie-cli
 
-# Sign in to your ikie account
+# 2. Sign in to your Ikie account
 ikie login
 
-# Start coding
-ikie "refactor this file and add tests"
+# 3a. One-shot — run a single task and exit
+ikie "add input validation to src/api/users.ts and write tests"
+
+# 3b. Interactive — start a REPL session
+ikie
+```
+
+**Requirements:** Node.js 20+ and an Ikie account (`ikie login`).
+
+---
+
+## Modes
+
+Ikie runs in one of two modes, shown in the prompt header:
+
+| Mode | What it can do |
+| --- | --- |
+| **agent** *(default)* | Full access — edit files, run commands, everything. |
+| **plan** | Read-only research. Ikie explores and proposes a plan but makes no changes until you approve. |
+
+Switch any time with **Shift+Tab** (toggles in place), or with `/plan`, `/agent`,
+and `/mode`. When a plan is approved, Ikie automatically switches to agent mode
+and carries it out.
+
+---
+
+## Tools
+
+Ikie has 28 built-in tools, grouped by purpose:
+
+- **Files** — `read_file`, `write_file`, `edit_file` (surgical exact-string edits), `list_dir`
+- **Search** — `search_files` (glob), `grep` (regex over contents)
+- **Shell** — `bash` (builds, tests, package managers; `&` backgrounds long-running processes)
+- **Git** — `git_status`, `git_diff`, `git_log`, `git_commit`, `git_branch`
+- **Web** — `fetch_url` (read any page as text), `web_search` (no extra API key — your login is enough)
+- **Memory** — `memory_write` (persist notes across sessions, project- or global-scoped)
+- **Delegation** — `spawn_agent` (hand isolated/parallel work to a focused sub-agent), `ask_user`
+- **Skills** — `use_skill`, `install_skill`, `remove_skill`
+- **MCP** — `mcp_list`, `mcp_add` (configured servers expose tools as `mcp__server__tool`)
+- **Mode** — `switch_mode`
+
+---
+
+## Skills
+
+Skills are curated instruction packs (and optional bundled scripts) that load on
+demand when a task matches them. Install from a git URL or local path:
+
+```bash
+ikie skills install https://github.com/user/some-skill.git
+ikie skills list
+ikie skills remove some-skill
+```
+
+Inside a session, Ikie loads a matching skill automatically before doing the work.
+You can also manage them with `/skills`.
+
+---
+
+## MCP (Model Context Protocol)
+
+Extend Ikie with external MCP servers. When a server is configured, each of its
+tools appears as a first-class tool named `mcp__<server>__<tool>` — call them
+directly, no meta-tool dance.
+
+Paste a Claude/Cline-style config and Ikie will wire it up:
+
+```
+claude mcp add magic --scope user --env API_KEY="…" -- npx -y @21st-dev/magic@latest
 ```
 
-## Web access
+Or create a `.mcp.json` file in the project root (or `.mcp.local.json` for
+machine-local overrides, or `~/.ikie/mcp.json` for global ones):
+
+```json
+{
+  "mcpServers": {
+    "magic": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@21st-dev/magic@latest"],
+      "env": { "API_KEY": "…" },
+      "enabled": true,
+      "autoStart": true
+    }
+  }
+}
+```
+
+In the REPL, use `/mcp` to list servers and their tools, `/mcp add <line>` to
+add one from a `claude mcp add …` line, `/mcp remove <name>`, and `/mcp reconnect
+<name>`.
+
+---
+
+## In-session commands
+
+Type `/` to open the command menu. Highlights:
+
+| Command | Description |
+| --- | --- |
+| `/help` | Show all commands |
+| `/plan` · `/agent` · `/mode` | Switch or show mode *(Shift+Tab toggles)* |
+| `/clear` | Clear conversation history |
+| `/compact` | Summarize the conversation to free up context |
+| `/session list\|load\|new\|delete` | Manage saved sessions |
+| `/memory [save]` | View or save persistent notes |
+| `/context` | Show the detected project context |
+| `/model <name>` · `/models` | Switch or list models |
+| `/settings [show\|model\|reset]` | View/change persisted settings |
+| `/skills` | List, show, install, or remove skills |
+| `/mcp` · `/mcp add` · `/mcp remove` · `/mcp reconnect` | MCP server status and management |
+| `/theme [name]` | Change the color theme |
+| `/usage` · `/tokens` | Account usage/credit and token estimate |
+| `/rpm <n>` | Set the model request-per-minute limit |
+| `/onboarding` | Re-run the first-time tutorial |
+| `!<cmd>` | Run a shell command directly (output lands in the session) |
+
+---
+
+## CLI usage
+
+```text
+ikie "<message>"            One-shot command
+ikie                        Start an interactive session
+ikie login                  Sign in to your Ikie account
+ikie logout                 Sign out
+ikie skills <…>             Manage skills (list / install / remove)
+
+Flags:
+  -m, --model <id>          Use a specific model
+  -y, --yes                 Auto-approve all tool executions
+      --rpm <n>             Max model requests per minute (default: 10)
+      --verbose             Debug output
+      --onboarding          Re-run first-time onboarding
+  -h, --help                Show help
+  -v, --version             Show version
+```
+
+---
+
+## Themes
+
+Seven built-in color schemes: **nebula**, **cyberpunk**, **dracula**, **forest**,
+**slate**, **amber**, and **aurora**. Switch with `/theme <name>`.
+
+---
+
+## Permissions & safety
 
-ikie can read pages and search the web:
+- `bash`, `write_file`, and `edit_file` ask before running. Press `y` to allow
+  once, `a` to always-allow that tool for the session, `n`/`!` to deny.
+- Reading project files is silent; reading credential files (`.env`, `.ssh`, keys,
+  `.npmrc`, …) prompts first.
+- Ikie warns before any command that could terminate its own session by killing
+  processes on its host port.
+- Run with `-y` / `--yes` to auto-approve everything (use with care).
 
-- **`fetch_url`** — read any page or URL (HTML is stripped to plain text).
-- **`web_search`** — search the web and get back titles, URLs, and snippets. Powered by the ikie
-  server — no separate search API key needed; your ikie login is enough.
+---
 
-## Requirements
+## License
 
-- Node.js 20+
-- An ikie account — sign in with `ikie login`
+MIT — see [LICENSE](./LICENSE).

package/dist/agent.d.ts

@@ -6,7 +6,13 @@ export interface AgentOptions {
     autoApprove?: boolean;
     signal?: AbortSignal;
     startedAt?: number;
+    /** Max model→tool round-trips in a single turn before forcing a graceful stop. */
+    maxSteps?: number;
 }
+/** Default per-turn step budget — guards against runaway tool loops. */
+export declare const DEFAULT_MAX_STEPS = 60;
+/** Result synthesized for a tool call that never produced one (cancel/crash). */
+export declare const INTERRUPTED_TOOL_RESULT = "Interrupted: this tool did not run to completion (the turn was cancelled).";
 /** Plan = read-only research + propose; Agent = full execution. */
 export type AgentMode = 'agent' | 'plan';
 export interface AgentTurnStats {
@@ -20,6 +26,32 @@ export declare function estimateTokens(chars: number): number;
  * The SDK wraps provider responses; we prefer the nested error.message if it exists.
  */
 export declare function extractUpstreamError(err: unknown): string;
+/**
+ * Guarantee the OpenAI invariant: every `assistant` message that carries
+ * `tool_calls` is followed by a `tool` message for each call id. A turn that is
+ * cancelled (ESC/Ctrl-C), throws mid-stream, or is restored from a session saved
+ * mid-flight can leave "dangling" tool calls with no result — and the provider
+ * then rejects the *next* request ("an assistant message with 'tool_calls' must
+ * be followed by tool messages"). This splices a synthetic result for any
+ * unanswered call so history is always replayable. Pure and idempotent.
+ */
+export declare function repairDanglingToolCalls(messages: ChatCompletionMessageParam[]): ChatCompletionMessageParam[];
+/**
+ * Whether the agent loop should make another model call. We continue purely on
+ * "there were tool calls to answer" — NOT on `finishReason`, because some
+ * providers send `finish_reason: 'stop'` (or null) alongside tool calls, which
+ * would otherwise silently drop the calls. `maxSteps` caps runaway loops.
+ */
+export declare function shouldContinue(toolCallCount: number, _finishReason: string, step: number, maxSteps: number): boolean;
+/**
+ * Drop malformed tool calls (no function name) accumulated from a stream. An
+ * unnamed call can't be dispatched or answered, so keeping it would create an
+ * un-satisfiable `tool_calls` entry. Applied to both the dispatch list and the
+ * assistant message so they stay in lockstep.
+ */
+export declare function normalizeToolCalls<T extends {
+    name: string;
+}>(calls: T[]): T[];
 /**
  * Safely restore previously-saved stdin listeners after a raw-mode interaction
  * (permission prompt, ask_user, theme picker, agent turn).
@@ -62,16 +94,28 @@ export declare class Agent {
     private groupToolCalls;
     private formatGroupSummary;
     private runLoop;
+    /**
+     * Final wrap-up when the per-turn step budget is exhausted. One model call with
+     * tools disabled, so it produces a plain summary and can never leave a dangling
+     * tool call. Best-effort: failures here don't throw out of the turn.
+     */
+    private summarizeAndStop;
     private callModel;
     private buildParams;
     private throttleModelRequest;
     private callModelStreaming;
     private callModelNonStreaming;
     private handleToolCall;
+    private handleUseSkill;
     private handleSwitchMode;
     private requestModeSwitch;
     private askUser;
     private runSubagent;
+    /**
+     * Best-effort: one tool-less model call asking for a concise, self-contained
+     * summary of the work so far. Used to guarantee a non-empty subagent result.
+     */
+    requestFinalSummary(signal?: AbortSignal): Promise<string>;
     getLastAssistantText(): string;
     private checkPermission;
 }