@jmfederico/pi-web 1.202606.1 → 1.202606.2

package/dist/shared/apiTypes.d.ts

@@ -1,5 +1,9 @@
 export type MachineKind = "local" | "remote";
 export type MachineStatus = "unknown" | "online" | "offline" | "error";
+export declare const PI_WEB_CAPABILITIES: {
+    readonly sessionsDeleteArchived: "sessions.deleteArchived";
+};
+export type PiWebCapability = typeof PI_WEB_CAPABILITIES[keyof typeof PI_WEB_CAPABILITIES];
 export interface Machine {
     id: string;
     name: string;
@@ -19,6 +23,16 @@ export interface MachineHealth {
     sessiond?: PiWebComponentStatus;
     error?: string;
 }
+export interface MachineRuntime {
+    machineId: string;
+    ok: boolean;
+    checkedAt: string;
+    packageName?: string;
+    generatedAt?: string;
+    components?: PiWebRuntimeResponse["components"];
+    capabilities?: PiWebCapability[];
+    error?: string;
+}
 export type PiWebShortcutConfig = Record<string, string | null>;
 export type PiWebPluginSettings = Record<string, unknown>;
 export type PiWebPluginConfigMap = Record<string, PiWebPluginConfig>;
@@ -40,6 +54,7 @@ export interface PiWebPluginInfo {
     module: string;
     source: string;
     scope: PiWebPluginScope;
+    machineSpecific: boolean;
     enabled: boolean;
 }
 export interface PiWebPluginsResponse {
@@ -73,10 +88,12 @@ export interface Workspace {
     isGitRepo: boolean;
     isGitWorktree: boolean;
 }
-export interface SessionInfo {
+export interface SessionRef {
     id: string;
-    path: string;
     cwd: string;
+}
+export interface SessionInfo extends SessionRef {
+    path: string;
     name?: string;
     created: string;
     modified: string;
@@ -312,6 +329,14 @@ export interface PiWebComponentStatus {
     installation?: PiWebInstallationInfo;
     error?: string;
 }
+export interface PiWebRuntimeComponent {
+    component: PiWebServiceComponent;
+    label: string;
+    runtimeVersion?: string;
+    available: boolean;
+    capabilities: PiWebCapability[];
+    error?: string;
+}
 export interface PiWebReleaseStatus {
     packageName: string;
     latestVersion?: string;
@@ -335,6 +360,15 @@ export interface PiWebVersionResponse {
         sessiond: PiWebComponentStatus;
     };
 }
+export interface PiWebRuntimeResponse {
+    packageName: string;
+    generatedAt: string;
+    components: {
+        web: PiWebRuntimeComponent;
+        sessiond: PiWebRuntimeComponent;
+    };
+    capabilities: PiWebCapability[];
+}
 export interface PiWebStatusResponse extends PiWebVersionResponse {
     release: PiWebReleaseStatus;
     commands: {

package/dist/shared/apiTypes.js

@@ -1,2 +1,4 @@
-export {};
+export const PI_WEB_CAPABILITIES = {
+    sessionsDeleteArchived: "sessions.deleteArchived",
+};
 //# sourceMappingURL=apiTypes.js.map

package/dist/shared/apiTypes.js.map

@@ -1 +1 @@
-{"version":3,"file":"apiTypes.js","sourceRoot":"","sources":["../../src/shared/apiTypes.ts"],"names":[],"mappings":""}
+{"version":3,"file":"apiTypes.js","sourceRoot":"","sources":["../../src/shared/apiTypes.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,sBAAsB,EAAE,yBAAyB;CACzC,CAAC"}

package/dist/shared/capabilities.js

@@ -0,0 +1,25 @@
+import { PI_WEB_CAPABILITIES } from "./apiTypes.js";
+export { PI_WEB_CAPABILITIES };
+export const KNOWN_PI_WEB_CAPABILITIES = Object.values(PI_WEB_CAPABILITIES);
+const knownPiWebCapabilities = new Set(KNOWN_PI_WEB_CAPABILITIES);
+export const WEB_RUNTIME_CAPABILITIES = [PI_WEB_CAPABILITIES.sessionsDeleteArchived];
+export const SESSIOND_RUNTIME_CAPABILITIES = [PI_WEB_CAPABILITIES.sessionsDeleteArchived];
+const EFFECTIVE_CAPABILITY_REQUIREMENTS = {
+    [PI_WEB_CAPABILITIES.sessionsDeleteArchived]: ["web", "sessiond"],
+};
+export function isPiWebCapability(value) {
+    return typeof value === "string" && knownPiWebCapabilities.has(value);
+}
+export function supportsPiWebCapability(source, capability) {
+    return source?.capabilities?.includes(capability) === true;
+}
+export function effectivePiWebCapabilities(components) {
+    return KNOWN_PI_WEB_CAPABILITIES.filter((capability) => {
+        const requiredComponents = EFFECTIVE_CAPABILITY_REQUIREMENTS[capability];
+        return requiredComponents.every((component) => {
+            const runtime = components[component];
+            return runtime?.available === true && supportsPiWebCapability(runtime, capability);
+        });
+    });
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/shared/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/shared/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAgF,MAAM,eAAe,CAAC;AAElI,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAG/B,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAC5E,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAEvF,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,mBAAmB,CAAC,sBAAsB,CAA+C,CAAC;AACnI,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,mBAAmB,CAAC,sBAAsB,CAA+C,CAAC;AAExI,MAAM,iCAAiC,GAAG;IACxC,CAAC,mBAAmB,CAAC,sBAAsB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC;CACW,CAAC;AAE/E,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,sBAAsB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,MAAiE,EAAE,UAA2B;IACpI,OAAO,MAAM,EAAE,YAAY,EAAE,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,UAA6G;IACtJ,OAAO,yBAAyB,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE;QACrD,MAAM,kBAAkB,GAAG,iCAAiC,CAAC,UAAU,CAAC,CAAC;QACzE,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,EAAE;YAC5C,MAAM,OAAO,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;YACtC,OAAO,OAAO,EAAE,SAAS,KAAK,IAAI,IAAI,uBAAuB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QACrF,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/shared/federatedRoutes.js

@@ -1,4 +1,5 @@
 export const FEDERATED_HTTP_ROUTES = [
+    { method: "GET", path: "/pi-web/status" },
     { method: "GET", path: "/projects" },
     { method: "POST", path: "/projects" },
     { method: "DELETE", path: "/projects/:projectId" },
@@ -41,6 +42,7 @@ export const FEDERATED_HTTP_ROUTES = [
     { method: "POST", path: "/sessions/:sessionId/archive" },
     { method: "POST", path: "/sessions/:sessionId/archive-tree" },
     { method: "POST", path: "/sessions/:sessionId/restore" },
+    { method: "DELETE", path: "/sessions/:sessionId" },
     { method: "POST", path: "/sessions/:sessionId/detach-parent" },
     { method: "GET", path: "/auth/providers" },
     { method: "POST", path: "/auth/api-key" },

package/dist/shared/federatedRoutes.js.map

@@ -1 +1 @@
-{"version":3,"file":"federatedRoutes.js","sourceRoot":"","sources":["../../src/shared/federatedRoutes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"federatedRoutes.js","sourceRoot":"","sources":["../../src/shared/federatedRoutes.ts"],"names":[],"mappings":"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"}

package/dist/shared/piWebStatusParsing.js

@@ -1,3 +1,4 @@
+import { isPiWebCapability } from "./capabilities.js";
 export function parsePiWebVersionResponse(value) {
     if (!isRecord(value))
         return undefined;
@@ -12,6 +13,43 @@ export function parsePiWebVersionResponse(value) {
         return undefined;
     return { packageName, generatedAt, components: { web, sessiond } };
 }
+export function parsePiWebRuntimeResponse(value) {
+    if (!isRecord(value))
+        return undefined;
+    const packageName = value["packageName"];
+    const generatedAt = value["generatedAt"];
+    const components = value["components"];
+    if (typeof packageName !== "string" || packageName === "" || typeof generatedAt !== "string" || generatedAt === "" || !isRecord(components))
+        return undefined;
+    const web = parsePiWebRuntimeComponent(components["web"]);
+    const sessiond = parsePiWebRuntimeComponent(components["sessiond"]);
+    const capabilities = parsePiWebCapabilities(value["capabilities"]);
+    if (web === undefined || sessiond === undefined || capabilities === undefined)
+        return undefined;
+    return { packageName, generatedAt, components: { web, sessiond }, capabilities };
+}
+export function parsePiWebRuntimeComponent(value) {
+    if (!isRecord(value))
+        return undefined;
+    const component = value["component"];
+    const label = value["label"];
+    const runtimeVersion = value["runtimeVersion"];
+    const available = value["available"];
+    const capabilities = parsePiWebCapabilities(value["capabilities"]);
+    const error = value["error"];
+    if (component !== "web" && component !== "sessiond")
+        return undefined;
+    if (typeof label !== "string" || label === "" || typeof available !== "boolean" || capabilities === undefined)
+        return undefined;
+    return {
+        component,
+        label,
+        ...(typeof runtimeVersion === "string" ? { runtimeVersion } : {}),
+        available,
+        capabilities,
+        ...(typeof error === "string" ? { error } : {}),
+    };
+}
 export function parsePiWebComponentStatus(value) {
     if (!isRecord(value))
         return undefined;
@@ -38,6 +76,11 @@ export function parsePiWebComponentStatus(value) {
         ...(typeof error === "string" ? { error } : {}),
     };
 }
+function parsePiWebCapabilities(value) {
+    if (!Array.isArray(value) || !value.every(isPiWebCapability))
+        return undefined;
+    return value;
+}
 export function parsePiWebInstallationInfo(value) {
     if (!isRecord(value))
         return undefined;

package/dist/shared/piWebStatusParsing.js.map

@@ -1 +1 @@
-{"version":3,"file":"piWebStatusParsing.js","sourceRoot":"","sources":["../../src/shared/piWebStatusParsing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"piWebStatusParsing.js","sourceRoot":"","sources":["../../src/shared/piWebStatusParsing.ts"],"names":[],"mappings":"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"}

package/docs/plugins.md

@@ -22,7 +22,7 @@ Plugins run as JavaScript in the browser app. Treat them as trusted code:
 - they can render arbitrary Lit templates/custom elements in plugin contribution areas;
 - they should not be installed from untrusted sources.
 
-PI WEB's `/api/...` HTTP and WebSocket endpoints are internal implementation details. Plugin code should not fetch PI WEB API endpoints directly; use the documented context helpers instead.
+PI WEB's `/api/...` HTTP and WebSocket endpoints are internal implementation details. Plugin code should use the documented context helpers instead. Daring plugins can still reach private routes or runtime objects because they run in the browser, but those private surfaces are experimental: they may graduate into stable helpers, change shape, or disappear.
 
 ## What to ask AI to build
 
@@ -131,17 +131,22 @@ Reload the PI WEB browser tab. PI WEB serves plugin modules with an mtime-based
 
 ## Remote machine plugins
 
-When machine federation is enabled, PI WEB also loads discovered plugins from the selected remote machine. Remote plugins are trusted browser-side code like local plugins, but their contributions are machine-scoped:
+When [machine federation](https://pi-web.dev/machines.html) is enabled, PI WEB also loads discovered plugins from the selected remote machine. Remote plugins are trusted browser-side code like local plugins, but their contributions are machine-scoped:
 
 - actions, workspace panels, and workspace labels only appear while that machine is selected;
 - plugin file and terminal helpers run against that machine;
 - plugin code is loaded best-effort through the current gateway and cached for the browser page lifetime;
-- if the gateway already has an enabled plugin with the same original id, the gateway plugin wins and the remote duplicate stays hidden;
+- if the gateway and remote machine both have an enabled plugin with the same original id, `machineSpecific` metadata decides whether the gateway copy is reused or only the selected machine's copy can appear;
 - remote theme contributions are ignored for now because themes are app-wide;
 - mixed PI WEB versions across federated machines are best-effort and not guaranteed compatible.
 
 Remote plugin enablement is controlled by the remote machine's PI WEB plugin config. To edit or disable a remote machine plugin, open that machine directly or update its config file.
 
+Plugin package metadata may set `machineSpecific: true` when the plugin's meaning is tied to the selected PI WEB machine:
+
+- Omitted or `false`: use the gateway copy when the same plugin id is also present on a remote machine. This is best for portable UI plugins whose helpers already route through the selected machine.
+- `true`: the gateway copy only appears for the local machine. When a remote machine is selected, only that remote machine's copy can appear; if the remote machine does not expose the plugin, the plugin is hidden. This is best for plugins that report machine-local PI WEB status or depend on machine-local plugin code.
+
 For portable plugin assets, prefer URLs relative to the plugin module, for example:
 
 ```js
@@ -185,7 +190,7 @@ Built-in plugins can be managed from **Settings → Plugins** or with the top-le
 **Plugin id:** `updates`
 **What it does:** adds a conditional **Updates** workspace tab with PI WEB update, restart, and installed-service guidance.
 
-Updates is enabled by default. To hide it, disable `updates` in **Settings → Plugins** or set:
+Updates is enabled by default. It declares `machineSpecific: true` so the gateway Updates tab only appears for the local machine; while a remote machine is selected, that remote machine's Updates plugin is used if available. To hide it, disable `updates` in **Settings → Plugins** or set:
 
 ```json
 {
@@ -286,7 +291,7 @@ A package can expose one or more PI WEB plugin modules. There is exactly one sup
   "piWeb": {
     "plugins": [
       { "id": "review", "module": "dist/review.js" },
-      { "id": "dashboard", "module": "dist/dashboard.js" }
+      { "id": "dashboard", "module": "dist/dashboard.js", "machineSpecific": true }
     ]
   }
 }
@@ -298,6 +303,7 @@ Rules:
 - Each entry must have an explicit `id` and `module`.
 - `id` must match `^[a-z][a-z0-9.-]*$`.
 - `module` must be a safe relative path inside the plugin package root.
+- `machineSpecific` is optional and must be a boolean; omit it for the default portable gateway behavior.
 - Duplicate plugin ids are not auto-renamed; later duplicates are skipped.
 - Legacy shortcuts such as `piWeb.plugin`, string entries in `piWeb.plugins`, `piWeb.id` fallback ids, and no-`package.json` fallbacks are not supported.
 
@@ -312,13 +318,14 @@ The manifest contains each discovered plugin module:
       "id": "my-plugin",
       "module": "/pi-web-plugins/my-plugin/pi-web-plugin.js?v=1234567890",
       "source": "local",
-      "scope": "local"
+      "scope": "local",
+      "machineSpecific": false
     }
   ]
 }
 ```
 
-`source` describes where the plugin came from (`bundled`, `local`, or the Pi package source). `scope` is `bundled`, `local`, `user`, or `project`.
+`source` describes where the plugin came from (`bundled`, `local`, or the Pi package source). `scope` is `bundled`, `local`, `user`, or `project`. `machineSpecific` controls whether the gateway copy is valid for remote machines or only each selected machine's own copy can appear.
 
 A plugin can fetch its own static assets with URLs under:
 
@@ -450,12 +457,12 @@ interface PluginRuntimeContext {
 Notes:
 
 - `state` is a snapshot of current UI state when actions are built.
-- The stable state fields are `state.selectedWorkspace`, `state.selectedSession`, and `state.piWebStatus`.
-- Other `state` fields may exist at runtime, but they are PI WEB internals and can change quickly.
+- The stable state fields are `state.selectedWorkspace`, `state.selectedSession`, and `state.piWebStatus`. `state.piWebStatus` describes the currently selected machine's PI WEB runtime, or the gateway/local runtime when the local machine is selected.
+- Other `state` fields may exist at runtime, but they are private PI WEB internals that may graduate into stable helpers, change shape, or disappear.
 - `enabled` is evaluated when the action palette asks for actions.
 - `selectWorkspaceTool()` expects a qualified panel id such as `my-plugin:workspace.info`.
 - `openTerminal()` switches to the built-in terminal panel. Pass `{ terminalId }` to deep-link to a specific terminal.
-- Only fields documented here and declared in `plugin-api.d.ts` are stable public plugin API. Unstable runtime fields are intentionally omitted from these types; if a plugin author chooses to depend on them, they must explicitly import unstable types from `@jmfederico/pi-web/plugin-api/unstable` and type-assert the context in their own code.
+- Only fields documented here and declared in `plugin-api.d.ts` are stable public plugin API. Anything else is experimental: it may become public API later, change shape, or disappear.
 
 #### Keyboard shortcuts
 
@@ -763,22 +770,11 @@ render: ({ terminal }) => html`
 
 Review command strings carefully. They are trusted shell commands executed in the workspace terminal.
 
-## Internal PI WEB APIs and explicit unstable opt-in
-
-PI WEB's `/api/...` HTTP and WebSocket routes are private implementation details. Plugin code should not fetch PI WEB API endpoints directly because those URLs, response shapes, and machine-federation routing rules can change.
-
-If a plugin author deliberately chooses to depend on an unstable runtime field while a public helper is still being designed, make that decision explicit in code with a type-only unstable import and a local type assertion:
+## Private and experimental PI WEB APIs
 
-```ts
-import type { WorkspacePanelContext } from "@jmfederico/pi-web/plugin-api";
-import type { UnstableWorkspacePanelContext } from "@jmfederico/pi-web/plugin-api/unstable";
-
-function unstableContext(context: WorkspacePanelContext) {
-  return context as WorkspacePanelContext & UnstableWorkspacePanelContext;
-}
-```
+PI WEB's `/api/...` HTTP and WebSocket routes and runtime-only fields are private implementation details. They exist because plugins are trusted browser code, and because some capabilities may be evaluated there before they are designed as stable helpers.
 
-Unstable APIs are not covered by the v1 compatibility promise. Prefer documented helpers whenever they exist.
+That is allowed, but outside the v1 compatibility promise: URLs, response shapes, runtime fields, and machine-federation routing may graduate into stable APIs, change shape, or disappear. The stable public plugin API is only the documented helpers and declarations in `plugin-api.d.ts`. Prefer those whenever they exist; if you rely on private surfaces, keep the dependency local to the plugin and expect to revisit it after PI WEB upgrades.
 
 ## Async data and caching
 
@@ -795,7 +791,7 @@ PI WEB does not provide a plugin cache/invalidation framework. Keep host callbac
 If you are an AI agent building or editing a PI WEB plugin, follow this checklist:
 
 1. Create or update a plugin folder with `package.json` and a JavaScript module such as `pi-web-plugin.js`.
-2. Use the single supported package metadata shape: `piWeb.plugins` array with `{ id, module }` entries.
+2. Use the single supported package metadata shape: `piWeb.plugins` array with `{ id, module, machineSpecific? }` entries.
 3. Default-export `{ apiVersion: 1, name, activate }` from the module.
 4. Return `{ contributions: { actions, workspacePanels, workspaceLabels } }` from `activate()`.
 5. Use ids matching `^[a-z][a-z0-9.-]*$`.
@@ -806,7 +802,7 @@ If you are an AI agent building or editing a PI WEB plugin, follow this checklis
 10. Add workspace labels for compact inline metadata.
 11. Return arrays from workspace label `items()`; return an empty array to render nothing.
 12. Use documented context helpers first: `files`, `terminal`, `host.requestRender`, `workspace`, `machine`, `state.selectedWorkspace`, `state.selectedSession`, and `state.piWebStatus`.
-13. Do not fetch PI WEB `/api/...` endpoints directly. If an unstable runtime field is intentionally required, import the type from `@jmfederico/pi-web/plugin-api/unstable` and type-assert locally.
+13. Do not fetch PI WEB `/api/...` endpoints directly unless you intentionally accept private API churn; prefer documented helpers.
 14. Treat plugins as trusted code and avoid reading or displaying secrets unless intentional.
 15. After local edits, tell the user to hard reload the browser and check the console for plugin errors.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmfederico/pi-web",
-  "version": "1.202606.1",
+  "version": "1.202606.2",
   "description": "Remote web UI and browser control plane for persistent Pi Coding Agent sessions.",
   "license": "MIT",
   "author": "Federico Jaramillo Martinez",