@agentage/cli 0.38.1 → 0.40.0

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

@@ -0,0 +1,35 @@
+import { type ConfigMap } from '../profile/schema.js';
+export type ExtensionSource = 'tree' | 'dev';
+export interface DiscoveredExtension {
+    pkg: string;
+    source: ExtensionSource;
+    dir: string;
+    version: string | null;
+    id: string | null;
+    entry: string | null;
+    commands: string[];
+    peers: string[];
+    optionalPeers: string[];
+    config: Record<string, unknown>;
+    secrets: string[];
+    descriptions: Record<string, string>;
+    problem: string | null;
+    missing: boolean;
+}
+export interface DiscoverInput {
+    extensionsDir: string;
+    names: string[];
+    dev: Record<string, string>;
+    config: ConfigMap;
+    tree?: string;
+}
+export interface Discovery {
+    extensions: DiscoveredExtension[];
+    warnings: string[];
+}
+export interface CurrentTree {
+    dir: string | null;
+    warning: string | null;
+}
+export declare const currentTree: (extensionsDir: string) => CurrentTree;
+export declare const discover: (input: DiscoverInput) => Discovery;

package/dist/core/loader/discover.js

@@ -0,0 +1,118 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { isRecord } from '../../lib/fs/json-file.js';
+import {} from '../profile/schema.js';
+import { checkConfig } from './config.js';
+import { unsafeDevPath } from './dev-path.js';
+import { manifestInfo, manifestProblem } from './manifest.js';
+const readText = (path) => {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+};
+const TREE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const readManifest = (dir) => {
+    const raw = readText(join(dir, 'package.json'));
+    try {
+        const value = raw === null ? null : JSON.parse(raw);
+        return isRecord(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+};
+// `extensions/current` names the tree; one without its `.complete` marker was never finished.
+export const currentTree = (extensionsDir) => {
+    const name = readText(join(extensionsDir, 'current'))?.trim() ?? '';
+    if (name === '')
+        return { dir: null, warning: null };
+    if (!TREE_NAME.test(name))
+        return { dir: null, warning: `extensions/current: bad tree "${name}"` };
+    const dir = join(extensionsDir, 'trees', name);
+    if (existsSync(join(dir, '.complete')))
+        return { dir, warning: null };
+    return { dir: null, warning: `extensions 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) => {
+    if (info.entry === null)
+        return null;
+    if (path === null)
+        return `entry ${info.entry} is outside the package`;
+    return existsSync(path) ? null : `entry ${info.entry} not found`;
+};
+const blank = (pkg, source, dir) => ({
+    pkg,
+    source,
+    dir,
+    version: null,
+    id: null,
+    entry: null,
+    commands: [],
+    peers: [],
+    optionalPeers: [],
+    config: {},
+    secrets: [],
+    descriptions: {},
+    problem: null,
+    missing: false,
+});
+const inspect = ({ pkg, source, dir }, configs) => {
+    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);
+    if (dir === null || manifest === null)
+        return { ...base, missing: true };
+    const info = manifestInfo(manifest);
+    const entry = info.entry === null ? null : inside(dir, info.entry);
+    const { version, id, commands, peers, optionalPeers } = info;
+    const slice = configs[id ?? ''] ?? {};
+    const { problem: badConfig, ...declared } = checkConfig(id ?? '', info.configuration, slice);
+    const unsafe = source === 'dev' ? unsafeDevPath(dir, process.getuid?.()) : null;
+    const problem = unsafe ?? manifestProblem(pkg, info) ?? entryProblem(info, entry) ?? badConfig;
+    return { ...base, version, id, entry, commands, peers, optionalPeers, ...declared, problem };
+};
+// Every claimant of a shared id is invalid; a dev copy of the same package never reaches here.
+const markDuplicates = (extensions) => extensions.map((p) => {
+    const others = extensions.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 an extension unless the tree holds it as a plain library without `agentage`.
+const extensionPeers = (p, known, nodeModules) => p.peers.filter((peer) => {
+    if (known.has(peer) || nodeModules === null)
+        return true;
+    const manifest = readManifest(join(nodeModules, peer));
+    return manifest === null || isRecord(manifest['agentage']);
+});
+export const discover = (input) => {
+    const tree = input.tree ? { dir: input.tree, warning: null } : currentTree(input.extensionsDir);
+    const nodeModules = tree.dir === null ? null : join(tree.dir, 'node_modules');
+    const installed = input.names.filter((name) => !(name in input.dev));
+    const found = markDuplicates([
+        ...installed.map((pkg) => ({
+            pkg,
+            source: 'tree',
+            dir: nodeModules && join(nodeModules, pkg),
+        })),
+        ...Object.entries(input.dev).map(([pkg, dir]) => ({ pkg, source: 'dev', dir })),
+    ].map((candidate) => inspect(candidate, input.config)));
+    const known = new Set(found.map((p) => p.pkg));
+    const extensions = found.map((p) => ({
+        ...p,
+        peers: extensionPeers(p, known, nodeModules),
+    }));
+    return { extensions, warnings: tree.warning === null ? [] : [tree.warning] };
+};

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

@@ -0,0 +1,4 @@
+import { type Disposable } from '../../extension.js';
+export declare const DISPOSE_TIMEOUT_MS = 5000;
+export declare const disposeAll: (id: string, subscriptions: Disposable[]) => Promise<void>;
+export declare const holdSignals: (dispose: () => Promise<void>) => (() => void);

package/dist/core/loader/dispose.js

@@ -0,0 +1,24 @@
+import {} from '../../extension.js';
+import { extensionLog } from './log.js';
+import { withTimeout } from './timeout.js';
+export const DISPOSE_TIMEOUT_MS = 5_000;
+const messageOf = (err) => (err instanceof Error ? err.message : String(err));
+// Each subscription gets its 5 s at once; one that hangs is abandoned, and every result is logged.
+export const disposeAll = async (id, subscriptions) => {
+    const log = extensionLog(id);
+    await Promise.all(subscriptions.map(async (subscription, index) => {
+        const disposing = Promise.resolve().then(() => subscription.dispose());
+        const result = await withTimeout(disposing, DISPOSE_TIMEOUT_MS).then(() => 'done', messageOf);
+        log('dispose', { subscription: index, result });
+    }));
+};
+const SIGNALS = ['SIGINT', 'SIGTERM'];
+// The signal waits for disposal, then is raised again with no handler: the exit it would have had.
+export const holdSignals = (dispose) => {
+    const handlers = SIGNALS.map((signal) => {
+        const handler = () => void dispose().finally(() => process.kill(process.pid, signal));
+        process.once(signal, handler);
+        return { signal, handler };
+    });
+    return () => handlers.forEach(({ signal, handler }) => process.off(signal, handler));
+};

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

@@ -0,0 +1,13 @@
+import { Command } from 'commander';
+import { type DiscoveredExtension } from './discover.js';
+import { type LoadedExtension } from './register.js';
+export interface LoadOutcome {
+    state: 'ok' | 'failed' | 'blocked';
+    error: string | null;
+}
+export interface LoadSession {
+    outcomes: Map<string, LoadOutcome>;
+    loaded: Map<string, LoadedExtension>;
+    dispose: () => Promise<void>;
+}
+export declare const loadExtensions: (extensions: DiscoveredExtension[], template?: Command) => Promise<LoadSession>;

package/dist/core/loader/load.js

@@ -0,0 +1,61 @@
+import { Command } from 'commander';
+import {} from './discover.js';
+import { disposeAll, holdSignals } from './dispose.js';
+import { loadOrder } from './order.js';
+import { registerExtension } from './register.js';
+import { writeRunState } from './state.js';
+import { createUse } from './use.js';
+const blockedBy = (ext, outcomes) => {
+    const required = ext.peers.filter((peer) => !ext.optionalPeers.includes(peer));
+    const peer = required.find((name) => outcomes.get(name)?.state !== 'ok');
+    return peer === undefined ? null : `peer ${peer} is ${outcomes.get(peer)?.state ?? 'not loaded'}`;
+};
+const attempt = async (ext, session, template) => {
+    const blocked = blockedBy(ext, session.outcomes);
+    if (blocked)
+        return { state: 'blocked', error: blocked };
+    const result = await registerExtension(ext, createUse(ext, session.loaded), template);
+    if (!result.ok)
+        return { state: 'failed', error: result.error };
+    session.loaded.set(ext.id ?? '', result.loaded);
+    return { state: 'ok', error: null };
+};
+// What an extension prints while it loads goes to stderr, so stdout stays the command's own.
+const toStderr = async (fn) => {
+    const saved = { log: console.log, info: console.info, debug: console.debug };
+    console.log = console.info = console.debug = console.error;
+    try {
+        await fn();
+    }
+    finally {
+        Object.assign(console, saved);
+    }
+};
+const newSession = () => {
+    const loaded = new Map();
+    let disposed;
+    const disposeOnce = async () => {
+        disposed ??= Promise.all([...loaded.values()].map((l) => disposeAll(l.ext.id ?? '', l.subscriptions)));
+        await disposed;
+    };
+    const release = holdSignals(disposeOnce);
+    const dispose = () => {
+        release();
+        return disposeOnce();
+    };
+    return { outcomes: new Map(), loaded, dispose };
+};
+// Loads in peer order; one extension failing never stops the others, only what depends on it.
+export const loadExtensions = async (extensions, template = new Command('agentage')) => {
+    // Not a sandbox, but the token never reaches extension code through the environment.
+    delete process.env['AGENTAGE_TOKEN'];
+    const session = newSession();
+    await toStderr(async () => {
+        for (const ext of loadOrder(extensions)) {
+            const outcome = await attempt(ext, session, template);
+            session.outcomes.set(ext.pkg, outcome);
+            writeRunState(ext.id ?? '', { ...outcome, version: ext.version });
+        }
+    });
+    return session;
+};

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

@@ -0,0 +1,3 @@
+import { type ExtensionLog } from '../../extension.js';
+export declare const LOG_CAP_BYTES: number;
+export declare const extensionLog: (id: string) => ExtensionLog;

package/dist/core/loader/log.js

@@ -0,0 +1,23 @@
+import { appendFileSync, mkdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import {} from '../../extension.js';
+import { writeTextAtomic } from '../../lib/fs/json-file.js';
+import { logsDir } from '../paths.js';
+export const LOG_CAP_BYTES = 1024 * 1024;
+// Past the cap, keep the newest half from its first whole line, so the file stays small.
+const trim = (path) => {
+    if (statSync(path).size <= LOG_CAP_BYTES)
+        return;
+    const tail = readFileSync(path)
+        .subarray(-LOG_CAP_BYTES / 2)
+        .toString('utf-8');
+    writeTextAtomic(path, tail.slice(tail.indexOf('\n') + 1));
+};
+// The extension's own log; the core never reads it, its run state lives in state/<id>.json.
+export const extensionLog = (id) => (message, fields = {}) => {
+    const path = join(logsDir(), `${id}.log`);
+    mkdirSync(logsDir(), { recursive: true, mode: 0o700 });
+    const line = JSON.stringify({ at: new Date().toISOString(), message, ...fields });
+    appendFileSync(path, `${line}\n`, { mode: 0o600 });
+    trim(path);
+};

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

@@ -0,0 +1,14 @@
+export declare const ID_PATTERN: RegExp;
+export interface ManifestInfo {
+    name: string | null;
+    version: string | null;
+    id: string | null;
+    engine: string;
+    entry: string | null;
+    commands: string[];
+    peers: string[];
+    optionalPeers: string[];
+    configuration: Record<string, unknown>;
+}
+export declare const manifestInfo: (pkg: Record<string, unknown>) => ManifestInfo;
+export declare const manifestProblem: (pkg: string, info: ManifestInfo, api?: string) => string | null;

package/dist/core/loader/manifest.js

@@ -0,0 +1,77 @@
+import { isRecord } from '../../lib/fs/json-file.js';
+import { EXTENSION_API_VERSION } from '../../extension.js';
+import { isRange, satisfies } from '../semver-range.js';
+export const ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+const DEFAULT_ENGINE = '^1';
+const CORE_COMMANDS = ['setup', 'status', 'update', 'extension', 'add', 'remove', 'help'];
+const DEVICE_NAMES = ['con', 'prn', 'aux', 'nul'].concat(...Array.from({ length: 10 }, (_, n) => [`com${n}`, `lpt${n}`]));
+const RESERVED_IDS = new Set([...CORE_COMMANDS, ...DEVICE_NAMES]);
+const SUBCOMMAND = /^[a-z0-9][a-z0-9-]*$/;
+const str = (value) => (typeof value === 'string' ? value : null);
+const record = (value) => (isRecord(value) ? value : {});
+const strings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+const fromConditions = (value, depth = 0) => {
+    if (typeof value === 'string')
+        return value;
+    if (!isRecord(value) || depth > 3)
+        return null;
+    return fromConditions(value['import'], depth + 1) ?? fromConditions(value['default'], depth + 1);
+};
+// Node semantics: a present `exports` field is authoritative, `main` only applies without it.
+const entryOf = (pkg) => {
+    const exp = pkg['exports'];
+    if (exp === undefined)
+        return str(pkg['main']);
+    if (isRecord(exp) && '.' in exp)
+        return fromConditions(exp['.']);
+    const subpathsOnly = isRecord(exp) && Object.keys(exp).some((key) => key.startsWith('.'));
+    return subpathsOnly ? null : fromConditions(exp);
+};
+const optionalPeersOf = (meta) => Object.entries(meta)
+    .filter(([, m]) => isRecord(m) && m['optional'] === true)
+    .map(([name]) => name);
+export const manifestInfo = (pkg) => {
+    const agentage = record(pkg['agentage']);
+    return {
+        name: str(pkg['name']),
+        version: str(pkg['version']),
+        id: str(agentage['id']),
+        engine: str(record(pkg['engines'])['agentage']) ?? DEFAULT_ENGINE,
+        entry: entryOf(pkg),
+        commands: [...new Set(strings(record(agentage['contributes'])['commands']))],
+        peers: Object.keys(record(pkg['peerDependencies'])),
+        optionalPeers: optionalPeersOf(record(pkg['peerDependenciesMeta'])),
+        configuration: record(agentage['configuration']),
+    };
+};
+const idProblem = (id) => {
+    if (id === null)
+        return 'agentage.id is missing';
+    if (!ID_PATTERN.test(id))
+        return `agentage.id "${id}" must match [a-z][a-z0-9-]*`;
+    return RESERVED_IDS.has(id) ? `agentage.id "${id}" is reserved` : null;
+};
+const engineProblem = (engine, api) => {
+    if (!isRange(engine))
+        return `engines.agentage "${engine}" is not a supported range`;
+    if (satisfies(api, engine))
+        return null;
+    return `engines.agentage "${engine}" does not match extension API ${api}`;
+};
+// Commands are named after the id, so no two extensions, nor the core, can claim one.
+const commandsProblem = (id, commands) => {
+    const ownSub = (name) => name.startsWith(`${id}:`) && SUBCOMMAND.test(name.slice(id.length + 1));
+    const bad = commands.find((name) => name !== id && !ownSub(name));
+    if (bad === undefined)
+        return null;
+    return `agentage.contributes.commands: "${bad}" must be "${id}" or "${id}:<name>"`;
+};
+// Static checks only: the manifest is read as data and the entry is never imported.
+export const manifestProblem = (pkg, info, api = EXTENSION_API_VERSION) => {
+    if (info.name !== pkg)
+        return `package.json name ${JSON.stringify(info.name)} is not ${pkg}`;
+    return (idProblem(info.id) ??
+        engineProblem(info.engine, api) ??
+        (info.entry === null ? 'no entry point (exports or main)' : null) ??
+        commandsProblem(info.id ?? '', info.commands));
+};

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

@@ -0,0 +1,2 @@
+import { type DiscoveredExtension } from './discover.js';
+export declare const loadOrder: (roots: DiscoveredExtension[], all?: DiscoveredExtension[]) => DiscoveredExtension[];

package/dist/core/loader/order.js

@@ -0,0 +1,20 @@
+import {} from './discover.js';
+// Peers first, from `roots` through `all`; cycles are invalid already, `seen` ends the walk anyway.
+export const loadOrder = (roots, all = roots) => {
+    const byPkg = new Map(all.map((ext) => [ext.pkg, ext]));
+    const seen = new Set();
+    const ordered = [];
+    const visit = (ext) => {
+        if (seen.has(ext.pkg))
+            return;
+        seen.add(ext.pkg);
+        for (const peer of [...ext.peers, ...ext.optionalPeers]) {
+            const found = byPkg.get(peer);
+            if (found)
+                visit(found);
+        }
+        ordered.push(ext);
+    };
+    roots.forEach(visit);
+    return ordered;
+};

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

@@ -0,0 +1,19 @@
+import { type Command } from 'commander';
+import { type Disposable, type ExtensionApi, type ExtensionUse } from '../../extension.js';
+import { type DiscoveredExtension } from './discover.js';
+export declare const DEFAULT_REGISTER_TIMEOUT_MS = 10000;
+export interface LoadedExtension {
+    ext: DiscoveredExtension;
+    program: Command;
+    subscriptions: Disposable[];
+    facade: ExtensionApi;
+}
+export type Attempt = {
+    ok: true;
+    loaded: LoadedExtension;
+} | {
+    ok: false;
+    error: string;
+};
+export declare const registerTimeoutMs: () => number;
+export declare const registerExtension: (ext: DiscoveredExtension, use: ExtensionUse, template: Command) => Promise<Attempt>;

package/dist/core/loader/register.js

@@ -0,0 +1,39 @@
+import { pathToFileURL } from 'node:url';
+import {} from 'commander';
+import {} from '../../extension.js';
+import { isRecord } from '../../lib/fs/json-file.js';
+import { createContext } from './ctx.js';
+import {} from './discover.js';
+import { disposeAll } from './dispose.js';
+import { withTimeout } from './timeout.js';
+import { facadeOf } from './use.js';
+export const DEFAULT_REGISTER_TIMEOUT_MS = 10_000;
+// Tests shorten the wait; anything but a positive integer keeps the default.
+export const registerTimeoutMs = () => {
+    const raw = process.env['AGENTAGE_REGISTER_TIMEOUT_MS'] ?? '';
+    return /^[1-9]\d{0,8}$/.test(raw) ? Number(raw) : DEFAULT_REGISTER_TIMEOUT_MS;
+};
+const messageOf = (err) => (err instanceof Error ? err.message : String(err));
+const isRegister = (value) => typeof value === 'function';
+const importAndRegister = async (entry, ctx) => {
+    const exported = await import(pathToFileURL(entry).href);
+    const register = isRecord(exported) ? exported['register'] : undefined;
+    if (!isRegister(register))
+        throw new Error('the entry exports no register function');
+    return register(ctx);
+};
+// The import counts toward the timeout too: a top-level await can hang like register can.
+export const registerExtension = async (ext, use, template) => {
+    const staged = createContext({ ext, use, template });
+    try {
+        const api = await withTimeout(importAndRegister(ext.entry ?? '', staged.ctx), registerTimeoutMs());
+        staged.close();
+        const { program, subscriptions } = staged;
+        return { ok: true, loaded: { ext, program, subscriptions, facade: facadeOf(api) } };
+    }
+    catch (err) {
+        staged.revoke();
+        await disposeAll(ext.id ?? '', staged.subscriptions);
+        return { ok: false, error: messageOf(err) };
+    }
+};

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

@@ -0,0 +1,18 @@
+import { type Plan } from '../installer/plan.js';
+import { type MachineFile } from '../profile/machine.js';
+import { type Effective } from '../profile/merge.js';
+import { type ProfileParse } from '../profile/schema.js';
+import { type DiscoveredExtension, type Discovery } from './discover.js';
+import { type StaticResult } from './states.js';
+export interface Scan {
+    machine: MachineFile;
+    parsed: ProfileParse | null;
+    eff: Effective;
+    found: Discovery;
+    states: Map<string, StaticResult>;
+    plan: Plan;
+    removed: DiscoveredExtension[];
+    drift: string[];
+}
+export declare const scan: (machine: MachineFile, tree?: string) => Scan;
+export declare const loadSet: (found: Scan) => DiscoveredExtension[];

package/dist/core/loader/scan.js

@@ -0,0 +1,34 @@
+import { currentDependencies, lockDrift, planChanges } from '../installer/plan.js';
+import {} from '../profile/machine.js';
+import { effective } from '../profile/merge.js';
+import { readProfile } from '../profile/profile.js';
+import {} from '../profile/schema.js';
+import { extensionsDir } from '../paths.js';
+import { discover } from './discover.js';
+import { staticStates } from './states.js';
+// A tree extension whose bytes the two locks disagree on is never trusted, so never imported.
+const withDrift = (found, drift) => ({
+    ...found,
+    extensions: found.extensions.map((p) => {
+        const key = `${p.pkg}@${p.version}`;
+        const drifted = p.source === 'tree' && p.problem === null && drift.includes(key);
+        return drifted ? { ...p, problem: `integrity drift: ${key}` } : p;
+    }),
+});
+// Everything known about this machine's extensions without running any of them; `tree` reads
+// that tree instead of the current one.
+export const scan = (machine, tree) => {
+    const parsed = readProfile();
+    const eff = effective(parsed?.ok ? parsed.profile : null, machine);
+    const dir = extensionsDir();
+    const drift = lockDrift(dir).integrity;
+    const input = { extensionsDir: dir, dev: eff.dev, config: eff.config, tree };
+    const found = withDrift(discover({ ...input, names: Object.keys(eff.install) }), drift);
+    const plan = planChanges(eff, currentDependencies(dir));
+    const gone = plan.extensions.filter((e) => e.verb === 'remove' && !(e.name in eff.dev));
+    const removed = discover({ ...input, dev: {}, names: gone.map((e) => e.name) }).extensions;
+    const states = staticStates(found.extensions, eff.off);
+    return { machine, parsed, eff, found, states, plan, removed, drift };
+};
+// What can load: a valid manifest, installed, not off here, and peers that can load too.
+export const loadSet = (found) => found.found.extensions.filter((ext) => found.states.get(ext.pkg)?.state === 'installed');

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

@@ -0,0 +1,9 @@
+import { type ExtensionSecrets } from '../../extension.js';
+import { type DiscoveredExtension } from './discover.js';
+export interface SecretKey {
+    id: string;
+    key: string;
+    description: string | null;
+}
+export declare const secretsFor: (id: string) => ExtensionSecrets;
+export declare const missingSecrets: (extensions: DiscoveredExtension[]) => SecretKey[];

package/dist/core/loader/secrets.js

@@ -0,0 +1,28 @@
+import {} from '../../extension.js';
+import { withFileLock } from '../../lib/fs/file-lock.js';
+import { isRecord, readJson, writeJsonAtomic } from '../../lib/fs/json-file.js';
+import { secretsPath } from '../paths.js';
+import {} from './discover.js';
+const isStrings = (value) => isRecord(value) && Object.values(value).every((v) => typeof v === 'string');
+const isSecretsFile = (value) => isRecord(value) && Object.values(value).every(isStrings);
+const readSecrets = () => readJson(secretsPath(), isSecretsFile) ?? {};
+// Re-read under the lock, so two processes never drop each other's secret.
+const change = (id, fn) => withFileLock(secretsPath(), () => {
+    const all = readSecrets();
+    writeJsonAtomic(secretsPath(), { ...all, [id]: fn(all[id] ?? {}) });
+});
+export const secretsFor = (id) => ({
+    get: async (key) => readSecrets()[id]?.[key],
+    set: (key, value) => change(id, (own) => ({ ...own, [key]: value })),
+    delete: (key) => change(id, (own) => Object.fromEntries(Object.entries(own).filter(([k]) => k !== key))),
+});
+// The keys extensions declare `secret: true` that this machine has no value for yet.
+export const missingSecrets = (extensions) => {
+    const stored = readSecrets();
+    return extensions.flatMap((ext) => {
+        const id = ext.id ?? '';
+        return ext.secrets
+            .filter((key) => stored[id]?.[key] === undefined)
+            .map((key) => ({ id, key, description: ext.descriptions[key] ?? null }));
+    });
+};

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

@@ -0,0 +1,12 @@
+export declare const RUN_STATES: readonly ["ok", "failed", "invalid", "off", "blocked", "installed"];
+export type RunStateName = (typeof RUN_STATES)[number];
+export interface RunState {
+    at: string;
+    pid: number;
+    state: RunStateName;
+    error: string | null;
+    version: string | null;
+    lastOk: string | null;
+}
+export declare const readRunState: (id: string) => RunState | null;
+export declare const writeRunState: (id: string, run: Pick<RunState, "state" | "error" | "version">) => void;

package/dist/core/loader/state.js

@@ -0,0 +1,31 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { isRecord, readJson, writeJsonAtomic } from '../../lib/fs/json-file.js';
+import { stateDir } from '../paths.js';
+import { ID_PATTERN } from './manifest.js';
+export const RUN_STATES = ['ok', 'failed', 'invalid', 'off', 'blocked', 'installed'];
+const isRunStateName = (value) => RUN_STATES.some((name) => name === value);
+// Absent in files written before the field existed.
+const optionalText = (value) => value === undefined || value === null || typeof value === 'string';
+const isRunState = (value) => isRecord(value) &&
+    typeof value['at'] === 'string' &&
+    typeof value['pid'] === 'number' &&
+    isRunStateName(value['state']) &&
+    ['error', 'version', 'lastOk'].every((key) => optionalText(value[key]));
+// Reads the core's own record of the last run; extension logs are never consulted.
+export const readRunState = (id) => {
+    if (!ID_PATTERN.test(id))
+        return null;
+    const found = readJson(join(stateDir(), `${id}.json`), isRunState);
+    if (!found)
+        return null;
+    const { at, pid, state, error = null, version = null, lastOk = null } = found;
+    return { at, pid, state, error, version, lastOk };
+};
+// Written by the core after each load attempt; a failed one keeps the last ok version.
+export const writeRunState = (id, run) => {
+    const lastOk = run.state === 'ok' ? run.version : (readRunState(id)?.lastOk ?? null);
+    mkdirSync(stateDir(), { recursive: true, mode: 0o700 });
+    const state = { at: new Date().toISOString(), pid: process.pid, ...run, lastOk };
+    writeJsonAtomic(join(stateDir(), `${id}.json`), state);
+};

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

@@ -0,0 +1,7 @@
+import { type DiscoveredExtension } from './discover.js';
+export type StaticState = 'installed' | 'off' | 'blocked' | 'invalid' | 'missing';
+export interface StaticResult {
+    state: StaticState;
+    error: string | null;
+}
+export declare const staticStates: (extensions: DiscoveredExtension[], off: string[]) => Map<string, StaticResult>;