@finngi/pi-resources 0.0.0-stage → 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 finngi2 contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# @finngi/pi-resources
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Experimental alpha; tested with Node 24 and stock Pi 1.2.0.
+
+`pi install npm:@finngi/pi-resources@0.1.0-alpha.0`
+
+This download includes its workspace dependencies. No sibling packages are required.
+
+
+Choose which skills and packages a Pi session can use, without loading delegation, background
+jobs or permissions. It adds `/skills`, `/packages` and the shared `session_setup` tool, using
+Pi's loaded resources and the shared resource browser.
+
+- `/skills` chooses which skill descriptions the parent's prompt lists. Skill bodies still load on
+  demand, and `/skill:name` is refused for skills that are off.
+- `/packages` makes package resources available or hides them. It does not select their skills,
+  agents or instructions. Those choices stay independent, and return when a disabled package is
+  enabled again. Packages with only extensions are not listed: availability never changes which
+  extension code loads. Agents need `pi-delegation` and instructions need `pi-context`. Opening
+  the picker loads neither.
+
+## Saving choices
+
+Session, Project and Global each show their own Inherit, On or Off choice. The most specific
+explicit choice wins; Inherit follows the broader scope, ending at Pi's default. Turning a skill
+off for this session leaves its project and global choices intact. The picker shows the effective
+choice and where it came from separately.
+
+Project and Global also offer a session type: **Any session**, **Interactive only** or
+**Type: Inherit**. Interactive means Pi's TUI; RPC (even with dialogs), print mode and delegated
+children are excluded. Session type does not turn a resource on or off. A project type overrides
+the global one. Session has no type of its own.
+
+Ctrl+S copies eligible current On/Off selections to project defaults; Ctrl+Shift+S copies them to
+personal defaults. Bulk saves leave session types alone. Changing a single scope control only
+writes that resource at that scope. Editing defaults here rereads them for this session without
+replacing its explicit overrides. Other running sessions keep their current defaults.
+
+`/skills enable NAME` and `/skills disable NAME` set one skill's session choice, like the picker;
+other skills keep inheriting. `/skills all` and `/skills none` turn every listed skill on or off
+for this session, and `/skills inherit` clears this session's skill choices.
+
+Leaving and resuming a session rereads saved defaults. Explicit session choices stay; inherited
+choices follow the current defaults. Resuming never reloads executable extensions or stops
+children. New package registrations and native skill paths still need Pi's idle `/reload` or a
+new invocation.
+
+If a saved choice or session type is not valid (for example an old list instead of an ID map), that
+category uses Pi's defaults and Pi shows a warning; `session_setup` also returns it. Other
+categories and the active tools are unaffected. In an RPC or print session, `session_setup apply`
+names any requested interactive-only resources it leaves out.
+
+Older session records contain complete selection snapshots rather than per-item overrides. Those
+snapshots stay explicit so an upgrade cannot guess which choices you meant to keep. Choose Inherit
+for a row, or reset that category with `session_setup`, to follow saved defaults again.
+
+A grey Global control means the resource only exists in this project or this `-e` run. The reason
+shows in Overview and when you use the control. To make a package available in every project,
+register its source in personal settings with Pi and include the resource in any package filters.
+Saving defaults does not register sources. Package availability is saved separately in
+`resourcePackages`; it never rewrites individual resource defaults or the native source list.
+
+New delegated children follow saved package availability as headless sessions, so packages that
+are off or Interactive only stay out. Package skills with no saved choice are off in children too.
+An agent's explicit `skills` list cannot pull a skill from a hidden package; the launch warns.
+
+## Picking is not installing
+
+`pi install SOURCE` saves a personal package source, `pi install --local SOURCE` a project one,
+and `pi -e SOURCE` tries a package for one run. Those are Pi commands. This extension never
+installs packages, unloads code, changes permissions or restarts children. See
+[package design](https://github.com/finngi/pi-packages/blob/main/docs/package-design.md).
+
+`pi-delegation` owns `/agents` and child sessions; `pi-context` owns `/instructions` and adds
+snippets to the prompt. All three share one `session_setup` service and session record format.
+Without `pi-resources`, Pi loads skills as usual and delegation's skill rules still work. Children
+get their launcher's explicit skills and never run a picker.
+
+When you resume a session with recorded skill choices, load `pi-resources` again. Resources from
+missing packages do not appear; their recorded overrides remain available if the resources return.
+
+## Library APIs
+
+Other extensions can import these without turning on `/skills`, `/packages` or parent skill
+filtering:
+
+| Import | Provides |
+| --- | --- |
+| `pi-resources/discovery` | Resolved package resources and agent and instruction descriptors |
+| `pi-resources/selection` | Saved personal and project selections and saving |
+| `pi-resources/session-setup` | The shared session selection service, installed by calling a function |
+| `pi-resources/instructions` | Requests saved instruction text from the loaded context extension |
+| `pi-resources/picker` | Shared scope controls for skills, agents, instructions and package groups |
+
+The package's default entrypoint is the extension, and the library subpaths never import it.
+Delegation and context use these APIs but still load on their own; each installs the session setup
+service it needs. Pi still owns installation, trust and filters. No import scans a new catalogue,
+loads another extension or writes settings.
+
+## Tests
+
+```sh
+npm run test --workspace=pi-resources
+npm run typecheck --workspace=pi-resources
+```
+
+Stock-Pi tests cover each extension on its own, both loading orders and resumed choices.
+Entrypoint: [resources.ts](https://github.com/finngi/pi-packages/blob/main/packages/pi-resources/extensions/resources.ts).

package/node_modules/pi-resources/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 finngi2 contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/pi-resources/README.md

@@ -0,0 +1,101 @@
+# pi-resources
+
+Choose which skills and packages a Pi session can use, without loading delegation, background
+jobs or permissions. It adds `/skills`, `/packages` and the shared `session_setup` tool, using
+Pi's loaded resources and the shared resource browser.
+
+- `/skills` chooses which skill descriptions the parent's prompt lists. Skill bodies still load on
+  demand, and `/skill:name` is refused for skills that are off.
+- `/packages` makes package resources available or hides them. It does not select their skills,
+  agents or instructions. Those choices stay independent, and return when a disabled package is
+  enabled again. Packages with only extensions are not listed: availability never changes which
+  extension code loads. Agents need `pi-delegation` and instructions need `pi-context`. Opening
+  the picker loads neither.
+
+## Saving choices
+
+Session, Project and Global each show their own Inherit, On or Off choice. The most specific
+explicit choice wins; Inherit follows the broader scope, ending at Pi's default. Turning a skill
+off for this session leaves its project and global choices intact. The picker shows the effective
+choice and where it came from separately.
+
+Project and Global also offer a session type: **Any session**, **Interactive only** or
+**Type: Inherit**. Interactive means Pi's TUI; RPC (even with dialogs), print mode and delegated
+children are excluded. Session type does not turn a resource on or off. A project type overrides
+the global one. Session has no type of its own.
+
+Ctrl+S copies eligible current On/Off selections to project defaults; Ctrl+Shift+S copies them to
+personal defaults. Bulk saves leave session types alone. Changing a single scope control only
+writes that resource at that scope. Editing defaults here rereads them for this session without
+replacing its explicit overrides. Other running sessions keep their current defaults.
+
+`/skills enable NAME` and `/skills disable NAME` set one skill's session choice, like the picker;
+other skills keep inheriting. `/skills all` and `/skills none` turn every listed skill on or off
+for this session, and `/skills inherit` clears this session's skill choices.
+
+Leaving and resuming a session rereads saved defaults. Explicit session choices stay; inherited
+choices follow the current defaults. Resuming never reloads executable extensions or stops
+children. New package registrations and native skill paths still need Pi's idle `/reload` or a
+new invocation.
+
+If a saved choice or session type is not valid (for example an old list instead of an ID map), that
+category uses Pi's defaults and Pi shows a warning; `session_setup` also returns it. Other
+categories and the active tools are unaffected. In an RPC or print session, `session_setup apply`
+names any requested interactive-only resources it leaves out.
+
+Older session records contain complete selection snapshots rather than per-item overrides. Those
+snapshots stay explicit so an upgrade cannot guess which choices you meant to keep. Choose Inherit
+for a row, or reset that category with `session_setup`, to follow saved defaults again.
+
+A grey Global control means the resource only exists in this project or this `-e` run. The reason
+shows in Overview and when you use the control. To make a package available in every project,
+register its source in personal settings with Pi and include the resource in any package filters.
+Saving defaults does not register sources. Package availability is saved separately in
+`resourcePackages`; it never rewrites individual resource defaults or the native source list.
+
+New delegated children follow saved package availability as headless sessions, so packages that
+are off or Interactive only stay out. Package skills with no saved choice are off in children too.
+An agent's explicit `skills` list cannot pull a skill from a hidden package; the launch warns.
+
+## Picking is not installing
+
+`pi install SOURCE` saves a personal package source, `pi install --local SOURCE` a project one,
+and `pi -e SOURCE` tries a package for one run. Those are Pi commands. This extension never
+installs packages, unloads code, changes permissions or restarts children. See
+[package design](../../docs/package-design.md).
+
+`pi-delegation` owns `/agents` and child sessions; `pi-context` owns `/instructions` and adds
+snippets to the prompt. All three share one `session_setup` service and session record format.
+Without `pi-resources`, Pi loads skills as usual and delegation's skill rules still work. Children
+get their launcher's explicit skills and never run a picker.
+
+When you resume a session with recorded skill choices, load `pi-resources` again. Resources from
+missing packages do not appear; their recorded overrides remain available if the resources return.
+
+## Library APIs
+
+Other extensions can import these without turning on `/skills`, `/packages` or parent skill
+filtering:
+
+| Import | Provides |
+| --- | --- |
+| `pi-resources/discovery` | Resolved package resources and agent and instruction descriptors |
+| `pi-resources/selection` | Saved personal and project selections and saving |
+| `pi-resources/session-setup` | The shared session selection service, installed by calling a function |
+| `pi-resources/instructions` | Requests saved instruction text from the loaded context extension |
+| `pi-resources/picker` | Shared scope controls for skills, agents, instructions and package groups |
+
+The package's default entrypoint is the extension, and the library subpaths never import it.
+Delegation and context use these APIs but still load on their own; each installs the session setup
+service it needs. Pi still owns installation, trust and filters. No import scans a new catalogue,
+loads another extension or writes settings.
+
+## Tests
+
+```sh
+npm run test --workspace=pi-resources
+npm run typecheck --workspace=pi-resources
+```
+
+Stock-Pi tests cover each extension on its own, both loading orders and resumed choices.
+Entrypoint: [resources.ts](extensions/resources.ts).

package/node_modules/pi-resources/dist/extensions/resources.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** Session-only selection of native loaded resources. Importing shared helpers has no effect. */
+export default function (pi: ExtensionAPI): void;

package/node_modules/pi-resources/dist/extensions/resources.js

@@ -0,0 +1,273 @@
+import { statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { getAgentDir, loadSkills, parseFrontmatter, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { SESSION_SETUP_CONTRIBUTIONS } from "pi-contracts";
+import { showResourceBrowser, resourceBrowserNavigation, } from "pi-resource-browser";
+import { configuredSkillChoices, filterPromptSkills, selectedSkills, } from "pi-resources/selection";
+import { discoverResourcePackages, resourcePackageKeywords, } from "pi-resources/discovery";
+import { installSessionSetup } from "pi-resources/session-setup";
+import { resourcePickerControls } from "pi-resources/picker";
+import { registerPackagePicker } from "../lib/package-picker.js";
+/** Session-only selection of native loaded resources. Importing shared helpers has no effect. */
+export default function (pi) {
+    // Children already receive an explicit public/private skill set from their launcher.
+    if (process.env.PI_SUBAGENT === "1")
+        return;
+    const setup = installSessionSetup(pi);
+    let packageResources = {
+        packs: [],
+        problems: [],
+    };
+    let nativePersonalSkillPaths = new Set();
+    let skillChoicesSnapshot = [];
+    let skillIdentities = new Map();
+    const errorText = (error) => (error instanceof Error ? error.message : String(error));
+    const skills = () => pi
+        .getCommands()
+        .filter((c) => c.source === "skill")
+        .map((c) => ({
+        name: c.name.replace(/^skill:/, ""),
+        description: c.description,
+        path: c.sourceInfo.path,
+        source: c.sourceInfo,
+    }));
+    const personalSkillDefault = (skill) => {
+        const pack = packageResources.packs.find((pack) => pack.name === skill.packName);
+        // Native metadata may label a CLI-enabled skill as user-scoped even when the personal
+        // package excludes it. Only the resolver's enabled personal members are defaultable.
+        if (pack)
+            return pack.globalDefaultable !== false && !!pack.personalSkills?.includes(skill.path);
+        return !skill.defaultSelected || nativePersonalSkillPaths.has(skill.path);
+    };
+    const settingsManager = (ctx) => SettingsManager.create(ctx.cwd, getAgentDir(), { projectTrusted: ctx.isProjectTrusted() });
+    const selectedPublicSkills = (ctx) => {
+        const manager = settingsManager(ctx);
+        const choices = currentSkillChoices(ctx);
+        const selected = setup.selection("skills");
+        if (selected !== undefined) {
+            const missing = selected.filter((name) => !choices.some((choice) => choice.name === name));
+            if (missing.length)
+                throw Error(`Selected skills are no longer registered or unchanged: ${missing.join(", ")}. Reload resources.`);
+            return choices.filter((choice) => selected.includes(choice.name));
+        }
+        return selectedSkills(manager, choices, false, undefined, ctx.mode === "tui");
+    };
+    const currentSkillChoices = (ctx) => {
+        const registered = skills();
+        return skillChoicesSnapshot.filter((choice) => {
+            try {
+                if (!registered.some((skill) => skill.name === choice.name &&
+                    resolve(ctx.cwd, skill.path) === resolve(ctx.cwd, choice.path)))
+                    return false;
+                const info = statSync(choice.path), identity = skillIdentities.get(choice.path);
+                if (!identity || !info.isFile() || info.dev !== identity.dev || info.ino !== identity.ino)
+                    return false;
+                const actual = loadSkills({
+                    cwd: ctx.cwd,
+                    agentDir: getAgentDir(),
+                    skillPaths: [choice.path],
+                    includeDefaults: false,
+                }).skills;
+                return actual.some((skill) => skill.name === choice.name && skill.filePath === choice.path);
+            }
+            catch {
+                return false;
+            }
+        });
+    };
+    const refreshResources = async (ctx) => {
+        packageResources = await discoverResourcePackages(settingsManager(ctx), ctx.cwd, getAgentDir(), skills().map((skill) => skill.source));
+        // Only resources already loaded by native Pi can enter this session selection.
+        nativePersonalSkillPaths = new Set(skills()
+            .filter((skill) => skill.source.scope === "user")
+            .map((skill) => skill.path));
+        skillChoicesSnapshot = configuredSkillChoices(ctx.cwd, getAgentDir(), skills().map((skill) => ({ name: skill.name, path: skill.path })), packageResources.packs);
+        skillIdentities = new Map();
+        skillChoicesSnapshot = skillChoicesSnapshot.filter((skill) => {
+            try {
+                const { dev, ino } = statSync(skill.path);
+                skillIdentities.set(skill.path, { dev, ino });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+    };
+    pi.on("session_start", async (_input, ctx) => refreshResources(ctx));
+    pi.on("input", (event, ctx) => {
+        const match = /^\/skill:([^\s]+)(?:\s|$)/.exec(event.text);
+        if (!match)
+            return;
+        try {
+            const selected = new Set(selectedPublicSkills(ctx).map((skill) => skill.name));
+            if (selected.has(match[1]))
+                return;
+            ctx.ui.notify(`Skill "${match[1]}" is not selected for this session. Use /skills to choose it.`, "warning");
+            return { action: "handled" };
+        }
+        catch (error) {
+            ctx.ui.notify(`Could not validate skill selection: ${error instanceof Error ? error.message : String(error)}`, "warning");
+            return { action: "handled" };
+        }
+    });
+    pi.on("before_agent_start", (input, ctx) => {
+        try {
+            input.systemPromptOptions.skills = filterPromptSkills(input.systemPromptOptions.skills ?? [], selectedPublicSkills(ctx));
+        }
+        catch (error) {
+            input.systemPromptOptions.skills = [];
+            if (ctx.hasUI)
+                ctx.ui.notify(`Could not validate selected skills; no skills were added to the prompt. Run /skills to inspect settings. (${errorText(error)})`, "warning");
+        }
+    });
+    pi.events.on(SESSION_SETUP_CONTRIBUTIONS, (value) => {
+        const request = value;
+        if (request?.version !== 1 || typeof request.contribute !== "function")
+            return;
+        const ctx = request.ctx, manager = settingsManager(ctx);
+        const choices = currentSkillChoices(ctx);
+        let selectedSkillIds = [];
+        try {
+            selectedSkillIds = selectedSkills(manager, choices, false, undefined, ctx.mode === "tui").map((skill) => skill.name);
+        }
+        catch { }
+        request.contribute({
+            kind: "skills",
+            candidates: choices.map((skill) => ({
+                kind: "skills",
+                id: skill.name,
+                name: skill.name,
+                description: skill.description,
+                path: skill.path,
+                nativeDefault: skill.defaultSelected,
+                globalDefaultable: personalSkillDefault(skill),
+                ...(skill.manualOnly ? { manualOnly: true } : {}),
+                ...(skill.packName ? { packName: skill.packName, keywords: skill.packKeywords } : {}),
+            })),
+            selected: selectedSkillIds,
+        });
+        request.contribute({
+            kind: "packages",
+            candidates: packageResources.packs.map((pack) => ({
+                kind: "packages",
+                id: pack.name,
+                name: pack.name,
+                description: pack.description,
+                keywords: resourcePackageKeywords(pack),
+                globalDefaultable: pack.globalDefaultable,
+                nativeDefault: true,
+            })),
+            selected: [],
+        });
+    });
+    registerPackagePicker(pi, setup, () => packageResources.problems);
+    const selectionArgs = (args) => {
+        const match = /^(enable|disable|none|all|inherit|inspect)(?:\s+(.+))?$/.exec(args.trim());
+        return match ? { action: match[1], name: match[2]?.trim() } : undefined;
+    };
+    pi.registerCommand("skills", {
+        description: "Select skills for this session; Ctrl+S saves project defaults; Ctrl+Shift+S saves personal defaults",
+        async handler(args, ctx) {
+            const command = args.trim();
+            const action = selectionArgs(command);
+            const repairingInvalidProjectSelection = action?.action === "none" || action?.action === "all" || action?.action === "inherit";
+            const manager = settingsManager(ctx);
+            const loaded = skills().map((skill) => ({ name: skill.name, path: skill.path }));
+            const available = new Set(setup
+                .inspect(ctx)
+                .find((value) => value.kind === "skills")
+                ?.candidates.map((candidate) => candidate.id));
+            const choices = configuredSkillChoices(ctx.cwd, getAgentDir(), loaded, packageResources.packs).filter((choice) => available.has(choice.name));
+            const selected = selectedSkills(manager, choices, repairingInvalidProjectSelection, undefined, ctx.mode === "tui");
+            const selectedNames = new Set(setup.selection("skills") ?? selected.map((skill) => skill.name));
+            if (action) {
+                // Session choices are per skill, like the picker; unlisted skills keep inheriting.
+                const toggleable = choices.filter((skill) => skill.toggleable);
+                if (action.action === "none" || action.action === "all") {
+                    const state = action.action === "all" ? "on" : "off";
+                    setup.setStates("skills", Object.fromEntries(toggleable.map((skill) => [skill.name, state])), ctx);
+                    return;
+                }
+                else if (action.action === "inherit") {
+                    setup.execute({ op: "reset", kinds: ["skills"] }, ctx);
+                    return;
+                }
+                else if (action.action === "enable" || action.action === "disable") {
+                    const choice = toggleable.find((skill) => skill.name === action.name);
+                    if (!choice)
+                        throw Error(`Unknown selectable public skill "${action.name ?? ""}"`);
+                    setup.setState("skills", choice.name, action.action === "enable" ? "on" : "off", ctx);
+                    return;
+                }
+                else if (action.action === "inspect" && !action.name) {
+                    throw Error("Use /skills inspect NAME");
+                }
+                else if (action.action !== "inspect") {
+                    throw Error(`Unsupported skill selection command: ${action.action}`);
+                }
+            }
+            let inspectName = action?.action === "inspect" ? action.name : undefined;
+            if (!action && command)
+                inspectName = command;
+            if (!inspectName && !action && ctx.hasUI && choices.length) {
+                const entries = choices.map((skill) => {
+                    return {
+                        id: skill.name,
+                        name: skill.name,
+                        description: skill.description,
+                        keywords: `${skill.manualOnly ? "manual command" : "model skill"} ${skill.packKeywords ?? ""}`,
+                        selected: selectedNames.has(skill.name),
+                        globalDefaultable: personalSkillDefault(skill),
+                        toggleable: skill.toggleable,
+                        badge: skill.packName ?? (skill.manualOnly ? "manual" : undefined),
+                        preview: async () => {
+                            const { body, frontmatter } = parseFrontmatter(await readFile(skill.path, "utf8"));
+                            const invocation = frontmatter["disable-model-invocation"] === true
+                                ? "Manual command only"
+                                : "Description advertised when selected";
+                            return {
+                                fields: [{ label: "Invocation", value: invocation }],
+                                source: skill.path,
+                                body,
+                            };
+                        },
+                    };
+                });
+                await showResourceBrowser(ctx, {
+                    title: "Skills",
+                    ...resourceBrowserNavigation(pi, "skills"),
+                    selectionScope: "session",
+                    defaultsScope: "project",
+                    entries,
+                    ...resourcePickerControls({
+                        ctx,
+                        setup,
+                        entries,
+                        members: (entry) => [
+                            {
+                                kind: "skills",
+                                id: entry.id,
+                                nativeDefault: choices.find((choice) => choice.name === entry.id)?.defaultSelected,
+                                globalDefaultable: entry.globalDefaultable,
+                            },
+                        ],
+                    }),
+                });
+                return;
+            }
+            if (inspectName) {
+                const skill = choices.find((item) => item.name === inspectName);
+                if (!skill)
+                    throw Error(`Unknown public skill "${inspectName}"`);
+                ctx.ui.notify(`${skill.name} — ${skill.description}\n${skill.path}`, "info");
+                return;
+            }
+            const rows = [
+                ...choices.map((skill) => `${selectedNames.has(skill.name) ? "[x]" : "[ ]"} ${skill.name} — ${skill.description}\n${skill.path}`),
+            ];
+            ctx.ui.notify(rows.join("\n\n") || "No public skills are available.", "info");
+        },
+    });
+}

package/node_modules/pi-resources/dist/lib/package-picker.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { installSessionSetup } from "pi-resources/session-setup";
+export declare function registerPackagePicker(pi: ExtensionAPI, setup: ReturnType<typeof installSessionSetup>, diagnostics: () => string[]): void;

package/node_modules/pi-resources/dist/lib/package-picker.js

@@ -0,0 +1,61 @@
+import { showResourceBrowser, resourceBrowserNavigation, } from "pi-resource-browser";
+import { resourcePickerControls } from "./picker.js";
+export function registerPackagePicker(pi, setup, diagnostics) {
+    pi.registerCommand("packages", {
+        description: "Choose available packages without selecting their contents",
+        async handler(_args, ctx) {
+            await ctx.waitForIdle();
+            const inspect = () => setup.inspect(ctx);
+            const contributions = inspect();
+            const entries = contributions
+                .filter((value) => value.kind === "packages")
+                .flatMap((value) => value.candidates)
+                .map((pack) => ({
+                id: pack.id,
+                name: pack.name.replace(/^@[^/]+\/pi-/, ""),
+                description: pack.description,
+                keywords: pack.keywords,
+                selected: false,
+                globalDefaultable: pack.globalDefaultable,
+                preview: async () => ({
+                    fields: [
+                        { label: "Package", value: pack.id },
+                        {
+                            label: "Resources",
+                            value: "Discoverable when enabled; select contents separately.",
+                        },
+                        {
+                            label: "Code",
+                            value: "Native extensions load at startup; code changes need restart.",
+                        },
+                    ],
+                }),
+            }));
+            if (!ctx.hasUI) {
+                ctx.ui.notify("Use session_setup to select package guidance in a headless session.", "info");
+                return;
+            }
+            await showResourceBrowser(ctx, {
+                title: "Packages",
+                ...resourceBrowserNavigation(pi, "packages"),
+                entries,
+                selectionScope: "session",
+                defaultsScope: "project",
+                notice: diagnostics().join("\n") || undefined,
+                ...resourcePickerControls({
+                    ctx,
+                    setup,
+                    entries,
+                    members: (entry) => [
+                        {
+                            kind: "packages",
+                            id: entry.id,
+                            nativeDefault: true,
+                            globalDefaultable: entry.globalDefaultable,
+                        },
+                    ],
+                }),
+            });
+        },
+    });
+}

package/node_modules/pi-resources/dist/lib/picker.d.ts

@@ -0,0 +1,25 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ResourceEntry, ResourceDefaultState, ResourceSessionMode } from "pi-resource-browser";
+import { type ResourceKind } from "./resource-selection.ts";
+import type { installSessionSetup } from "./session-setup.ts";
+export interface PickerMember {
+    kind: ResourceKind;
+    id: string;
+    nativeDefault?: boolean;
+    globalDefaultable?: boolean;
+}
+/** One scope implementation for independent resources and package availability. */
+export declare function resourcePickerControls(options: {
+    ctx: ExtensionCommandContext;
+    setup: ReturnType<typeof installSessionSetup>;
+    entries: ResourceEntry[];
+    members(entry: ResourceEntry): PickerMember[];
+}): {
+    refresh: () => void;
+    toggle: (entry: ResourceEntry, selected: boolean) => Promise<void>;
+    setSession: (entry: ResourceEntry, state: ResourceDefaultState) => Promise<void>;
+    setDefault: (entry: ResourceEntry, state: ResourceDefaultState, scope: "project" | "global") => Promise<void>;
+    setMode: (entry: ResourceEntry, mode: ResourceSessionMode, scope: "project" | "global") => Promise<void>;
+    saveDefaults: (rows: ResourceEntry[]) => Promise<void>;
+    saveGlobalDefaults: (rows: ResourceEntry[]) => Promise<void>;
+};