ptbk 0.117.0-0 → 0.119.0-4

package/README.md

@@ -1,29 +1,40 @@
 # Promptbook (`ptbk`)
 
-`ptbk` is the repository’s single npm package. It installs the `ptbk` CLI for local coding tasks, with interchangeable coding harnesses, project checks, Git persistence, and a persistent loopback dashboard.
+Promptbook operates readable agent and task Books over a Git project. This repository publishes one npm package, `ptbk`, which installs the `ptbk` command. Runtime state, requests, traces and the shared browser profile live in ignored `.ptbk/` files.
 
-Requires Node.js 22.13+ in the Node 22 line, or Node 24+, npm 10+, and Git. macOS and Linux are target platforms; use WSL on Windows. Install a coding harness separately and authenticate with its provider.
+Requires Node.js 22.13+ in the Node 22 line, or Node 24+, and npm 10+.
 
 ```bash
 # Global installation
 npm install --global ptbk
-ptbk init --path ./my-project
+ptbk init --path ./project
 
-# Or install into a project
+# Project-local installation
 npm install --save-dev ptbk
 npx ptbk init
-npx ptbk add "Fix CSV quoting and add a regression test"
-npx ptbk list
-npx ptbk run --harness openai-codex --dry-run
-npx ptbk run --harness openai-codex --check "npm run check"
 ```
 
-The coder owns task state and commits. Harnesses receive instructions to leave commits to the coder. Initial project changes are preserved; the default run refuses a dirty working tree. Pull and push require explicit flags. `list` and `run --dry-run` are offline read-only operations.
+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.
 
-Current Codex account execution requires explicit `--allow-credits` because its CLI cannot enforce the default credit prohibition. Add that flag only when authorizing account credits; see [the credit policy and provider limits](docs/coder.md#harnesses-planning-and-team).
+```bash
+ptbk add "Implement the new behavior and its acceptance checks" --commit
+ptbk list
+ptbk run --dry-run
+ptbk start                     # background agenda, localhost 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
+```
+
+`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.
+
+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.
 
-New work is stored as task Books under `tasks/`. Existing top-level Markdown tasks under `prompts/` remain supported by the same engine. Agent Books under `agents/` define roles and are distinct from task Books.
+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).
 
-See [the coder guide](docs/coder.md), [compatibility and verification](docs/compatibility.md), `ptbk --help`, and [the specification](https://github.com/webgptorg/promptbook/blob/main/specs/_main.md). Run `npm run check` to verify the build, deterministic fixtures, and installation of the actual npm tarball in an external project.
+For development, use `npm ci` and `npm run check`. Checks validate types, deterministic integration fixtures and real tarball installations in disposable external projects. CI runs on Linux, macOS and Windows with Node 22 and 24.
 
-This prerelease replaces the old collection of npm packages. Publishing runs only in GitHub Actions when a `vVERSION` tag is pushed. From a clean, committed tree on a named branch, `npm run release:preminor` or `npm run release:prerelease` checks the release, creates npm's version commit/tag, and atomically pushes the branch and exact tag. Normal releases, including numeric prereleases, use `latest` so the default install gets the current CLI. See [release and push-retry instructions](docs/coder.md#releasing).
+For releases, run `npm version patch`, `npm version minor`, or `npm version prerelease` on a clean named branch after committing your work. Basic `preversion` checks run locally; `postversion` atomically pushes the version commit and exact `vVERSION` tag. GitHub Actions checks and publishes only `ptbk` with npm provenance, then verifies the public registry and installed CLI. Configure npm trusted publishing once as described in [releasing](docs/releasing.md).

package/bin/ptbk.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-/** Runs the compiled CLI from either a local or global npm installation. */
-import('../dist/coder/cli.js')
-    .then(async ({ main }) => { process.exitCode = await main(process.argv.slice(2)); })
-    .catch(error => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });
+
+/** Load the runtime relative to this installation, independently of the project directory. */
+import('../dist/cli.js').then(({ main }) => main()).catch((error) => {
+    process.stderr.write(`ptbk: ${error.message}\n`);
+    process.exitCode = 1;
+});

package/changelog/_current-preversion.md

@@ -1,57 +1,22 @@
--   Removed npm installation deprecation warnings by upgrading ESLint from 8 to 10 and refreshing the lockfile.
-    Migrated to flat configuration, preserving custom rules and file overrides, and installed the previously
-    missing TypeScript lint dependencies and runtime global definitions.
-    Updated the declared Node.js requirement to 22.13+ in the Node 22 line, or 24+.
--   Replaced the former multi-package publishing pipeline with the single `ptbk` CLI package,
-    versioned as a pre-minor prerelease. Added compiled executable packaging,
-    release/version validation, npm prerelease tags, version-tag-triggered GitHub publication,
-    macOS/Linux CI, external local/global installation checks, and post-publication registry
-    version, dist-tag, artifact integrity and executable verification. Node 22.13+ is required.
--   Restricted npm publication to the official repository's GitHub Actions release job.
-    Local npm version hooks check types, metadata, a named branch and clean tracked/untracked
-    tree, create the normal version commit/tag, and atomically push the current
-    branch and exact new tag to trigger CI. Failed pushes can be retried with
-    `npm run postversion`; local registry verification remains available without publishing.
--   Wait for npm registry propagation after a successful upload instead of failing on the
-    first temporary missing-version response. Keep verification bounded and reject invalid
-    artifact metadata and authentication failures immediately.
--   Restore `latest` as the npm channel for normal `ptbk` releases, including numeric
-    prereleases, so default local/global installs receive the current coder CLI instead
-    of the legacy package. Verify unversioned installs against the released version and
-    clarify npm's selected-version publication date versus package-wide last publication.
--   Implemented the coder task engine with legacy Markdown and task Books, strict scheduling,
-    recurrence, deterministic migration, project initialization and authoring, safe Git/check
-    phase persistence, recovery journals, harness adapters, agent context and TEAM tools,
-    read-only planning, human verification, and a protected loopback persistent dashboard.
-    Read-only previews report blocked/future tasks without initializing or calling models.
-    Restored legacy trace filenames while preserving immutable occurrence records and exact
-    finalization outcomes in journals. This prerelease refuses Qwen/Cline TEAM before inference;
-    they require an agent without TEAM. OpenCode TEAM requires an explicit qualified model.
--   Codex account inference now requires either an advertised provider credit-prohibition
-    capability or explicit `--allow-credits`. Current Codex versions without that capability
-    are refused before inference, including accounts with remaining included usage. Account
-    and API authentication are forced explicitly; generated scripts never opt into credits.
--   Reorganized the specifications around `specs/_main.md`, splitting coder contracts into focused,
-    interlinked files and expanding the dictionary into a linked term index. Preserved the dated
-    audit, acceptance IDs and lower-authority historical agent/server specs in `specs/deprecated/`,
-    repaired specification links, and left `old-prompts` and implementation code untouched.
--   Translated all organized specifications into English, including examples and cross-reference labels,
-    updated heading links, and simplified the dictionary to linked bullet points. The `old-prompts` archive
-    and implementation code remain unchanged.
--   Simplified prose-heavy specification tables into bullet points and a numbered delivery list,
-    retaining tables for compact state/harness comparisons, module ownership and reference resolution.
--   Defined Promptbook in the specifications solely as the `ptbk` CLI, replacing the nested coder
-    commands with top-level workflows, grouping the contracts under `specs/cli/`, and retaining
-    the broader APT framework/server vision as historical material. Preserved legacy identifiers
-    and source references for compatibility; implementation code and `old-prompts` are unchanged.
--   Restored the compiled TypeScript CLI after the implementation cleanup and moved every workflow
-    to the top-level `ptbk` commands, including initialization, execution, checks, planning,
-    migration, recovery and the persistent dashboard. Historical storage paths and task markers
-    retain their compatibility meaning. The removed `coder` command group now explains the replacement.
--   Initialization upgrades only exact recognized generated npm callers, supplies root-command
-    run/list/fix/plan scripts, and diagnoses custom legacy scripts/workflows without rewriting them.
-    Checks reject both root and historical worker invocations, including indirect npm-script recursion.
--   Release preflight now rejects dirty/detached checkouts before doing other work and verifies the
-    compiled build before npm changes the version. CI checks all branches on macOS/Linux and Node 22/24;
-    publication remains restricted to the single `ptbk` package through GitHub Actions. Updated the
-    packed local/global installation regressions and documentation to exercise root commands.
+- Implement the complete `ptbk` runtime from the current specification, including modern task Books and legacy Markdown, normalized agent discovery and inheritance, core roles, Manager assignment, Expert agenda bootstrap, TEAM consultations and OPEN/CLOSED Teacher follow-ups.
+- Add finite checked execution and continuous project supervision with one task at a time, dated completion and implementation in one result commit, bounded retries, safe staging, recovery journals, synchronization and isolated worktree integration.
+- Add project-specific daemon/raw/interactive modes, authenticated shared CLI/terminal/dashboard/API controls, durable questions and answers, browser CDP tools with persistent sessions, and current-user startup persistence for Linux, macOS and Windows.
+- Preserve custom initialization files and routing requirements, schedule prerequisites and recurrence, and materialize bounded goal enquiries only when unfinished present/future work is exhausted.
+- Publish only the installable root `ptbk` npm package. Add local npm version preflight and atomic branch/tag push, tagged GitHub Actions publication with OIDC/provenance, and bounded public registry/default installation verification.
+- Validate Node 22/24 installations on Linux/macOS/Windows, deterministic provider and recovery fixtures, real local browser sessions where available, and checked task execution from local/global tarball installations in disposable external projects.
+- 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.

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+/** Return the selected installation's package version, independently of project metadata. @private */
+export declare function installedVersion(): Promise<string>;
+/** Run the installed root command and preserve its documented exit status. @private */
+export declare function main(args?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,11 @@
+import { readFile } from 'node:fs/promises';
+import { main as runCli } from './coder/cli.js';
+/** Return the selected installation's package version, independently of project metadata. @private */
+export async function installedVersion() {
+    return JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version;
+}
+/** Run the installed root command and preserve its documented exit status. @private */
+export async function main(args = process.argv.slice(2)) {
+    process.exitCode = await runCli(args);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,IAAI,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAEhD,sGAAsG;AACtG,MAAM,CAAC,KAAK,UAAU,gBAAgB;IAClC,OAAQ,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAyB,CAAC,OAAO,CAAC;AAC5H,CAAC;AAED,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,OAAiB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7D,OAAO,CAAC,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;AAC1C,CAAC"}

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":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAG3C,OAAO,EAAE,mBAAmB,EAA6B,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAQzD,mGAAmG;AACnG,KAAK,UAAU,aAAa,CAAC,SAAoB;IAC7C,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IACnG,IAAI,CAAC;QACD,OAAO,CAAC,MAAM,OAAO,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;aAC/H,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACjK,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAAC,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAAC,MAAM,KAAK,CAAC;IAAC,CAAC;AACvG,CAAC;AAED,8FAA8F;AAC9F,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,SAAoB,EAAE,UAA4B,EAAE;IACpF,MAAM,OAAO,GAAG,MAAM,sBAAsB,EAAE,CAAC;IAC/C,MAAM,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IACzF,MAAM,OAAO,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,cAAc,OAAO,iBAAiB,IAAI,IAAI,CAAC;IACzF,IAAI,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACtC,IAAI,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAChC,IAAI,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAChC,iGAAiG;IACjG,MAAM,QAAQ,GAAG,GAAoB,EAAE,CAAC,UAAU,CAAC,kBAAkB,EAAE,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW;QAC1H,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,sCAAsC,EAAE,CAAC,CAAC;IAC5F,oGAAoG;IACpG,MAAM,cAAc,GAAG,KAAK,IAAmB,EAAE;QAC7C,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,SAAS,CAAC,CAAC;QACjD,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;YAAC,QAAQ,GAAG,SAAS,CAAC;YAAC,OAAO;QAAC,CAAC;QACxD,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,eAAe,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,oCAAoC,EAAE,EAAE,GAAG,SAAS,CAAC,EAAE;YAC5J,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO;SAC7H,CAAC,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;IACvD,CAAC,CAAC;IACF,uGAAuG;IACvG,MAAM,cAAc,GAAG,KAAK,IAAmB,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,yCAAyC,EAAE;YACzE,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE;YACxE,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE;YACtE,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,kBAAkB,EAAE;SACjD,EAAE,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,KAAK,SAAS,IAAI,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;QACvJ,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;YAAC,OAAO;QAAC,CAAC;QAC/D,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,6BAA6B,EAAE,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC;YAC3H,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,iCAAiC,EAAE,CAAC,CAAC;QAChJ,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC;IACF,IAAI,WAAW,KAAK,SAAS;QAAE,WAAW,GAAG,MAAM,QAAQ,EAAE,CAAC;IAC9D,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE;QAAE,MAAM,IAAI,UAAU,CAAC,2CAA2C,CAAC,CAAC;IAC3F,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;QAAE,MAAM,cAAc,EAAE,CAAC;IAC3D,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;QAAE,MAAM,cAAc,EAAE,CAAC;IAC3D,SAAS,CAAC;QACN,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,SAAS,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC3F,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,+BAA+B,EAAE;YAC/D,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE;YAC1C,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,qBAAqB,EAAE;YACtD,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,kBAAkB,EAAE;YAChD,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,kBAAkB,EAAE;YAChD,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,gCAAgC,EAAE;SAC/D,EAAE,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,SAAS,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC9I,IAAI,MAAM,KAAK,MAAM;YAAE,OAAO,QAAQ,CAAC;QACvC,IAAI,MAAM,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC1C,IAAI,MAAM,KAAK,aAAa;YAAE,WAAW,GAAG,MAAM,QAAQ,EAAE,CAAC;aACxD,IAAI,MAAM,KAAK,UAAU;YAAE,MAAM,cAAc,EAAE,CAAC;;YAClD,MAAM,cAAc,EAAE,CAAC;IAChC,CAAC;AACL,CAAC"}

package/dist/coder/agents.d.ts

@@ -3,18 +3,56 @@ export interface TeamMember {
     name: string;
     path: string;
     declaringPath: string;
+    kind?: 'agent' | 'expert' | 'user' | 'void';
+}
+/** Learning permission belongs to the local Book, independently of its ancestors. @private */
+export interface LearningPolicy {
+    open: boolean;
+    limits?: string;
+}
+/** A discovered project identity, including hidden supporting definitions. @private */
+export interface AgentDefinition {
+    name: string;
+    normalizedName: string;
+    path: string;
+    hidden: boolean;
+    learning: LearningPolicy;
 }
 /** Immutable Book snapshot used for one inference attempt. @private */
 export interface PreparedAgent {
+    name: string;
+    path: string;
     instructions: string;
     aliases: string[];
     team: TeamMember[];
+    learning: LearningPolicy;
+    sources: Record<string, string>;
     model?: string;
     modelParameters?: Record<string, string>;
 }
+/** Missing core definitions are created from these installed-engine defaults only. @private */
+export declare const CORE_BOOKS: Readonly<Record<string, string>>;
+/** Normalize identity across case, diacritics, separators and camel case. @private */
+export declare function normalizeAgentName(name: string): string;
+/** Resolve engine-owned identities without consulting or materializing project files. @private */
+export declare function nonAgentReference(reference: string): {
+    name: string;
+    path: string;
+    kind: 'expert' | 'user' | 'void';
+} | undefined;
 /** Resolve a local file without allowing a symlink to escape the selected project. @private */
 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;
-/** Compile persona, local/remote inheritance, knowledge and distinct advisor tools. @private */
+/** Discover canonical identities recursively, rejecting every ambiguity before selection. @private */
+export declare function discoverAgents(projectPath: string): 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 */
+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>;
+/** Compile immutable instruction provenance, inheritance, knowledge and distinct TEAM tools. @private */
 export declare function prepareAgent(agentPath: string, projectPath: string): Promise<PreparedAgent>;
+/** Validate every effective local Book before unattended execution, including hidden supporting roles. @private */
+export declare function validateAgents(projectPath: string): Promise<PreparedAgent[]>;