chainlesschain 0.45.81 → 0.47.0

package/src/lib/skill-loader.js

@@ -109,6 +109,71 @@ export function parseSkillMd(content) {
   return { data, body };
 }
 
+/**
+ * Substitute $ARGUMENTS / $1 / $2 / ... placeholders in a skill body.
+ * Inspired by open-agents substituteArguments.
+ *
+ * Rules:
+ *  - $ARGUMENTS → full args string (joined by space if array)
+ *  - $1, $2, ... → positional args (shell-like; split on whitespace if string)
+ *  - Escape $ via $$ → literal $
+ *  - Unmatched placeholders are left as-is (non-destructive)
+ *
+ * @param {string} body - Skill body text
+ * @param {string|string[]} args - Args as raw string or pre-split array
+ * @returns {string}
+ */
+export function substituteArguments(body, args) {
+  if (typeof body !== "string" || body.length === 0) return body || "";
+  let full = "";
+  let positional = [];
+  if (Array.isArray(args)) {
+    positional = args.map((a) => String(a));
+    full = positional.join(" ");
+  } else if (typeof args === "string") {
+    full = args;
+    positional = args.trim() === "" ? [] : args.trim().split(/\s+/);
+  }
+  // Protect literal $$
+  const MARKER = "\u0000DOLLAR\u0000";
+  let out = body.replace(/\$\$/g, MARKER);
+  out = out.replace(/\$ARGUMENTS\b/g, full);
+  out = out.replace(/\$(\d+)/g, (match, idx) => {
+    const i = parseInt(idx, 10) - 1;
+    if (i < 0 || i >= positional.length) return match;
+    return positional[i];
+  });
+  return out.replace(new RegExp(MARKER, "g"), "$");
+}
+
+/**
+ * Prepend `Skill directory: <abs>` line to body so the LLM can resolve
+ * relative paths declared inside the SKILL.md.
+ * Inspired by open-agents injectSkillDirectory.
+ *
+ * @param {string} body
+ * @param {string} skillDir - Absolute path to the skill directory
+ * @returns {string}
+ */
+export function injectSkillDirectory(body, skillDir) {
+  if (!skillDir) return body || "";
+  const header = `Skill directory: ${skillDir}\n\n`;
+  return header + (body || "");
+}
+
+/**
+ * Prepare a skill body for execution: substitute $ARGUMENTS / $N placeholders
+ * and prepend the skill directory header.
+ *
+ * @param {object} skill - Skill metadata (must have .body and .skillDir)
+ * @param {string|string[]} args - Runtime args
+ * @returns {string}
+ */
+export function prepareSkillBody(skill, args) {
+  const withArgs = substituteArguments(skill?.body || "", args);
+  return injectSkillDirectory(withArgs, skill?.skillDir);
+}
+
 /**
  * Multi-layer CLI skill loader
  */

package/src/lib/sub-agent-context.js

@@ -61,7 +61,14 @@ export class SubAgentContext {
     this.parentId = options.parentId || null;
     this.role = options.role || "general";
     this.task = options.task || "";
-    this.maxIterations = options.maxIterations || DEFAULT_MAX_ITERATIONS;
+    // Declarative profile (Phase 3) — explorer/executor/design, etc.
+    // Provides systemPrompt + maxIterations + modelHint defaults that
+    // explicit options can still override.
+    this._profile = options.profile || null;
+    this.maxIterations =
+      options.maxIterations ||
+      this._profile?.maxIterations ||
+      DEFAULT_MAX_ITERATIONS;
     this.iterationBudget = options.iterationBudget || null; // shared budget from parent
     this.tokenBudget = options.tokenBudget || null;
     this.inheritedContext = options.inheritedContext || null;
@@ -107,8 +114,30 @@ export class SubAgentContext {
     // Optional abort signal for cancellation
     this._signal = options.signal || null;
 
+    // Optional MCP / external tool plumbing. These are forwarded into the
+    // agentLoop options so MCP-backed tools (e.g. from a cowork template's
+    // `mcpServers`) appear in the LLM's tool list and route through
+    // `mcpClient.callTool()` in agent-core's default-case dispatch.
+    this._extraToolDefinitions = Array.isArray(options.extraToolDefinitions)
+      ? options.extraToolDefinitions
+      : [];
+    this._externalToolDescriptors =
+      options.externalToolDescriptors &&
+      typeof options.externalToolDescriptors === "object"
+        ? options.externalToolDescriptors
+        : {};
+    this._externalToolExecutors =
+      options.externalToolExecutors &&
+      typeof options.externalToolExecutors === "object"
+        ? options.externalToolExecutors
+        : {};
+    this._mcpClient = options.mcpClient || null;
+
     // Build isolated system prompt
     const basePrompt = buildSystemPrompt(this.cwd);
+    const profilePrompt = this._profile?.systemPrompt
+      ? `\n\n## Profile: ${this._profile.name}\n${this._profile.systemPrompt}`
+      : "";
     const rolePrompt = `\n\n## Sub-Agent Role: ${this.role}\nYou are a focused sub-agent with the role "${this.role}". Your task is:\n${this.task}\n\nStay focused on this specific task. Be concise and return results directly.`;
     const contextSection = this.inheritedContext
       ? `\n\n## Parent Context\n${this.inheritedContext}`
@@ -116,7 +145,7 @@ export class SubAgentContext {
 
     this.messages.push({
       role: "system",
-      content: basePrompt + rolePrompt + contextSection,
+      content: basePrompt + profilePrompt + rolePrompt + contextSection,
     });
   }
 
@@ -226,6 +255,29 @@ export class SubAgentContext {
       options.iterationBudget = this.iterationBudget;
     }
 
+    // Forward MCP / external tool plumbing into the agent loop
+    if (this._extraToolDefinitions.length > 0) {
+      options.extraToolDefinitions = [
+        ...(options.extraToolDefinitions || []),
+        ...this._extraToolDefinitions,
+      ];
+    }
+    if (Object.keys(this._externalToolDescriptors).length > 0) {
+      options.externalToolDescriptors = {
+        ...(options.externalToolDescriptors || {}),
+        ...this._externalToolDescriptors,
+      };
+    }
+    if (Object.keys(this._externalToolExecutors).length > 0) {
+      options.externalToolExecutors = {
+        ...(options.externalToolExecutors || {}),
+        ...this._externalToolExecutors,
+      };
+    }
+    if (this._mcpClient) {
+      options.mcpClient = this._mcpClient;
+    }
+
     try {
       // Use a separate messages array for the agent loop
       // The agentLoop will append to this.messages directly

package/src/lib/sub-agent-profiles.js

@@ -0,0 +1,164 @@
+/**
+ * Sub-Agent Profiles — declarative registry of subagent roles.
+ *
+ * Inspired by open-agents SUBAGENT_REGISTRY. Separate from the runtime
+ * `sub-agent-registry.js` which tracks *instances*; this module describes
+ * the *kinds* (explorer/executor/design) a parent agent may delegate to.
+ *
+ * Each profile defines:
+ *  - name           stable identifier used by spawn_sub_agent
+ *  - shortDescription  one-line hook for the parent prompt
+ *  - systemPrompt      prepended to sub-agent messages[0]
+ *  - toolAllowlist     array of tool names the sub-agent may call
+ *                      (null = inherit all)
+ *  - maxIterations     optional per-profile iteration cap
+ *  - modelHint         optional { category } hint for llm-manager
+ */
+
+const READONLY_TOOLS = Object.freeze([
+  "read_file",
+  "list_dir",
+  "search_files",
+  "search_sessions",
+  "web_fetch",
+  "list_skills",
+]);
+
+const FULL_TOOLS = Object.freeze([
+  "read_file",
+  "write_file",
+  "edit_file",
+  "edit_file_hashed",
+  "list_dir",
+  "search_files",
+  "search_sessions",
+  "run_shell",
+  "git",
+  "run_code",
+  "run_skill",
+  "list_skills",
+  "web_fetch",
+  "todo_write",
+  "ask_user_question",
+]);
+
+const DESIGN_TOOLS = Object.freeze([
+  "read_file",
+  "write_file",
+  "edit_file",
+  "edit_file_hashed",
+  "list_dir",
+  "search_files",
+  "web_fetch",
+  "run_skill",
+  "list_skills",
+  "todo_write",
+]);
+
+const _builtinProfiles = {
+  explorer: {
+    name: "explorer",
+    shortDescription:
+      "Read-only researcher. Investigates code, searches files/sessions, fetches web docs. Cannot write or execute.",
+    systemPrompt:
+      "You are a read-only research sub-agent. Your job is to gather facts and report back concisely. You MUST NOT write files or execute commands. When done, return a structured summary of findings.",
+    toolAllowlist: READONLY_TOOLS,
+    maxIterations: 20,
+    modelHint: { category: "quick" },
+  },
+  executor: {
+    name: "executor",
+    shortDescription:
+      "Full-permission implementer. Writes code, runs tests, executes shell/git. Use for end-to-end task completion.",
+    systemPrompt:
+      "You are a full-permission execution sub-agent. Implement the task to completion. Prefer edit_file_hashed over edit_file. Always verify with tests/build when relevant. Return a summary plus list of files changed.",
+    toolAllowlist: FULL_TOOLS,
+    maxIterations: 40,
+    modelHint: { category: "deep" },
+  },
+  design: {
+    name: "design",
+    shortDescription:
+      "Frontend/UI specialist. Produces polished Vue/React/HTML with distinctive aesthetics. No shell/git access.",
+    systemPrompt:
+      "You are a frontend design sub-agent. Produce high-quality, production-grade UI code. Avoid generic AI aesthetics. Prefer semantic HTML, accessible components, and thoughtful typography. You may read/write files and fetch references from the web, but cannot run shell or git.",
+    toolAllowlist: DESIGN_TOOLS,
+    maxIterations: 30,
+    modelHint: { category: "creative" },
+  },
+};
+
+const _registry = new Map(Object.entries(_builtinProfiles));
+
+export function getSubAgentProfile(name) {
+  if (!name) return null;
+  const entry = _registry.get(name);
+  if (!entry) return null;
+  return {
+    ...entry,
+    toolAllowlist: Array.isArray(entry.toolAllowlist)
+      ? [...entry.toolAllowlist]
+      : null,
+  };
+}
+
+export function listSubAgentProfiles() {
+  return Array.from(_registry.values()).map((p) => ({
+    ...p,
+    toolAllowlist: Array.isArray(p.toolAllowlist) ? [...p.toolAllowlist] : null,
+  }));
+}
+
+/**
+ * Register a custom profile (or override a built-in).
+ * Returns true on success, false on invalid input.
+ */
+export function registerSubAgentProfile(profile) {
+  if (!profile || typeof profile.name !== "string" || !profile.name) {
+    return false;
+  }
+  if (typeof profile.shortDescription !== "string") return false;
+  if (typeof profile.systemPrompt !== "string") return false;
+  const toolAllowlist = Array.isArray(profile.toolAllowlist)
+    ? [...profile.toolAllowlist]
+    : null;
+  _registry.set(profile.name, {
+    name: profile.name,
+    shortDescription: profile.shortDescription,
+    systemPrompt: profile.systemPrompt,
+    toolAllowlist,
+    maxIterations:
+      typeof profile.maxIterations === "number" ? profile.maxIterations : 20,
+    modelHint: profile.modelHint || null,
+  });
+  return true;
+}
+
+export function unregisterSubAgentProfile(name) {
+  return _registry.delete(name);
+}
+
+export function resetToBuiltins() {
+  _registry.clear();
+  for (const [k, v] of Object.entries(_builtinProfiles)) {
+    _registry.set(k, v);
+  }
+}
+
+/**
+ * Build a one-section system-prompt snippet listing available subagents.
+ * Inspired by open-agents buildSubagentSummaryLines.
+ *
+ * @returns {string}
+ */
+export function buildSubagentSummaryLines() {
+  const profiles = listSubAgentProfiles();
+  if (profiles.length === 0) return "";
+  const lines = ["## Available sub-agents (via spawn_sub_agent)"];
+  for (const p of profiles) {
+    lines.push(`- **${p.name}**: ${p.shortDescription}`);
+  }
+  return lines.join("\n");
+}
+
+export const _deps = { _registry, _builtinProfiles };

package/src/lib/todo-manager.js

@@ -0,0 +1,108 @@
+/**
+ * Session TODO Manager
+ *
+ * In-memory per-session TODO list. One instance per sessionId.
+ * Inspired by open-agents todo_write tool.
+ *
+ * Contract:
+ *  - Exactly one item may be in_progress at a time (validator enforces)
+ *  - writeTodos replaces the full list (idempotent updates)
+ *  - getTodos returns a deep-cloned array
+ */
+
+const VALID_STATUSES = Object.freeze([
+  "pending",
+  "in_progress",
+  "completed",
+  "cancelled",
+]);
+
+const _stores = new Map();
+
+export function getTodoStore(sessionId) {
+  const key = sessionId || "__default__";
+  if (!_stores.has(key)) {
+    _stores.set(key, { todos: [] });
+  }
+  return _stores.get(key);
+}
+
+export function validateTodos(todos) {
+  if (!Array.isArray(todos)) {
+    return { valid: false, error: "todos must be an array" };
+  }
+  const ids = new Set();
+  let inProgressCount = 0;
+  for (const todo of todos) {
+    if (!todo || typeof todo !== "object") {
+      return { valid: false, error: "each todo must be an object" };
+    }
+    if (typeof todo.id !== "string" || !todo.id) {
+      return { valid: false, error: "todo.id must be a non-empty string" };
+    }
+    if (ids.has(todo.id)) {
+      return { valid: false, error: `duplicate todo id: ${todo.id}` };
+    }
+    ids.add(todo.id);
+    if (typeof todo.content !== "string" || !todo.content) {
+      return { valid: false, error: `todo.content required for id=${todo.id}` };
+    }
+    if (!VALID_STATUSES.includes(todo.status)) {
+      return {
+        valid: false,
+        error: `todo.status must be one of ${VALID_STATUSES.join("|")} (id=${todo.id})`,
+      };
+    }
+    if (todo.status === "in_progress") inProgressCount += 1;
+  }
+  if (inProgressCount > 1) {
+    return {
+      valid: false,
+      error: "only one todo may be in_progress at a time",
+    };
+  }
+  return { valid: true };
+}
+
+export function writeTodos(sessionId, todos) {
+  const check = validateTodos(todos);
+  if (!check.valid) {
+    return { success: false, error: check.error };
+  }
+  const store = getTodoStore(sessionId);
+  store.todos = todos.map((t) => ({
+    id: t.id,
+    content: t.content,
+    status: t.status,
+  }));
+  return {
+    success: true,
+    count: store.todos.length,
+    summary: summarizeTodos(store.todos),
+  };
+}
+
+export function getTodos(sessionId) {
+  const store = getTodoStore(sessionId);
+  return store.todos.map((t) => ({ ...t }));
+}
+
+export function clearTodos(sessionId) {
+  const store = getTodoStore(sessionId);
+  store.todos = [];
+  return { success: true };
+}
+
+export function summarizeTodos(todos) {
+  const counts = { pending: 0, in_progress: 0, completed: 0, cancelled: 0 };
+  for (const t of todos || []) {
+    if (counts[t.status] !== undefined) counts[t.status] += 1;
+  }
+  return counts;
+}
+
+export function resetAllStores() {
+  _stores.clear();
+}
+
+export const _deps = { _stores };

package/src/lib/turn-context.js

@@ -0,0 +1,95 @@
+/**
+ * Turn-scoped context builder — inspired by open-agents' prepareCall.
+ *
+ * Produces a short system-prompt supplement that is re-computed before each
+ * LLM call in the agent loop. Gives the model fresh runtime signals (cwd,
+ * git HEAD/branch/dirty, active skills, turn counter) without polluting the
+ * persistent message history.
+ *
+ * Callers: agent-core.agentLoop's pre-call hook, via options.prepareCall.
+ *
+ * @module turn-context
+ */
+
+import { execSync } from "child_process";
+import path from "path";
+
+const _deps = { execSync };
+
+/**
+ * Run a git command with stdio pipe and return stdout or null.
+ * @param {string} cmd
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+function _git(cmd, cwd) {
+  try {
+    return _deps
+      .execSync(`git ${cmd}`, {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 1500,
+      })
+      .trim();
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Build a compact turn-scoped context block.
+ *
+ * @param {object} input
+ * @param {number} [input.iteration] - 1-based iteration counter for this turn.
+ * @param {string} [input.cwd] - Working directory (defaults to process.cwd()).
+ * @param {string|null} [input.sessionId] - Agent session id.
+ * @param {string[]} [input.activeSkills] - Names of skills currently active.
+ * @returns {string} Markdown-formatted supplement, or empty string if nothing useful.
+ */
+export function buildTurnContext({
+  iteration = 1,
+  cwd = process.cwd(),
+  sessionId = null,
+  activeSkills = [],
+} = {}) {
+  const lines = [];
+  lines.push(`## Turn context (iteration ${iteration})`);
+  lines.push(`- cwd: ${path.resolve(cwd)}`);
+
+  const branch = _git("rev-parse --abbrev-ref HEAD", cwd);
+  if (branch) {
+    const head = _git("rev-parse --short HEAD", cwd);
+    const status = _git("status --porcelain", cwd);
+    const dirty = status && status.length > 0;
+    const fileCount = dirty ? status.split("\n").filter(Boolean).length : 0;
+    lines.push(
+      `- git: ${branch}@${head || "?"}${dirty ? ` (${fileCount} uncommitted)` : " (clean)"}`,
+    );
+  }
+
+  if (sessionId) {
+    lines.push(`- session: ${sessionId}`);
+  }
+
+  if (Array.isArray(activeSkills) && activeSkills.length > 0) {
+    lines.push(`- active skills: ${activeSkills.join(", ")}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Default prepareCall implementation — builds a turn-context supplement and
+ * returns it as a structured payload. agent-core wraps this into a transient
+ * system message for the next llmCall without mutating persistent history.
+ *
+ * @param {object} ctx - Supplied by agent-core at call site.
+ * @returns {{ systemSuffix: string } | null}
+ */
+export function defaultPrepareCall(ctx) {
+  const supplement = buildTurnContext(ctx);
+  return supplement ? { systemSuffix: supplement } : null;
+}
+
+export { _deps };