@cuylabs/agent-code 0.6.0 → 0.8.0

package/dist/{chunk-U6W6NJNW.js → chunk-DXHZSPO6.js}

@@ -756,6 +756,58 @@ IMPORTANT:
   }
 });
 
+// src/tools/plan.ts
+import { z as z7 } from "zod";
+import { Tool as Tool7 } from "@cuylabs/agent-core";
+var planEntrySchema = z7.object({
+  id: z7.number().describe("Unique sequential identifier (1, 2, 3\u2026)"),
+  title: z7.string().max(120).describe("Concise action-oriented description of the task"),
+  status: z7.enum(["pending", "in-progress", "done"]).describe("Current status of this task")
+});
+var planParameters = z7.object({
+  entries: z7.array(planEntrySchema).min(1).describe("The complete plan \u2014 all tasks with current statuses")
+});
+var planTool = Tool7.define("plan", {
+  description: `Create or update a structured task plan for tracking multi-step work.
+
+When to use:
+- Before starting complex tasks that involve multiple files or steps
+- After completing a step, to mark it done and show progress
+- When the approach changes and tasks need to be revised
+
+Rules:
+- Send the COMPLETE plan every time (all entries, not just changes)
+- Keep titles short and action-oriented (max 120 chars)
+- Only ONE entry should be "in-progress" at a time
+- Use sequential IDs starting from 1
+- Mark tasks "done" as you complete them`,
+  parameters: planParameters,
+  replayPolicy: {
+    sideEffectLevel: "none",
+    reason: "Plan updates are informational \u2014 no file or network effects."
+  },
+  async execute(params) {
+    const { entries } = params;
+    const pending = entries.filter((e) => e.status === "pending").length;
+    const active = entries.filter((e) => e.status === "in-progress").length;
+    const done = entries.filter((e) => e.status === "done").length;
+    const lines = [];
+    for (const entry of entries) {
+      const marker = entry.status === "done" ? "\u2713" : entry.status === "in-progress" ? "\u2192" : "\u25CB";
+      lines.push(`${marker} ${entry.id}. ${entry.title}`);
+    }
+    return {
+      title: `Plan: ${done}/${entries.length} done`,
+      output: [
+        lines.join("\n"),
+        "",
+        `${done} done \xB7 ${active} active \xB7 ${pending} pending`
+      ].join("\n"),
+      metadata: { entries, done, active, pending, total: entries.length }
+    };
+  }
+});
+
 // src/tools/defaults.ts
 var defaultCodingTools = [
   bashTool,
@@ -763,18 +815,19 @@ var defaultCodingTools = [
   editTool,
   writeTool,
   grepTool,
-  globTool
+  globTool,
+  planTool
 ];
 
 // src/tools/toolset.ts
 import { defaultRegistry } from "@cuylabs/agent-core";
 function setupToolRegistry() {
-  for (const tool of [bashTool, readTool, editTool, writeTool, grepTool, globTool]) {
+  for (const tool of [bashTool, readTool, editTool, writeTool, grepTool, globTool, planTool]) {
     defaultRegistry.set(tool);
   }
-  defaultRegistry.registerGroup("all", ["bash", "read", "edit", "write", "grep", "glob"]);
+  defaultRegistry.registerGroup("all", ["bash", "read", "edit", "write", "grep", "glob", "plan"]);
   defaultRegistry.registerGroup("read-only", ["read", "grep", "glob"]);
-  defaultRegistry.registerGroup("safe", ["read", "edit", "write", "grep", "glob"]);
+  defaultRegistry.registerGroup("safe", ["read", "edit", "write", "grep", "glob", "plan"]);
   defaultRegistry.registerGroup("minimal", ["read", "write"]);
 }
 var ToolsetBuilder = class {
@@ -858,9 +911,11 @@ export {
   grepTool,
   globParameters,
   globTool,
-  defaultCodingTools,
+  planParameters,
+  planTool,
   setupToolRegistry,
   ToolsetBuilder,
   toolset,
-  resolveTools
+  resolveTools,
+  defaultCodingTools
 };

package/dist/index.d.ts

@@ -1,3 +1,100 @@
+import { AgentConfig, ToolSpec, ApprovalMiddlewareConfig, PromptCacheConfig, SkillConfig, SkillRegistry, SubAgentToolConfig, AgentProfile, SessionManager, FileStorageOptions, Agent } from '@cuylabs/agent-core';
 export * from '@cuylabs/agent-core';
-export { BashParams, EditParams, GlobParams, GrepParams, ReadParams, ToolsetBuilder, WriteParams, bashParameters, bashTool, defaultCodingTools, editParameters, editTool, executeBash, executeGrep, globParameters, globTool, grepParameters, grepTool, readParameters, readTool, resolveTools, setupToolRegistry, toolset, writeParameters, writeTool } from './tools/index.js';
-import 'zod';
+export { z } from 'zod';
+export { B as BashParams, E as EditParams, G as GlobParams, a as GrepParams, R as ReadParams, T as ToolsetBuilder, W as WriteParams, b as bashParameters, c as bashTool, d as defaultCodingTools, e as editParameters, f as editTool, g as executeBash, h as executeGrep, i as globParameters, j as globTool, k as grepParameters, l as grepTool, r as readParameters, m as readTool, n as resolveTools, s as setupToolRegistry, t as toolset, w as writeParameters, o as writeTool } from './toolset-DdlrWOqv.js';
+
+interface CodingSessionStorageOptions extends Partial<Omit<FileStorageOptions, "directory">> {
+    /**
+     * Explicit directory for project sessions.
+     *
+     * When omitted, `getProjectSessionsDir(cwd, appName)` is used.
+     */
+    directory?: string;
+    /**
+     * App namespace used by `getProjectSessionsDir()`.
+     *
+     * @default "cuylabs"
+     */
+    appName?: string;
+}
+interface CodingSubAgentOptions extends Omit<SubAgentToolConfig, "profiles"> {
+    /**
+     * Specialist profiles exposed through `invoke_agent`.
+     *
+     * Defaults to `defaultCodingProfiles`.
+     */
+    profiles?: AgentProfile[];
+}
+interface CodingAgentOptions extends AgentConfig {
+    /**
+     * Coding tools to expose. Defaults to the full coding toolset.
+     *
+     * Accepts the same `ToolSpec` formats as `resolveTools()`.
+     */
+    tools?: ToolSpec;
+    /**
+     * Optional approval middleware configuration.
+     *
+     * Pass `false` to disable approval wiring entirely.
+     */
+    approval?: false | ApprovalMiddlewareConfig;
+    /**
+     * Enable the prompt cache middleware.
+     *
+     * `true` uses provider defaults.
+     */
+    promptCache?: boolean | PromptCacheConfig;
+    /**
+     * Skill discovery configuration or a pre-built registry.
+     *
+     * Defaults to `true`, which scans the current project and user skill roots.
+     */
+    skills?: boolean | SkillConfig | SkillRegistry;
+    /**
+     * Sub-agent delegation configuration.
+     *
+     * Defaults to `true`, which enables `invoke_agent` with the default
+     * coding specialist profiles.
+     */
+    subAgents?: boolean | CodingSubAgentOptions;
+    /**
+     * Explicit session manager. Overrides `sessionStorage` when provided.
+     */
+    sessionManager?: SessionManager;
+    /**
+     * Configure project-scoped file-backed sessions.
+     *
+     * Defaults to `true`, which stores sessions under the project storage dir.
+     * Pass `false` to keep the agent on the default in-memory session manager.
+     */
+    sessionStorage?: boolean | CodingSessionStorageOptions;
+}
+interface CodingAgentSetupResult {
+    agent: Agent;
+    skillRegistry: SkillRegistry | null;
+}
+/**
+ * Assemble a batteries-included coding agent from `agent-core` primitives.
+ *
+ * This wires the coding toolset, optional approval middleware, skill tools,
+ * persistent sessions, and sub-agent delegation into a reusable package-level
+ * surface. UI-specific concerns stay outside this helper.
+ */
+declare function setupCodingAgent(options: CodingAgentOptions): Promise<CodingAgentSetupResult>;
+/**
+ * Create a fully-wired coding agent.
+ *
+ * Returns just the agent instance for the common embeddable case. Use
+ * `setupCodingAgent()` when you also need the resolved skill registry.
+ */
+declare function createCodingAgent(options: CodingAgentOptions): Promise<Agent>;
+
+/**
+ * Default specialist profiles for coding-focused agents.
+ *
+ * These are the profiles enabled by `setupCodingAgent()` when
+ * `subAgents: true` is used.
+ */
+declare const defaultCodingProfiles: AgentProfile[];
+
+export { type CodingAgentOptions, type CodingAgentSetupResult, type CodingSessionStorageOptions, type CodingSubAgentOptions, createCodingAgent, defaultCodingProfiles, setupCodingAgent };

package/dist/index.js

@@ -18,14 +18,185 @@ import {
   toolset,
   writeParameters,
   writeTool
-} from "./chunk-U6W6NJNW.js";
+} from "./chunk-DXHZSPO6.js";
 
 // src/index.ts
 export * from "@cuylabs/agent-core";
+import { z } from "zod";
+
+// src/create.ts
+import process from "process";
+import {
+  PRIORITY_SKILLS,
+  FileStorage,
+  SessionManager,
+  SkillRegistry,
+  approvalMiddleware,
+  createAgent,
+  createSkillRegistry,
+  createSkillTools,
+  createSubAgentTools,
+  getProjectSessionsDir,
+  promptCacheMiddleware
+} from "@cuylabs/agent-core";
+
+// src/profiles.ts
+import { Presets } from "@cuylabs/agent-core";
+var defaultCodingProfiles = [
+  {
+    name: "explorer",
+    description: 'Fast read-only codebase search and exploration. Use for finding files by pattern, searching code for keywords, reading file contents, answering questions about the codebase, and mapping project structure. Starts with glob/grep to discover paths. Specify thoroughness: "quick" for basic lookups, "thorough" for deep analysis across multiple locations.',
+    preset: Presets.explore,
+    maxSteps: 20
+  },
+  {
+    name: "coder",
+    description: "Full-power implementation agent for writing, editing, and modifying code. Use for implementing features, fixing bugs, refactoring, writing tests, and any task that requires file modifications. Reads context first, follows existing conventions, verifies changes. Iterates until done.",
+    preset: Presets.code,
+    maxSteps: 40
+  },
+  {
+    name: "planner",
+    description: "Read-only analysis and planning agent. Use when you need a detailed implementation plan before starting work. Breaks down complex tasks into numbered, actionable steps. Does not make changes.",
+    preset: Presets.plan,
+    maxSteps: 15
+  },
+  {
+    name: "runner",
+    description: "Process execution and monitoring agent. Use for running test suites, builds, lint, or any command that takes time. Executes the command, waits for output, and reports a clear pass/fail summary. Does not modify files.",
+    preset: Presets.watch,
+    maxSteps: 10
+  }
+];
+
+// src/create.ts
+function resolveSessionManager(cwd, sessionManager, sessionStorage) {
+  if (sessionManager) {
+    return sessionManager;
+  }
+  if (sessionStorage === false) {
+    return void 0;
+  }
+  const storageOptions = sessionStorage && sessionStorage !== true ? sessionStorage : void 0;
+  const directory = storageOptions?.directory ?? getProjectSessionsDir(cwd, storageOptions?.appName);
+  return new SessionManager(
+    new FileStorage({
+      directory,
+      extension: storageOptions?.extension,
+      cache: storageOptions?.cache
+    })
+  );
+}
+async function resolveSkillRegistry(cwd, skills) {
+  if (skills === false) {
+    return null;
+  }
+  if (skills instanceof SkillRegistry) {
+    return skills;
+  }
+  const config = skills === true || skills === void 0 ? void 0 : skills;
+  return await createSkillRegistry(cwd, config);
+}
+function resolveSubAgentOptions(subAgents) {
+  if (subAgents === false) {
+    return null;
+  }
+  const config = subAgents && subAgents !== true ? subAgents : void 0;
+  const profiles = config?.profiles ?? defaultCodingProfiles;
+  if (profiles.length === 0) {
+    return null;
+  }
+  return {
+    profiles,
+    maxConcurrent: config?.maxConcurrent,
+    maxDepth: config?.maxDepth,
+    currentDepth: config?.currentDepth,
+    async: config?.async,
+    sessionTitlePrefix: config?.sessionTitlePrefix
+  };
+}
+function mergePromptConfig(options) {
+  const { prompt, systemPrompt, skillRegistry } = options;
+  const skillSummary = skillRegistry?.formatSummary() ?? "";
+  if (skillSummary.length === 0) {
+    return prompt;
+  }
+  if (prompt === void 0 && systemPrompt !== void 0) {
+    return void 0;
+  }
+  if (prompt?.skills !== void 0) {
+    return prompt;
+  }
+  const sections = [...prompt?.sections ?? []];
+  sections.push({
+    id: "coding-skills",
+    label: "Available Skills",
+    content: skillSummary,
+    priority: PRIORITY_SKILLS
+  });
+  return {
+    ...prompt,
+    sections
+  };
+}
+async function setupCodingAgent(options) {
+  const {
+    tools: toolSpec = true,
+    approval = false,
+    promptCache = false,
+    skills = true,
+    subAgents = true,
+    sessionManager,
+    sessionStorage = true,
+    middleware,
+    prompt,
+    cwd = process.cwd(),
+    ...agentOptions
+  } = options;
+  const tools = resolveTools(toolSpec);
+  const skillRegistry = await resolveSkillRegistry(cwd, skills);
+  if (skillRegistry && skillRegistry.size > 0) {
+    tools.push(...createSkillTools(skillRegistry));
+  }
+  const resolvedMiddleware = [...middleware ?? []];
+  if (approval) {
+    resolvedMiddleware.push(approvalMiddleware(approval));
+  }
+  if (promptCache) {
+    resolvedMiddleware.push(
+      promptCacheMiddleware(promptCache === true ? void 0 : promptCache)
+    );
+  }
+  const agent = createAgent({
+    ...agentOptions,
+    cwd,
+    prompt: mergePromptConfig({
+      prompt,
+      systemPrompt: agentOptions.systemPrompt,
+      skillRegistry
+    }),
+    sessionManager: resolveSessionManager(cwd, sessionManager, sessionStorage),
+    ...resolvedMiddleware.length > 0 ? { middleware: resolvedMiddleware } : {},
+    ...tools.length > 0 ? { tools } : {}
+  });
+  const subAgentConfig = resolveSubAgentOptions(subAgents);
+  if (subAgentConfig && tools.length > 0) {
+    for (const tool of createSubAgentTools(agent, subAgentConfig)) {
+      agent.addTool(tool);
+    }
+  }
+  return { agent, skillRegistry };
+}
+async function createCodingAgent(options) {
+  const { agent } = await setupCodingAgent(options);
+  return agent;
+}
 export {
   ToolsetBuilder,
   bashParameters,
   bashTool,
+  createCodingAgent,
+  defaultCodingProfiles,
   defaultCodingTools,
   editParameters,
   editTool,
@@ -38,8 +209,10 @@ export {
   readParameters,
   readTool,
   resolveTools,
+  setupCodingAgent,
   setupToolRegistry,
   toolset,
   writeParameters,
-  writeTool
+  writeTool,
+  z
 };

package/dist/tools/index.d.ts

@@ -1,354 +1,93 @@
-import { Tool, ToolHost, ExecResult, ToolSpec } from '@cuylabs/agent-core';
+export { B as BashParams, E as EditParams, G as GlobParams, a as GrepParams, R as ReadParams, T as ToolsetBuilder, W as WriteParams, b as bashParameters, c as bashTool, d as defaultCodingTools, e as editParameters, f as editTool, g as executeBash, h as executeGrep, i as globParameters, j as globTool, k as grepParameters, l as grepTool, r as readParameters, m as readTool, n as resolveTools, s as setupToolRegistry, t as toolset, w as writeParameters, o as writeTool } from '../toolset-DdlrWOqv.js';
 import { z } from 'zod';
+import { Tool } from '@cuylabs/agent-core';
 
 /**
- * Bash tool - Execute shell commands
- */
-
-declare const bashParameters: z.ZodObject<{
-    command: z.ZodString;
-    timeout: z.ZodOptional<z.ZodNumber>;
-    workdir: z.ZodOptional<z.ZodString>;
-    description: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    description: string;
-    command: string;
-    timeout?: number | undefined;
-    workdir?: string | undefined;
-}, {
-    description: string;
-    command: string;
-    timeout?: number | undefined;
-    workdir?: string | undefined;
-}>;
-type BashParams = z.infer<typeof bashParameters>;
-/**
- * Execute a bash command via a ToolHost.
- */
-declare function executeBash(params: BashParams, host: ToolHost, cwd: string, abort?: AbortSignal): Promise<ExecResult>;
-/**
- * Bash tool definition
- */
-declare const bashTool: Tool.Info<z.ZodObject<{
-    command: z.ZodString;
-    timeout: z.ZodOptional<z.ZodNumber>;
-    workdir: z.ZodOptional<z.ZodString>;
-    description: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    description: string;
-    command: string;
-    timeout?: number | undefined;
-    workdir?: string | undefined;
-}, {
-    description: string;
-    command: string;
-    timeout?: number | undefined;
-    workdir?: string | undefined;
-}>, {
-    exitCode: number | null;
-    timedOut: boolean;
-    truncated: boolean;
-    outputPath: string | undefined;
-}>;
-
-/**
- * Read tool - Read file contents
- */
-
-declare const readParameters: z.ZodObject<{
-    filePath: z.ZodString;
-    offset: z.ZodOptional<z.ZodNumber>;
-    limit: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    filePath: string;
-    limit?: number | undefined;
-    offset?: number | undefined;
-}, {
-    filePath: string;
-    limit?: number | undefined;
-    offset?: number | undefined;
-}>;
-type ReadParams = z.infer<typeof readParameters>;
-/**
- * Read tool definition
- */
-declare const readTool: Tool.Info<z.ZodObject<{
-    filePath: z.ZodString;
-    offset: z.ZodOptional<z.ZodNumber>;
-    limit: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    filePath: string;
-    limit?: number | undefined;
-    offset?: number | undefined;
-}, {
-    filePath: string;
-    limit?: number | undefined;
-    offset?: number | undefined;
-}>, {
-    totalLines: number;
-    linesRead: number;
-    offset: number;
-    truncated: boolean;
-    preview: string;
-}>;
-
-/**
- * Edit tool - Edit files by replacing text
- */
-
-declare const editParameters: z.ZodObject<{
-    filePath: z.ZodString;
-    oldString: z.ZodString;
-    newString: z.ZodString;
-    replaceAll: z.ZodOptional<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    filePath: string;
-    oldString: string;
-    newString: string;
-    replaceAll?: boolean | undefined;
-}, {
-    filePath: string;
-    oldString: string;
-    newString: string;
-    replaceAll?: boolean | undefined;
-}>;
-type EditParams = z.infer<typeof editParameters>;
-/**
- * Edit tool definition
- */
-declare const editTool: Tool.Info<z.ZodObject<{
-    filePath: z.ZodString;
-    oldString: z.ZodString;
-    newString: z.ZodString;
-    replaceAll: z.ZodOptional<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    filePath: string;
-    oldString: string;
-    newString: string;
-    replaceAll?: boolean | undefined;
-}, {
-    filePath: string;
-    oldString: string;
-    newString: string;
-    replaceAll?: boolean | undefined;
-}>, {
-    filepath: string;
-    created: boolean;
-    additions: number;
-    deletions: number;
-    diff: string;
-}>;
-
-/**
- * Write tool - Create or overwrite files
- */
-
-declare const writeParameters: z.ZodObject<{
-    filePath: z.ZodString;
-    content: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    content: string;
-    filePath: string;
-}, {
-    content: string;
-    filePath: string;
-}>;
-type WriteParams = z.infer<typeof writeParameters>;
-/**
- * Write tool definition
- */
-declare const writeTool: Tool.Info<z.ZodObject<{
-    filePath: z.ZodString;
-    content: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    content: string;
-    filePath: string;
-}, {
-    content: string;
-    filePath: string;
-}>, {
-    filepath: string;
-    created: boolean;
-    updated: boolean;
-    lines: number;
-}>;
-
-/**
- * Grep tool - Search file contents
+ * Plan tool — structured task planning for multi-step work.
+ *
+ * Allows the agent to create, track, and update a structured plan
+ * that is visible to the user. Each invocation replaces the full plan,
+ * so the agent always sends the complete current state.
  */
 
-declare const grepParameters: z.ZodObject<{
-    pattern: z.ZodString;
-    path: z.ZodOptional<z.ZodString>;
-    include: z.ZodOptional<z.ZodString>;
+declare const planEntrySchema: z.ZodObject<{
+    id: z.ZodNumber;
+    title: z.ZodString;
+    status: z.ZodEnum<["pending", "in-progress", "done"]>;
 }, "strip", z.ZodTypeAny, {
-    pattern: string;
-    path?: string | undefined;
-    include?: string | undefined;
+    id: number;
+    status: "done" | "pending" | "in-progress";
+    title: string;
 }, {
-    pattern: string;
-    path?: string | undefined;
-    include?: string | undefined;
-}>;
-type GrepParams = z.infer<typeof grepParameters>;
-/**
- * Execute grep search
- */
-declare function executeGrep(params: GrepParams, host: ToolHost, cwd: string, abort?: AbortSignal): Promise<{
-    matches: Array<{
-        file: string;
-        line: number;
-        text: string;
-    }>;
-    truncated: boolean;
+    id: number;
+    status: "done" | "pending" | "in-progress";
+    title: string;
 }>;
-/**
- * Grep tool definition
- */
-declare const grepTool: Tool.Info<z.ZodObject<{
-    pattern: z.ZodString;
-    path: z.ZodOptional<z.ZodString>;
-    include: z.ZodOptional<z.ZodString>;
+declare const planParameters: z.ZodObject<{
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        title: z.ZodString;
+        status: z.ZodEnum<["pending", "in-progress", "done"]>;
+    }, "strip", z.ZodTypeAny, {
+        id: number;
+        status: "done" | "pending" | "in-progress";
+        title: string;
+    }, {
+        id: number;
+        status: "done" | "pending" | "in-progress";
+        title: string;
+    }>, "many">;
 }, "strip", z.ZodTypeAny, {
-    pattern: string;
-    path?: string | undefined;
-    include?: string | undefined;
+    entries: {
+        id: number;
+        status: "done" | "pending" | "in-progress";
+        title: string;
+    }[];
 }, {
-    pattern: string;
-    path?: string | undefined;
-    include?: string | undefined;
-}>, {
-    matches: number;
-    truncated: boolean;
+    entries: {
+        id: number;
+        status: "done" | "pending" | "in-progress";
+        title: string;
+    }[];
 }>;
-
-/**
- * Glob tool - Find files by pattern
- */
-
-declare const globParameters: z.ZodObject<{
-    pattern: z.ZodString;
-    path: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    pattern: string;
-    path?: string | undefined;
-}, {
-    pattern: string;
-    path?: string | undefined;
-}>;
-type GlobParams = z.infer<typeof globParameters>;
-/**
- * Glob tool definition
- */
-declare const globTool: Tool.Info<z.ZodObject<{
-    pattern: z.ZodString;
-    path: z.ZodOptional<z.ZodString>;
+type PlanParams = z.infer<typeof planParameters>;
+type PlanEntry = z.infer<typeof planEntrySchema>;
+declare const planTool: Tool.Info<z.ZodObject<{
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        title: z.ZodString;
+        status: z.ZodEnum<["pending", "in-progress", "done"]>;
+    }, "strip", z.ZodTypeAny, {
+        id: number;
+        status: "done" | "pending" | "in-progress";
+        title: string;
+    }, {
+        id: number;
+        status: "done" | "pending" | "in-progress";
+        title: string;
+    }>, "many">;
 }, "strip", z.ZodTypeAny, {
-    pattern: string;
-    path?: string | undefined;
+    entries: {
+        id: number;
+        status: "done" | "pending" | "in-progress";
+        title: string;
+    }[];
 }, {
-    pattern: string;
-    path?: string | undefined;
+    entries: {
+        id: number;
+        status: "done" | "pending" | "in-progress";
+        title: string;
+    }[];
 }>, {
-    count: number;
-    truncated: boolean;
+    entries: {
+        id: number;
+        status: "done" | "pending" | "in-progress";
+        title: string;
+    }[];
+    done: number;
+    active: number;
+    pending: number;
+    total: number;
 }>;
 
-/**
- * Default tool collections
- */
-
-/**
- * Default tools for a coding agent
- */
-declare const defaultCodingTools: Tool.AnyInfo[];
-
-/**
- * Tool composition and registry setup for @cuylabs/agent-code.
- *
- * Registers all coding tools into the default registry, defines standard
- * groups, and provides a fluent `toolset()` builder for easy composition.
- *
- * @example
- * ```typescript
- * import { toolset, resolveTools } from "@cuylabs/agent-code";
- *
- * // Fluent builder
- * const tools = toolset("read-only").add(myCustomTool).build();
- *
- * // Spec-based resolution
- * const tools = resolveTools("all,-bash");
- * const tools = resolveTools("read,grep,glob");
- * const tools = resolveTools("safe");
- * ```
- */
-
-/**
- * Register all coding tools and standard groups into the default registry.
- * Uses `set()` (upsert) so it's safe to call multiple times, even after
- * `clear()`.
- */
-declare function setupToolRegistry(): void;
-/**
- * Fluent tool composition builder.
- *
- * @example
- * ```typescript
- * // Start from a group and customize
- * const tools = toolset("read-only").add(myTool).build();
- *
- * // Start from all and exclude
- * const tools = toolset("all").remove("bash").build();
- *
- * // Start empty and pick
- * const tools = toolset().add("read").add("grep").build();
- * ```
- */
-declare class ToolsetBuilder {
-    private tools;
-    constructor(base?: ToolSpec);
-    /** Add a tool by ID (from registry) or by instance. */
-    add(tool: string | Tool.AnyInfo): this;
-    /** Remove a tool by ID. */
-    remove(id: string): this;
-    /** Keep only the specified tool IDs (intersection). */
-    only(...ids: string[]): this;
-    /** Return the final tool array. */
-    build(): Tool.AnyInfo[];
-}
-/**
- * Create a toolset builder with an optional base spec.
- *
- * @param base Starting point — group name, tool IDs, boolean, or array.
- *             Defaults to empty (call `.add()` to populate).
- *
- * @example
- * ```typescript
- * // All tools except bash
- * const tools = toolset("all").remove("bash").build();
- *
- * // Read-only with a custom tool
- * const tools = toolset("read-only").add(mySearchTool).build();
- * ```
- */
-declare function toolset(base?: ToolSpec): ToolsetBuilder;
-/**
- * Resolve a tool spec to an array of tools.
- *
- * Ensures the coding tool registry is initialized, then delegates to
- * `defaultRegistry.resolve()`.
- *
- * @param spec Group name, comma-separated IDs, boolean, or array.
- *
- * @example
- * ```typescript
- * resolveTools("read-only");         // → [readTool, grepTool, globTool]
- * resolveTools("all,-bash");         // → all except bash
- * resolveTools("read,grep");         // → [readTool, grepTool]
- * resolveTools(true);                // → all coding tools
- * resolveTools(false);               // → []
- * ```
- */
-declare function resolveTools(spec: ToolSpec): Tool.AnyInfo[];
-
-export { type BashParams, type EditParams, type GlobParams, type GrepParams, type ReadParams, ToolsetBuilder, type WriteParams, bashParameters, bashTool, defaultCodingTools, editParameters, editTool, executeBash, executeGrep, globParameters, globTool, grepParameters, grepTool, readParameters, readTool, resolveTools, setupToolRegistry, toolset, writeParameters, writeTool };
+export { type PlanEntry, type PlanParams, planParameters, planTool };

package/dist/tools/index.js

@@ -11,6 +11,8 @@ import {
   globTool,
   grepParameters,
   grepTool,
+  planParameters,
+  planTool,
   readParameters,
   readTool,
   resolveTools,
@@ -18,7 +20,7 @@ import {
   toolset,
   writeParameters,
   writeTool
-} from "../chunk-U6W6NJNW.js";
+} from "../chunk-DXHZSPO6.js";
 export {
   ToolsetBuilder,
   bashParameters,
@@ -32,6 +34,8 @@ export {
   globTool,
   grepParameters,
   grepTool,
+  planParameters,
+  planTool,
   readParameters,
   readTool,
   resolveTools,

package/dist/toolset-DdlrWOqv.d.ts

@@ -0,0 +1,354 @@
+import { z } from 'zod';
+import { Tool, ToolHost, ExecResult, ToolSpec } from '@cuylabs/agent-core';
+
+/**
+ * Bash tool - Execute shell commands
+ */
+
+declare const bashParameters: z.ZodObject<{
+    command: z.ZodString;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    workdir: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    command: string;
+    timeout?: number | undefined;
+    workdir?: string | undefined;
+}, {
+    description: string;
+    command: string;
+    timeout?: number | undefined;
+    workdir?: string | undefined;
+}>;
+type BashParams = z.infer<typeof bashParameters>;
+/**
+ * Execute a bash command via a ToolHost.
+ */
+declare function executeBash(params: BashParams, host: ToolHost, cwd: string, abort?: AbortSignal): Promise<ExecResult>;
+/**
+ * Bash tool definition
+ */
+declare const bashTool: Tool.Info<z.ZodObject<{
+    command: z.ZodString;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    workdir: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    command: string;
+    timeout?: number | undefined;
+    workdir?: string | undefined;
+}, {
+    description: string;
+    command: string;
+    timeout?: number | undefined;
+    workdir?: string | undefined;
+}>, {
+    exitCode: number | null;
+    timedOut: boolean;
+    truncated: boolean;
+    outputPath: string | undefined;
+}>;
+
+/**
+ * Read tool - Read file contents
+ */
+
+declare const readParameters: z.ZodObject<{
+    filePath: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    filePath: string;
+    limit?: number | undefined;
+    offset?: number | undefined;
+}, {
+    filePath: string;
+    limit?: number | undefined;
+    offset?: number | undefined;
+}>;
+type ReadParams = z.infer<typeof readParameters>;
+/**
+ * Read tool definition
+ */
+declare const readTool: Tool.Info<z.ZodObject<{
+    filePath: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    filePath: string;
+    limit?: number | undefined;
+    offset?: number | undefined;
+}, {
+    filePath: string;
+    limit?: number | undefined;
+    offset?: number | undefined;
+}>, {
+    totalLines: number;
+    linesRead: number;
+    offset: number;
+    truncated: boolean;
+    preview: string;
+}>;
+
+/**
+ * Edit tool - Edit files by replacing text
+ */
+
+declare const editParameters: z.ZodObject<{
+    filePath: z.ZodString;
+    oldString: z.ZodString;
+    newString: z.ZodString;
+    replaceAll: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    filePath: string;
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean | undefined;
+}, {
+    filePath: string;
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean | undefined;
+}>;
+type EditParams = z.infer<typeof editParameters>;
+/**
+ * Edit tool definition
+ */
+declare const editTool: Tool.Info<z.ZodObject<{
+    filePath: z.ZodString;
+    oldString: z.ZodString;
+    newString: z.ZodString;
+    replaceAll: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    filePath: string;
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean | undefined;
+}, {
+    filePath: string;
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean | undefined;
+}>, {
+    filepath: string;
+    created: boolean;
+    additions: number;
+    deletions: number;
+    diff: string;
+}>;
+
+/**
+ * Write tool - Create or overwrite files
+ */
+
+declare const writeParameters: z.ZodObject<{
+    filePath: z.ZodString;
+    content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    filePath: string;
+}, {
+    content: string;
+    filePath: string;
+}>;
+type WriteParams = z.infer<typeof writeParameters>;
+/**
+ * Write tool definition
+ */
+declare const writeTool: Tool.Info<z.ZodObject<{
+    filePath: z.ZodString;
+    content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    filePath: string;
+}, {
+    content: string;
+    filePath: string;
+}>, {
+    filepath: string;
+    created: boolean;
+    updated: boolean;
+    lines: number;
+}>;
+
+/**
+ * Grep tool - Search file contents
+ */
+
+declare const grepParameters: z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    include: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    pattern: string;
+    path?: string | undefined;
+    include?: string | undefined;
+}, {
+    pattern: string;
+    path?: string | undefined;
+    include?: string | undefined;
+}>;
+type GrepParams = z.infer<typeof grepParameters>;
+/**
+ * Execute grep search
+ */
+declare function executeGrep(params: GrepParams, host: ToolHost, cwd: string, abort?: AbortSignal): Promise<{
+    matches: Array<{
+        file: string;
+        line: number;
+        text: string;
+    }>;
+    truncated: boolean;
+}>;
+/**
+ * Grep tool definition
+ */
+declare const grepTool: Tool.Info<z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    include: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    pattern: string;
+    path?: string | undefined;
+    include?: string | undefined;
+}, {
+    pattern: string;
+    path?: string | undefined;
+    include?: string | undefined;
+}>, {
+    matches: number;
+    truncated: boolean;
+}>;
+
+/**
+ * Glob tool - Find files by pattern
+ */
+
+declare const globParameters: z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    pattern: string;
+    path?: string | undefined;
+}, {
+    pattern: string;
+    path?: string | undefined;
+}>;
+type GlobParams = z.infer<typeof globParameters>;
+/**
+ * Glob tool definition
+ */
+declare const globTool: Tool.Info<z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    pattern: string;
+    path?: string | undefined;
+}, {
+    pattern: string;
+    path?: string | undefined;
+}>, {
+    count: number;
+    truncated: boolean;
+}>;
+
+/**
+ * Default tool collections
+ */
+
+/**
+ * Default tools for a coding agent
+ */
+declare const defaultCodingTools: Tool.AnyInfo[];
+
+/**
+ * Tool composition and registry setup for @cuylabs/agent-code.
+ *
+ * Registers all coding tools into the default registry, defines standard
+ * groups, and provides a fluent `toolset()` builder for easy composition.
+ *
+ * @example
+ * ```typescript
+ * import { toolset, resolveTools } from "@cuylabs/agent-code";
+ *
+ * // Fluent builder
+ * const tools = toolset("read-only").add(myCustomTool).build();
+ *
+ * // Spec-based resolution
+ * const tools = resolveTools("all,-bash");
+ * const tools = resolveTools("read,grep,glob");
+ * const tools = resolveTools("safe");
+ * ```
+ */
+
+/**
+ * Register all coding tools and standard groups into the default registry.
+ * Uses `set()` (upsert) so it's safe to call multiple times, even after
+ * `clear()`.
+ */
+declare function setupToolRegistry(): void;
+/**
+ * Fluent tool composition builder.
+ *
+ * @example
+ * ```typescript
+ * // Start from a group and customize
+ * const tools = toolset("read-only").add(myTool).build();
+ *
+ * // Start from all and exclude
+ * const tools = toolset("all").remove("bash").build();
+ *
+ * // Start empty and pick
+ * const tools = toolset().add("read").add("grep").build();
+ * ```
+ */
+declare class ToolsetBuilder {
+    private tools;
+    constructor(base?: ToolSpec);
+    /** Add a tool by ID (from registry) or by instance. */
+    add(tool: string | Tool.AnyInfo): this;
+    /** Remove a tool by ID. */
+    remove(id: string): this;
+    /** Keep only the specified tool IDs (intersection). */
+    only(...ids: string[]): this;
+    /** Return the final tool array. */
+    build(): Tool.AnyInfo[];
+}
+/**
+ * Create a toolset builder with an optional base spec.
+ *
+ * @param base Starting point — group name, tool IDs, boolean, or array.
+ *             Defaults to empty (call `.add()` to populate).
+ *
+ * @example
+ * ```typescript
+ * // All tools except bash
+ * const tools = toolset("all").remove("bash").build();
+ *
+ * // Read-only with a custom tool
+ * const tools = toolset("read-only").add(mySearchTool).build();
+ * ```
+ */
+declare function toolset(base?: ToolSpec): ToolsetBuilder;
+/**
+ * Resolve a tool spec to an array of tools.
+ *
+ * Ensures the coding tool registry is initialized, then delegates to
+ * `defaultRegistry.resolve()`.
+ *
+ * @param spec Group name, comma-separated IDs, boolean, or array.
+ *
+ * @example
+ * ```typescript
+ * resolveTools("read-only");         // → [readTool, grepTool, globTool]
+ * resolveTools("all,-bash");         // → all except bash
+ * resolveTools("read,grep");         // → [readTool, grepTool]
+ * resolveTools(true);                // → all coding tools
+ * resolveTools(false);               // → []
+ * ```
+ */
+declare function resolveTools(spec: ToolSpec): Tool.AnyInfo[];
+
+export { type BashParams as B, type EditParams as E, type GlobParams as G, type ReadParams as R, ToolsetBuilder as T, type WriteParams as W, type GrepParams as a, bashParameters as b, bashTool as c, defaultCodingTools as d, editParameters as e, editTool as f, executeBash as g, executeGrep as h, globParameters as i, globTool as j, grepParameters as k, grepTool as l, readTool as m, resolveTools as n, writeTool as o, readParameters as r, setupToolRegistry as s, toolset as t, writeParameters as w };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-code",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Embeddable AI coding agent built on @cuylabs/agent-core",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,7 +24,7 @@
   "dependencies": {
     "ai": "^6.0.67",
     "zod": "^3.24.0",
-    "@cuylabs/agent-core": "^0.6.0"
+    "@cuylabs/agent-core": "^0.8.0"
   },
   "peerDependencies": {
     "@ai-sdk/anthropic": "^3.0.0",