@scira/cli 0.1.1 → 0.1.3

package/README.md

@@ -2,6 +2,8 @@
 
 Terminal-native AI research and coding agent. Ask a question, get a grounded report with cited sources and verified claims — all stored locally and inspectable.
 
+**Documentation:** [docs site](./docs) (local: `cd docs && bun run dev`) · MDX sources in `docs/content/docs/`
+
 ## Install
 
 ```bash
@@ -14,12 +16,13 @@ Requires **Node.js ≥ 20**. Run the interactive setup:
 scira init
 ```
 
-This walks you through API keys and configuration. Keys go in `~/.scira/.env` so they work from any directory.
+This walks you through API keys and configuration with signup links and step-by-step instructions.
 
 Check your setup:
 
 ```bash
-scira doctor
+scira doctor    # verify keys are detected
+scira keys      # show where to get any missing keys
 ```
 
 ## Quickstart
@@ -38,20 +41,55 @@ scira new "history of the Silk Road" --tui
 scira new "history of the Silk Road" --shell
 ```
 
-## Setup
+## API keys
+
+Scira needs credentials for an **LLM provider** (model calls) and a **search provider** (web search). Run `scira init` for a guided setup, or copy `.env.example` and fill in keys manually.
 
-Put your API keys in `~/.scira/.env` (loaded automatically from any working directory):
+**Where keys are loaded from** (highest priority first):
+
+1. Shell environment (already exported in your terminal)
+2. `<project>/.scira/.env` when you run Scira from that project
+3. `~/.scira/.env` for global defaults
 
 ```bash
+# Option A: interactive wizard (saves to ~/.scira/.env)
+scira init
+
+# Option B: manual — global keys
 mkdir -p ~/.scira && cp .env.example ~/.scira/.env
-# then edit ~/.scira/.env
+
+# Option B: manual — project keys only
+mkdir -p .scira && cp .env.example .scira/.env
+
+scira doctor   # confirm keys are detected
+scira keys     # signup links + steps for anything still missing
 ```
 
+### LLM providers (set one in config via `scira init` or `/llm`)
+
+| Key | Provider | Where to get it |
+|---|---|---|
+| `AI_GATEWAY_API_KEY` | Vercel AI Gateway (default) | [vercel.com/docs/ai-gateway](https://vercel.com/docs/ai-gateway) → dashboard → AI Gateway → API Keys |
+| `XAI_API_KEY` | xAI (Grok) | [console.x.ai](https://console.x.ai/) → API Keys |
+| `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_API_TOKEN` | Cloudflare Workers AI | [dash.cloudflare.com](https://dash.cloudflare.com/) (account ID) + [API Tokens](https://dash.cloudflare.com/profile/api-tokens) with Workers AI permission |
+| `HF_API_KEY` | Hugging Face Inference | [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) |
+
+### Search providers (set one via `scira init` or `/provider`)
+
+| Key | Provider | Where to get it |
+|---|---|---|
+| `EXA_API_KEY` | Exa (default) | [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys) |
+| `FIRECRAWL_API_KEY` | Firecrawl | [firecrawl.dev/app/api-keys](https://www.firecrawl.dev/app/api-keys) |
+| `PARALLEL_API_KEY` | Parallel | [platform.parallel.ai](https://platform.parallel.ai/) |
+
+`FIRECRAWL_API_KEY` is also used as an automatic fallback when Exa or Parallel search fails, so it is worth setting even if Firecrawl is not your primary search provider.
+
 ## Commands
 
 | Command | Description |
 |---|---|
 | `scira init` | Interactive setup for API keys and configuration |
+| `scira keys` | Show where to get and save missing API keys |
 | `scira [question]` | Open TUI home, or run headlessly if a question is given |
 | `scira new <question>` | Start a run; add `--tui` or `--shell` to open interactive UI |
 | `scira resume <run-id>` | Resume a run; add `--tui` or `--shell` to specify UI |
@@ -101,13 +139,19 @@ Config merges `~/.scira/config.json` (global) with `.scira/config.json` (project
 | `search.provider` | `exa` | `exa`, `firecrawl`, or `parallel` |
 | `search.maxResults` | `8` | Max results per search query |
 
-## Environment Variables
+## Environment variables
+
+See [API keys](#api-keys) for signup links. Required keys depend on your `llmProvider` and `search.provider` in config.
 
-| Variable | Required | Purpose |
+| Variable | Required when | Purpose |
 |---|---|---|
-| `AI_GATEWAY_API_KEY` | Yes | Vercel AI Gateway — all model calls |
-| `EXA_API_KEY` | With Exa | Web search via Exa |
-| `FIRECRAWL_API_KEY` | With Firecrawl | Web scraping via Firecrawl |
+| `AI_GATEWAY_API_KEY` | `llmProvider: gateway` | Vercel AI Gateway model calls |
+| `XAI_API_KEY` | `llmProvider: xai` or xSearch | Grok model calls; also enables the `xSearch` tool for real-time X/Twitter posts |
+| `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_API_TOKEN` | `llmProvider: workers-ai` | Workers AI model calls |
+| `HF_API_KEY` | `llmProvider: huggingface` | Hugging Face Inference |
+| `EXA_API_KEY` | `search.provider: exa` | Web search via Exa |
+| `FIRECRAWL_API_KEY` | `search.provider: firecrawl` | Web search + scrape via Firecrawl |
+| `PARALLEL_API_KEY` | `search.provider: parallel` | Web search via Parallel |
 
 ## Run Directory
 

package/dist/agent/background-tasks.js

@@ -0,0 +1,173 @@
+import { spawn } from "node:child_process";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+const MAX_OUTPUT_LINES = 500;
+const MAX_TAIL_CHARS = 4000;
+function nextTaskId(existing) {
+    const nums = existing
+        .map((t) => /^task_(\d+)$/u.exec(t.id)?.[1])
+        .filter((n) => Boolean(n))
+        .map((n) => Number.parseInt(n, 10));
+    const next = nums.length > 0 ? Math.max(...nums) + 1 : 1;
+    return `task_${String(next).padStart(3, "0")}`;
+}
+function tailText(lines, maxChars = MAX_TAIL_CHARS) {
+    const joined = lines.join("\n");
+    if (joined.length <= maxChars)
+        return joined;
+    return `…[truncated]\n${joined.slice(-maxChars)}`;
+}
+export class BackgroundTaskManager {
+    persistPath;
+    defaultCwd;
+    runtime = new Map();
+    records = [];
+    loaded = false;
+    constructor(persistPath, defaultCwd) {
+        this.persistPath = persistPath;
+        this.defaultCwd = defaultCwd;
+    }
+    async ensureLoaded() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        try {
+            const raw = await readFile(this.persistPath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed)) {
+                this.records = parsed.filter((t) => typeof t === "object" && t !== null && typeof t.id === "string");
+            }
+        }
+        catch {
+            this.records = [];
+        }
+    }
+    async persist() {
+        await mkdir(dirname(this.persistPath), { recursive: true });
+        await writeFile(this.persistPath, JSON.stringify(this.records, null, 2) + "\n");
+    }
+    syncRecord(task) {
+        const idx = this.records.findIndex((r) => r.id === task.record.id);
+        task.record.outputTail = tailText(task.output);
+        if (idx === -1)
+            this.records.push({ ...task.record });
+        else
+            this.records[idx] = { ...task.record };
+    }
+    async spawn(command, cwd) {
+        await this.ensureLoaded();
+        const id = nextTaskId(this.records);
+        const workDir = cwd ?? this.defaultCwd;
+        const proc = spawn(command, {
+            cwd: workDir,
+            shell: "/bin/bash",
+            env: process.env,
+            detached: false,
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        const record = {
+            id,
+            command,
+            cwd: workDir,
+            pid: proc.pid ?? 0,
+            startedAt: new Date().toISOString(),
+            status: "running",
+            exitCode: null,
+            outputTail: ""
+        };
+        const output = [];
+        const append = (chunk) => {
+            const text = chunk.toString();
+            for (const line of text.split("\n")) {
+                if (line.length > 0)
+                    output.push(line);
+            }
+            while (output.length > MAX_OUTPUT_LINES)
+                output.shift();
+            const rt = this.runtime.get(id);
+            if (rt) {
+                rt.output = output;
+                rt.record.outputTail = tailText(output);
+            }
+        };
+        proc.stdout?.on("data", append);
+        proc.stderr?.on("data", append);
+        const runtime = { record, proc, output };
+        this.runtime.set(id, runtime);
+        this.records.push({ ...record });
+        await this.persist();
+        proc.on("close", (code) => {
+            record.status = "exited";
+            record.exitCode = code;
+            record.outputTail = tailText(output);
+            this.syncRecord(runtime);
+            void this.persist();
+            this.runtime.delete(id);
+        });
+        proc.on("error", (err) => {
+            output.push(`[spawn error] ${err.message}`);
+            record.status = "exited";
+            record.exitCode = 1;
+            record.outputTail = tailText(output);
+            this.syncRecord(runtime);
+            void this.persist();
+            this.runtime.delete(id);
+        });
+        return { ...record };
+    }
+    async list() {
+        await this.ensureLoaded();
+        for (const rt of this.runtime.values()) {
+            rt.record.outputTail = tailText(rt.output);
+            this.syncRecord(rt);
+        }
+        return this.records.map((r) => {
+            const live = this.runtime.get(r.id);
+            return live ? { ...live.record } : { ...r };
+        });
+    }
+    async getOutput(taskId, tailLines = 50) {
+        await this.ensureLoaded();
+        const live = this.runtime.get(taskId);
+        if (live) {
+            const lines = live.output.slice(-tailLines);
+            return lines.length > 0 ? lines.join("\n") : "(no output yet)";
+        }
+        const rec = this.records.find((r) => r.id === taskId);
+        if (!rec)
+            return `Task "${taskId}" not found.`;
+        const lines = rec.outputTail.split("\n").slice(-tailLines);
+        return lines.length > 0 ? lines.join("\n") : "(no output)";
+    }
+    async kill(taskId) {
+        await this.ensureLoaded();
+        const live = this.runtime.get(taskId);
+        if (live) {
+            live.proc.kill("SIGTERM");
+            live.record.status = "killed";
+            live.record.exitCode = live.record.exitCode ?? 143;
+            this.syncRecord(live);
+            await this.persist();
+            return `Killed ${taskId} (pid ${live.record.pid}).`;
+        }
+        const rec = this.records.find((r) => r.id === taskId);
+        if (!rec)
+            return `Task "${taskId}" not found.`;
+        if (rec.status !== "running")
+            return `${taskId} is already ${rec.status}.`;
+        rec.status = "killed";
+        await this.persist();
+        return `Marked ${taskId} as killed (process not tracked in this session).`;
+    }
+    async formatContextForAgent() {
+        const tasks = await this.list();
+        const active = tasks.filter((t) => t.status === "running");
+        if (active.length === 0)
+            return "";
+        const lines = active.map((t) => `  - ${t.id}: [running pid ${t.pid}] ${t.command} (cwd: ${t.cwd})`);
+        return `\nActive background tasks:\n${lines.join("\n")}\nUse bash with action "output" and taskId to read logs, or action "kill" to stop a task.\n`;
+    }
+}
+export function createBackgroundTaskManager(runPath, workspacePath) {
+    return new BackgroundTaskManager(join(runPath, "background-tasks.json"), workspacePath);
+}

package/dist/agent/research-agent.js

@@ -3,10 +3,31 @@ import { stdin, stdout } from "node:process";
 import { ToolLoopAgent, isLoopFinished } from "ai";
 import { Spinner } from "picospinner";
 import { getLanguageModel, requireLlmKeys } from "../providers/llm/registry.js";
-import { createResearchTools, createOneShotTools, createCodingTools } from "./tools.js";
+import { createResearchTools, createOneShotTools, createCodingTools, wrapToolsForPlanMode } from "../tools/agent-tools.js";
 import { SKILL_CATALOG } from "./skills.js";
 import { createMcpBridge } from "../tools/mcp-bridge.js";
-function instructions(goal, config, workspacePath) {
+import { createBackgroundTaskManager } from "../tools/background-tasks.js";
+function resolvePlanMode(options) {
+    return options.getPlanMode ? options.getPlanMode() : (options.planMode ?? false);
+}
+function planModeBlock(active) {
+    if (!active)
+        return "";
+    return `
+
+PLAN MODE (active):
+You are in plan mode. Explore and plan before making changes.
+- Use readFile, grepWorkspace, listWorkspaceDir, webSearch, and readUrl to understand the task
+- Use the todo tool to break work into trackable steps (create, mark in_progress when starting, completed when done)
+- Write or update plan.md with your approach (harness file, bare name)
+- Do NOT use writeFile or editFile except plan.md, and do not use bash action=run/background
+- Do NOT use MCP or browser tools while plan mode is active
+- Read-only bash is OK: ls, cat, git status, git log, git diff, find, grep (workspace-relative paths only)
+- When the plan is ready, summarize it and tell the user to type /plan to exit plan mode and begin execution`;
+}
+function instructions(goal, config, options = {}) {
+    const { workspacePath } = options;
+    const planMode = resolvePlanMode(options);
     const now = new Date();
     const temporalContext = now.toLocaleDateString("en-US", {
         weekday: "long",
@@ -19,26 +40,29 @@ function instructions(goal, config, workspacePath) {
         : "Citation policy (balanced): cite source IDs for all major claims; minor background context may be uncited but must not be overstated.";
     const codingSection = workspacePath ? `
 
-CODING CAPABILITIES:
-You also have workspace-aware coding tools to build, modify, and debug code:
-- readWorkspaceFile: Read any file in the workspace
-- writeWorkspaceFile: Create or overwrite files (requires approval)
-- editWorkspaceFile: Make surgical edits by replacing exact strings (requires approval)
-- listWorkspaceDir: List files and directories
-- grepWorkspace: Search for patterns across the codebase
-- runWorkspaceCommand: Execute shell commands like builds, tests, installs (requires approval)
+PROJECT LAYOUT:
+- Project root (codebase): ${workspacePath}
+- Run harness (.scira/runs/…): plan.md, notes.md, report.md, sources.jsonl, claims.jsonl, todos.json
 
-Workspace: ${workspacePath}
+FILE TOOLS:
+- readFile / writeFile / editFile route automatically:
+  - Harness files by bare name: plan.md, notes.md, report.md, sources.jsonl → stored under .scira/runs/
+  - Everything else (src/…, package.json, …) → project root
+- Never write source code under .scira. Never put harness files at the project root.
 
-When the task involves code:
-- Use grepWorkspace and readWorkspaceFile to understand existing code structure
-- Use editWorkspaceFile for precise changes, writeWorkspaceFile for new files
-- Run tests/builds with runWorkspaceCommand to verify changes
-- Research APIs, libraries, or error messages with webSearch + readUrl when needed
-- Match existing code style and patterns
+CODING TOOLS:
+- listWorkspaceDir, grepWorkspace: explore the codebase
+- bash: shell in the project root. action=run (default), action=background for dev servers, action=list/output/kill for background tasks
+- runBash: shell in the run harness directory for grepping or listing harness artifacts (notes.md, sources.jsonl, etc.)
+- todo: structured task list (create, edit, mark, remove, rewrite, list)
 
-You can seamlessly combine research and coding - e.g., research how to implement a feature, then implement it, or debug an issue by researching the error and fixing the code.` : "";
-    return `You are Scira AI CLI, made by Zaid Mukaddam, an autonomous research ${workspacePath ? "and coding " : ""}agent operating inside a single run directory on the user's machine.
+When the task involves code:
+- Use todo to track multi-step work
+- Use grepWorkspace and readFile to understand the codebase
+- Use editFile for precise changes, writeFile for new source files (paths like src/foo.ts)
+- Run tests/builds with bash; use bash action=background for servers then action=output to check logs
+- Match existing code style and patterns` : "";
+    return `You are Scira AI CLI, made by Zaid Mukaddam, an autonomous research ${workspacePath ? "and coding " : ""}agent.${workspacePath ? " Source code lives at the project root; harness artifacts live under .scira/runs/." : " You operate inside a single run directory on the user's machine."}
 
 Your goal:
 ${goal}
@@ -53,7 +77,7 @@ You have shell, file, search, skill${config.files ? ", and local files" : ""}${w
 0. Bootstrap: these built-in research skills are available — pull the relevant ones with readSkill before you begin. This is mandatory — skills contain concrete tactics for search, source quality, claim verification, and report writing.
 ${SKILL_CATALOG}
 1. Plan: write a short plan.md outlining your approach (use the research-plan skill as a template).
-2. Gather: use webSearch with 3-5 parallel query variations to find real, citable sources, then readUrl to read the most relevant ones. Record findings in notes.md as you go. Never invent sources or URLs.
+2. Gather: use webSearch with 3-5 parallel query variations to find real, citable sources, then readUrl to read the most relevant ones. Use xSearch for current reactions, announcements, and real-time opinions on X/Twitter (requires XAI_API_KEY). Record findings in notes.md as you go. Never invent sources or URLs.
 3. Extract claims: after reading each source, use createClaim to record significant findings. Assign a short ID like claim_001, set confidence, and link source IDs.
 4. Verify: once all claims are recorded, use verifyClaim to update each claim's status (verified / weak / contradicted / needs_review). Be honest — flag weak or vendor-only evidence.
 5. Record sources: write all sources you actually used to sources.jsonl (include the snapshotPath reported by readUrl for each one) — STRICT JSONL rules: one compact JSON object per line, no literal newlines inside string values, no trailing commas. Use writeFile to write the entire file at once.
@@ -62,10 +86,10 @@ ${SKILL_CATALOG}
 
 Rules:
 - Prefer primary sources. Cross-check important claims across multiple sources.
-- Keep files inside the run directory (paths are relative to it).
+${workspacePath ? "- Harness files (plan.md, notes.md, report.md, sources.jsonl) go in the run directory. All source code changes go under the project root." : "- Keep files inside the run directory (paths are relative to it)."}
 - Be terse in your narration between tool calls — say what you're doing and why in one line.
 - Do not claim something is done before you have actually written report.md.
-- Re-read a skill with readSkill any time you are uncertain how to proceed.`;
+- Re-read a skill with readSkill any time you are uncertain how to proceed.${planModeBlock(planMode ?? false)}`;
 }
 function devtoolsInstructionsBlock(toolNames) {
     if (toolNames.length === 0)
@@ -103,21 +127,32 @@ Rules for browser tools:
   - Browser observations are primary evidence for page state but not independent corroboration; cross-check important factual claims with separate sources.
   - Never paste secrets or credentials into the browser.`;
 }
-export async function createResearchAgent(runPath, goal, config, onApprovalRequired, workspacePath) {
+export async function createResearchAgent(runPath, goal, config, onApprovalRequired, options = {}) {
     requireLlmKeys(config);
     const bridge = await createMcpBridge(config);
-    const researchTools = createResearchTools(runPath, config, onApprovalRequired);
-    const codingTools = workspacePath ? createCodingTools(workspacePath, config, onApprovalRequired) : {};
-    const tools = { ...researchTools, ...codingTools, ...bridge.tools };
+    const getPlanMode = options.getPlanMode ?? (() => options.planMode ?? false);
+    const researchTools = createResearchTools(runPath, config, onApprovalRequired, options.workspacePath, getPlanMode);
+    const codingTools = options.workspacePath
+        ? createCodingTools(options.workspacePath, config, onApprovalRequired, options.backgroundTasks, runPath, getPlanMode)
+        : {};
+    const tools = { ...researchTools, ...codingTools, ...wrapToolsForPlanMode(bridge.tools, getPlanMode) };
+    const bgContext = options.backgroundTasks ? await options.backgroundTasks.formatContextForAgent() : "";
     const agent = new ToolLoopAgent({
         model: getLanguageModel(config),
-        instructions: instructions(goal, config, workspacePath) + devtoolsInstructionsBlock(bridge.toolNames),
+        instructions: instructions(goal, config, options) + bgContext + devtoolsInstructionsBlock(bridge.toolNames),
         tools,
         stopWhen: isLoopFinished()
     });
     return { agent, close: bridge.close };
 }
-function oneShotInstructions(goal, hasDevtools) {
+function oneShotInstructions(goal, hasDevtools, options = {}) {
+    const { workspacePath } = options;
+    const planMode = resolvePlanMode(options);
+    const codingHint = workspacePath ? `
+
+Project root: ${workspacePath}. readFile/writeFile/editFile route code paths to the project root; harness files (plan.md, notes.md, …) stay under .scira/runs/.
+- listWorkspaceDir, grepWorkspace, bash (with background tasks), todo
+Use them for code questions, debugging, and implementation tasks.` : "";
     const now = new Date();
     const temporalContext = now.toLocaleDateString("en-US", {
         weekday: "long",
@@ -152,18 +187,23 @@ Step 1 — Decide the depth required:
 - When in doubt, escalate.${browserHint}
 
 Step 2 — If you decide to answer directly:
-- Default path: use webSearch (2-3 query variations) to find relevant, recent sources, then readUrl to read the best 1-2.
+- Default path: use webSearch (2-3 query variations) to find relevant, recent sources, then readUrl to read the best 1-2. Use xSearch to surface real-time X posts when the question involves public reactions, announcements, or social discussions.
 - Browser path (only if the routing rules above triggered): use the devtools_* tools to drive a real Chromium session, then summarize what you observed (cite the URL you visited).
 - Synthesize a clear, direct answer in a few short paragraphs. Cite sources inline as [title](url). Never invent sources or URLs.
-- Do NOT write files, create claims, or produce a formal report — just answer in chat.`;
+- Do NOT write files, create claims, or produce a formal report — just answer in chat.${codingHint}${planModeBlock(planMode ?? false)}`;
 }
-export async function createOneShotAgent(runPath, goal, config, onApprovalRequired, onEscalate) {
+export async function createOneShotAgent(runPath, goal, config, onApprovalRequired, onEscalate, options = {}) {
     requireLlmKeys(config);
     const bridge = await createMcpBridge(config);
-    const tools = { ...createOneShotTools(runPath, config, onApprovalRequired, onEscalate), ...bridge.tools };
+    const getPlanMode = options.getPlanMode ?? (() => options.planMode ?? false);
+    const tools = {
+        ...createOneShotTools(runPath, config, onApprovalRequired, onEscalate, options.workspacePath, options.backgroundTasks, getPlanMode),
+        ...wrapToolsForPlanMode(bridge.tools, getPlanMode)
+    };
+    const bgContext = options.backgroundTasks ? await options.backgroundTasks.formatContextForAgent() : "";
     const agent = new ToolLoopAgent({
         model: getLanguageModel(config),
-        instructions: oneShotInstructions(goal, bridge.toolNames.length > 0) + devtoolsInstructionsBlock(bridge.toolNames),
+        instructions: oneShotInstructions(goal, bridge.toolNames.length > 0, options) + bgContext + devtoolsInstructionsBlock(bridge.toolNames),
         tools,
         stopWhen: isLoopFinished()
     });
@@ -173,6 +213,15 @@ export async function createOneShotAgent(runPath, goal, config, onApprovalRequir
  * Run the research agent headlessly, streaming a compact timeline to stdout.
  */
 export async function runResearchAgent(runPath, goal, config, workspacePath) {
+    const options = {
+        ...(workspacePath
+            ? {
+                workspacePath,
+                backgroundTasks: createBackgroundTaskManager(runPath, workspacePath)
+            }
+            : {}),
+        getPlanMode: () => false
+    };
     const spinner = new Spinner();
     const onApprovalRequired = async (toolName, description) => {
         spinner.stop();
@@ -188,7 +237,7 @@ export async function runResearchAgent(runPath, goal, config, workspacePath) {
             spinner.start();
         return approved;
     };
-    const bundle = await createResearchAgent(runPath, goal, config, onApprovalRequired, workspacePath);
+    const bundle = await createResearchAgent(runPath, goal, config, onApprovalRequired, options);
     try {
         const result = await bundle.agent.stream({ prompt: goal });
         for await (const part of result.fullStream) {
@@ -230,6 +279,7 @@ const TOOL_ICONS = {
     createClaim: "◎",
     verifyClaim: "✓",
     webSearch: "⌕",
+    xSearch: "𝕏",
     readUrl: "↗",
     listSkills: "★",
     readSkill: "★",
@@ -238,17 +288,24 @@ const TOOL_ICONS = {
     getFile: "▤",
     fileExists: "▤",
     moveFile: "✎",
-    deleteFile: "✗"
+    deleteFile: "✗",
+    todo: "☐"
 };
 function summarize(input) {
     const obj = (input ?? {});
-    return String(obj.command ?? obj.query ?? obj.url ?? obj.path ?? obj.key ?? obj.pattern ?? obj.source ?? "").slice(0, 100);
+    if (obj.action && obj.action !== "run") {
+        return `${obj.action}${obj.taskId ? ` ${obj.taskId}` : ""}`.slice(0, 100);
+    }
+    if (Array.isArray(obj.queries)) {
+        const qs = obj.queries;
+        return (qs.slice(0, 2).join(" · ") + (qs.length > 2 ? ` +${qs.length - 2}` : "")).slice(0, 100);
+    }
+    return String(obj.command ?? obj.query ?? obj.url ?? obj.path ?? obj.key ?? obj.pattern ?? obj.source ?? obj.action ?? "").slice(0, 100);
 }
 const CODING_ICONS = {
     readWorkspaceFile: "▤",
     writeWorkspaceFile: "✎",
     editWorkspaceFile: "✎",
     listWorkspaceDir: "▤",
-    grepWorkspace: "⌕",
-    runWorkspaceCommand: "⌘"
+    grepWorkspace: "⌕"
 };

package/dist/agent/todos.js

@@ -0,0 +1,140 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import { logEvent } from "../storage/run-store.js";
+const TodoStatusSchema = z.enum(["pending", "in_progress", "completed", "cancelled"]);
+function nextTodoId(existing) {
+    const nums = existing
+        .map((t) => /^todo_(\d+)$/u.exec(t.id)?.[1])
+        .filter((n) => Boolean(n))
+        .map((n) => Number.parseInt(n, 10));
+    const next = nums.length > 0 ? Math.max(...nums) + 1 : 1;
+    return `todo_${String(next).padStart(3, "0")}`;
+}
+async function loadTodos(path) {
+    try {
+        const raw = await readFile(path, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((t) => typeof t === "object" && t !== null && typeof t.id === "string");
+    }
+    catch {
+        return [];
+    }
+}
+async function saveTodos(path, items) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(items, null, 2) + "\n");
+}
+function formatTodoList(items) {
+    if (items.length === 0)
+        return "No todos.";
+    const icon = {
+        pending: "[ ]",
+        in_progress: "[~]",
+        completed: "[x]",
+        cancelled: "[-]"
+    };
+    return items
+        .map((t) => `${icon[t.status]} ${t.id}: ${t.content} (${t.status})`)
+        .join("\n");
+}
+export function createTodoTool(runPath) {
+    const todosPath = join(runPath, "todos.json");
+    return tool({
+        description: "Manage structured task todos for the current session. " +
+            "Actions: create (add items), edit (change content), mark (set status), remove (delete one), rewrite (replace entire list), list (show all). " +
+            "Statuses: pending, in_progress, completed, cancelled.",
+        inputSchema: z.object({
+            action: z.enum(["create", "edit", "mark", "remove", "rewrite", "list"]),
+            id: z.string().optional().describe("Todo id for edit, mark, or remove."),
+            content: z.string().optional().describe("Todo text for create, edit, or rewrite items."),
+            status: TodoStatusSchema.optional().describe("Status for mark action or rewrite items."),
+            items: z
+                .array(z.object({
+                id: z.string().optional(),
+                content: z.string(),
+                status: TodoStatusSchema.optional()
+            }))
+                .optional()
+                .describe("Items for create or rewrite.")
+        }),
+        execute: async ({ action, id, content, status, items }) => {
+            const now = new Date().toISOString();
+            let todos = await loadTodos(todosPath);
+            switch (action) {
+                case "list":
+                    return formatTodoList(todos);
+                case "create": {
+                    const toAdd = items ?? (content ? [{ content, status: status ?? "pending" }] : []);
+                    if (toAdd.length === 0)
+                        return "create requires content or items.";
+                    for (const item of toAdd) {
+                        const todoId = item.id ?? nextTodoId(todos);
+                        todos.push({
+                            id: todoId,
+                            content: item.content,
+                            status: item.status ?? "pending",
+                            createdAt: now,
+                            updatedAt: now
+                        });
+                    }
+                    await saveTodos(todosPath, todos);
+                    await logEvent(runPath, "todo.created", { count: toAdd.length });
+                    return `Created ${toAdd.length} todo(s).\n\n${formatTodoList(todos)}`;
+                }
+                case "edit": {
+                    if (!id || !content)
+                        return "edit requires id and content.";
+                    const idx = todos.findIndex((t) => t.id === id);
+                    if (idx === -1)
+                        return `Todo "${id}" not found.`;
+                    todos[idx] = { ...todos[idx], content, updatedAt: now };
+                    await saveTodos(todosPath, todos);
+                    await logEvent(runPath, "todo.edited", { id });
+                    return `Updated ${id}.\n\n${formatTodoList(todos)}`;
+                }
+                case "mark": {
+                    if (!id || !status)
+                        return "mark requires id and status.";
+                    const idx = todos.findIndex((t) => t.id === id);
+                    if (idx === -1)
+                        return `Todo "${id}" not found.`;
+                    todos[idx] = { ...todos[idx], status, updatedAt: now };
+                    await saveTodos(todosPath, todos);
+                    await logEvent(runPath, "todo.marked", { id, status });
+                    return `Marked ${id} as ${status}.\n\n${formatTodoList(todos)}`;
+                }
+                case "remove": {
+                    if (!id)
+                        return "remove requires id.";
+                    const before = todos.length;
+                    todos = todos.filter((t) => t.id !== id);
+                    if (todos.length === before)
+                        return `Todo "${id}" not found.`;
+                    await saveTodos(todosPath, todos);
+                    await logEvent(runPath, "todo.removed", { id });
+                    return `Removed ${id}.\n\n${formatTodoList(todos)}`;
+                }
+                case "rewrite": {
+                    if (!items || items.length === 0)
+                        return "rewrite requires a non-empty items array.";
+                    todos = items.map((item, i) => ({
+                        id: item.id ?? `todo_${String(i + 1).padStart(3, "0")}`,
+                        content: item.content,
+                        status: item.status ?? "pending",
+                        createdAt: now,
+                        updatedAt: now
+                    }));
+                    await saveTodos(todosPath, todos);
+                    await logEvent(runPath, "todo.rewritten", { count: todos.length });
+                    return `Rewrote todo list (${todos.length} items).\n\n${formatTodoList(todos)}`;
+                }
+                default:
+                    return `Unknown action: ${action}`;
+            }
+        }
+    });
+}