@cuylabs/agent-code 0.8.0 → 0.10.0

package/README.md

@@ -20,7 +20,7 @@ such as:
 
 - middleware and prompt construction
 - runtime helpers
-- skills, presets, and sub-agent composition
+- skills, profiles, and subagent composition
 - non-coding toolsets or framework-level customization
 
 Focused tool imports are available from `@cuylabs/agent-code/tools`.

package/dist/{chunk-DXHZSPO6.js → chunk-554MRR24.js}

@@ -1,6 +1,6 @@
 // src/tools/bash.ts
 import { z } from "zod";
-import { Tool, truncateOutput } from "@cuylabs/agent-core";
+import { Tool, getRequiredToolHost, truncateOutput } from "@cuylabs/agent-core";
 var DEFAULT_TIMEOUT = 2 * 60 * 1e3;
 var bashParameters = z.object({
   command: z.string().describe("The shell command to execute"),
@@ -39,13 +39,19 @@ IMPORTANT:
 - Output is automatically truncated if too long
 - For pager commands, output is piped through 'cat' automatically`,
   parameters: bashParameters,
+  hostRequirements: {
+    shell: true
+  },
   replayPolicy: {
     mode: "manual",
     sideEffectLevel: "external",
     reason: "Arbitrary shell execution may affect processes, services, or systems outside the current turn."
   },
   async execute(params, ctx) {
-    const host = ctx.host;
+    const host = getRequiredToolHost(ctx, {
+      toolName: "bash",
+      usage: "shell execution"
+    });
     const result = await executeBash(params, host, ctx.cwd, ctx.abort);
     let output = "";
     if (result.stdout) {
@@ -82,7 +88,7 @@ ${result.stderr}`;
 // src/tools/read.ts
 import { z as z2 } from "zod";
 import * as path from "path";
-import { Tool as Tool2 } from "@cuylabs/agent-core";
+import { Tool as Tool2, getRequiredToolHost as getRequiredToolHost2 } from "@cuylabs/agent-core";
 var DEFAULT_READ_LIMIT = 2e3;
 var MAX_LINE_LENGTH = 2e3;
 var MAX_BYTES = 50 * 1024;
@@ -164,12 +170,18 @@ IMPORTANT:
 - Binary files cannot be read
 - Images and PDFs are returned as attachments`,
   parameters: readParameters,
+  hostRequirements: {
+    filesystem: "read"
+  },
   replayPolicy: {
     sideEffectLevel: "none",
     reason: "Read-only file inspection is safe to replay."
   },
   async execute(params, ctx) {
-    const host = ctx.host;
+    const host = getRequiredToolHost2(ctx, {
+      toolName: "read",
+      usage: "filesystem read access"
+    });
     let filepath = params.filePath;
     if (!path.isAbsolute(filepath)) {
       filepath = path.resolve(ctx.cwd, filepath);
@@ -260,7 +272,7 @@ ${suggestions.join("\n")}`
 // src/tools/edit.ts
 import { z as z3 } from "zod";
 import * as path2 from "path";
-import { Tool as Tool3 } from "@cuylabs/agent-core";
+import { Tool as Tool3, getRequiredToolHost as getRequiredToolHost3 } from "@cuylabs/agent-core";
 function normalizeLineEndings(text) {
   return text.replaceAll("\r\n", "\n");
 }
@@ -369,6 +381,9 @@ IMPORTANT:
 - Use replaceAll: true to replace all occurrences
 - For creating new files, use the write tool instead`,
   parameters: editParameters,
+  hostRequirements: {
+    filesystem: "write"
+  },
   replayPolicy: {
     mode: "manual",
     sideEffectLevel: "local",
@@ -387,7 +402,10 @@ IMPORTANT:
     if (!path2.isAbsolute(filepath)) {
       filepath = path2.resolve(ctx.cwd, filepath);
     }
-    const host = ctx.host;
+    const host = getRequiredToolHost3(ctx, {
+      toolName: "edit",
+      usage: "filesystem write access"
+    });
     const title = path2.relative(ctx.cwd, filepath);
     if (params.oldString === "") {
       await host.mkdir(path2.dirname(filepath));
@@ -453,7 +471,7 @@ ${diff}`,
 // src/tools/write.ts
 import { z as z4 } from "zod";
 import * as path3 from "path";
-import { Tool as Tool4 } from "@cuylabs/agent-core";
+import { Tool as Tool4, getRequiredToolHost as getRequiredToolHost4 } from "@cuylabs/agent-core";
 var writeParameters = z4.object({
   filePath: z4.string().describe("The absolute path to the file to write"),
   content: z4.string().describe("The content to write to the file")
@@ -467,6 +485,9 @@ IMPORTANT:
 - Parent directories are created automatically
 - Existing content is completely replaced`,
   parameters: writeParameters,
+  hostRequirements: {
+    filesystem: "write"
+  },
   replayPolicy: {
     mode: "manual",
     sideEffectLevel: "local",
@@ -483,7 +504,10 @@ IMPORTANT:
       filepath = path3.resolve(ctx.cwd, filepath);
     }
     const title = path3.relative(ctx.cwd, filepath);
-    const host = ctx.host;
+    const host = getRequiredToolHost4(ctx, {
+      toolName: "write",
+      usage: "filesystem write access"
+    });
     let exists = false;
     let oldContent = "";
     try {
@@ -523,7 +547,7 @@ Created with ${lines} lines`;
 // src/tools/grep.ts
 import { z as z5 } from "zod";
 import * as path4 from "path";
-import { Tool as Tool5 } from "@cuylabs/agent-core";
+import { Tool as Tool5, getRequiredToolHost as getRequiredToolHost5 } from "@cuylabs/agent-core";
 var MAX_LINE_LENGTH2 = 2e3;
 var MAX_RESULTS = 100;
 function sq(s) {
@@ -600,6 +624,10 @@ IMPORTANT:
 - Results are sorted by modification time (newest first)
 - Maximum ${MAX_RESULTS} results returned`,
   parameters: grepParameters,
+  hostRequirements: {
+    filesystem: "read",
+    shell: true
+  },
   replayPolicy: {
     sideEffectLevel: "none",
     reason: "Content search is read-only and safe to repeat."
@@ -608,7 +636,10 @@ IMPORTANT:
     if (!params.pattern) {
       throw new Error("pattern is required");
     }
-    const host = ctx.host;
+    const host = getRequiredToolHost5(ctx, {
+      toolName: "grep",
+      usage: "filesystem search and shell execution"
+    });
     const result = await executeGrep(params, host, ctx.cwd, ctx.abort);
     if (result.matches.length === 0) {
       return {
@@ -636,7 +667,7 @@ IMPORTANT:
 // src/tools/glob.ts
 import { z as z6 } from "zod";
 import * as path5 from "path";
-import { Tool as Tool6 } from "@cuylabs/agent-core";
+import { Tool as Tool6, getRequiredToolHost as getRequiredToolHost6 } from "@cuylabs/agent-core";
 var MAX_RESULTS2 = 100;
 function sq2(s) {
   return "'" + s.replace(/'/g, "'\\''") + "'";
@@ -709,12 +740,19 @@ IMPORTANT:
 - Results are sorted by modification time (newest first)
 - Maximum ${MAX_RESULTS2} results returned`,
   parameters: globParameters,
+  hostRequirements: {
+    filesystem: "read",
+    shell: true
+  },
   replayPolicy: {
     sideEffectLevel: "none",
     reason: "Filesystem discovery does not mutate state."
   },
   async execute(params, ctx) {
-    const host = ctx.host;
+    const host = getRequiredToolHost6(ctx, {
+      toolName: "glob",
+      usage: "filesystem search"
+    });
     const searchPath = params.path ? path5.isAbsolute(params.path) ? params.path : path5.resolve(ctx.cwd, params.path) : ctx.cwd;
     const { files, truncated } = await findFiles(
       params.pattern,

package/dist/index.d.ts

@@ -1,5 +1,8 @@
-import { AgentConfig, ToolSpec, ApprovalMiddlewareConfig, PromptCacheConfig, SkillConfig, SkillRegistry, SubAgentToolConfig, AgentProfile, SessionManager, FileStorageOptions, Agent } from '@cuylabs/agent-core';
+import { AgentConfig, ToolSpec, ApprovalMiddlewareConfig, PromptCacheConfig, SkillConfig, SkillRegistry, SessionManager, FileStorageOptions, Agent } from '@cuylabs/agent-core';
 export * from '@cuylabs/agent-core';
+export { Agent, ApprovalAction, ApprovalMiddlewareConfig, ApprovalRequest, LLMError, ModelEntry, PluginCommand, PluginRegistry, SkillMetadata, SkillRegistry, StaticSettings, configureResolver, createSkillRegistry, defaultRegistry, discoverPlugins, getDefaultResolver, isDefinedPlugin, loadPluginModule } from '@cuylabs/agent-core';
+import { SubAgentConfig, SubAgentRole } from '@cuylabs/agent-core/subagents';
+export { SubAgentRole, discoverSubAgentRoles } from '@cuylabs/agent-core/subagents';
 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';
 
@@ -17,15 +20,31 @@ interface CodingSessionStorageOptions extends Partial<Omit<FileStorageOptions, "
      */
     appName?: string;
 }
-interface CodingSubAgentOptions extends Omit<SubAgentToolConfig, "profiles"> {
+interface CodingSubAgentOptions extends Omit<SubAgentConfig, "roles"> {
     /**
-     * Specialist profiles exposed through `invoke_agent`.
+     * Specialist roles exposed through `invoke_agent`.
      *
-     * Defaults to `defaultCodingProfiles`.
+     * Defaults to `defaultCodingRoles`.
      */
-    profiles?: AgentProfile[];
+    roles?: SubAgentRole[];
+    /**
+     * Additional markdown agent file paths to load.
+     *
+     * Resolved relative to `cwd`. These are loaded in addition to
+     * the standard discovery directories.
+     */
+    agentPaths?: string[];
+    /**
+     * Disable markdown agent discovery.
+     *
+     * When `true`, only built-in TypeScript roles (and any explicit
+     * `roles` array) are used — no filesystem scanning.
+     *
+     * @default false
+     */
+    disableDiscovery?: boolean;
 }
-interface CodingAgentOptions extends AgentConfig {
+interface CodingAgentOptions extends Omit<AgentConfig, "approval"> {
     /**
      * Coding tools to expose. Defaults to the full coding toolset.
      *
@@ -51,12 +70,14 @@ interface CodingAgentOptions extends AgentConfig {
      */
     skills?: boolean | SkillConfig | SkillRegistry;
     /**
-     * Sub-agent delegation configuration.
+     * Subagent delegation configuration.
      *
      * Defaults to `true`, which enables `invoke_agent` with the default
-     * coding specialist profiles.
+     * coding specialist roles. The concrete backend is selected by the host:
+     * local agents install the in-process backend, while compatible runtime
+     * packages can replace it with their own implementation.
      */
-    subAgents?: boolean | CodingSubAgentOptions;
+    subagents?: boolean | CodingSubAgentOptions;
     /**
      * Explicit session manager. Overrides `sessionStorage` when provided.
      */
@@ -77,7 +98,7 @@ interface CodingAgentSetupResult {
  * 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
+ * persistent sessions, and subagent delegation into a reusable package-level
  * surface. UI-specific concerns stay outside this helper.
  */
 declare function setupCodingAgent(options: CodingAgentOptions): Promise<CodingAgentSetupResult>;
@@ -90,11 +111,11 @@ declare function setupCodingAgent(options: CodingAgentOptions): Promise<CodingAg
 declare function createCodingAgent(options: CodingAgentOptions): Promise<Agent>;
 
 /**
- * Default specialist profiles for coding-focused agents.
+ * Default specialist roles for coding-focused subagents.
  *
- * These are the profiles enabled by `setupCodingAgent()` when
- * `subAgents: true` is used.
+ * These are the roles enabled by `setupCodingAgent()` when
+ * `subagents: true` is used.
  */
-declare const defaultCodingProfiles: AgentProfile[];
+declare const defaultCodingRoles: SubAgentRole[];
 
-export { type CodingAgentOptions, type CodingAgentSetupResult, type CodingSessionStorageOptions, type CodingSubAgentOptions, createCodingAgent, defaultCodingProfiles, setupCodingAgent };
+export { type CodingAgentOptions, type CodingAgentSetupResult, type CodingSessionStorageOptions, type CodingSubAgentOptions, createCodingAgent, defaultCodingRoles, setupCodingAgent };

package/dist/index.js

@@ -18,10 +18,27 @@ import {
   toolset,
   writeParameters,
   writeTool
-} from "./chunk-DXHZSPO6.js";
+} from "./chunk-554MRR24.js";
 
 // src/index.ts
 export * from "@cuylabs/agent-core";
+import {
+  Agent,
+  configureResolver,
+  createSkillRegistry as createSkillRegistry2,
+  defaultRegistry,
+  discoverPlugins,
+  getDefaultResolver,
+  isDefinedPlugin,
+  LLMError,
+  loadPluginModule,
+  PluginRegistry,
+  SkillRegistry as SkillRegistry2,
+  StaticSettings
+} from "@cuylabs/agent-core";
+import {
+  discoverSubAgentRoles as discoverSubAgentRoles2
+} from "@cuylabs/agent-core/subagents";
 import { z } from "zod";
 
 // src/create.ts
@@ -35,36 +52,40 @@ import {
   createAgent,
   createSkillRegistry,
   createSkillTools,
-  createSubAgentTools,
   getProjectSessionsDir,
   promptCacheMiddleware
 } from "@cuylabs/agent-core";
+import {
+  configureSubAgents,
+  discoverSubAgentRoles,
+  installLocalSubAgents
+} from "@cuylabs/agent-core/subagents";
 
-// src/profiles.ts
-import { Presets } from "@cuylabs/agent-core";
-var defaultCodingProfiles = [
+// src/roles.ts
+import { Profiles } from "@cuylabs/agent-core/profiles";
+var defaultCodingRoles = [
   {
     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,
+    profile: Profiles.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,
+    profile: Profiles.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,
+    profile: Profiles.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,
+    profile: Profiles.watch,
     maxSteps: 10
   }
 ];
@@ -97,17 +118,32 @@ async function resolveSkillRegistry(cwd, skills) {
   const config = skills === true || skills === void 0 ? void 0 : skills;
   return await createSkillRegistry(cwd, config);
 }
-function resolveSubAgentOptions(subAgents) {
-  if (subAgents === false) {
+function resolveSubAgentOptions(subagents, cwd) {
+  if (subagents === false) {
     return null;
   }
-  const config = subAgents && subAgents !== true ? subAgents : void 0;
-  const profiles = config?.profiles ?? defaultCodingProfiles;
-  if (profiles.length === 0) {
+  const config = subagents && subagents !== true ? subagents : void 0;
+  let roles;
+  if (config?.roles) {
+    roles = config.roles;
+  } else if (config?.disableDiscovery) {
+    roles = defaultCodingRoles;
+  } else {
+    const discovery = discoverSubAgentRoles({
+      cwd,
+      builtInRoles: defaultCodingRoles,
+      configPaths: config?.agentPaths
+    });
+    roles = discovery.roles;
+    for (const { path: p, error } of discovery.errors) {
+      console.error(`[agents] ${p}: ${error}`);
+    }
+  }
+  if (roles.length === 0) {
     return null;
   }
   return {
-    profiles,
+    roles,
     maxConcurrent: config?.maxConcurrent,
     maxDepth: config?.maxDepth,
     currentDepth: config?.currentDepth,
@@ -145,7 +181,7 @@ async function setupCodingAgent(options) {
     approval = false,
     promptCache = false,
     skills = true,
-    subAgents = true,
+    subagents = true,
     sessionManager,
     sessionStorage = true,
     middleware,
@@ -179,11 +215,10 @@ async function setupCodingAgent(options) {
     ...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);
-    }
+  const subAgentConfig = resolveSubAgentOptions(subagents, cwd);
+  if (subAgentConfig) {
+    configureSubAgents(agent, subAgentConfig);
+    installLocalSubAgents(agent, subAgentConfig);
   }
   return { agent, skillRegistry };
 }
@@ -192,20 +227,33 @@ async function createCodingAgent(options) {
   return agent;
 }
 export {
+  Agent,
+  LLMError,
+  PluginRegistry,
+  SkillRegistry2 as SkillRegistry,
+  StaticSettings,
   ToolsetBuilder,
   bashParameters,
   bashTool,
+  configureResolver,
   createCodingAgent,
-  defaultCodingProfiles,
+  createSkillRegistry2 as createSkillRegistry,
+  defaultCodingRoles,
   defaultCodingTools,
+  defaultRegistry,
+  discoverPlugins,
+  discoverSubAgentRoles2 as discoverSubAgentRoles,
   editParameters,
   editTool,
   executeBash,
   executeGrep,
+  getDefaultResolver,
   globParameters,
   globTool,
   grepParameters,
   grepTool,
+  isDefinedPlugin,
+  loadPluginModule,
   readParameters,
   readTool,
   resolveTools,

package/dist/tools/index.d.ts

@@ -16,12 +16,12 @@ declare const planEntrySchema: z.ZodObject<{
     status: z.ZodEnum<["pending", "in-progress", "done"]>;
 }, "strip", z.ZodTypeAny, {
     id: number;
-    status: "done" | "pending" | "in-progress";
     title: string;
+    status: "pending" | "done" | "in-progress";
 }, {
     id: number;
-    status: "done" | "pending" | "in-progress";
     title: string;
+    status: "pending" | "done" | "in-progress";
 }>;
 declare const planParameters: z.ZodObject<{
     entries: z.ZodArray<z.ZodObject<{
@@ -30,24 +30,24 @@ declare const planParameters: z.ZodObject<{
         status: z.ZodEnum<["pending", "in-progress", "done"]>;
     }, "strip", z.ZodTypeAny, {
         id: number;
-        status: "done" | "pending" | "in-progress";
         title: string;
+        status: "pending" | "done" | "in-progress";
     }, {
         id: number;
-        status: "done" | "pending" | "in-progress";
         title: string;
+        status: "pending" | "done" | "in-progress";
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     entries: {
         id: number;
-        status: "done" | "pending" | "in-progress";
         title: string;
+        status: "pending" | "done" | "in-progress";
     }[];
 }, {
     entries: {
         id: number;
-        status: "done" | "pending" | "in-progress";
         title: string;
+        status: "pending" | "done" | "in-progress";
     }[];
 }>;
 type PlanParams = z.infer<typeof planParameters>;
@@ -59,30 +59,30 @@ declare const planTool: Tool.Info<z.ZodObject<{
         status: z.ZodEnum<["pending", "in-progress", "done"]>;
     }, "strip", z.ZodTypeAny, {
         id: number;
-        status: "done" | "pending" | "in-progress";
         title: string;
+        status: "pending" | "done" | "in-progress";
     }, {
         id: number;
-        status: "done" | "pending" | "in-progress";
         title: string;
+        status: "pending" | "done" | "in-progress";
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     entries: {
         id: number;
-        status: "done" | "pending" | "in-progress";
         title: string;
+        status: "pending" | "done" | "in-progress";
     }[];
 }, {
     entries: {
         id: number;
-        status: "done" | "pending" | "in-progress";
         title: string;
+        status: "pending" | "done" | "in-progress";
     }[];
 }>, {
     entries: {
         id: number;
-        status: "done" | "pending" | "in-progress";
         title: string;
+        status: "pending" | "done" | "in-progress";
     }[];
     done: number;
     active: number;

package/dist/tools/index.js

@@ -20,7 +20,7 @@ import {
   toolset,
   writeParameters,
   writeTool
-} from "../chunk-DXHZSPO6.js";
+} from "../chunk-554MRR24.js";
 export {
   ToolsetBuilder,
   bashParameters,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-code",
-  "version": "0.8.0",
+  "version": "0.10.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.8.0"
+    "@cuylabs/agent-core": "^0.10.0"
   },
   "peerDependencies": {
     "@ai-sdk/anthropic": "^3.0.0",