@crouton-kit/crouter 0.3.11 → 0.3.12

package/dist/core/jobs.d.ts

@@ -1,107 +0,0 @@
-type TerminalStatus = 'done' | 'failed' | 'canceled' | 'closed';
-type JobState = 'live' | TerminalStatus;
-type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-/**
- * Allocate a new job directory and write meta.json atomically.
- * Returns the job_id and the absolute directory path.
- */
-export declare function createJob(kind: string, opts: {
-    cwd: string;
-    pid?: number;
-}): {
-    jobId: string;
-    dir: string;
-};
-/**
- * Record the tmux pane hosting a detached worker so `cancelJob` can kill it.
- */
-export declare function recordJobPane(jobId: string, paneId: string): void;
-/**
- * Record the pid of a detached worker (e.g. a headless background agent) so
- * jobStatus can mark the job failed if the process dies without a result.
- */
-export declare function recordJobPid(jobId: string, pid: number): void;
-/**
- * Append one event line to log.jsonl. Does NOT throw if jobId doesn't exist —
- * a crashed writer should not further corrupt state; use a guard at the call site.
- */
-export declare function appendEvent(jobId: string, event: {
-    level: LogLevel;
-    event: string;
-    message: string;
-    data?: object;
-}): void;
-/**
- * Atomically write result.json (structured object) and update meta.json status.
- * Used by programmatic callers (human, sys) that produce object results.
- * The result file's appearance is the completion signal — never inferred from log content.
- */
-export declare function writeResult(jobId: string, result: object, terminalStatus: TerminalStatus): void;
-/**
- * Atomically write result.md (YAML frontmatter + markdown body) and update meta.json status.
- * Used by `crtr job submit` for agent-driven markdown results.
- */
-export declare function writeMarkdownResult(jobId: string, body: string, terminalStatus: TerminalStatus, reason?: string): void;
-/**
- * Read whichever result file exists (result.md or result.json). If neither
- * exists and waitMs is given, block via fs.watch until one appears or the
- * timeout elapses.
- *
- * Race safety: registers the watcher THEN re-stats. If a result file appeared
- * between the first stat and the watch registration, the re-stat catches it
- * before the watcher has a chance to miss it.
- *
- * Returns shape:
- *   - JSON path:     { status, result: object }
- *   - Markdown path: { status, result_md: string, reason?: string }
- *   - Timeout:       { status: 'timeout' }
- *   - Closed:        pane vanished with no result → status 'closed'
- */
-export interface ReadResultResponse {
-    status: 'done' | 'failed' | 'canceled' | 'closed' | 'timeout';
-    result?: object;
-    result_md?: string;
-    reason?: string;
-}
-export declare function readResult(jobId: string, opts?: {
-    waitMs?: number;
-}): Promise<ReadResultResponse>;
-/**
- * Derive job state from meta.json, the result file, and the tail of log.jsonl.
- * If a pid is recorded, is not alive, and no result file exists → 'failed'.
- */
-export declare function jobStatus(jobId: string): {
-    state: JobState;
-    age_s: number;
-    last_event: {
-        event: string;
-        ts: string;
-    } | null;
-};
-/**
- * List all jobs sorted by created_at ascending. Pagination is applied by the
- * caller, not here.
- */
-export declare function listJobs(): {
-    job_id: string;
-    kind: string;
-    state: JobState;
-    created_at: string;
-}[];
-/**
- * Read and filter log events. Ordering preserved. sinceTs/untilTs are ISO8601
- * strings; minLevel filters by severity rank (inclusive).
- */
-export declare function readLog(jobId: string, opts?: {
-    sinceTs?: string;
-    untilTs?: string;
-    minLevel?: LogLevel;
-}): object[];
-/**
- * Best-effort cancel: send SIGTERM to the recorded pid (if any), mark meta
- * canceled. Success means the signal was delivered, not that execution stopped.
- */
-export declare function cancelJob(jobId: string): {
-    canceled: boolean;
-};
-export {};

package/dist/core/jobs.js

@@ -1,565 +0,0 @@
-// Job / long-running-operation infrastructure.
-//
-// Files are the single source of truth. No in-memory registry. An agent picks
-// up a job by id across processes. Crashes recover by reading files.
-//
-// Layout: ${XDG_STATE_HOME or ~/.local/state}/crtr/jobs/<job_id>/
-//   meta.json    — written atomically on create; updated atomically on terminal transition.
-//   log.jsonl    — append-only event log.
-//   result.md    — agent submissions (markdown body + YAML frontmatter). Written atomically.
-//   result.json  — programmatic submissions (structured object). Written atomically.
-// Either result file's APPEARANCE is the completion signal. Exactly one is written per job.
-//
-// A worker is not required to submit. Besides an explicit submit, a job becomes
-// terminal when (a) the wrapper shell's `crtr job _fail` runs on a clean exit,
-// or (b) the hosting tmux pane is closed — which sends SIGHUP so (a) never runs.
-// Case (b) is reaped here: when a live job's recorded pane is gone and no result
-// exists, we write a `closed` result (terminal, but distinct from `failed`) so
-// the job stops being a zombie without claiming an outcome we can't know.
-import { existsSync, mkdirSync, appendFileSync, readFileSync, writeFileSync, renameSync, readdirSync, statSync, } from 'node:fs';
-import { watch } from 'node:fs';
-import { spawnSync } from 'node:child_process';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
-import { randomBytes } from 'node:crypto';
-import { notFound, general } from './errors.js';
-// ---------------------------------------------------------------------------
-// Paths
-// ---------------------------------------------------------------------------
-function jobsRoot() {
-    const xdg = process.env['XDG_STATE_HOME'];
-    const base = (xdg !== undefined && xdg !== '') ? xdg : join(homedir(), '.local', 'state');
-    return join(base, 'crtr', 'jobs');
-}
-function jobDir(jobId) {
-    return join(jobsRoot(), jobId);
-}
-function metaPath(jobId) {
-    return join(jobDir(jobId), 'meta.json');
-}
-function logPath(jobId) {
-    return join(jobDir(jobId), 'log.jsonl');
-}
-function resultJsonPath(jobId) {
-    return join(jobDir(jobId), 'result.json');
-}
-function resultMdPath(jobId) {
-    return join(jobDir(jobId), 'result.md');
-}
-/** Path of whichever result file currently exists, or null if neither does. */
-function existingResultPath(jobId) {
-    const md = resultMdPath(jobId);
-    if (existsSync(md))
-        return md;
-    const js = resultJsonPath(jobId);
-    if (existsSync(js))
-        return js;
-    return null;
-}
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-function generateJobId() {
-    const ts = Date.now().toString(36);
-    const rnd = randomBytes(4).toString('hex');
-    return `${ts}-${rnd}`;
-}
-function ensureJobsRoot() {
-    mkdirSync(jobsRoot(), { recursive: true });
-}
-function readMeta(jobId) {
-    const p = metaPath(jobId);
-    if (!existsSync(p)) {
-        throw notFound(`job not found: ${jobId}`, { job_id: jobId });
-    }
-    try {
-        return JSON.parse(readFileSync(p, 'utf8'));
-    }
-    catch {
-        throw general(`failed to parse meta.json for job ${jobId}`, { job_id: jobId });
-    }
-}
-function writeMeta(jobId, meta) {
-    const dir = jobDir(jobId);
-    const tmp = join(dir, '.meta.tmp');
-    writeFileSync(tmp, JSON.stringify(meta, null, 2), 'utf8');
-    renameSync(tmp, metaPath(jobId));
-}
-function pidAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Set of every tmux pane id across all sessions on the running server. Empty
- * when no server is running (→ every recorded pane is treated as gone).
- *
- * This bridges tmux's pane lifecycle to the job registry. A worker whose pane
- * is closed/killed receives SIGHUP, so the wrapper shell's `crtr job _fail`
- * never runs and the job would otherwise stay `live` forever (a zombie). We
- * detect the vanished pane and reap the job instead.
- */
-function allTmuxPaneIds() {
-    const set = new Set();
-    const r = spawnSync('tmux', ['list-panes', '-a', '-F', '#{pane_id}'], { encoding: 'utf8' });
-    if (r.status !== 0 || typeof r.stdout !== 'string')
-        return set;
-    for (const line of r.stdout.split('\n')) {
-        const t = line.trim();
-        if (t !== '')
-            set.add(t);
-    }
-    return set;
-}
-/**
- * Reap a job whose hosting tmux pane has disappeared. Acts only when the job is
- * still `live`, has a recorded pane, and has produced no result file. Writes a
- * terminal `closed` result so the job stops being a zombie and every reader
- * (status, list, result --wait) agrees. `closed` is distinct from `failed`: we
- * don't know the outcome, only that the pane is gone. Returns true if it reaped.
- *
- * `panes` lets a caller reuse a single tmux query across many jobs (listJobs).
- */
-function reapIfPaneDead(meta, panes) {
-    if (meta.status !== 'live')
-        return false;
-    if (meta.pane_id === undefined || meta.pane_id === '')
-        return false;
-    if (existingResultPath(meta.job_id) !== null)
-        return false;
-    const set = panes ?? allTmuxPaneIds();
-    if (set.has(meta.pane_id))
-        return false;
-    try {
-        writeMarkdownResult(meta.job_id, '', 'closed', 'worker pane closed before submitting a result');
-    }
-    catch {
-        return false;
-    }
-    return true;
-}
-/** Poll cadence (ms) for detecting a closed worker pane during result --wait. */
-const PANE_POLL_MS = 2000;
-const LEVEL_RANK = {
-    debug: 0,
-    info: 1,
-    warn: 2,
-    error: 3,
-};
-// ---------------------------------------------------------------------------
-// Exported API
-// ---------------------------------------------------------------------------
-/**
- * Allocate a new job directory and write meta.json atomically.
- * Returns the job_id and the absolute directory path.
- */
-export function createJob(kind, opts) {
-    ensureJobsRoot();
-    const jobId = generateJobId();
-    const dir = jobDir(jobId);
-    mkdirSync(dir, { recursive: true });
-    const meta = {
-        job_id: jobId,
-        kind,
-        created_at: new Date().toISOString(),
-        cwd: opts.cwd,
-        status: 'live',
-    };
-    if (opts.pid !== undefined) {
-        meta.pid = opts.pid;
-    }
-    writeMeta(jobId, meta);
-    return { jobId, dir };
-}
-/**
- * Record the tmux pane hosting a detached worker so `cancelJob` can kill it.
- */
-export function recordJobPane(jobId, paneId) {
-    const meta = readMeta(jobId);
-    meta.pane_id = paneId;
-    writeMeta(jobId, meta);
-}
-/**
- * Record the pid of a detached worker (e.g. a headless background agent) so
- * jobStatus can mark the job failed if the process dies without a result.
- */
-export function recordJobPid(jobId, pid) {
-    const meta = readMeta(jobId);
-    meta.pid = pid;
-    writeMeta(jobId, meta);
-}
-/**
- * Append one event line to log.jsonl. Does NOT throw if jobId doesn't exist —
- * a crashed writer should not further corrupt state; use a guard at the call site.
- */
-export function appendEvent(jobId, event) {
-    const p = logPath(jobId);
-    const line = {
-        ts: new Date().toISOString(),
-        level: event.level,
-        event: event.event,
-        message: event.message,
-    };
-    if (event.data !== undefined) {
-        line.data = event.data;
-    }
-    appendFileSync(p, JSON.stringify(line) + '\n', 'utf8');
-}
-/**
- * Atomically write result.json (structured object) and update meta.json status.
- * Used by programmatic callers (human, sys) that produce object results.
- * The result file's appearance is the completion signal — never inferred from log content.
- */
-export function writeResult(jobId, result, terminalStatus) {
-    const dir = jobDir(jobId);
-    if (!existsSync(dir)) {
-        throw notFound(`job not found: ${jobId}`, { job_id: jobId });
-    }
-    const payload = {
-        status: terminalStatus,
-        result,
-        written_at: new Date().toISOString(),
-    };
-    const tmp = join(dir, '.result.tmp');
-    writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8');
-    renameSync(tmp, resultJsonPath(jobId));
-    const meta = readMeta(jobId);
-    meta.status = terminalStatus;
-    writeMeta(jobId, meta);
-}
-/**
- * Atomically write result.md (YAML frontmatter + markdown body) and update meta.json status.
- * Used by `crtr job submit` for agent-driven markdown results.
- */
-export function writeMarkdownResult(jobId, body, terminalStatus, reason) {
-    const dir = jobDir(jobId);
-    if (!existsSync(dir)) {
-        throw notFound(`job not found: ${jobId}`, { job_id: jobId });
-    }
-    const fm = {
-        status: terminalStatus,
-        written_at: new Date().toISOString(),
-    };
-    if (reason !== undefined && reason !== '') {
-        fm.reason = reason;
-    }
-    const content = `${renderFrontmatter(fm)}${body}`;
-    const tmp = join(dir, '.result.tmp');
-    writeFileSync(tmp, content, 'utf8');
-    renameSync(tmp, resultMdPath(jobId));
-    const meta = readMeta(jobId);
-    meta.status = terminalStatus;
-    writeMeta(jobId, meta);
-}
-/**
- * Render a small fixed-shape frontmatter block. We control writer and reader,
- * so a 3-key hand-rolled emitter is plenty — no YAML dep, no escaping surprises.
- * Values are plain strings; we double-quote `reason` to survive newlines/colons.
- */
-function renderFrontmatter(fm) {
-    const lines = ['---', `status: ${fm.status}`, `written_at: ${fm.written_at}`];
-    if (fm.reason !== undefined) {
-        const escaped = fm.reason.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
-        lines.push(`reason: "${escaped}"`);
-    }
-    lines.push('---', '');
-    return lines.join('\n');
-}
-/**
- * Parse the small fixed-shape frontmatter we emit. Tolerant of trailing
- * whitespace; returns `{ frontmatter, body }`. Throws if the document does not
- * start with `---\n` or no closing `---` is found.
- */
-function parseMarkdownResult(raw) {
-    if (!raw.startsWith('---\n') && !raw.startsWith('---\r\n')) {
-        throw new Error('result.md missing opening --- delimiter');
-    }
-    const afterOpen = raw.indexOf('\n') + 1;
-    const closeIdx = raw.indexOf('\n---', afterOpen);
-    if (closeIdx === -1) {
-        throw new Error('result.md missing closing --- delimiter');
-    }
-    const fmBlock = raw.slice(afterOpen, closeIdx);
-    // Body starts after the closing `---` line.
-    const afterCloseLine = raw.indexOf('\n', closeIdx + 1);
-    const body = afterCloseLine === -1 ? '' : raw.slice(afterCloseLine + 1);
-    const fm = {};
-    for (const line of fmBlock.split('\n')) {
-        const m = line.match(/^([a-z_]+):\s*(.*)$/);
-        if (m === null)
-            continue;
-        const key = m[1];
-        if (m[2] === undefined)
-            continue;
-        let val = m[2];
-        if (val.startsWith('"') && val.endsWith('"') && val.length >= 2) {
-            val = val.slice(1, -1).replace(/\\n/g, '\n').replace(/\\"/g, '"').replace(/\\\\/g, '\\');
-        }
-        if (key === 'status') {
-            fm.status = val;
-        }
-        else if (key === 'written_at') {
-            fm.written_at = val;
-        }
-        else if (key === 'reason') {
-            fm.reason = val;
-        }
-    }
-    if (fm.status === undefined || fm.written_at === undefined) {
-        throw new Error('result.md frontmatter missing status or written_at');
-    }
-    return { frontmatter: fm, body };
-}
-export function readResult(jobId, opts = {}) {
-    const dir = jobDir(jobId);
-    if (!existsSync(dir)) {
-        throw notFound(`job not found: ${jobId}`, { job_id: jobId });
-    }
-    function parseAt(path) {
-        const raw = readFileSync(path, 'utf8');
-        if (path.endsWith('.md')) {
-            const { frontmatter, body } = parseMarkdownResult(raw);
-            const out = { status: frontmatter.status, result_md: body };
-            if (frontmatter.reason !== undefined) {
-                out.reason = frontmatter.reason;
-            }
-            return out;
-        }
-        const parsed = JSON.parse(raw);
-        return { status: parsed.status, result: parsed.result };
-    }
-    const existing = existingResultPath(jobId);
-    if (existing !== null) {
-        return Promise.resolve(parseAt(existing));
-    }
-    if (opts.waitMs === undefined || opts.waitMs <= 0) {
-        return Promise.resolve({ status: 'timeout' });
-    }
-    return new Promise((resolve) => {
-        let settled = false;
-        let timer;
-        let poll;
-        const finish = (response) => {
-            if (settled)
-                return;
-            settled = true;
-            if (timer !== undefined)
-                clearTimeout(timer);
-            if (poll !== undefined)
-                clearInterval(poll);
-            try {
-                watcher.close();
-            }
-            catch { /* noop */ }
-            resolve(response);
-        };
-        const watcher = watch(dir, (_event, name) => {
-            if (name !== 'result.md' && name !== 'result.json')
-                return;
-            const path = existingResultPath(jobId);
-            if (path !== null) {
-                finish(parseAt(path));
-            }
-        });
-        const path = existingResultPath(jobId);
-        if (path !== null) {
-            finish(parseAt(path));
-            return;
-        }
-        // fs.watch only fires on result files. A pane that closes without a submit
-        // produces no such event, so poll to reap it instead of hanging until the
-        // full timeout budget elapses.
-        poll = setInterval(() => {
-            const found = existingResultPath(jobId);
-            if (found !== null) {
-                finish(parseAt(found));
-                return;
-            }
-            try {
-                if (reapIfPaneDead(readMeta(jobId))) {
-                    const reaped = existingResultPath(jobId);
-                    if (reaped !== null)
-                        finish(parseAt(reaped));
-                }
-            }
-            catch { /* noop */ }
-        }, PANE_POLL_MS);
-        // A non-finite budget (Infinity) means block until a result appears or the
-        // worker pane dies — used by `human review`, where the human may take an
-        // unbounded amount of time. The poll above still reaps a dead pane, so this
-        // never hangs forever on a closed pane.
-        if (Number.isFinite(opts.waitMs)) {
-            timer = setTimeout(() => {
-                finish({ status: 'timeout' });
-            }, opts.waitMs);
-        }
-    });
-}
-/**
- * Derive job state from meta.json, the result file, and the tail of log.jsonl.
- * If a pid is recorded, is not alive, and no result file exists → 'failed'.
- */
-export function jobStatus(jobId) {
-    let meta = readMeta(jobId);
-    if (reapIfPaneDead(meta)) {
-        meta = readMeta(jobId);
-    }
-    const age_s = (Date.now() - new Date(meta.created_at).getTime()) / 1000;
-    let state = meta.status;
-    if (state === 'live') {
-        const existing = existingResultPath(jobId);
-        if (existing !== null) {
-            // Result file present but meta not yet updated (rare); trust the file.
-            try {
-                if (existing.endsWith('.md')) {
-                    const { frontmatter } = parseMarkdownResult(readFileSync(existing, 'utf8'));
-                    state = frontmatter.status;
-                }
-                else {
-                    const r = JSON.parse(readFileSync(existing, 'utf8'));
-                    state = r.status;
-                }
-            }
-            catch { /* leave as live */ }
-        }
-        else if (meta.pid !== undefined && !pidAlive(meta.pid)) {
-            state = 'failed';
-        }
-    }
-    // Tail of log for last_event.
-    let last_event = null;
-    const lp = logPath(jobId);
-    if (existsSync(lp)) {
-        const lines = readFileSync(lp, 'utf8').trimEnd().split('\n');
-        for (let i = lines.length - 1; i >= 0; i--) {
-            const line = lines[i];
-            if (line === undefined || line.trim() === '')
-                continue;
-            try {
-                const ev = JSON.parse(line);
-                last_event = { event: ev.event, ts: ev.ts };
-                break;
-            }
-            catch {
-                continue;
-            }
-        }
-    }
-    return { state, age_s, last_event };
-}
-/**
- * List all jobs sorted by created_at ascending. Pagination is applied by the
- * caller, not here.
- */
-export function listJobs() {
-    const root = jobsRoot();
-    if (!existsSync(root))
-        return [];
-    const entries = readdirSync(root);
-    const jobs = [];
-    // One tmux query, reused to reap every job whose pane has vanished.
-    const panes = allTmuxPaneIds();
-    for (const entry of entries) {
-        const dir = join(root, entry);
-        try {
-            if (!statSync(dir).isDirectory())
-                continue;
-            const mp = join(dir, 'meta.json');
-            if (!existsSync(mp))
-                continue;
-            let meta = JSON.parse(readFileSync(mp, 'utf8'));
-            if (reapIfPaneDead(meta, panes)) {
-                meta = JSON.parse(readFileSync(mp, 'utf8'));
-            }
-            // Derive effective state (result file beats meta.status for live jobs).
-            let state = meta.status;
-            if (state === 'live') {
-                const mdP = join(dir, 'result.md');
-                const jsP = join(dir, 'result.json');
-                try {
-                    if (existsSync(mdP)) {
-                        const { frontmatter } = parseMarkdownResult(readFileSync(mdP, 'utf8'));
-                        state = frontmatter.status;
-                    }
-                    else if (existsSync(jsP)) {
-                        const r = JSON.parse(readFileSync(jsP, 'utf8'));
-                        state = r.status;
-                    }
-                }
-                catch { /* leave as live */ }
-            }
-            jobs.push({ job_id: meta.job_id, kind: meta.kind, state, created_at: meta.created_at });
-        }
-        catch {
-            continue;
-        }
-    }
-    jobs.sort((a, b) => a.created_at.localeCompare(b.created_at));
-    return jobs;
-}
-/**
- * Read and filter log events. Ordering preserved. sinceTs/untilTs are ISO8601
- * strings; minLevel filters by severity rank (inclusive).
- */
-export function readLog(jobId, opts = {}) {
-    const dir = jobDir(jobId);
-    if (!existsSync(dir)) {
-        throw notFound(`job not found: ${jobId}`, { job_id: jobId });
-    }
-    const lp = logPath(jobId);
-    if (!existsSync(lp))
-        return [];
-    const raw = readFileSync(lp, 'utf8');
-    const results = [];
-    const minRank = opts.minLevel !== undefined ? LEVEL_RANK[opts.minLevel] : 0;
-    for (const line of raw.split('\n')) {
-        if (line.trim() === '')
-            continue;
-        let ev;
-        try {
-            ev = JSON.parse(line);
-        }
-        catch {
-            continue;
-        }
-        if (opts.sinceTs !== undefined && ev.ts < opts.sinceTs)
-            continue;
-        if (opts.untilTs !== undefined && ev.ts >= opts.untilTs)
-            continue;
-        if (LEVEL_RANK[ev.level] < minRank)
-            continue;
-        results.push(ev);
-    }
-    return results;
-}
-/**
- * Best-effort cancel: send SIGTERM to the recorded pid (if any), mark meta
- * canceled. Success means the signal was delivered, not that execution stopped.
- */
-export function cancelJob(jobId) {
-    const meta = readMeta(jobId);
-    if (meta.status !== 'live') {
-        // Already terminal — nothing to cancel.
-        return { canceled: false };
-    }
-    let signaled = false;
-    if (meta.pid !== undefined) {
-        try {
-            process.kill(meta.pid, 'SIGTERM');
-            signaled = true;
-        }
-        catch { /* pid gone or unpermitted */ }
-    }
-    if (meta.pane_id !== undefined && meta.pane_id !== '') {
-        const k = spawnSync('tmux', ['kill-pane', '-t', meta.pane_id], { encoding: 'utf8' });
-        if (k.status === 0)
-            signaled = true;
-    }
-    meta.status = 'canceled';
-    writeMeta(jobId, meta);
-    return { canceled: signaled };
-}

package/dist/core/subagents.d.ts

@@ -1,18 +0,0 @@
-import type { Scope, Subagent } from '../types.js';
-/** `<scope-root>/agents` for a given scope, or null when the scope has no root. */
-export declare function scopeAgentsDir(scope: Scope): string | null;
-/** Scope-root agents under `<scope-root>/agents/*.md`. */
-export declare function listScopeRootSubagents(scope: Scope): Subagent[];
-/** All subagents: scope-root agents (project, user) plus enabled plugins. */
-export declare function listSubagents(scopeFilter?: Scope): Subagent[];
-/** Canonical, unambiguous identifier: `<plugin>/<name>`, or bare `<name>` for
- *  scope-root agents. */
-export declare function subagentId(a: Subagent): string;
-export interface SubagentResolutionOpts {
-    scope?: Scope;
-    plugin?: string;
-}
-/** 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 declare function resolveSubagent(rawName: string, opts?: SubagentResolutionOpts): Subagent;