@crouton-kit/crouter 0.3.8 → 0.3.11

package/dist/core/subagents.js

@@ -0,0 +1,163 @@
+// Subagent discovery + resolution.
+//
+// Subagents are markdown files with YAML frontmatter, modeled on the pi
+// subagent extension but surfaced through the crtr `agent` CLI. Each file
+// declares a name/description (+ optional tools/model) in frontmatter; its
+// markdown body becomes the spawned agent's appended system prompt.
+//
+// Layout mirrors skills, one level shallower (flat files, not nested dirs):
+//   <scope-root>/agents/<name>.md        — scope-root agents (user/project)
+//   <plugin-root>/agents/<name>.md       — plugin-provided agents
+//
+// Resolution precedence matches skills: project before user before builtin;
+// scope-root agents before plugin agents within a scope.
+import { join, basename } from 'node:path';
+import { readdirSync } from 'node:fs';
+import { AGENTS_DIR, SCOPE_SKILL_PLUGIN } from '../types.js';
+import { listAllPlugins, listInstalledPlugins } from './resolver.js';
+import { parseFrontmatterGeneric } from './frontmatter.js';
+import { pathExists, readText } from './fs-utils.js';
+import { projectScopeRoot, scopeRoot } from './scope.js';
+import { ambiguous, notFound } from './errors.js';
+/** `<scope-root>/agents` for a given scope, or null when the scope has no root. */
+export function scopeAgentsDir(scope) {
+    const root = scopeRoot(scope);
+    return root ? join(root, AGENTS_DIR) : null;
+}
+function coerceTools(value) {
+    if (Array.isArray(value)) {
+        const arr = value.map((v) => String(v).trim()).filter(Boolean);
+        return arr.length > 0 ? arr : undefined;
+    }
+    if (typeof value === 'string') {
+        const arr = value
+            .split(',')
+            .map((t) => t.trim())
+            .filter(Boolean);
+        return arr.length > 0 ? arr : undefined;
+    }
+    return undefined;
+}
+function parseSubagentFile(filePath, scope, plugin) {
+    let source;
+    try {
+        source = readText(filePath);
+    }
+    catch {
+        return null;
+    }
+    const { data, body } = parseFrontmatterGeneric(source);
+    if (data === null)
+        return null;
+    // Name defaults to the filename stem when frontmatter omits it. A description
+    // is required for the agent to be useful in listings; skip files without one.
+    const fileStem = basename(filePath).replace(/\.md$/i, '');
+    const name = typeof data.name === 'string' && data.name.trim() !== ''
+        ? data.name.trim()
+        : fileStem;
+    if (typeof data.description !== 'string' || data.description.trim() === '') {
+        return null;
+    }
+    const fm = {
+        name,
+        description: data.description.trim(),
+        tools: coerceTools(data.tools),
+        model: typeof data.model === 'string' && data.model.trim() !== '' ? data.model.trim() : undefined,
+    };
+    return {
+        name,
+        plugin,
+        scope,
+        path: filePath,
+        frontmatter: fm,
+        systemPrompt: body,
+    };
+}
+function listAgentsInDir(dir, scope, plugin) {
+    if (!pathExists(dir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const e of entries) {
+        if (!e.name.toLowerCase().endsWith('.md'))
+            continue;
+        if (!e.isFile() && !e.isSymbolicLink())
+            continue;
+        const parsed = parseSubagentFile(join(dir, e.name), scope, plugin);
+        if (parsed !== null)
+            out.push(parsed);
+    }
+    return out;
+}
+/** Scope-root agents under `<scope-root>/agents/*.md`. */
+export function listScopeRootSubagents(scope) {
+    if (scope === 'builtin')
+        return [];
+    const dir = scopeAgentsDir(scope);
+    if (!dir)
+        return [];
+    return listAgentsInDir(dir, scope, SCOPE_SKILL_PLUGIN);
+}
+/** All subagents: scope-root agents (project, user) plus enabled plugins. */
+export function listSubagents(scopeFilter) {
+    const scopes = scopeFilter
+        ? [scopeFilter]
+        : [projectScopeRoot() ? 'project' : null, 'user'].filter(Boolean);
+    const fromScopeRoots = scopes.flatMap((s) => listScopeRootSubagents(s));
+    const plugins = scopeFilter ? listInstalledPlugins(scopeFilter) : listAllPlugins();
+    const fromPlugins = plugins
+        .filter((p) => p.enabled)
+        .flatMap((p) => listAgentsInDir(join(p.root, AGENTS_DIR), p.scope, p.name));
+    return [...fromScopeRoots, ...fromPlugins].sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Canonical, unambiguous identifier: `<plugin>/<name>`, or bare `<name>` for
+ *  scope-root agents. */
+export function subagentId(a) {
+    return a.plugin === SCOPE_SKILL_PLUGIN ? a.name : `${a.plugin}/${a.name}`;
+}
+/** Resolve a subagent by name. Accepts a bare `<name>` or a `<plugin>/<name>`
+ *  qualifier. Project precedes user precedes builtin; scope-root precedes
+ *  plugin. Throws notFound / ambiguous as the skill resolver does. */
+export function resolveSubagent(rawName, opts = {}) {
+    const slash = rawName.indexOf('/');
+    const pluginQualifier = opts.plugin ?? (slash !== -1 ? rawName.slice(0, slash) : undefined);
+    const name = slash !== -1 && opts.plugin === undefined ? rawName.slice(slash + 1) : rawName;
+    const all = listSubagents(opts.scope);
+    let matches = all.filter((a) => a.name === name);
+    if (pluginQualifier !== undefined) {
+        matches = matches.filter((a) => a.plugin === pluginQualifier ||
+            (pluginQualifier === SCOPE_SKILL_PLUGIN && a.plugin === SCOPE_SKILL_PLUGIN));
+    }
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length === 0) {
+        const known = all.map(subagentId).slice(0, 8).join(', ');
+        throw notFound(`subagent not found: ${rawName}`, {
+            subagent: name,
+            plugin: pluginQualifier,
+            next: known !== ''
+                ? `Known subagents: ${known}. Run \`crtr agent subagent list\` for the full set.`
+                : 'No subagents defined. Run `crtr agent subagent author -h` to scaffold one.',
+        });
+    }
+    // Multiple matches: prefer the highest-precedence scope/source deterministically.
+    const score = (a) => {
+        const scopeScore = a.scope === 'project' ? 0 : a.scope === 'user' ? 1 : 2;
+        const sourceScore = a.plugin === SCOPE_SKILL_PLUGIN ? 0 : 1;
+        return scopeScore * 2 + sourceScore;
+    };
+    const sorted = [...matches].sort((a, b) => score(a) - score(b));
+    if (score(sorted[0]) !== score(sorted[1]))
+        return sorted[0];
+    throw ambiguous(`ambiguous subagent: ${rawName}`, {
+        subagent: name,
+        candidates: matches.map((m) => ({ id: subagentId(m), scope: m.scope, path: m.path })),
+        next: 'Qualify with `<plugin>/<name>` or pass --scope to disambiguate.',
+    });
+}

package/dist/prompts/agent.d.ts

@@ -2,7 +2,7 @@
  * First user message for a spec → plan handoff.
  *
  * Thin prompt: the worker discovers the full planning workflow by running
- * `crtr agent plan new -h`, then saves the plan via `crtr agent plan new`. This
+ * `crtr mode plan new -h`, then saves the plan via `crtr mode plan new`. This
  * avoids embedding the planPrompt() blob here and keeps the prompt in sync
  * with the live CLI without any coupling.
  */
@@ -16,3 +16,12 @@ export declare function implementHandoffPrompt(planPath: string, jobId: string):
  * The reviewer submits via `crtr job submit` rather than `crtr agent submit`.
  */
 export declare function reviewerHandoffPrompt(artifactPath: string, artifactKind: 'plan' | 'spec', specPath: string | null, jobId: string): string;
+/**
+ * First user message for a general `agent new` worker.
+ *
+ * The worker runs as an interactive agent in a tmux pane (not print mode), so
+ * its stdout is NOT captured as the result — it must deliver its answer via
+ * `crtr job submit`, exactly like the mode-handoff workers. The original task
+ * is sent verbatim; the submit contract is appended after a separator.
+ */
+export declare function agentNewPrompt(task: string, jobId: string): string;

package/dist/prompts/agent.js

@@ -3,7 +3,7 @@ import { planReviewPrompt, specReviewPrompt } from './review.js';
  * First user message for a spec → plan handoff.
  *
  * Thin prompt: the worker discovers the full planning workflow by running
- * `crtr agent plan new -h`, then saves the plan via `crtr agent plan new`. This
+ * `crtr mode plan new -h`, then saves the plan via `crtr mode plan new`. This
  * avoids embedding the planPrompt() blob here and keeps the prompt in sync
  * with the live CLI without any coupling.
  */
@@ -12,9 +12,9 @@ export function planHandoffPrompt(specPath, jobId) {
 
 **Spec:** ${specPath}
 
-1. Run \`crtr agent plan new -h\` to load the planning workflow and output schema.
+1. Run \`crtr mode plan new -h\` to load the planning workflow and output schema.
 2. Read the spec end-to-end.
-3. Follow the workflow from step 1 and save the plan by passing the plan markdown to \`crtr agent plan new\` on stdin.
+3. Follow the workflow from step 1 and save the plan by passing the plan markdown to \`crtr mode plan new\` on stdin.
 4. When done, submit a short markdown report on stdin:
 
 \`\`\`bash
@@ -151,3 +151,34 @@ export function reviewerHandoffPrompt(artifactPath, artifactKind, specPath, jobI
 
 After calling \`crtr job submit\`, your turn ends and the pane closes itself. Do NOT chat or summarize after submission.`;
 }
+/**
+ * First user message for a general `agent new` worker.
+ *
+ * The worker runs as an interactive agent in a tmux pane (not print mode), so
+ * its stdout is NOT captured as the result — it must deliver its answer via
+ * `crtr job submit`, exactly like the mode-handoff workers. The original task
+ * is sent verbatim; the submit contract is appended after a separator.
+ */
+export function agentNewPrompt(task, jobId) {
+    return `${task}
+
+---
+
+When you have finished the task above, deliver your final answer by piping your
+full markdown result to \`crtr job submit\` — this is how the result is returned
+to whoever spawned you:
+
+\`\`\`bash
+crtr job submit ${jobId} <<'MD'
+<your complete answer / findings>
+MD
+\`\`\`
+
+If you cannot complete the task, submit a failure with a reason instead:
+
+\`\`\`bash
+crtr job submit ${jobId} --status failed --reason "<why>"
+\`\`\`
+
+Do your work first; submit exactly once when done. After submitting, your turn ends.`;
+}

package/dist/types.d.ts

@@ -90,6 +90,26 @@ export interface Skill {
     enabled: boolean;
     disabledIn?: Scope;
 }
+export interface SubagentFrontmatter {
+    name: string;
+    description?: string;
+    /** Tool allow-list (pi tool names). Passed through to pi via `--tools`. */
+    tools?: string[];
+    /** Model pattern/id passed to the agent CLI via `--model`. */
+    model?: string;
+}
+export interface Subagent {
+    name: string;
+    /** Plugin the subagent belongs to, or SCOPE_SKILL_PLUGIN ('_') for a
+     *  scope-root agent stored at `<scope-root>/agents/<name>.md`. */
+    plugin: string;
+    scope: Scope;
+    /** Absolute path to the agent's .md file. */
+    path: string;
+    frontmatter: SubagentFrontmatter;
+    /** Markdown body — used as the spawned agent's appended system prompt. */
+    systemPrompt: string;
+}
 export interface InstalledPlugin {
     name: string;
     scope: Scope;
@@ -117,6 +137,7 @@ export declare const CONFIG_FILE = "config.json";
 export declare const STATE_FILE = "state.json";
 export declare const SKILL_ENTRY_FILE = "SKILL.md";
 export declare const SKILLS_DIR = "skills";
+export declare const AGENTS_DIR = "agents";
 export declare const SCOPE_SKILL_PLUGIN = "_";
 export declare const DEFAULT_MAX_PANES_PER_WINDOW = 3;
 export declare function defaultScopeConfig(): ScopeConfig;

package/dist/types.js

@@ -20,6 +20,9 @@ export const CONFIG_FILE = 'config.json';
 export const STATE_FILE = 'state.json';
 export const SKILL_ENTRY_FILE = 'SKILL.md';
 export const SKILLS_DIR = 'skills';
+// Subagent definitions live as flat `<name>.md` files under `<root>/agents/`,
+// for both scope roots and plugins. Mirrors SKILLS_DIR.
+export const AGENTS_DIR = 'agents';
 // Sentinel plugin name for skills that live at a scope root (no plugin wrapper).
 // Stored as `<scope-root>/skills/<name>/SKILL.md`. Shown in listings without the
 // `_/` prefix.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.8",
+  "version": "0.3.11",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -35,7 +35,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@crouton-kit/humanloop": "^0.3.11",
+    "@crouton-kit/humanloop": "^0.3.12",
     "commander": "^13.0.0"
   },
   "devDependencies": {