ptbk 0.118.0-1 → 0.119.0-13

package/README.md

@@ -14,13 +14,14 @@ npm install --save-dev ptbk
 npx ptbk init
 ```
 
-Initialization creates missing core agents, task templates and project conventions, preserving customized files. It offers supported harness installation and interactive authentication. `--no-install` skips installation; `--no-questions` avoids terminal prompts. Configure a meaningful project `check` script and commit the initialized project before starting work.
+Initialization creates missing core agents, task templates, `ptbk.json` and project conventions, preserving customized files. Its wizard offers destination-local installation of the exact running version and selected global harness setup, reusing native login. Unattended setup requires `--installation local|global` or `--no-install`; `--non-interactive` disables prompts. Setup commits only safe generated artifacts; `--no-commit` defers persistence, and edits overlapping user work remain pending review. Configure meaningful project checks before starting work.
 
 ```bash
-ptbk add "Implement the new behavior and its acceptance checks" --commit
+ptbk add "Implement the new behavior and its acceptance checks"
 ptbk list
 ptbk run --dry-run
-ptbk start                     # background agenda, localhost dashboard, reboot persistence
+ptbk start                     # background agenda, protected remote dashboard, reboot persistence
+ptbk dashboard                 # attach terminal controls to the existing service
 ptbk show                      # inspect the same process and pending requests
 ptbk answer REQUEST_ID "Reply"
 ptbk stop                      # intentional stop also disables automatic restart
@@ -28,7 +29,9 @@ ptbk stop                      # intentional stop also disables automatic restar
 
 `start` discovers available authenticated harnesses, uses Manager for missing assignments, and executes one task at a time. It requires reported outcome evidence and passing project checks before committing implementation, dated task completion and learning follow-ups together. It watches future work and materializes goal enquiries when no unfinished backlog remains. Failures retain work and expose recovery diagnostics.
 
-Use `start --raw` for foreground logs or `start --interactive` for terminal controls. `--no-persist`, `--no-server`, `--no-qr` and `--port` customize startup. `run` executes a finite queue with one configuration; for example `ptbk run --harness openai-codex --check "npm run check" --limit 1`. Harness availability, account policy and capability checks happen before inference; unsupported installed provider features produce an actionable diagnostic.
+Lifecycle commands report once and return; `start --raw` still launches a daemon. Use `dashboard` to attach terminal controls, or `start --foreground` to own execution in the current terminal (`--raw` gives plain foreground events). Q/Ctrl+C leaves an attached dashboard while its service continues. `--no-persist`, `--no-server`, `--no-qr` and `--port` customize startup. `run` executes a finite queue with one configuration; for example `ptbk run --harness openai-codex --check "npm run check" --limit 1`. Harness availability, account policy and capability checks happen before inference; unsupported installed provider features produce an actionable diagnostic.
+
+Suitable terminals default to rich presentation; `--raw` or redirected output gives plain results without prompts or QR codes. `ptbk add` guides and confirms task creation. Use `ptbk init --help`, `ptbk init help` or `ptbk help init` for the same command-specific offline reference.
 
 Global installation, local `npx ptbk`, or a project script such as `"ptbk": "ptbk"` work outside this repository. Each process loads its own installed runtime/version and pins that installation for restart. See [runtime usage](docs/runtime.md), [compatibility and verification](docs/compatibility.md), and [the specification](https://github.com/webgptorg/promptbook/blob/main/specs/_main.md).
 

package/changelog/_current-preversion.md

@@ -7,3 +7,33 @@
 - Fix Windows runtime state/browser startup sharing violations, process cancellation, secret-redaction scope, portable trace/learning paths and isolation recovery across Git checkout line-ending filters.
 - Make integration fixtures independent of host path separators and Git line-ending defaults, with bounded completion waits that tolerate hosted-runner load and surface runtime failures immediately.
 - Keep all platform checks running after a matrix failure, bound concurrent fixture processes, and document releasing code fixes under a new immutable version tag.
+- Fix `ptbk run` failing with `Invalid string length` while claiming tasks in large checkouts by storing deduplicated snapshot bytes separately from recovery journal JSON; preserve existing journal compatibility and verify stored bytes before recovery.
+- Resolve versioned `ptbk.json` project defaults beneath temporary CLI overrides, preserve explicit disabled/empty settings, and keep credentials out of configuration. Make bare/help/about output offline, concise and specific to the invoked engine version.
+- Add incremental initialization with exact-version destination-local installation, explicit ignored-child/submodule boundaries, scoped setup commits, and durable pending review for generated changes overlapping user edits. Separate invoked-engine self-update from selected global harness maintenance.
+- Move the seven harness integrations into a common plugin contract with featured/More catalogs, selected-only setup, native login reuse, actual version evidence and bounded global updates protected against concurrent project invocations.
+- Share versioned terminal/dashboard state and authenticated controls between finite run and ongoing start; add multiline input with safe paste, keyboard/pointer editing and draft preservation, independent persistent browser profile/mode changes, and actionable redacted diagnostics with real trace references.
+- Replace typed predefined answers with labeled arrow-key pickers and Space-toggle checkboxes throughout setup, harness updates, confirmations and runtime requests. Preserve selections while browsing More, resizing and receiving logs; clarify the shared choice controls in the specification.
+- Separate daemon/foreground placement from pretty/raw presentation: lifecycle commands render one result, `start --raw` launches a daemon, and `--foreground` explicitly owns execution. Add an authenticated attached `dashboard` client with client-only exit, shared controls and continuous raw observation.
+- Add coherent rich terminal summaries and live panels, an independently usable local API with a lightweight synchronized browser SPA, explicit connection/control outcomes, retained input drafts and safe task editing. Preserve color suppression and plain redirected output.
+- Add a finite task-creation wizard with reusable supplied inputs, template/priority selection, exact preview, Back and confirmation before any task is saved. Resolve offline command-scoped help in all supported help forms, with relevant defaults/examples, alias support and scoped usage diagnostics.
+- Fix release validation on runners without a Git identity by isolating initialization fixtures from host configuration and supplying fixture-only authorship.
+- Synchronize browser dashboard control outcomes with a fresh snapshot and make browser tests wait for document/control readiness. Bound DevTools and owned-browser shutdown waits, preserve ownership when termination fails, and close browsers before removing fixture profiles to prevent Windows CI hangs.
+- Retry transient Windows file-sharing failures when recording task completion and saving dashboard edits, rechecking source revision, path confinement and workspace ownership before each attempt while preserving concurrent edits and checked work. Read decoded Git submodule configuration in release fixtures so escaped Windows paths are validated correctly.
+- Fix daemon stop failing when a read-only shutdown inspection encounters a reset control connection. Bound inspection retries with fresh process authentication, preserve ownership checks and never replay a mutation whose reply was lost; keep client disconnects from terminating the supervisor.
+- Resolve missing project validation through a shared init/start setup picker with exact-command confirmation and saved check defaults. Preserve custom validation and temporary overrides, reject recursive/placeholder checks before work, and report incomplete setup with actionable correction instead of recommending a start that will fail.
+- Align Book parsing with documented rule, note, writing and example aliases, including instruction withdrawal. Recognize UTF-8 BOM task sources without rewriting their bytes, reject task controls used as titles, and keep fenced agent examples literal with actionable unclosed-fence diagnostics.
+- Propagate invalid prerequisites through the complete dependency graph regardless of source order or priority, and require recurring prerequisites' completion evidence to match their current assignment before unblocking dependent work.
+- Reevaluate pending finite-run tasks after each accepted result so completed prerequisites and elapsed earliest-start boundaries unlock existing work. Keep skip counts and next due times current, avoid repeated unchanged blocker logs, and retain finite queue and one-occurrence limits.
+- Align initialization with ready-to-start setup: provide real sample validation and one checked readiness/Expert task, retain a versioned first-task record across completion and archiving, verify saved harness execution capabilities and validation prerequisites, and report deferred or temporary-only setup as incomplete.
+- Share prominent User attention, actual activity, stable offline geometric agent identities and available URL/QR presentation across launch results, status snapshots, terminal dashboards and the browser; preserve focused drafts and raw/no-QR/narrow-terminal behavior.
+- Arrange missing routing through Manager without requiring a Developer role or bypassing prerequisites, retain explicit routing blockers, limit discovery to ordinary goal-bearing agents, and expose idle reasons and next opportunities.
+- Fix GitHub Actions fixtures to compare canonical Book diagnostic paths, preserve inherited Windows Path when adding provider stubs, and wait for the accepted runtime result before asserting completion events. Specify passing hosted checks and verified publication as required outcomes, retaining the full platform matrix and immutable release tags.
+- Reuse an authenticated native Codex ChatGPT session for setup, ordinary execution, TEAM and planning without requiring unsupported credit-control flags or `--allow-credits`. Keep explicit API billing opt-in and account preference, report native credit limits honestly, and clarify subscription access versus provider billing controls in the specification.
+- Preserve non-secret CLI/native-store discovery paths across OS-managed daemon restarts, including Node version-manager global binaries. Keep setup/recovery failures and their actual repair/recheck information visible instead of relabeling them as provider/pacing waits; recheck prerequisites on resume/answers and restrict Skip wait to real pacing.
+- Checkpoint User clarification outside provider tool timeouts, retaining the task and request across restart without automatic repair calls or false recovery failures. Apply real replies once, continue the agenda after checked completion, and distinguish nested tool observations/echoed instructions from terminal provider failures.
+- Resolve normalized agent references through engine identities, recursive agents, ordinary project Books and explicitly requested ignored dependencies; enforce winning-tier ambiguity and private-runtime boundaries without treating shadowed copies as global duplicates.
+- Commit owned authoring, planning saves and dashboard edits by default with exactly one `PTBK: ` prefix. Support explicit uncommitted supervision with verified ownership checkpoints, preserving unrelated edits and the persistence policy through intent bootstrap and restart.
+- Replace default geometric portraits with stable offline Coder mascot badges, truthful activity expressions and individually bounded attention, work, queue, results/activity and connection panels across terminal and browser views.
+- Add managed Cloudflare Quick/named tunnel lifecycles, setup of checksum-verified official connectors, explicit tunnel opt-out/provider configuration, bounded verification/retries and local controls during remote failure. Protect remote project data with single-use pairing, expiring revocable device/API grants, origin checks, authentication limits and private uncached responses; keep pairing secrets out of ordinary status and logs.
+- Fix GitHub Actions validation and its blocked publication by supplying repository-local planning fixture identity, excluding canonically unsafe Git-enumerated Books below Windows junctions, preserving full-width file IDs during agent deduplication, and closing finite fixture runtimes before deleting their workspaces. Require successful hosted check and publication outcomes for release acceptance and distinguish pending hosted verification from local checks.
+- Fix Windows planning saves silently missing their scoped commit by converting native relative paths to Git paths. Verify the actual reviewed Git blobs, preserve ignored writes as pending persistence, and strengthen hosted check/publication acceptance. Allow bounded Chrome startup under runner load and include bounded, redacted startup diagnostics on failure while retaining profiles and owned-process cleanup.

package/dist/coder/add-wizard.d.ts

@@ -0,0 +1,14 @@
+import type { Readable, Writable } from 'node:stream';
+import type { Workspace } from './domain.js';
+import { type PreparedAuthoredTask } from './authoring.js';
+/** Supplied authoring inputs are reused rather than asked for again. @private */
+export interface AddWizardOptions {
+    description?: string;
+    template?: string;
+    priority?: number;
+    signal?: AbortSignal;
+    input?: Readable;
+    output?: Writable;
+}
+/** Review exact task bytes in a finite wizard; cancellation never creates a task. @private */
+export declare function addTaskWizard(workspace: Workspace, options?: AddWizardOptions): Promise<PreparedAuthoredTask | undefined>;

package/dist/coder/add-wizard.js

@@ -0,0 +1,88 @@
+import { readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { prepareAuthoredTask } from './authoring.js';
+import { promptChoice } from './choices.js';
+import { promptText } from './interactive.js';
+import { installedEngineVersion } from './version.js';
+import { confinePath, InputError } from './workspace.js';
+/** Inspect the selected project's templates without creating files or following escaping links. */
+async function taskTemplates(workspace) {
+    const directory = await confinePath(workspace.projectPath, join(workspace.tasksPath, 'templates'));
+    try {
+        return (await readdir(directory, { withFileTypes: true })).filter(entry => entry.isFile() && /\.(?:book|md|txt)$/i.test(entry.name))
+            .sort((a, b) => a.name.localeCompare(b.name)).map(entry => ({ value: relative(workspace.projectPath, join(directory, entry.name)), label: entry.name }));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+/** Review exact task bytes in a finite wizard; cancellation never creates a task. @private */
+export async function addTaskWizard(workspace, options = {}) {
+    const version = await installedEngineVersion();
+    const surface = { input: options.input, output: options.output, signal: options.signal };
+    const heading = (step) => `Promptbook ${version} · Add task · ${step}/4`;
+    let description = options.description;
+    let template = options.template;
+    let priority = options.priority;
+    /** Keep descriptions in the shared multiline editor while enforcing nonempty authoring input. */
+    const describe = () => promptText('Task description', { ...surface, heading: heading(1), initial: description,
+        validate: value => value.trim() ? undefined : 'Describe the task before continuing.' });
+    /** Select existing templates with labels; an omitted template keeps the description as supplied. */
+    const selectTemplate = async () => {
+        const templates = await taskTemplates(workspace);
+        if (!templates.length) {
+            template = undefined;
+            return;
+        }
+        const choice = await promptChoice('Task template', [{ value: '@none', label: 'No template', description: 'Use the task description directly.' }, ...templates], {
+            ...surface, heading: heading(2), initial: template && templates.some(item => item.value === template) ? template : '@none',
+        });
+        template = choice === '@none' ? undefined : choice;
+    };
+    /** Offer common priorities while retaining arbitrary nonnegative priorities through a custom field. */
+    const selectPriority = async () => {
+        const choice = await promptChoice('Task priority (higher values run first)', [
+            { value: '0', label: 'Normal · 0' }, { value: '1', label: 'Raised · 1' },
+            { value: '2', label: 'High · 2' }, { value: '3', label: 'Urgent · 3' },
+            { value: 'custom', label: 'Custom priority…' },
+        ], { ...surface, heading: heading(3), initial: priority !== undefined && priority <= 3 ? String(priority) : priority === undefined ? '0' : 'custom' });
+        if (choice !== 'custom') {
+            priority = Number(choice);
+            return;
+        }
+        const value = await promptText('Custom nonnegative priority', { ...surface, heading: heading(3), initial: String(priority ?? 0),
+            validate: text => /^\d+$/.test(text.trim()) && Number.isSafeInteger(Number(text.trim())) ? undefined : 'Use a nonnegative safe integer.' });
+        priority = Number(value.trim());
+    };
+    if (description === undefined)
+        description = await describe();
+    if (!description.trim())
+        throw new InputError('A non-empty task description is required.');
+    if (options.template === undefined)
+        await selectTemplate();
+    if (options.priority === undefined)
+        await selectPriority();
+    for (;;) {
+        const prepared = await prepareAuthoredTask(workspace, description, { template, priority });
+        const action = await promptChoice('Review the task before saving', [
+            { value: 'save', label: 'Save this task' },
+            { value: 'description', label: 'Back to description' },
+            { value: 'template', label: 'Back to template' },
+            { value: 'priority', label: 'Back to priority' },
+            { value: 'cancel', label: 'Cancel without creating a task' },
+        ], { ...surface, heading: heading(4), initial: 'cancel', preview: `${relative(workspace.projectPath, prepared.path)}\n${prepared.content}` });
+        if (action === 'save')
+            return prepared;
+        if (action === 'cancel')
+            return undefined;
+        if (action === 'description')
+            description = await describe();
+        else if (action === 'template')
+            await selectTemplate();
+        else
+            await selectPriority();
+    }
+}
+//# sourceMappingURL=add-wizard.js.map

package/dist/coder/add-wizard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-wizard.js","sourceRoot":"","sources":["../../src/coder/add-wizard.ts"],"names":[],"mappings":"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"}

package/dist/coder/agent-identity.d.ts

@@ -0,0 +1,23 @@
+import { type AgentDefinition } from './agents.js';
+/** Offline artwork derived solely from an agent's canonical identity. @private */
+export interface AgentVisualIdentity {
+    id: string;
+    name: string;
+    color: string;
+    pattern: number[];
+    symbol: string;
+    mascot: {
+        left: string;
+        opening: string;
+        eyes: string;
+        body: string;
+        closing: string;
+        right: string;
+    };
+}
+/** Compose an offline Coder mascot from deliberate faces, silhouettes and appendages. @private */
+export declare function agentVisualIdentity(name: string): AgentVisualIdentity;
+/** Truthful activity labels are independent of appearance and never turn Void into a worker. @private */
+export declare function agentActivity(state: Record<string, any>): string;
+/** Attach display identities to observed references while retaining their exact execution values. @private */
+export declare function identifyRuntime(state: Record<string, any>, agents?: AgentDefinition[]): Record<string, any>;

package/dist/coder/agent-identity.js

@@ -0,0 +1,67 @@
+import { relative } from 'node:path';
+import { createHash } from 'node:crypto';
+import { normalizeAgentName, nonAgentReference } from './agents.js';
+/** Compose an offline Coder mascot from deliberate faces, silhouettes and appendages. @private */
+export function agentVisualIdentity(name) {
+    const canonical = nonAgentReference(name)?.name ?? name;
+    const id = normalizeAgentName(canonical);
+    const hash = createHash('sha256').update(`ptbk-avatar-v1:${id}`).digest();
+    const pattern = Array.from({ length: 25 }, (_, index) => (hash[Math.floor(index / 5) * 3 + Math.min(index % 5, 4 - index % 5)] & 1));
+    pattern[12] = 1;
+    const colors = ['#2563a6', '#9343a0', '#28764c', '#a04b23', '#7954b3', '#257c87'];
+    const faces = ['@@', 'oo', '00', '^^', '··', '••'];
+    const silhouettes = [['<', '>'], ['[', ']'], ['(', ')']];
+    const arms = [['~', '-'], ['=', '~'], ['_', '_'], ['^', '~'], ['~', '^'], ['-', '=']];
+    const silhouette = silhouettes[hash[17] % silhouettes.length];
+    const appendages = arms[hash[18] % arms.length];
+    const mascot = { left: appendages[0], opening: silhouette[0], eyes: faces[hash[19] % faces.length], body: '/', closing: silhouette[1], right: appendages[1] };
+    return { id, name: canonical, color: colors[hash[16] % colors.length], pattern,
+        mascot, symbol: `[${mascot.left}${mascot.opening}${mascot.eyes}${mascot.body}${mascot.closing}${mascot.right}]` };
+}
+/** Truthful activity labels are independent of appearance and never turn Void into a worker. @private */
+export function agentActivity(state) {
+    if (state.currentSelection?.visualIdentity?.id === 'void')
+        return 'Idle';
+    if (state.requests?.some((request) => request.taskId === state.currentTask && state.currentTask))
+        return 'Waiting for User';
+    if (['stopped', 'completed', 'interrupted', 'disconnected'].includes(state.status) || state.connection === 'disconnected')
+        return 'Idle';
+    if (state.paused && !state.running)
+        return 'Paused';
+    if (['blocked', 'failed', 'recovery-required', 'setup-required', 'sync-pending'].includes(state.status))
+        return 'Blocked / failed';
+    if (state.waiting)
+        return state.running ? 'Waiting for provider / pacing' : 'Waiting between prompts';
+    if (state.currentTask && state.running)
+        return state.phase === 'checking' ? 'Checking' : 'Working';
+    return 'Idle';
+}
+/** Attach display identities to observed references while retaining their exact execution values. @private */
+export function identifyRuntime(state, agents = []) {
+    /** Resolve file references through the discovered Book name; paths and Book bytes are never identity seeds. */
+    const identity = (reference, name) => {
+        if (name)
+            return agentVisualIdentity(name);
+        if (!reference)
+            return undefined;
+        const special = nonAgentReference(reference);
+        if (special)
+            return agentVisualIdentity(special.name);
+        const agent = agents.find(candidate => candidate.path === reference || candidate.normalizedName === normalizeAgentName(reference));
+        if (agent)
+            return agentVisualIdentity(agent.name);
+        return /[\\/]|\.book$|^https?:/.test(reference) ? undefined : agentVisualIdentity(reference);
+    };
+    /** Preserve historical attribution rather than assigning old messages to the currently active worker. */
+    const event = (entry) => ({ ...entry, visualIdentity: identity(entry.agent, entry.agentName) });
+    const selection = state.currentSelection;
+    const currentSelection = selection ? { ...selection, visualIdentity: identity(selection.agent, selection.agentName) } : undefined;
+    const result = { ...state, observedAt: Date.now(), currentSelection,
+        agents: agents.map(agent => ({ name: agent.name, hidden: agent.hidden, tier: agent.tier, path: relative(state.project ?? '.', agent.path), visualIdentity: agentVisualIdentity(agent.name) })).concat([{ name: 'Expert', hidden: true, tier: undefined, path: 'ptbk:expert', visualIdentity: agentVisualIdentity('Expert') }]),
+        tasks: (state.tasks ?? []).map((task) => ({ ...task, visualIdentity: identity(task.agent, task.agentName) })),
+        requests: (state.requests ?? []).map((request) => ({ ...request, visualIdentity: agentVisualIdentity('User') })),
+        events: (state.events ?? []).map(event),
+        ...(state.lastResult ? { lastResult: { ...state.lastResult, events: (state.lastResult.events ?? []).map(event) } } : {}), };
+    return { ...result, activity: agentActivity(result) };
+}
+//# sourceMappingURL=agent-identity.js.map

package/dist/coder/agent-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-identity.js","sourceRoot":"","sources":["../../src/coder/agent-identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAwB,MAAM,aAAa,CAAC;AAK1F,kGAAkG;AAClG,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC5C,MAAM,SAAS,GAAG,iBAAiB,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC;IACxD,MAAM,EAAE,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IAC1E,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IACtI,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAChB,MAAM,MAAM,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IAClF,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACnD,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IACtF,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,CAAC,EAAE,CAAE,GAAG,WAAW,CAAC,MAAM,CAAE,CAAC;IAChE,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAE,GAAG,IAAI,CAAC,MAAM,CAAE,CAAC;IAClD,MAAM,MAAM,GAAG,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAE,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAE,GAAG,KAAK,CAAC,MAAM,CAAE,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAE,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAE,EAAE,CAAC;IACpK,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAE,GAAG,MAAM,CAAC,MAAM,CAAE,EAAE,OAAO;QAC5E,MAAM,EAAE,MAAM,EAAE,IAAI,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,KAAK,GAAG,EAAE,CAAC;AAC1H,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,aAAa,CAAC,KAA0B;IACpD,IAAI,KAAK,CAAC,gBAAgB,EAAE,cAAc,EAAE,EAAE,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC;IACzE,IAAI,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,OAA4B,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,KAAK,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,WAAW,CAAC;QAAE,OAAO,kBAAkB,CAAC;IACjJ,IAAI,CAAC,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,UAAU,KAAK,cAAc;QAAE,OAAO,MAAM,CAAC;IACzI,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO;QAAE,OAAO,QAAQ,CAAC;IACpD,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,cAAc,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,kBAAkB,CAAC;IACnI,IAAI,KAAK,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,yBAAyB,CAAC;IACtG,IAAI,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;IACnG,OAAO,MAAM,CAAC;AAClB,CAAC;AAED,8GAA8G;AAC9G,MAAM,UAAU,eAAe,CAAC,KAA0B,EAAE,SAA4B,EAAE;IACtF,+GAA+G;IAC/G,MAAM,QAAQ,GAAG,CAAC,SAAkB,EAAE,IAAa,EAAmC,EAAE;QACpF,IAAI,IAAI;YAAE,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,SAAS;YAAE,OAAO,SAAS,CAAC;QACjC,MAAM,OAAO,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;QAC7C,IAAI,OAAO;YAAE,OAAO,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACtD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,SAAS,IAAI,SAAS,CAAC,cAAc,KAAK,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC;QACnI,IAAI,KAAK;YAAE,OAAO,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAClD,OAAO,wBAAwB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC;IACjG,CAAC,CAAC;IACF,yGAAyG;IACzG,MAAM,KAAK,GAAG,CAAC,KAA0B,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,cAAc,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACrH,MAAM,SAAS,GAAG,KAAK,CAAC,gBAAgB,CAAC;IACzC,MAAM,gBAAgB,GAAG,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,EAAE,cAAc,EAAE,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAClI,MAAM,MAAM,GAAG,EAAE,GAAG,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,gBAAgB;QAC/D,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,OAAO,IAAI,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,cAAc,EAAE,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,cAAc,EAAE,mBAAmB,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC9T,KAAK,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAyB,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,cAAc,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAClI,QAAQ,EAAE,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAA4B,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,cAAc,EAAE,mBAAmB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACrI,MAAM,EAAE,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;QACvC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,GAAG,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,GAC3H,CAAC;IACF,OAAO,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;AAC1D,CAAC"}

package/dist/coder/agents.d.ts

@@ -17,6 +17,7 @@ export interface AgentDefinition {
     path: string;
     hidden: boolean;
     learning: LearningPolicy;
+    tier?: 'agents' | 'project' | 'ignored';
 }
 /** Immutable Book snapshot used for one inference attempt. @private */
 export interface PreparedAgent {
@@ -44,11 +45,16 @@ export declare function nonAgentReference(reference: string): {
 export declare function agentLocalPath(path: string, projectPath: string): Promise<string>;
 /** Recognize public-network exclusions, including IPv4-mapped IPv6 literals. @private */
 export declare function isPrivateBookAddress(address: string): boolean;
-/** Discover canonical identities recursively, rejecting every ambiguity before selection. @private */
-export declare function discoverAgents(projectPath: string): Promise<AgentDefinition[]>;
+/** Discover winning identities in precedence order; ignored dependencies are searched only for explicit lookup. @private */
+export declare function discoverAgents(projectPath: string, options?: {
+    name?: string;
+    includeIgnored?: boolean;
+}): Promise<AgentDefinition[]>;
 /** Repair missing core definitions individually; existing custom Books are never overwritten. @private */
 export declare function ensureCoreAgents(projectPath: string): Promise<string[]>;
-/** Resolve a shared identity from its declaring Book; filenames never override name uniqueness. @private */
+/** Validate reference syntax without consuming prose after an unbraced @ token. @private */
+export declare function agentReferenceName(raw: string): string;
+/** Resolve a shared identity from its declaring Book using ordered, read-only lookup. @private */
 export declare function resolveAgentReference(raw: string, declaring: string, projectPath: string): Promise<string>;
 /** Resolve an inherited local MODEL without network, knowledge reads, setup or advisor calls. @private */
 export declare function readLocalAgentModel(agentPath: string, projectPath: string): Promise<string | undefined>;