@agentage/cli 0.38.0 → 0.39.0

package/dist/cli.js

@@ -3,8 +3,10 @@
 const nodeMajor = Number(process.versions.node.split('.')[0]);
 if (nodeMajor < 22) {
     process.stderr.write(`agentage requires Node.js >= 22 (you have v${process.versions.node})\n`);
-    process.exit(1);
+    process.exitCode = 1;
+}
+else {
+    const { run } = await import('./program.js');
+    process.exitCode = await run();
 }
-const { run } = await import('./program.js');
-await run();
 export {};

package/dist/commands/auth/setup.d.ts

@@ -1,20 +1,12 @@
 import { type Command } from 'commander';
-import { startCallbackServer } from '../../lib/auth/callback-server.js';
-import { introspectToken } from '../../lib/auth/api.js';
-import { exchangeCode, registerClient, revokeToken } from '../../lib/auth/oauth.js';
-export interface SetupOptions {
+import { type SignInOptions, type SignInResult } from '../../lib/auth/sign-in.js';
+export interface SetupOptions extends SignInOptions {
     disconnect?: boolean;
-    reauth?: boolean;
-    browser?: boolean;
 }
 export interface SetupDeps {
-    register: typeof registerClient;
-    exchange: typeof exchangeCode;
-    revoke: typeof revokeToken;
-    startServer: typeof startCallbackServer;
-    openBrowser: (url: string) => Promise<void>;
+    ensureSignedIn: (opts: SignInOptions) => Promise<SignInResult>;
+    signOut: () => Promise<void>;
     printStatus: () => Promise<void>;
-    introspect: typeof introspectToken;
 }
-export declare const runSetup: (opts: SetupOptions, deps?: SetupDeps) => Promise<void>;
-export declare const registerSetup: (program: Command) => void;
+export declare const runSetup: (opts: SetupOptions, deps: SetupDeps) => Promise<void>;
+export declare const registerSetup: (program: Command, action: (opts: SetupOptions) => Promise<void>) => void;

package/dist/commands/auth/setup.js

@@ -1,129 +1,17 @@
-import chalk from 'chalk';
-import { startCallbackServer } from '../../lib/auth/callback-server.js';
-import { deleteAuth, ensureConfigDir, mutateAuth, readAuth, } from '../../lib/fs/config.js';
-import { AuthRequiredError, introspectToken } from '../../lib/auth/api.js';
-import { detectEnvMismatch } from '../../lib/auth/env-match.js';
-import { buildAuthorizeUrl, exchangeCode, pkcePair, randomState, registerClient, revokeToken, } from '../../lib/auth/oauth.js';
-import { links, siteFqdn } from '../../lib/net/origins.js';
-import { runStatus } from '../status/status.js';
-const defaultDeps = {
-    register: registerClient,
-    exchange: exchangeCode,
-    revoke: revokeToken,
-    startServer: startCallbackServer,
-    openBrowser: async (url) => {
-        const { default: open } = await import('open');
-        await open(url);
-    },
-    printStatus: () => runStatus({}),
-    introspect: introspectToken,
+import {} from 'commander';
+import {} from '../../lib/auth/sign-in.js';
+export const runSetup = async (opts, deps) => {
+    if (opts.disconnect)
+        return deps.signOut();
+    await deps.ensureSignedIn({ reauth: opts.reauth, browser: opts.browser });
+    await deps.printStatus();
 };
-const toAuthState = (fqdn, clientId, tokens) => ({
-    siteFqdn: fqdn,
-    clientId,
-    tokens: {
-        accessToken: tokens.access_token,
-        refreshToken: tokens.refresh_token,
-        expiresAt: tokens.expires_in ? Date.now() + tokens.expires_in * 1000 : undefined,
-    },
-});
-const disconnect = async (deps) => {
-    const auth = readAuth();
-    if (!auth) {
-        console.log('Nothing to disconnect.');
-        return;
-    }
-    await deps.revoke(links(auth.siteFqdn).auth, auth.tokens.accessToken);
-    await deleteAuth();
-    console.log('Disconnected - local credentials removed.');
-};
-// Validate the stored session instead of trusting mere token presence. Returns true to short-circuit
-// (valid or a transient blip - creds intact), false to proceed into a fresh sign-in (truly expired or
-// the credential belongs to a different target than the current run).
-const alreadySignedIn = async (auth, deps) => {
-    const mismatch = detectEnvMismatch(auth, siteFqdn());
-    if (mismatch) {
-        console.log(`Signed in to ${mismatch.credentialFqdn} (${mismatch.credentialEnv}), but this run targets ` +
-            `${mismatch.targetFqdn} (${mismatch.targetEnv}) - signing you into ${mismatch.targetEnv}.\n`);
-        return false; // proceed to a fresh sign-in against the current target
-    }
-    try {
-        await deps.introspect(auth, links(auth.siteFqdn));
-        console.log(`Already signed in. Run ${chalk.white('agentage setup --reauth')} to sign in again.\n`);
-        await deps.printStatus();
-        return true;
-    }
-    catch (err) {
-        if (err instanceof AuthRequiredError) {
-            console.log('Session expired - signing you in again.\n');
-            return false; // fall through to the sign-in flow, no --reauth needed
-        }
-        // Transient: do not force reauth on a blip; keep credentials and show status.
-        console.log('You appear signed in (could not fully verify - temporary).\n');
-        await deps.printStatus();
-        return true;
-    }
-};
-export const runSetup = async (opts, deps = defaultDeps) => {
-    if (opts.disconnect) {
-        await disconnect(deps);
-        return;
-    }
-    const stored = readAuth();
-    if (stored && !opts.reauth && (await alreadySignedIn(stored, deps)))
-        return;
-    const fqdn = siteFqdn();
-    const target = links(fqdn);
-    ensureConfigDir();
-    const { verifier, challenge } = pkcePair();
-    const state = randomState();
-    const server = await deps.startServer(state);
-    try {
-        const clientId = await deps.register(target.auth, server.redirectUri);
-        const url = buildAuthorizeUrl(target.auth, {
-            clientId,
-            redirectUri: server.redirectUri,
-            challenge,
-            state,
-        });
-        console.log(`\nSign in to agentage (${fqdn}):\n\n  ${url}\n`);
-        if (opts.browser === false)
-            console.log('Open the URL above in a browser to continue.');
-        else
-            await deps
-                .openBrowser(url)
-                .catch(() => console.log('Could not open a browser - use the URL above.'));
-        console.log('Waiting for sign-in to complete...');
-        const code = await server.waitForCode();
-        const tokens = await deps.exchange(target.auth, {
-            clientId,
-            code,
-            redirectUri: server.redirectUri,
-            verifier,
-        });
-        await mutateAuth(() => toAuthState(fqdn, clientId, tokens));
-        console.log(chalk.green('\nSigned in.\n'));
-        await deps.printStatus();
-    }
-    finally {
-        server.close();
-    }
-};
-export const registerSetup = (program) => {
+export const registerSetup = (program, action) => {
     program
         .command('setup')
         .description('Sign in and connect this machine to your agentage account')
         .option('--disconnect', 'sign out and remove local credentials')
         .option('--reauth', 'force a fresh sign-in')
         .option('--no-browser', 'print the sign-in URL instead of opening a browser')
-        .action(async (opts) => {
-        try {
-            await runSetup(opts);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            console.error(chalk.red(`Setup failed: ${message}`));
-            process.exitCode = 1;
-        }
-    });
+        .action(action);
 };

package/dist/commands/plugins/status-print.d.ts

@@ -0,0 +1,2 @@
+import { type PluginsStatus } from './status-rows.js';
+export declare const pluginStatusLines: (status: PluginsStatus) => string[];

package/dist/commands/plugins/status-print.js

@@ -0,0 +1,44 @@
+import chalk from 'chalk';
+import {} from '../../core/loader/states.js';
+import {} from './status-rows.js';
+const COLOR = {
+    installed: chalk.green,
+    off: chalk.dim,
+    blocked: chalk.yellow,
+    invalid: chalk.red,
+    missing: chalk.yellow,
+};
+const STATE_WIDTH = Math.max(...Object.keys(COLOR).map((state) => state.length));
+const line = (label, value) => `${label.padEnd(10)} ${value}`;
+const profileText = (profile) => {
+    if (profile.state === 'missing')
+        return 'no profile';
+    if (profile.state === 'invalid')
+        return chalk.red('profile.json is invalid');
+    const readOnly = profile.readOnly ? chalk.yellow(', read-only') : '';
+    return `version ${profile.version} (source: ${profile.source}${readOnly})`;
+};
+const lastRunText = (run) => {
+    if (run === null)
+        return '';
+    const error = run.error === null ? '' : ` "${run.error}"`;
+    return `  last run: ${run.state}${error} at ${run.at}`;
+};
+const pluginLine = (row, idWidth) => {
+    const id = (row.id ?? '?').padEnd(idWidth);
+    const state = COLOR[row.state](row.state.padEnd(STATE_WIDTH));
+    const wanted = row.mode === 'dev' ? 'dev' : `wants ${row.wanted ?? '?'}`;
+    const pkg = `${row.package} ${row.installed ?? '-'} (${wanted})`;
+    const commands = row.commands.length > 0 ? `  commands: ${row.commands.join(', ')}` : '';
+    const error = row.error === null ? '' : chalk.dim(`  ${row.error}`);
+    return `  ${id}  ${state}  ${pkg}${commands}${lastRunText(row.lastRun)}${error}`;
+};
+export const pluginStatusLines = (status) => {
+    const idWidth = Math.max(0, ...status.plugins.map((row) => (row.id ?? '?').length));
+    return [
+        line('machine', `${status.machine.id} (${status.machine.name})`),
+        line('profile', profileText(status.profile)),
+        line('plugins', status.plugins.length === 0 ? 'none' : String(status.plugins.length)),
+        ...status.plugins.map((row) => pluginLine(row, idWidth)),
+    ];
+};

package/dist/commands/plugins/status-rows.d.ts

@@ -0,0 +1,51 @@
+import { type DiscoverInput, type Discovery } from '../../core/loader/discover.js';
+import { type RunState } from '../../core/loader/state.js';
+import { type StaticState } from '../../core/loader/states.js';
+import { type MachineFile, type ProfileSource } from '../../core/profile/machine.js';
+import { type ProfileParse } from '../../core/profile/schema.js';
+export interface PluginRow {
+    id: string | null;
+    package: string;
+    mode: 'installed' | 'dev';
+    wanted: string | null;
+    installed: string | null;
+    state: StaticState;
+    error: string | null;
+    commands: string[];
+    lastRun: {
+        at: string;
+        state: string;
+        error: string | null;
+    } | null;
+}
+export type ProfileStatus = {
+    state: 'missing';
+} | {
+    state: 'invalid';
+    errors: string[];
+} | {
+    state: 'ok';
+    version: number;
+    source: ProfileSource;
+    readOnly: boolean;
+};
+export interface PluginsStatus {
+    machine: {
+        id: string;
+        name: string;
+    };
+    profile: ProfileStatus;
+    plugins: PluginRow[];
+}
+export interface PluginsGather {
+    status: PluginsStatus;
+    warnings: string[];
+}
+export interface StatusRowsDeps {
+    loadMachine: () => Promise<MachineFile>;
+    readProfile: () => ProfileParse | null;
+    discover: (input: DiscoverInput) => Discovery;
+    readRunState: (id: string) => RunState | null;
+    pluginsDir: () => string;
+}
+export declare const gatherPluginStatus: (deps?: StatusRowsDeps) => Promise<PluginsGather>;

package/dist/commands/plugins/status-rows.js

@@ -0,0 +1,58 @@
+import { discover, } from '../../core/loader/discover.js';
+import { readRunState } from '../../core/loader/state.js';
+import { staticStates } from '../../core/loader/states.js';
+import { pluginsDir } from '../../core/paths.js';
+import { loadMachine } from '../../core/profile/machine.js';
+import { effective } from '../../core/profile/merge.js';
+import { readProfile } from '../../core/profile/profile.js';
+import {} from '../../core/profile/schema.js';
+const defaultDeps = {
+    loadMachine: () => loadMachine(),
+    readProfile: () => readProfile(),
+    discover: (input) => discover(input),
+    readRunState: (id) => readRunState(id),
+    pluginsDir,
+};
+const profileStatus = (parsed, machine) => {
+    if (parsed === null)
+        return { state: 'missing' };
+    if (!parsed.ok)
+        return { state: 'invalid', errors: parsed.errors };
+    const { version } = parsed.profile;
+    return { state: 'ok', version, source: machine.profileSource, readOnly: parsed.readOnly };
+};
+// A row for an invalid manifest has no trustworthy id, so it never shows another plugin's run.
+const lastRunOf = (p, s, deps) => {
+    const run = p.id === null || s.state === 'invalid' ? null : deps.readRunState(p.id);
+    return run && { at: run.at, state: run.state, error: run.error };
+};
+const toRow = (p, eff, s, deps) => ({
+    id: p.id,
+    package: p.pkg,
+    mode: p.source === 'dev' ? 'dev' : 'installed',
+    wanted: eff.install[p.pkg] ?? null,
+    installed: p.version,
+    state: s.state,
+    error: s.error,
+    commands: p.commands,
+    lastRun: lastRunOf(p, s, deps),
+});
+const UNKNOWN = { state: 'invalid', error: null };
+// Reads manifests, profile and state files; writes only a missing machine.json.
+export const gatherPluginStatus = async (deps = defaultDeps) => {
+    const machine = await deps.loadMachine();
+    const parsed = deps.readProfile();
+    const eff = effective(parsed?.ok ? parsed.profile : null, machine);
+    const names = Object.keys(eff.install);
+    const found = deps.discover({ pluginsDir: deps.pluginsDir(), names, dev: eff.dev });
+    const states = staticStates(found.plugins, eff.off);
+    const plugins = found.plugins
+        .map((p) => toRow(p, eff, states.get(p.pkg) ?? UNKNOWN, deps))
+        .sort((a, b) => (a.package < b.package ? -1 : 1));
+    const status = {
+        machine: { id: machine.id, name: machine.name },
+        profile: profileStatus(parsed, machine),
+        plugins,
+    };
+    return { status, warnings: [...(parsed?.ok ? parsed.warnings : []), ...found.warnings] };
+};

package/dist/commands/status/status.d.ts

@@ -1,8 +1,14 @@
 import { type Command } from 'commander';
 import { type StatusReport } from '../../lib/status/status-info.js';
+import { type PluginsGather } from '../plugins/status-rows.js';
 export declare const printStatus: (report: StatusReport) => void;
-export declare const runStatus: (opts?: {
+export interface StatusOptions {
     json?: boolean;
     token?: string;
-}) => Promise<void>;
-export declare const registerStatus: (program: Command) => void;
+}
+export interface StatusDeps {
+    gather: (opts: StatusOptions) => Promise<StatusReport>;
+    plugins: () => Promise<PluginsGather | null>;
+}
+export declare const runStatus: (opts?: StatusOptions, deps?: StatusDeps) => Promise<void>;
+export declare const registerStatus: (program: Command, action: (opts: StatusOptions) => Promise<void>) => void;

package/dist/commands/status/status.js

@@ -1,8 +1,12 @@
 import chalk from 'chalk';
+import {} from 'commander';
+import { pluginsEnabled } from '../../core/flag.js';
 import { resolveAuth } from '../../lib/auth/credentials.js';
 import { siteFqdn } from '../../lib/net/origins.js';
 import { gatherStatus } from '../../lib/status/status-info.js';
 import { INSTALL_HINT } from '../../lib/update/update-check.js';
+import { pluginStatusLines } from '../plugins/status-print.js';
+import { gatherPluginStatus } from '../plugins/status-rows.js';
 const mark = (good) => (good ? chalk.green('✓') : chalk.red('✗'));
 const row = (label, value) => {
     console.log(`${label.padEnd(10)} ${value}`);
@@ -46,19 +50,60 @@ export const printStatus = (report) => {
     if (report.update.message)
         console.log(chalk.yellow(`\n${report.update.message}`));
 };
-export const runStatus = async (opts = {}) => {
-    const report = await gatherStatus(resolveAuth({ token: opts.token }), siteFqdn());
-    if (opts.json) {
-        console.log(JSON.stringify(report, null, 2));
+const defaultDeps = {
+    gather: (opts) => gatherStatus(resolveAuth({ token: opts.token }), siteFqdn()),
+    plugins: () => (pluginsEnabled() ? gatherPluginStatus() : Promise.resolve(null)),
+};
+const settle = async (deps) => {
+    try {
+        return { gathered: await deps.plugins(), error: null };
+    }
+    catch (error) {
+        return { gathered: null, error };
+    }
+};
+const emit = (report, gathered, json) => {
+    if (json) {
+        console.log(JSON.stringify(gathered ? { ...report, ...gathered.status } : report, null, 2));
         return;
     }
     printStatus(report);
+    for (const text of gathered ? pluginStatusLines(gathered.status) : [])
+        console.log(text);
+};
+const profileFailure = (gathered) => {
+    const profile = gathered?.status.profile;
+    if (profile?.state !== 'invalid')
+        return null;
+    return new Error(`profile.json is invalid:\n${profile.errors.map((e) => `  ${e}`).join('\n')}`);
+};
+// The report always prints; a plugin-side failure then fails the step (exit 1) on stderr.
+export const runStatus = async (opts = {}, deps = defaultDeps) => {
+    const report = await deps.gather(opts);
+    const { gathered, error } = await settle(deps);
+    emit(report, gathered, opts.json);
+    for (const warning of gathered?.warnings ?? [])
+        console.error(chalk.yellow(`warning: ${warning}`));
+    if (error)
+        throw error;
+    const failure = profileFailure(gathered);
+    if (failure)
+        throw failure;
 };
-export const registerStatus = (program) => {
-    program
+const PLUGINS_HELP = `
+Plugins: one row per plugin in the profile or a dev path: id, state (installed, off,
+blocked, invalid, missing), package, installed version, wanted range, contributed commands,
+the last run from state/<id>.json, and the reason when it cannot load. Plugin code is never
+loaded; the only file written is machine.json.`;
+export const registerStatus = (program, action) => {
+    const command = program
         .command('status')
-        .description('Show CLI, account, and endpoint status')
+        .description(pluginsEnabled()
+        ? 'Show CLI, account, endpoint, machine, profile, and plugin status'
+        : 'Show CLI, account, and endpoint status')
         .option('--json', 'machine-readable output')
         .option('--token <token>', 'authenticate with a personal access token (aga_...); or set AGENTAGE_TOKEN')
-        .action(runStatus);
+        .action(action);
+    if (pluginsEnabled())
+        command.addHelpText('after', PLUGINS_HELP);
 };

package/dist/commands/update/update.d.ts

@@ -1,5 +1,7 @@
 import { type Command } from 'commander';
+import { requireNpm10, runNpm } from '../../lib/npm/npm-cli.js';
 import { type UpdateInfo } from '../../lib/update/update-check.js';
+export declare const installLatest: (run?: typeof runNpm, check?: typeof requireNpm10) => Promise<void>;
 export interface UpdateDeps {
     check: (installed: string) => Promise<UpdateInfo>;
     install: () => Promise<void>;
@@ -11,4 +13,4 @@ export interface UpdateOptions {
     check?: boolean;
 }
 export declare const runUpdate: (opts: UpdateOptions, deps?: UpdateDeps) => Promise<void>;
-export declare const registerUpdate: (program: Command) => void;
+export declare const registerUpdate: (program: Command, action: (opts: UpdateOptions) => Promise<void>) => void;

package/dist/commands/update/update.js

@@ -1,17 +1,30 @@
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
+import { join } from 'node:path';
 import chalk from 'chalk';
+import {} from 'commander';
+import { getConfigDir } from '../../lib/fs/config.js';
+import { acquireFileLock, releaseFileLock } from '../../lib/fs/file-lock.js';
+import { requireNpm10, runNpm } from '../../lib/npm/npm-cli.js';
 import { checkForUpdate, INSTALL_HINT } from '../../lib/update/update-check.js';
-import { acquireUpdateLock, releaseUpdateLock } from '../../lib/update/update-lock.js';
 import { VERSION } from '../../utils/version.js';
-const pexec = promisify(execFile);
+const INSTALL_TIMEOUT_MS = 5 * 60_000;
+const NPM_TAIL_LINES = 10;
+// An install takes minutes, so the crashed-holder ages scale up from the config-write defaults.
+const UPDATE_LOCK = { ttlMs: 10 * 60_000, hardStaleMs: 30 * 60_000 };
+const updateLockTarget = () => join(getConfigDir(), 'update');
+const tail = (text) => text.trimEnd().split('\n').slice(-NPM_TAIL_LINES).join('\n');
+export const installLatest = async (run = runNpm, check = requireNpm10) => {
+    await check(run);
+    const res = await run(['install', '-g', '@agentage/cli@latest'], {
+        timeoutMs: INSTALL_TIMEOUT_MS,
+    });
+    if (res.code !== 0)
+        throw new Error(`npm install failed (exit ${res.code}):\n${tail(res.stderr || res.stdout)}`);
+};
 const defaultDeps = {
     check: checkForUpdate,
-    install: async () => {
-        await pexec('npm', ['install', '-g', '@agentage/cli@latest']);
-    },
-    acquireLock: () => acquireUpdateLock(),
-    releaseLock: releaseUpdateLock,
+    install: () => installLatest(),
+    acquireLock: () => acquireFileLock(updateLockTarget(), Date.now(), UPDATE_LOCK),
+    releaseLock: () => releaseFileLock(updateLockTarget()),
     log: (msg) => console.log(msg),
 };
 const describe = (info) => {
@@ -32,9 +45,7 @@ const install = async (deps) => {
     await deps.install();
     deps.log(chalk.green('Updated. Run `agentage status` to confirm.'));
 };
-// --check reports the verdict and never installs. Otherwise, install only when the registry says
-// we're behind (available/unsupported), guarded by a single-writer lock; current/unreachable just
-// report.
+// --check never installs; otherwise install only when behind, under a single-writer lock.
 export const runUpdate = async (opts, deps = defaultDeps) => {
     const info = await deps.check(VERSION);
     deps.log(describe(info));
@@ -52,18 +63,10 @@ export const runUpdate = async (opts, deps = defaultDeps) => {
         deps.releaseLock();
     }
 };
-export const registerUpdate = (program) => {
+export const registerUpdate = (program, action) => {
     program
         .command('update')
         .description('Update @agentage/cli to the latest published version')
         .option('--check', 'report whether an update is available, without installing')
-        .action(async (opts) => {
-        try {
-            await runUpdate(opts);
-        }
-        catch (err) {
-            console.error(chalk.red(err instanceof Error ? err.message : String(err)));
-            process.exitCode = 1;
-        }
-    });
+        .action(action);
 };

package/dist/core/loader/discover.d.ts

@@ -0,0 +1,33 @@
+export type PluginSource = 'tree' | 'dev';
+export interface DiscoveredPlugin {
+    pkg: string;
+    source: PluginSource;
+    dir: string;
+    version: string | null;
+    id: string | null;
+    entry: string | null;
+    commands: string[];
+    peers: string[];
+    optionalPeers: string[];
+    problem: string | null;
+    missing: boolean;
+}
+export interface DiscoverInput {
+    pluginsDir: string;
+    names: string[];
+    dev: Record<string, string>;
+}
+export interface Discovery {
+    plugins: DiscoveredPlugin[];
+    warnings: string[];
+}
+export interface CurrentTree {
+    dir: string | null;
+    warning: string | null;
+}
+export interface DiscoverDeps {
+    readText: (path: string) => string | null;
+    exists: (path: string) => boolean;
+}
+export declare const currentTree: (pluginsDir: string, deps?: DiscoverDeps) => CurrentTree;
+export declare const discover: (input: DiscoverInput, deps?: DiscoverDeps) => Discovery;

package/dist/core/loader/discover.js

@@ -0,0 +1,103 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { isRecord } from '../../lib/fs/json-file.js';
+import { manifestInfo, manifestProblem } from './manifest.js';
+const readText = (path) => {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+};
+const defaultDeps = { readText, exists: existsSync };
+const TREE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const readManifest = (dir, deps) => {
+    const raw = deps.readText(join(dir, 'package.json'));
+    try {
+        const value = raw === null ? null : JSON.parse(raw);
+        return isRecord(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+};
+// `plugins/current` names the tree; one without its `.complete` marker was never finished.
+export const currentTree = (pluginsDir, deps = defaultDeps) => {
+    const name = deps.readText(join(pluginsDir, 'current'))?.trim() ?? '';
+    if (name === '')
+        return { dir: null, warning: null };
+    if (!TREE_NAME.test(name))
+        return { dir: null, warning: `plugins/current: bad tree "${name}"` };
+    const dir = join(pluginsDir, 'trees', name);
+    if (deps.exists(join(dir, '.complete')))
+        return { dir, warning: null };
+    return { dir: null, warning: `plugins tree "${name}" is incomplete and was ignored` };
+};
+const inside = (dir, entry) => {
+    const path = resolve(dir, entry);
+    const rel = relative(dir, path);
+    return rel === '' || rel.startsWith('..') || isAbsolute(rel) ? null : path;
+};
+const entryProblem = (info, path, deps) => {
+    if (info.entry === null)
+        return null;
+    if (path === null)
+        return `entry ${info.entry} is outside the package`;
+    return deps.exists(path) ? null : `entry ${info.entry} not found`;
+};
+const blank = (pkg, source, dir) => ({
+    pkg,
+    source,
+    dir,
+    version: null,
+    id: null,
+    entry: null,
+    commands: [],
+    peers: [],
+    optionalPeers: [],
+    problem: null,
+    missing: false,
+});
+const inspect = (pkg, source, dir, deps) => {
+    const base = blank(pkg, source, dir ?? '');
+    if (source === 'dev' && !isAbsolute(base.dir))
+        return { ...base, problem: 'dev path not absolute' };
+    const manifest = dir === null ? null : readManifest(dir, deps);
+    if (dir === null || manifest === null)
+        return { ...base, missing: true };
+    const info = manifestInfo(manifest);
+    const entry = info.entry === null ? null : inside(dir, info.entry);
+    const problem = manifestProblem(pkg, info) ?? entryProblem(info, entry, deps);
+    const { version, id, commands, peers, optionalPeers } = info;
+    return { ...base, version, id, entry, commands, peers, optionalPeers, problem };
+};
+// Every claimant of a shared id is invalid; a dev copy of the same package never reaches here.
+const markDuplicates = (plugins) => plugins.map((p) => {
+    const others = plugins.filter((o) => o !== p && p.id !== null && o.id === p.id);
+    if (others.length === 0 || p.problem)
+        return p;
+    return {
+        ...p,
+        problem: `duplicate id "${p.id}" (also ${others.map((o) => o.pkg).join(', ')})`,
+    };
+});
+// A peer counts as a plugin unless the tree holds it as a plain library without `agentage`.
+const pluginPeers = (p, known, modules, deps) => p.peers.filter((peer) => {
+    if (known.has(peer) || modules === null)
+        return true;
+    const manifest = readManifest(join(modules, peer), deps);
+    return manifest === null || isRecord(manifest['agentage']);
+});
+export const discover = (input, deps = defaultDeps) => {
+    const tree = currentTree(input.pluginsDir, deps);
+    const modules = tree.dir === null ? null : join(tree.dir, 'node_modules');
+    const installed = input.names.filter((name) => !(name in input.dev));
+    const found = markDuplicates([
+        ...installed.map((name) => inspect(name, 'tree', modules && join(modules, name), deps)),
+        ...Object.entries(input.dev).map(([name, path]) => inspect(name, 'dev', path, deps)),
+    ]);
+    const known = new Set(found.map((p) => p.pkg));
+    const plugins = found.map((p) => ({ ...p, peers: pluginPeers(p, known, modules, deps) }));
+    return { plugins, warnings: tree.warning === null ? [] : [tree.warning] };
+};