@crouton-kit/crouter 0.3.3 → 0.3.11

package/dist/core/resolver.js

@@ -5,6 +5,7 @@ import { listDirs, pathExists, readText, walkFiles, } from './fs-utils.js';
 import { readMarketplaceManifest, readPluginManifest } from './manifest.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { ambiguous, notFound, usage } from './errors.js';
+import { InputError } from './io.js';
 import { builtinSkillsRoot, marketplacesDir, pluginsDir, projectScopeRoot, scopeSkillsDir, userScopeRoot, } from './scope.js';
 function getBuiltinPlugin() {
     const root = builtinSkillsRoot();
@@ -202,33 +203,99 @@ export function resolveSkill(rawName, opts = {}) {
     if (parsed.scope && opts.scope && parsed.scope !== opts.scope) {
         throw usage(`scope conflict: identifier "${rawName}" uses scope "${parsed.scope}" but --scope is "${opts.scope}"`);
     }
-    if (parsed.plugin && opts.pluginFilter && parsed.plugin !== opts.pluginFilter) {
-        throw usage(`plugin conflict: identifier "${rawName}" uses plugin "${parsed.plugin}" but --plugin is "${opts.pluginFilter}"`);
-    }
     const effectiveScope = opts.scope ?? parsed.scope;
-    const effectivePluginFilter = opts.pluginFilter ?? parsed.plugin;
-    const direct = findSkillMatches(parsed.name, parsed.plugin, effectiveScope, effectivePluginFilter);
-    if (direct.length > 0)
-        return pickMatch(direct, parsed.name, parsed.plugin);
-    // Fallback: bare `plugin/name` (no colon) — try splitting on first `/`.
-    // Disambiguates "claude-authoring/rules" (which the search/list display also emits as
-    // "user:claude-authoring/rules") from a nested scope-root skill of the same shape.
-    if (!parsed.plugin && parsed.name.includes('/')) {
-        const slashIdx = parsed.name.indexOf('/');
-        const maybePlugin = parsed.name.slice(0, slashIdx);
-        const rest = parsed.name.slice(slashIdx + 1);
-        if (effectivePluginFilter === undefined || effectivePluginFilter === maybePlugin) {
-            const fallback = findSkillMatches(rest, maybePlugin, effectiveScope, maybePlugin);
-            if (fallback.length > 0)
-                return pickMatch(fallback, rest, maybePlugin);
+    // Lookup-based disambiguation: if segments[0] matches an installed plugin, treat it as plugin.
+    // Otherwise the entire segments array is the skill path under the scope-direct plugin.
+    let pluginQualifier;
+    let skillName;
+    if (parsed.segments.length === 0) {
+        throw usage(`skill name required`);
+    }
+    if (opts.pluginFilter !== undefined) {
+        // Explicit plugin filter overrides disambiguation.
+        pluginQualifier = opts.pluginFilter;
+        skillName = parsed.segments.join('/');
+    }
+    else if (parsed.segments.length > 1) {
+        const maybePlugin = parsed.segments[0];
+        const pluginMatch = findPluginByName(maybePlugin, effectiveScope) ??
+            (effectiveScope === undefined ? null : findPluginByName(maybePlugin));
+        if (pluginMatch !== null) {
+            pluginQualifier = maybePlugin;
+            skillName = parsed.segments.slice(1).join('/');
         }
+        else {
+            pluginQualifier = undefined;
+            skillName = parsed.segments.join('/');
+        }
+    }
+    else {
+        pluginQualifier = undefined;
+        skillName = parsed.segments[0];
     }
-    throw notFound(formatNotFoundMessage(rawName, parsed), {
-        skill: parsed.name,
-        plugin: parsed.plugin,
+    if (pluginQualifier && opts.pluginFilter && pluginQualifier !== opts.pluginFilter) {
+        throw usage(`plugin conflict: identifier "${rawName}" uses plugin "${pluginQualifier}" but --plugin is "${opts.pluginFilter}"`);
+    }
+    const effectivePluginFilter = opts.pluginFilter ?? pluginQualifier;
+    const direct = findSkillMatches(skillName, pluginQualifier, effectiveScope, effectivePluginFilter);
+    if (direct.length > 0)
+        return pickMatch(direct, skillName, pluginQualifier);
+    // Leaf-name fallback: the caller supplied only the final path segment
+    // (e.g. "cli-design" for "ai/interface/cli-design"). A direct path lookup
+    // missed because the skill lives under a nested path. Match by last segment.
+    const byLeaf = findSkillsByLeaf(skillName, pluginQualifier, effectiveScope, effectivePluginFilter);
+    if (byLeaf.length === 1)
+        return byLeaf[0];
+    if (byLeaf.length > 1) {
+        throw ambiguous(formatLeafAmbiguousMessage(skillName, byLeaf), {
+            skill: skillName,
+            candidates: byLeaf.map((m) => ({
+                id: formatSkillId(m),
+                plugin: m.plugin,
+                scope: m.scope,
+                path: m.path,
+            })),
+            next: 'Multiple skills share this leaf name. Re-run with one of the full paths in candidates.',
+        });
+    }
+    throw notFound(formatNotFoundMessage(rawName, skillName, pluginQualifier), {
+        skill: skillName,
+        plugin: pluginQualifier,
         scope: parsed.scope,
     });
 }
+/** Canonical, unambiguous identifier for a skill. Scope-root skills are
+ *  qualified by scope; plugin skills by plugin name. */
+function formatSkillId(s) {
+    return s.plugin === SCOPE_SKILL_PLUGIN ? `${s.scope}/${s.name}` : `${s.plugin}/${s.name}`;
+}
+/** Match skills whose final path segment equals `leaf`. Only meaningful when
+ *  `leaf` is a bare segment (no slash) — a slashed query can never equal a
+ *  single segment, so this returns empty and the caller falls through. */
+function findSkillsByLeaf(leaf, pluginQualifier, scope, pluginFilter) {
+    if (leaf.includes('/'))
+        return [];
+    let all;
+    try {
+        all = scope ? listAllSkills(scope) : listAllSkills();
+    }
+    catch {
+        return [];
+    }
+    return all.filter((s) => {
+        if ((s.name.split('/').pop() ?? s.name) !== leaf)
+            return false;
+        if (pluginQualifier && s.plugin !== pluginQualifier)
+            return false;
+        if (pluginFilter && s.plugin !== pluginFilter)
+            return false;
+        return true;
+    });
+}
+function formatLeafAmbiguousMessage(leaf, matches) {
+    const ids = matches.map(formatSkillId).join(', ');
+    return `ambiguous skill: ${leaf} matches multiple skills: ${ids}`;
+}
 function findSkillMatches(name, pluginQualifier, scope, pluginFilter) {
     const plugins = scope ? listInstalledPlugins(scope) : listAllPlugins();
     const enabledPlugins = plugins.filter((p) => p.enabled);
@@ -304,18 +371,18 @@ function pickMatch(matches, name, pluginQualifier) {
         })),
     });
 }
-function formatNotFoundMessage(rawName, parsed) {
-    const suggestions = suggestSkills(parsed.name, parsed.plugin);
+function formatNotFoundMessage(rawName, skillName, pluginQualifier) {
+    const suggestions = suggestSkills(skillName, pluginQualifier);
     const lines = [`skill not found: ${rawName}`];
-    lines.push('       expected forms: <name>, <plugin>:<name>, <scope>:<plugin>/<name>');
+    lines.push('       expected forms: <name>, <plugin>/<name>, <scope>/<name>, <scope>/<plugin>/<name>');
     if (suggestions.length > 0) {
         const formatted = suggestions
-            .map((s) => s.plugin === SCOPE_SKILL_PLUGIN ? s.name : `${s.plugin}:${s.name}`)
+            .map((s) => s.plugin === SCOPE_SKILL_PLUGIN ? s.name : `${s.plugin}/${s.name}`)
             .slice(0, 3);
         lines.push(`       did you mean: ${formatted.join(', ')}`);
     }
     else {
-        lines.push('       run `crtr skill list` or `crtr skill search <query>` to discover skills');
+        lines.push('       run `crtr skill find list` or `crtr skill find search <query>` to discover skills');
     }
     return lines.join('\n');
 }
@@ -386,29 +453,26 @@ function editDistance(a, b) {
 const SCOPE_QUALIFIERS = new Set(['user', 'project']);
 // Accepted identifier forms:
 //   <name>                         — bare name; scope-root first, then plugins
-//   <plugin>:<name>                — explicit plugin
-//   <scope>:<name>                 — scope-root in a specific scope
-//   <scope>:<plugin>/<name>        — fully qualified (matches `skill list` / `skill search` display)
-// Bare `<plugin>/<name>` (no colon) is handled as a fallback inside resolveSkill.
+//   <plugin>/<name>                — explicit plugin (plugin may contain slashes)
+//   <scope>/<name>                 — scope-root in a specific scope
+//   <scope>/<plugin>/<name>        — fully qualified; plugin-vs-path disambiguation is lookup-based in resolveSkill
 export function parseSkillQualifier(raw) {
-    const colonIdx = raw.indexOf(':');
-    if (colonIdx === -1)
-        return { name: raw };
-    const before = raw.slice(0, colonIdx);
-    const after = raw.slice(colonIdx + 1);
-    if (SCOPE_QUALIFIERS.has(before)) {
-        const scope = before;
-        const slashIdx = after.indexOf('/');
-        if (slashIdx !== -1) {
-            return {
-                scope,
-                plugin: after.slice(0, slashIdx),
-                name: after.slice(slashIdx + 1),
-            };
-        }
-        return { scope, name: after };
+    if (raw.includes(':')) {
+        const suggested = raw.replace(/:/g, '/');
+        throw new InputError({
+            error: 'invalid_qualifier',
+            message: "mixed separators ':' and '/' no longer supported; use slashes throughout",
+            received: raw,
+            field: 'name',
+            next: `Use ${suggested}.`,
+        });
+    }
+    const segments = raw.split('/');
+    if (SCOPE_QUALIFIERS.has(segments[0])) {
+        const scope = segments[0];
+        return { scope, segments: segments.slice(1) };
     }
-    return { plugin: before, name: after };
+    return { segments };
 }
 function orderPluginsByResolution(plugins) {
     const score = (p) => {

package/dist/core/spawn.d.ts

@@ -1,5 +1,5 @@
 export interface SpawnAgentOptions {
-    /** First user message for the new claude session. */
+    /** First user message for the new agent session. */
     prompt: string;
     cwd: string;
     /** crtr job_id injected as CRTR_JOB_ID env var in the pane. */
@@ -10,6 +10,14 @@ export interface SpawnAgentOptions {
     };
     /** Max panes per tmux window before overflowing to a new window. */
     maxPanesPerWindow: number;
+    /** Display name passed to the agent's `-n` flag; surfaces in pane title and resume picker. */
+    name?: string;
+    /** Persona appended via `--append-system-prompt` (subagent body). */
+    systemPrompt?: string;
+    /** Model pattern/id passed via `--model`. */
+    model?: string;
+    /** Tool allow-list passed to pi via `--tools`. */
+    tools?: string[];
 }
 export interface SpawnAgentResult {
     status: 'spawned' | 'spawn-failed' | 'not-in-tmux';
@@ -20,10 +28,11 @@ export interface SpawnAgentResult {
     message: string;
 }
 export interface DetachOptions {
-    /** Inner command to run in the pane. If omitted, build `claude … <prompt>`. */
+    /** Inner command to run in the pane. If omitted, build the detected agent's
+     *  invocation around `<prompt>`. */
     command?: string;
-    /** Full first user message for the new claude session (claude mode only;
-     *  ignored when `command` is set). No custom system prompt. */
+    /** Full first user message for the new agent session (ignored when `command`
+     *  is set). No custom system prompt. */
     prompt?: string;
     cwd: string;
     /** crtr job_id injected as CRTR_JOB_ID env var in the pane and used by the
@@ -40,6 +49,9 @@ export interface DetachOptions {
      *  uses the attached client's currently-focused pane — which drifts if the
      *  user switches windows between kickoff and spawn. */
     targetPane?: string;
+    /** Display name passed to the agent's `-n` flag; ignored when `command` is set
+     *  (caller controls the full argv in that mode). */
+    name?: string;
 }
 export interface DetachResult {
     status: 'spawned' | 'spawn-failed' | 'not-in-tmux';
@@ -48,7 +60,126 @@ export interface DetachResult {
 }
 export declare function isInTmux(): boolean;
 export declare function shellQuote(s: string): string;
+/** Coding-agent CLIs crtr knows how to spawn as a sibling worker. */
+export type AgentKind = 'claude' | 'pi';
+/**
+ * Detect which coding-agent CLI is hosting the current crtr process so spawns
+ * launch a matching sibling. pi exports `PI_CODING_AGENT=true` into its tool
+ * subprocess environment; Claude Code exports `CLAUDECODE` /
+ * `CLAUDE_CODE_SESSION_ID`. Defaults to claude when no signal is present
+ * (preserves prior behavior).
+ */
+export declare function detectAgentKind(): AgentKind;
+/**
+ * Normalize a `--model` value for the target agent CLI.
+ *
+ * Subagent frontmatter uses Claude Code's bare aliases (`sonnet`, `opus`,
+ * `haiku`, optionally with a `:thinking` suffix). The `claude` CLI resolves
+ * those natively, but `pi` maps a bare alias to its default provider —
+ * `amazon-bedrock` — which most users have not authenticated, so the spawn
+ * dies with "No API key found for amazon-bedrock". These aliases name Anthropic
+ * models, so under pi we pin them to the `anthropic/` provider (preserving any
+ * `:thinking` suffix). Values that already carry a `provider/` prefix or are
+ * concrete model ids are passed through untouched.
+ */
+export declare function normalizeModelForKind(model: string, kind: AgentKind): string;
+export interface AgentCommandOptions {
+    /** First user message delivered to the new agent session. */
+    prompt: string;
+    /** Display name (`-n`); surfaces in the pane title and resume picker. */
+    name?: string;
+    /** Fork an existing session into a fresh one rather than starting clean. */
+    fork?: {
+        sessionId: string;
+    };
+    /** Persona/system prompt appended to the agent's default (`--append-system-prompt`).
+     *  Used to apply a subagent definition's body. */
+    systemPrompt?: string;
+    /** Model pattern/id passed via `--model` (both claude and pi). */
+    model?: string;
+    /** Tool allow-list. Passed to pi via `--tools`; ignored for claude, whose
+     *  tool names and gating flag differ. */
+    tools?: string[];
+}
+/**
+ * Build the agent-CLI invocation (no job wrapper) for the given kind.
+ *
+ *   claude: `claude [-n <name>] [--resume <id> --fork-session] \
+ *            --dangerously-skip-permissions <prompt>`
+ *   pi:     `pi [-n <name>] [--fork <id>] <prompt>`
+ *
+ * pi has no permission popups, so it needs no skip-permissions flag.
+ */
+export declare function buildAgentCommand(opts: AgentCommandOptions, kind?: AgentKind): string;
+export interface AgentPrintArgv {
+    cmd: string;
+    args: string[];
+}
+/**
+ * Argv for a non-interactive print-mode run.
+ *
+ *   claude: `claude [-n <name>] [--resume <id> --fork-session] -p \
+ *            --dangerously-skip-permissions <prompt>`
+ *   pi:     `pi [-n <name>] [--fork <id>] -p <prompt>`
+ *
+ * Returned as a cmd + args array so callers can spawn without a shell.
+ */
+export declare function buildAgentPrintArgv(opts: AgentCommandOptions, kind?: AgentKind): AgentPrintArgv;
+/** Same as buildAgentPrintArgv but rendered as a single shell-quoted string. */
+export declare function buildAgentPrintCommand(opts: AgentCommandOptions, kind?: AgentKind): string;
+export interface HeadlessRunResult {
+    status: 'done' | 'failed';
+    /** Captured stdout on success; stdout+stderr (or an error message) on failure. */
+    output: string;
+    exitCode: number | null;
+}
+/**
+ * Run the agent headlessly and resolve once it exits. A blocking caller awaits
+ * this. stdout is captured as the result; a non-zero exit yields status
+ * 'failed' with the combined output.
+ */
+export declare function runAgentHeadless(opts: {
+    prompt: string;
+    name?: string;
+    cwd: string;
+    systemPrompt?: string;
+    model?: string;
+    tools?: string[];
+}): Promise<HeadlessRunResult>;
+export interface HeadlessDetachResult {
+    status: 'spawned' | 'spawn-failed';
+    pid?: number;
+    message: string;
+}
+/**
+ * Launch a headless agent detached (background). Its print output is captured
+ * and delivered to the job via `crtr job submit`; a non-zero exit marks the job
+ * failed. Returns immediately with the wrapper pid (recorded for crash
+ * detection). No tmux required.
+ */
+export declare function spawnHeadlessDetached(opts: {
+    prompt: string;
+    name?: string;
+    cwd: string;
+    jobId: string;
+    systemPrompt?: string;
+    model?: string;
+    tools?: string[];
+}): HeadlessDetachResult;
 export declare function countPanesInCurrentWindow(): number;
+/**
+ * Find a window in the current tmux session with fewer than `maxPanesPerWindow`
+ * panes AND where every existing pane hosts an agent (claude or pi) as its
+ * foreground process. Prefers the active window so the spawned pane is visible
+ * to the user; otherwise falls back to the first other eligible window. Returns
+ * the tmux window id (e.g. `@5`) to pass via `-t`, or null if no window qualifies.
+ *
+ * Windows holding non-agent panes (dashboards, log tails, idle shells, editors,
+ * REPLs, etc.) are skipped so spawning never disrupts those workflows. A pane
+ * qualifies as long as an agent comm is among its foreground commands —
+ * co-resident helpers like `caffeinate` don't disqualify it.
+ */
+export declare function findWindowWithSpace(maxPanesPerWindow: number): string | null;
 /**
  * Schedule a kill-pane on the *current* tmux pane after `delaySeconds`, detached
  * so the caller can return normally before the pane dies. No-op outside tmux
@@ -60,18 +191,27 @@ export declare function countPanesInCurrentWindow(): number;
  */
 export declare function scheduleKillCurrentPane(delaySeconds: number): boolean;
 /**
- * Fire-and-forget: launch an interactive `claude` in a new pane (or window),
+ * Fire-and-forget: launch an interactive agent in a new pane (or window),
  * then schedule the originating pane to be killed after `killAfterSeconds`.
  *
  * No custom system prompt — the task is delivered as the first user message.
- * Returns as soon as the new pane is up; does NOT wait for claude to finish.
+ * Returns as soon as the new pane is up; does NOT wait for the agent to finish.
  */
 export declare function spawnAndDetach(opts: DetachOptions): DetachResult;
+/** Originating pane id + session id of the host (pi/claude) crtr runs under. */
+export declare function originContext(): {
+    pane: string;
+    sessionId: string;
+} | null;
+/** Deterministic subagent session name for an originating pane id (e.g. `%5`). */
+export declare function subagentSessionName(pane: string): string;
 /**
- * Async sibling spawn. Launches a claude session in a new tmux pane or window
- * (depending on current pane count vs maxPanesPerWindow). Returns immediately
- * with the pane id; the parent stays alive.
+ * Async sibling spawn. Launches an interactive agent (claude or pi, per
+ * detectAgentKind) in the dedicated subagent session, progressively filling
+ * windows up to `maxPanesPerWindow` before creating a new window. Returns
+ * immediately with the pane id; the parent stays alive. Focus is never
+ * switched — the user jumps to the subagent session with Alt-o.
  *
- * If `fork` is set, uses `claude --resume <id> --fork-session`.
+ * If `fork` is set, forks the host session into a fresh one.
  */
 export declare function spawnAgent(opts: SpawnAgentOptions): SpawnAgentResult;