@timqi/pier 0.1.2 → 0.1.4

package/README.md

@@ -37,8 +37,8 @@ otherwise).
 **The first start generates a password and prints it once.** Lost it?
 `sqlite3 ~/.pier/db/pier.db 'DELETE FROM auth'` and restart. Open
 `http://localhost:3141`, sign in; **Console → Settings** configures Models,
-Agent, Channels, the public URL, password and master key; **New session** picks
-the directory the agent's shell runs in.
+Agent, Channels, Vault, the public URL, password and master key; **New session**
+picks the directory the agent's shell runs in.
 
 ## Configure Pi
 
@@ -67,7 +67,12 @@ Console → Settings:
   copy of yours registering the same tool makes Pier's stand down) and the
   managed CLI tools (`rtk`, `rg`, `fd`, `wt`, `jq`, or your own as a
   [ubix](https://github.com/timqi/ubix) block), installed into
-  `~/.pier/tools/bin`, first on every session's PATH.
+  `~/.pier/tools/bin`, first on every session's PATH beside the `pier` shim
+  Pier writes there at start.
+- **Vault** — named secrets an agent's commands receive through `pier vault
+  run` without the value entering its context (`docs/design/07-vault.md`);
+  `pier slack` and `pier task` reach the running Pier the same way
+  (`docs/design/08-cli-socket.md`).
 
 On first credential access an existing `auth.json` is imported into the sealed
 store and renamed `auth.json.imported`; literal keys in `models.json` likewise

package/dist/agent/config.js

@@ -3,16 +3,27 @@
 // project) but not the Pi SDK — pure filesystem, unit-testable in a tmp dir.
 import { randomUUID } from "node:crypto";
 import { promises as fs } from "node:fs";
-import { join, resolve, sep } from "node:path";
-import { isProviderApi, validateEndpoint, validateProviderSetup } from "../core/types.js";
+import { join } from "node:path";
+import { isProviderApi, isThinkingLevel, validateEndpoint, validateProviderSetup } from "../core/types.js";
 import { pierPath } from "../paths.js";
 import { mergeSnapshotProviders, normalizeAgentSnapshot, snapshotProviders } from "./config-sync.js";
 const GLOBAL_FILES = ["SYSTEM.md", "AGENTS.md", "settings.json", "models.json"];
 const PROJECT_FILES = ["AGENTS.md"];
-// settings.json is on the list for two fields: the default model and its
-// reasoning effort. Everything else in it is machine-local.
+// settings.json is Pier's to write: the default model and its reasoning effort
+// go through writeDefaults, and are the only fields a snapshot carries. The
+// Console shows the file and never edits it; the rest of it is machine-local.
+const READONLY_FILES = ["settings.json"];
 const SNAPSHOT_FILES = ["SYSTEM.md", "AGENTS.md", "models.json", "settings.json"];
-const RESOURCE_DEPTH = 3; // extensions/skills nest at most a couple of levels
+/** What a first boot writes (docs/deploy.md says why each key): the list the
+ *  Console installs into, Pi's attribution headers off — a server is not a
+ *  person to survey — and a retry budget of minutes, because an unattended
+ *  instance has nobody to re-ask after Pi's 14-second default gives up. Every
+ *  other key stays Pi's default by omission. */
+const SEED_SETTINGS = {
+    packages: [],
+    enableInstallTelemetry: false,
+    retry: { maxRetries: 5, baseDelayMs: 5000 },
+};
 /** Pier owns the Pi runtime dir; main.ts exports it as PI_CODING_AGENT_DIR. */
 export const defaultAgentDir = () => process.env.PI_CODING_AGENT_DIR ?? pierPath("pi");
 /** Stable mask: mapped back by field, without exposing key fragments. */
@@ -94,15 +105,11 @@ export class PiConfigStore {
         }
         return scope.kind === "global" ? join(this.agentDir, name) : join(scope.cwd, name);
     }
-    resourceRoot(scope, kind) {
-        return scope.kind === "global"
-            ? join(this.agentDir, kind)
-            : join(scope.cwd, ".pi", kind);
-    }
     async listFiles(scope) {
         return Promise.all(this.fileNames(scope).map(async (name) => ({
             name,
             exists: await pathExists(this.filePath(scope, name)),
+            readonly: READONLY_FILES.includes(name),
         })));
     }
     async readFile(scope, name) {
@@ -115,7 +122,10 @@ export class PiConfigStore {
     }
     async writeFile(scope, name, content, expected) {
         const path = this.filePath(scope, name);
-        return this.#withWrite(async () => {
+        if (READONLY_FILES.includes(name)) {
+            throw new Error(`${name} is written by Pier; edit it on disk, then run pier reload`);
+        }
+        return this.withWrite(async () => {
             const current = await readOptional(path);
             const visible = name === "models.json" ? maskModels(current) : current;
             if (expected !== undefined && visible !== expected)
@@ -160,7 +170,7 @@ export class PiConfigStore {
     }
     async setupProvider(input, verify) {
         validateProviderSetup(input);
-        await this.#withWrite(async () => {
+        await this.withWrite(async () => {
             const path = join(this.agentDir, "models.json");
             const raw = await readNullable(path);
             const parsed = raw?.trim() ? parseModels(raw) : {};
@@ -229,26 +239,49 @@ export class PiConfigStore {
             }
         });
     }
+    async readDefaults() {
+        await this.#writes;
+        this.#assertSnapshot();
+        return settingsDefaults(readSettings(await readNullable(join(this.agentDir, "settings.json"))));
+    }
+    writeDefaults(defaults) {
+        return this.withWrite(async () => {
+            const path = join(this.agentDir, "settings.json");
+            const raw = await readNullable(path);
+            const next = withDefaults(raw, defaults);
+            if (typeof next !== "string" || next === raw)
+                return;
+            await fs.mkdir(this.agentDir, { recursive: true });
+            await atomicWrite(path, next);
+        });
+    }
+    /** Once per boot, before a session opens: SEED_SETTINGS when there is no
+     *  settings.json at all. An existing file, whatever it holds, is never touched. */
+    seedSettings() {
+        return this.withWrite(async () => {
+            const path = join(this.agentDir, "settings.json");
+            if (await pathExists(path))
+                return;
+            await fs.mkdir(this.agentDir, { recursive: true });
+            await atomicWrite(path, `${JSON.stringify(SEED_SETTINGS, null, 2)}\n`);
+        });
+    }
     exportSnapshot() {
-        return this.#withWrite(async () => {
+        return this.withWrite(async () => {
             const [system, agents, raw, rawSettings] = await Promise.all(SNAPSHOT_FILES.map((name) => readNullable(join(this.agentDir, name))));
             const parsed = raw?.trim() ? parseModels(raw) : {};
             if (!parsed)
                 throw new Error("models.json must be valid JSON before exporting configuration");
-            const settings = readSettings(rawSettings);
             return normalizeAgentSnapshot({
                 files: { "SYSTEM.md": system, "AGENTS.md": agents },
                 providers: snapshotProviders(parsed.providers),
-                defaultModel: defaultModelRef(settings),
-                // Unlike the pair, a lone level needs no reading of its own; the
-                // snapshot boundary is the one place that says which ones exist.
-                defaultThinkingLevel: settings.defaultThinkingLevel ?? null,
+                ...settingsDefaults(readSettings(rawSettings)),
             });
         });
     }
     async applySnapshot(snapshot, commit) {
         const incoming = normalizeAgentSnapshot(snapshot);
-        await this.#withWrite(async () => {
+        await this.withWrite(async () => {
             const names = SNAPSHOT_FILES;
             const before = await Promise.all(names.map((name) => readNullable(join(this.agentDir, name))));
             const raw = before[2];
@@ -312,50 +345,14 @@ export class PiConfigStore {
             }
         });
     }
-    /** Pi loads several files directly; hold the same queue while it opens a session. */
-    withSnapshot(read) {
-        return this.#withWrite(read);
-    }
-    #withWrite(write) {
+    /** The one queue every writer of this directory holds: settings.json has two
+     *  writers (writeDefaults and Pi's SettingsManager in agent/packages.ts),
+     *  and Pi reads several files directly when it opens a session. */
+    withWrite(write) {
         const result = this.#writes.then(() => { this.#assertSnapshot(); return write(); });
         this.#writes = result.then(() => undefined, () => undefined);
         return result;
     }
-    async listResources(scope) {
-        return {
-            extensions: await listDir(this.resourceRoot(scope, "extensions")),
-            skills: await listDir(this.resourceRoot(scope, "skills")),
-        };
-    }
-    async readResource(scope, kind, name) {
-        const root = this.resourceRoot(scope, kind);
-        const path = resolve(root, name);
-        // Containment check — the listing is relative paths, reject anything else.
-        if (!path.startsWith(root + sep))
-            throw new Error(`invalid resource path: ${name}`);
-        return fs.readFile(path, "utf8");
-    }
-}
-/** Symlinks are followed (skills are routinely linked in from elsewhere) and
- *  flagged; the depth bound is also the cycle guard. */
-async function listDir(root, prefix = "", depth = RESOURCE_DEPTH, linked = false) {
-    if (depth === 0)
-        return [];
-    const entries = await fs.readdir(join(root, prefix), { withFileTypes: true }).catch(() => []);
-    const out = [];
-    for (const e of entries) {
-        const rel = prefix ? `${prefix}/${e.name}` : e.name;
-        const link = linked || e.isSymbolicLink();
-        // A Dirent for a symlink is neither file nor directory — stat through it.
-        const target = e.isSymbolicLink()
-            ? await fs.stat(join(root, rel)).catch(() => null) // dangling link → skip
-            : e;
-        if (target?.isDirectory())
-            out.push(...(await listDir(root, rel, depth - 1, link)));
-        else if (target?.isFile())
-            out.push({ name: rel, link });
-    }
-    return out.sort((a, b) => a.name.localeCompare(b.name));
 }
 /** models.json may contain legacy keys and literal headers. Only stable
  * masks cross the HTTP seam; malformed content must be repaired on disk. */
@@ -495,6 +492,13 @@ function defaultModelRef(settings) {
     }
     return { provider, id };
 }
+function settingsDefaults(settings) {
+    const level = settings.defaultThinkingLevel;
+    if (level !== undefined && !isThinkingLevel(level)) {
+        throw new Error("settings.json default reasoning effort must be a level Pi accepts");
+    }
+    return { defaultModel: defaultModelRef(settings), defaultThinkingLevel: level ?? null };
+}
 /** The incoming defaults replace their own fields and nothing else; a field
  *  the source never states (an older one) leaves the local settings.json
  *  alone, and `null` is a stated "no default" that clears it. Unchanged

package/dist/agent/events.js

@@ -33,8 +33,7 @@ function systemOrigin(message) {
     }
     if (origin.kind === "task-message" &&
         typeof origin.messageId === "string" &&
-        (origin.messageKind === "steer" || origin.messageKind === "follow_up" ||
-            origin.messageKind === "progress" || origin.messageKind === "decision" || origin.messageKind === "reply"))
+        (origin.messageKind === "steer" || origin.messageKind === "follow_up"))
         return shape;
     return null;
 }

package/dist/agent/listing.js

@@ -76,16 +76,34 @@ const SEARCH_LIMIT = 8;
 /** A trigram token is one character, so `snippet()` is asked for its ceiling
  *  of 64 tokens; the default 12 fits one word. */
 const SNIPPET_CHARS = 64;
+/** Whitespace splits a query: a space is "and this too", not a character to
+ *  find. A term is quoted where it has to be, so a phrase is still findable. */
+const termsOf = (query) => query.split(/\s+/).filter(Boolean);
 /** Delimited like `snippet()` (\u0001 … \u0002, `…` for a cut), so a surface
- *  draws one shape for both paths. ASCII case folding: LIKE found the row by
- *  the same rule. */
-function around(text, query) {
-    const hit = text.toLowerCase().indexOf(query.toLowerCase());
-    if (hit < 0)
+ *  draws one shape for both paths. Every term is marked where it first
+ *  appears inside the window, as `snippet()` marks every phrase it kept.
+ *  ASCII case folding: LIKE found the row by the same rule. */
+function around(text, terms) {
+    const lower = text.toLowerCase();
+    const found = terms
+        .map((term) => ({ at: lower.indexOf(term.toLowerCase()), length: term.length }))
+        .filter((mark) => mark.at >= 0)
+        .sort((a, b) => a.at - b.at);
+    const first = found[0];
+    if (!first)
         return text.slice(0, SNIPPET_CHARS);
-    const start = Math.max(0, hit - SNIPPET_CHARS / 2);
-    const end = Math.min(text.length, hit + query.length + SNIPPET_CHARS / 2);
-    return `${start ? "…" : ""}${text.slice(start, hit)}\u0001${text.slice(hit, hit + query.length)}\u0002${text.slice(hit + query.length, end)}${end < text.length ? "…" : ""}`;
+    const start = Math.max(0, first.at - SNIPPET_CHARS / 2);
+    const end = Math.min(text.length, first.at + first.length + SNIPPET_CHARS / 2);
+    let out = start ? "…" : "";
+    let at = start;
+    for (const mark of found) {
+        // Terms that overlap one another, or reach past the window, mark once.
+        if (mark.at < at || mark.at + mark.length > end)
+            continue;
+        out += `${text.slice(at, mark.at)}\u0001${text.slice(mark.at, mark.at + mark.length)}\u0002`;
+        at = mark.at + mark.length;
+    }
+    return `${out}${text.slice(at, end)}${end < text.length ? "…" : ""}`;
 }
 export class IndexedListing {
     dir;
@@ -194,15 +212,20 @@ export class IndexedListing {
         this.#save([], stale);
         return stale.length;
     }
-    /** Under three code points the trigram tokenizer has nothing to match, and a
-     *  two-character query is what a CJK word often is: substring scan instead. */
+    /** Every term must appear, in any order, anywhere in the one message. Under
+     *  three code points the trigram tokenizer has nothing to match, and a
+     *  two-character term is what a CJK word often is: substring scan instead —
+     *  one short term puts the whole query on that path. */
     search(query, limit = SEARCH_LIMIT) {
         const sql = this.#sql();
-        const rows = [...query].length >= 3
-            // Quoted: the query is a string to find, never FTS syntax.
+        const terms = termsOf(query);
+        if (!terms.length)
+            return [];
+        const rows = terms.every((term) => [...term].length >= 3)
+            // Quoted: a term is a string to find, never FTS syntax.
             ? sql(`SELECT session_id, role, at, snippet(session_fts, 0, char(1), char(2), '…', ${SNIPPET_CHARS}) AS snippet
-         FROM session_fts WHERE text MATCH ? ORDER BY bm25(session_fts), at DESC`).iterate(`"${query.replaceAll('"', '""')}"`)
-            : sql(`SELECT session_id, role, at, text FROM session_fts WHERE text LIKE ? ESCAPE '\\' ORDER BY at DESC`).iterate(`%${query.replaceAll(/[\\%_]/g, "\\$&")}%`);
+         FROM session_fts WHERE text MATCH ? ORDER BY bm25(session_fts), at DESC`).iterate(terms.map((term) => `"${term.replaceAll('"', '""')}"`).join(" AND "))
+            : sql(`SELECT session_id, role, at, text FROM session_fts WHERE ${terms.map(() => "text LIKE ? ESCAPE '\\'").join(" AND ")} ORDER BY at DESC`).iterate(...terms.map((term) => `%${term.replaceAll(/[\\%_]/g, "\\$&")}%`));
         const hits = [];
         const seen = new Set();
         // Walked, not fetched: a chatty session has hundreds of rows for one hit.
@@ -214,7 +237,7 @@ export class IndexedListing {
                 sessionId: row.session_id,
                 role: row.role,
                 at: row.at,
-                snippet: row.snippet ?? around(row.text ?? "", query),
+                snippet: row.snippet ?? around(row.text ?? "", terms),
             });
             if (hits.length >= limit)
                 break;

package/dist/agent/packages.js

@@ -0,0 +1,347 @@
+// The package registry behind the PackageStore seam: Pi's DefaultPackageManager
+// and SettingsManager, the second and last SDK-importing file in agent/. pi.ts
+// opens sessions; this file changes what they open with. No Pi type may appear
+// in an exported signature.
+import { existsSync, promises as fs } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { DefaultPackageManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { PackageError, } from "../core/types.js";
+import { BUNDLED } from "../extensions/index.js";
+import { logger } from "../log.js";
+import { defaultAgentDir } from "./config.js";
+import { shadowedBuiltin } from "./pi.js";
+const log = logger("packages");
+/** Set by how long a released fix may sit unnoticed, like update.ts. */
+const CHECK_EVERY_MS = 24 * 60 * 60_000;
+const KINDS = { extensions: "extension", skills: "skill" };
+/** Written by `rtk init -g --agent pi` (the rtk block's `post_install` hook): a `local` file whose
+ *  switch is the rtk tool's, so a settings.json pattern would fight the tool. */
+const RTK_FILE = join("extensions", "rtk.ts");
+const RTK_STATE = "installed by the rtk tool";
+export const kindOf = (source) => source.startsWith("npm:") ? "npm" : /^(git:|(https?|ssh|git):\/\/)/.test(source) ? "git" : "path";
+/** A trailing `@ref` on an npm or git source; the leading `@` of a scope is not one. */
+export const pinnedRef = (source) => {
+    const at = source.lastIndexOf("@");
+    const ref = at > 0 ? source.slice(at + 1) : "";
+    return ref && !/[/:]/.test(ref) ? ref : null;
+};
+/** An extension is named by its file (or the directory its index sits in); a
+ *  skill by its directory. Pi reads the frontmatter name at load, not here. */
+const nameOf = (kind, path) => {
+    const file = basename(path);
+    if (kind === "skill")
+        return file === "SKILL.md" ? basename(dirname(path)) : file.replace(/\.md$/, "");
+    const stem = file.replace(/\.[cm]?[jt]sx?$/, "");
+    return stem === "index" ? basename(dirname(path)) : stem;
+};
+const versionFile = async (dir) => {
+    if (!dir)
+        return null;
+    try {
+        const { version } = JSON.parse(await fs.readFile(join(dir, "package.json"), "utf8"));
+        return typeof version === "string" ? version : null;
+    }
+    catch (err) {
+        if (err instanceof Error && "code" in err && err.code === "ENOENT")
+            return null;
+        log.warn(`${dir}/package.json unreadable — no version shown`, err);
+        return null;
+    }
+};
+/** Pi's own toggle rule (its config selector): one `+path`/`-path` per resource,
+ *  any earlier pattern for the same path removed first. A bare entry stays: it
+ *  is what lists the file, not a pattern on it. */
+const flip = (entries, pattern, enabled) => [
+    ...entries.filter((p) => !(/^[!+-]/.test(p) && p.slice(1) === pattern)),
+    `${enabled ? "+" : "-"}${pattern}`,
+];
+/** What npm, git or Pi's manifest refused is the upstream's failure, answered
+ *  as such (502) with Pi's own sentence; a PackageError passes through. */
+const upstream = async (what, run) => {
+    try {
+        return await run();
+    }
+    catch (err) {
+        if (err instanceof PackageError)
+            throw err;
+        throw new PackageError("unreachable", `${what} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+};
+const resourceRow = (kind, r) => ({
+    kind, name: nameOf(kind, r.path), path: r.path, enabled: r.enabled, state: null,
+});
+export class PiPackageStore {
+    config;
+    pier;
+    skillDirs;
+    agentDir;
+    #busy = null;
+    #updates = new Set();
+    #checkedAt = null;
+    constructor(config, pier, 
+    /** Pier's own skill directories, the ones pi.ts loads per session. */
+    skillDirs, agentDir = defaultAgentDir()) {
+        this.config = config;
+        this.pier = pier;
+        this.skillDirs = skillDirs;
+        this.agentDir = agentDir;
+    }
+    /** Per call, never retained: Pi's manager caches nothing Pier wants to keep,
+     *  and a fresh SettingsManager reads whatever writeDefaults wrote last. */
+    #open(cwd) {
+        // Untrusted without a cwd: the project scope of the agent dir is nothing.
+        const settings = SettingsManager.create(cwd ?? this.agentDir, this.agentDir, { projectTrusted: cwd !== undefined });
+        this.#raise(settings, "read");
+        const manager = new DefaultPackageManager({ cwd: cwd ?? this.agentDir, agentDir: this.agentDir, settingsManager: settings });
+        manager.setProgressCallback((e) => log.info(`${e.action} ${e.source}: ${e.type}${e.message ? ` — ${e.message}` : ""}`));
+        return { settings, manager };
+    }
+    /** Pi's SettingsManager records a failed load or write and carries on (§5). */
+    #raise(settings, what) {
+        const errors = settings.drainErrors();
+        if (!errors.length)
+            return;
+        const detail = errors.map((e) => `${e.path ?? e.scope}: ${e.error.message}`).join("; ");
+        throw new PackageError("invalid", `settings.json could not be ${what}: ${detail}`);
+    }
+    async list(cwd) {
+        const { manager } = this.#open(cwd);
+        const rtkPath = join(this.agentDir, RTK_FILE);
+        const resolved = await manager.resolve(async () => "skip");
+        const rows = new Map();
+        const row = (source, kind, scope, installedPath) => {
+            const key = `${scope}\0${source}`;
+            let found = rows.get(key);
+            if (!found) {
+                found = { source, kind, scope, version: null, installedPath, updateAvailable: false, resources: [] };
+                rows.set(key, found);
+            }
+            return found;
+        };
+        row("pier", "pier", "global", null);
+        row("local", "local", "global", this.agentDir);
+        for (const key of Object.keys(KINDS)) {
+            for (const r of resolved[key]) {
+                const own = r.metadata.origin === "top-level";
+                const scope = r.metadata.scope === "project" ? "project" : "global";
+                const resource = resourceRow(KINDS[key], r);
+                if (r.path === rtkPath)
+                    Object.assign(resource, { state: RTK_STATE, locked: true });
+                row(own ? "local" : r.metadata.source, own ? "local" : kindOf(r.metadata.source), scope, r.metadata.baseDir ?? null)
+                    .resources.push(resource);
+            }
+        }
+        // Configured but unresolved (not installed, or empty): still a row.
+        for (const p of manager.listConfiguredPackages()) {
+            const found = row(p.source, kindOf(p.source), p.scope === "project" ? "project" : "global", p.installedPath ?? null);
+            found.installedPath ??= p.installedPath ?? null;
+            found.updateAvailable = this.#updates.has(p.source);
+        }
+        // pier, local, the global packages, then the project's rows; Pi's own order is precedence.
+        const rank = (p) => p.kind === "pier" ? 0 : p.scope === "project" ? 3 : p.kind === "local" ? 1 : 2;
+        const packages = [...rows.values()].sort((a, b) => rank(a) - rank(b));
+        for (const pkg of packages) {
+            if (pkg.kind === "pier")
+                await this.#fillPier(pkg);
+            else if (pkg.kind === "git")
+                pkg.version = pinnedRef(pkg.source);
+            else if (pkg.kind !== "local")
+                pkg.version = await versionFile(pkg.installedPath);
+        }
+        return { packages, checkedAt: this.#checkedAt, busy: this.#busy };
+    }
+    async #fillPier(pkg) {
+        pkg.version = this.pier.version;
+        const { extensions: on, skillsOff: off } = this.pier.settings.get();
+        // Off is off: a stand-down recorded while it was on is not this switch's state.
+        pkg.resources = BUNDLED.map(({ name }) => ({
+            kind: "extension", name, path: `<inline:${name}>`, enabled: on.includes(name),
+            state: on.includes(name) ? shadowedBuiltin(name) : null,
+        }));
+        for (const dir of this.skillDirs) {
+            for (const entry of (await fs.readdir(dir, { withFileTypes: true })).filter((e) => e.isDirectory())) {
+                const path = join(dir, entry.name, "SKILL.md");
+                if (!existsSync(path))
+                    continue;
+                pkg.resources.push({ kind: "skill", name: entry.name, path, enabled: !off.includes(entry.name), state: null });
+            }
+        }
+    }
+    /** One at a time: the second Console click is told, not queued behind an npm install. */
+    async #operate(source, run) {
+        if (this.#busy)
+            throw new PackageError("busy", `${this.#busy} is being changed; try again when it finishes`);
+        this.#busy = source;
+        try {
+            return await this.#write(run);
+        }
+        finally {
+            this.#busy = null;
+        }
+    }
+    /** Inside ConfigStore's queue, so writeDefaults and a session open never
+     *  interleave with Pi's merge-write; flushed and checked before it ends. */
+    #write(run, cwd) {
+        return this.config.withWrite(async () => {
+            const { manager, settings } = this.#open(cwd);
+            const result = await run(manager, settings);
+            await settings.flush();
+            this.#raise(settings, "written");
+            return result;
+        });
+    }
+    async #row(source) {
+        const found = (await this.list()).packages.find((p) => p.source === source);
+        if (!found)
+            throw new PackageError("missing", `${source} is not a configured package`);
+        return found;
+    }
+    /** `local` is one row per scope: the resource, not the source, picks the row. */
+    async #find({ source, kind, path, cwd }) {
+        const owners = (await this.list(cwd)).packages.filter((p) => p.source === source);
+        if (!owners.length)
+            throw new PackageError("missing", `${source} is not a configured package`);
+        for (const pkg of owners) {
+            const resource = pkg.resources.find((r) => r.kind === kind && r.path === path);
+            if (resource)
+                return { pkg, resource };
+        }
+        throw new PackageError("missing", `${source} has no ${kind} at ${path}`);
+    }
+    #builtin(source) {
+        if (source === "pier" || source === "local")
+            throw new PackageError("refused", `${source} is built in`);
+    }
+    async install(source) {
+        const spec = source.trim();
+        if (!spec)
+            throw new PackageError("invalid", "a package source is required");
+        this.#builtin(spec);
+        if (kindOf(spec) === "path" && !existsSync(resolve(this.agentDir, spec))) {
+            throw new PackageError("invalid", `no such path: ${resolve(this.agentDir, spec)}`);
+        }
+        // Pi stores a local path relative to the settings file: the row is named
+        // by what landed in settings.json, not by what was typed.
+        const stored = await this.#operate(spec, async (manager) => {
+            const sources = () => manager.listConfiguredPackages().filter((p) => p.scope === "user").map((p) => p.source);
+            const before = new Set(sources());
+            await upstream(`installing ${spec}`, () => manager.installAndPersist(spec));
+            const added = sources().find((s) => !before.has(s));
+            if (!added)
+                throw new PackageError("refused", `${spec} is already configured`);
+            return added;
+        });
+        return this.#row(stored);
+    }
+    async remove(source) {
+        this.#builtin(source);
+        await this.#operate(source, async (manager) => {
+            if (!manager.listConfiguredPackages().some((p) => p.scope === "user" && p.source === source)) {
+                throw new PackageError("missing", `${source} is not in settings.json`);
+            }
+            await upstream(`removing ${source}`, () => manager.removeAndPersist(source));
+        });
+    }
+    async update(source) {
+        const configured = this.#open().manager.listConfiguredPackages().filter((p) => p.scope === "user");
+        const movable = (s) => kindOf(s) !== "path" && pinnedRef(s) === null;
+        if (source !== undefined) {
+            this.#builtin(source);
+            if (!configured.some((p) => p.source === source))
+                throw new PackageError("missing", `${source} is not in settings.json`);
+            if (!movable(source))
+                throw new PackageError("refused", `${source} is pinned or local — nothing to move`);
+        }
+        const targets = source === undefined ? configured.map((p) => p.source).filter(movable) : [source];
+        await this.#operate(source ?? "every package", (manager) => upstream(`updating ${source ?? "every package"}`, () => manager.update(source)));
+        for (const s of targets)
+            this.#updates.delete(s);
+        const { packages } = await this.list();
+        return packages.filter((p) => p.scope === "global" && targets.includes(p.source));
+    }
+    async setEnabled(change) {
+        const { source, kind, path, enabled, cwd } = change;
+        const { pkg, resource } = await this.#find(change);
+        if (resource.locked)
+            throw new PackageError("refused", `${resource.name} is ${resource.state} — its switch is under Tools`);
+        if (pkg.kind === "pier") {
+            const { extensions, skillsOff } = this.pier.settings.get();
+            if (kind === "skill")
+                this.pier.settings.setSkillsOff(withName(skillsOff, resource.name, !enabled));
+            else
+                this.pier.settings.setExtensions(withName(extensions, resource.name, enabled));
+        }
+        else {
+            const key = kind === "extension" ? "extensions" : "skills";
+            await this.#write(async (manager, settings) => {
+                // Re-resolved under the lock: the pattern is relative to the base Pi
+                // resolved it from, which is the only base its filter will match.
+                const r = (await manager.resolve(async () => "skip"))[key].find((it) => it.path === path);
+                if (!r)
+                    throw new PackageError("missing", `${path} is not loaded from ${source}`);
+                const project = cwd !== undefined;
+                const inherited = project && r.metadata.scope !== "project";
+                const scoped = project ? settings.getProjectSettings() : settings.getGlobalSettings();
+                const projectDir = join(cwd ?? this.agentDir, ".pi");
+                if (r.metadata.origin === "top-level") {
+                    // A global resource switched for one project is named by its absolute path there.
+                    const pattern = inherited ? path : relative(r.metadata.baseDir ?? (project ? projectDir : this.agentDir), path);
+                    const next = flip(scoped[key] ?? [], pattern, enabled);
+                    if (inherited && !next.includes(path))
+                        next.unshift(path);
+                    if (project)
+                        settings[key === "extensions" ? "setProjectExtensionPaths" : "setProjectSkillPaths"](next);
+                    else
+                        settings[key === "extensions" ? "setExtensionPaths" : "setSkillPaths"](next);
+                }
+                else {
+                    const pattern = relative(r.metadata.baseDir ?? dirname(path), path);
+                    const packages = [...(scoped.packages ?? [])];
+                    let at = packages.findIndex((p) => (typeof p === "string" ? p : p.source) === source);
+                    // A global package overridden for one project: Pi's delta entry, a
+                    // local path re-based on .pi/ because that is where Pi resolves it from.
+                    if (at === -1 && inherited) {
+                        const own = kindOf(source) === "path" ? relative(projectDir, resolve(this.agentDir, source)) || "." : source;
+                        at = packages.push({ source: own, autoload: false }) - 1;
+                    }
+                    if (at === -1)
+                        throw new PackageError("missing", `${source} is not in settings.json`);
+                    const entry = packages[at];
+                    const filtered = typeof entry === "string" ? { source: entry } : { ...entry };
+                    filtered[key] = flip(filtered[key] ?? [], pattern, enabled);
+                    packages[at] = filtered;
+                    if (project)
+                        settings.setProjectPackages(packages);
+                    else
+                        settings.setPackages(packages);
+                }
+            }, cwd);
+        }
+        // By path, not source: an override moves the resource to the project's row.
+        const after = (await this.list(cwd)).packages.flatMap((p) => p.resources).find((r) => r.kind === kind && r.path === path);
+        if (!after)
+            throw new PackageError("missing", `${path} is no longer loaded`);
+        return after;
+    }
+    async checkUpdates() {
+        const { manager } = this.#open();
+        const found = await upstream("update check", () => manager.checkForAvailableUpdates());
+        this.#updates = new Set(found.filter((u) => u.scope === "user").map((u) => u.source));
+        this.#checkedAt = new Date().toISOString();
+        if (this.#updates.size)
+            log.info(`package updates available: ${[...this.#updates].join(", ")}`);
+        return this.list();
+    }
+    /** At boot and daily, like update.ts; the answer waits in `list` for the next
+     *  Console open. Returns its own stop. */
+    watchUpdates(everyMs = CHECK_EVERY_MS) {
+        const tick = () => {
+            void this.checkUpdates().catch((err) => log.warn(String(err)));
+        };
+        tick();
+        const timer = setInterval(tick, everyMs);
+        timer.unref();
+        return () => clearInterval(timer);
+    }
+}
+const withName = (names, name, on) => on ? [...new Set([...names, name])] : names.filter((n) => n !== name);