@gang-of-beads/pi-web-plugin-api 0.1.0-alpha.2 → 0.1.0-alpha.4

package/README.md

@@ -5,7 +5,7 @@ Lightweight browser and server plugin contracts for [PI WEB](https://github.com/
 ## Install
 
 ```sh
-npm install --save-dev @gang-of-beads/pi-web-plugin-api@alpha
+npm install --save-dev @gang-of-beads/pi-web-plugin-api
 ```
 
 Browser plugins also install `lit@^3`: the browser declarations use Lit's template and style types, including when rendering through the host's `context.html`. Server-only plugins do not need Lit; their declaration dependencies are included.
@@ -28,7 +28,7 @@ Bundle runtime imports into each plugin half: PI WEB loads plugin modules as the
 
 ## Compatibility
 
-`0.1.0-alpha.2` contains the declarations shipped by PI WEB `2.202610.11`, with the shape and typography tokens (`--pi-font-*`, `--pi-radius-*`) accepted in `ThemeTokens`. Browser plugins declare `apiVersion: 2`; server plugins declare `apiVersion: 1`. The existing `@gang-of-beads/pi-web/plugin-api` and `@gang-of-beads/pi-web/server-plugin-api` entry points remain available.
+`0.1.0-alpha.4` contains the declarations shipped by PI WEB `2.202610.13`: a server plugin receives its private settings as `context.serverSettings`, and the config types carry `serverSettings`; a composer contribution's context carries a `signal` that aborts when the composer leaves its session; and a browser plugin can list and add project folders on the selected machine through `projectFolders`. Browser plugins declare `apiVersion: 2`; server plugins declare `apiVersion: 1`. The existing `@gang-of-beads/pi-web/plugin-api` and `@gang-of-beads/pi-web/server-plugin-api` entry points remain available.
 
 This is an alpha release. Host-internal members marked unstable are not a supported third-party contract.
 

package/dist/plugin-api.d.ts

@@ -1,7 +1,7 @@
 import type { CSSResultGroup, TemplateResult } from "lit";
-import type { FileSuggestion, ForegroundToken, PluginListModel, PluginReadFailure, LegacyThemeToken, SemanticSurfaceToken, ShapeTypographyToken, TerminalCommandRun, TerminalInfo, DeleteWorkspaceFileResponse, FileContentResponse, FileTreeResponse, JsonValue, MachineKind, MoveWorkspaceFileOptions, MoveWorkspaceFileResponse, PiWebStatusResponse, TerminalCommandRunHandle, WorkspaceProviderMetadata, WorkspaceRemovalPresentation, WorkspaceUploadBatchProgress, WorkspaceUploadCancelHandle, WriteWorkspaceFileOptions, WriteWorkspaceFileResponse, MachineConnection } from "./shared/pluginApiTypes.js";
+import type { FileSuggestion, ProjectFolderListing, ProjectFolderListingRequest, ForegroundToken, MessageRoleToken, PluginListModel, PluginReadFailure, LegacyThemeToken, SemanticSurfaceToken, ShapeTypographyToken, TerminalCommandRun, TerminalInfo, DeleteWorkspaceFileResponse, FileContentResponse, FileTreeResponse, JsonValue, MachineKind, MoveWorkspaceFileOptions, MoveWorkspaceFileResponse, PiWebStatusResponse, TerminalCommandRunHandle, WorkspaceProviderMetadata, WorkspaceRemovalPresentation, WorkspaceUploadBatchProgress, WorkspaceUploadCancelHandle, WriteWorkspaceFileOptions, WriteWorkspaceFileResponse, MachineConnection } from "./shared/pluginApiTypes.js";
 export type { ThemeToken } from "./shared/pluginApiTypes.js";
-export type { FileSuggestion, LegacyThemeToken, SemanticSurfaceToken, TerminalInfo, FileContentMediaType, FileContentResponse, FileTreeEntry, FileTreeResponse, JsonObject, JsonPrimitive, JsonValue, MachineConnection, MachineKind, PiWebComponentStatus, PiWebDockerMode, PluginListAction, PluginListGroup, PluginListModel, PluginListRead, PluginListRow, PluginListStatus, PluginListTone, PluginListWords, PluginReadFailure, PiWebInstallationInfo, PiWebInstallationKind, PiWebPackageManager, PiWebReleaseStatus, PiWebServiceComponent, PiWebStatusMessage, PiWebStatusResponse, PiWebStatusSeverity, PiWebVersionResponse, TerminalCommandRun, TerminalCommandRunHandle, TerminalCommandRunStatus, WorkspaceProviderCapabilities, WorkspaceProviderMetadata, WorkspaceRemovalPresentation, WorkspaceFileUploadProgress, WorkspaceUploadBatchFileProgress, WorkspaceUploadBatchProgress, WorkspaceUploadCancelHandle, WriteWorkspaceFileOptions, WriteWorkspaceFileResponse, DeleteWorkspaceFileResponse, MoveWorkspaceFileOptions, MoveWorkspaceFileResponse, } from "./shared/pluginApiTypes.js";
+export type { FileSuggestion, ProjectFolderContents, ProjectFolderCrumb, ProjectFolderEntry, ProjectFolderListing, ProjectFolderListingRequest, ProjectFolderUnreadableCause, LegacyThemeToken, SemanticSurfaceToken, TerminalInfo, FileContentMediaType, FileContentResponse, FileTreeEntry, FileTreeResponse, JsonObject, JsonPrimitive, JsonValue, MachineConnection, MachineKind, PiWebComponentStatus, PiWebDockerMode, PluginListAction, PluginListGroup, PluginListModel, PluginListRead, PluginListRow, PluginListStatus, PluginListTone, PluginListWords, PluginReadFailure, PiWebInstallationInfo, PiWebInstallationKind, PiWebPackageManager, PiWebReleaseStatus, PiWebServiceComponent, PiWebStatusMessage, PiWebStatusResponse, PiWebStatusSeverity, PiWebVersionResponse, TerminalCommandRun, TerminalCommandRunHandle, TerminalCommandRunStatus, WorkspaceProviderCapabilities, WorkspaceProviderMetadata, WorkspaceRemovalPresentation, WorkspaceFileUploadProgress, WorkspaceUploadBatchFileProgress, WorkspaceUploadBatchProgress, WorkspaceUploadCancelHandle, WriteWorkspaceFileOptions, WriteWorkspaceFileResponse, DeleteWorkspaceFileResponse, MoveWorkspaceFileOptions, MoveWorkspaceFileResponse, } from "./shared/pluginApiTypes.js";
 export { CORE_STATUS_FLAGS } from "./shared/machineStatus.js";
 export { workspaceFileRefusalOf, type WorkspaceFileRefusal } from "./shared/apiTypes.js";
 export type PluginId = string;
@@ -492,12 +492,44 @@ export interface CodeFenceRendererContribution {
     render: (source: string) => Node | Promise<Node>;
 }
 export type ComposerSlot = "leading" | "trailing";
+/**
+ * What a composer control sees, bound to the machine and session the composer
+ * showed when the context was made. The composer is reused across sessions and
+ * machines, so work that outlives the click (a dictation still streaming) stays
+ * with the session it started in.
+ */
 export interface ComposerRuntimeContext {
+    /**
+     * The session the context is bound to. A context made while a new session
+     * was still starting reports the session's real id once it has one: the
+     * same session under its lasting id, so read it when you need it rather
+     * than keeping a copy. It changes at most that once, and only then.
+     */
     sessionId: string | undefined;
     machineId: string | undefined;
     draft: string;
     busy: boolean;
+    /**
+     * Aborted when the composer leaves this context's session: the reader
+     * switches session or machine, or the composer unmounts. A new session
+     * getting its real id is not leaving it. Already aborted if that happened
+     * before the context reached the plugin. Stop work bound to the session when
+     * it fires. Absent on hosts older than this member: there, nothing tells the
+     * plugin the composer left.
+     */
+    signal?: AbortSignal;
+    /**
+     * Append text to this session's draft. Once the composer has left the
+     * session, the text joins that session's stored draft instead of the one on
+     * screen. A context made before the composer had a session has no stored
+     * draft, so its writes after the composer left are discarded.
+     */
     insertText: (text: string) => void;
+    /**
+     * Replace this session's draft. Once the composer has left the session,
+     * the stored draft is replaced instead of the one on screen, or the write is
+     * discarded if the context was made before the composer had a session.
+     */
     replaceDraft: (text: string) => void;
     notify: (message: string, severity: "info" | "warning" | "error") => void;
     /** Ask the composer to redraw after state only the plugin can see changed. */
@@ -581,6 +613,41 @@ export interface PluginProjectTrustRead {
     readonly decision: boolean | null;
     readonly trusted: boolean;
 }
+/**
+ * The add-project dialog's access to one machine's folders, captured when the dialog opens: every
+ * folder listing, suggestion, trust read and the final add made through it go to `machine`,
+ * whatever is selected afterwards.
+ */
+export interface PluginProjectFolders {
+    readonly machine: {
+        readonly id: string;
+        readonly name: string | undefined;
+    };
+    listFolder: (request: ProjectFolderListingRequest, signal: AbortSignal) => Promise<PluginProjectFolderReply>;
+    directories: (query: string, signal: AbortSignal) => Promise<FileSuggestion[]>;
+    trust: (path: string) => Promise<PluginProjectTrustRead>;
+    create: (input: PluginProjectCreateInput) => Promise<string | undefined>;
+}
+/**
+ * How one folder listing came back, naming the machine that was asked: the listing; a new folder
+ * name that machine refuses, with its reason; a machine too old to list folders; or no answer.
+ */
+export type PluginProjectFolderReply = {
+    readonly kind: "listed";
+    readonly machineId: string;
+    readonly listing: ProjectFolderListing;
+} | {
+    readonly kind: "name-refused";
+    readonly machineId: string;
+    readonly reason: string;
+} | {
+    readonly kind: "unsupported";
+    readonly machineId: string;
+} | {
+    readonly kind: "unanswered";
+    readonly machineId: string;
+    readonly reason: string;
+};
 export interface PluginPromptEditor {
     /** Insert text at the current cursor position. Replaces any selection.
      *  If the editor is not focused, focuses it first.
@@ -627,6 +694,8 @@ export interface PluginRuntimeContext {
     projectDirectories: (query: string, signal: AbortSignal) => Promise<FileSuggestion[]>;
     /** Server-resolved existing trust for a raw path, on the selected machine. */
     projectTrust: (path: string) => Promise<PluginProjectTrustRead>;
+    /** Folder access bound to the machine selected now, for the add-project dialog. Absent on hosts without the folder browser. */
+    projectFolders?: () => PluginProjectFolders;
     configureAuth: () => void | Promise<void>;
     logoutAuth: () => void | Promise<void>;
     openThemePicker: () => void;
@@ -903,9 +972,11 @@ export interface WorkspaceLabelContribution {
     items: (context: WorkspaceLabelContext) => WorkspaceLabelItem[];
 }
 export type ThemeColorScheme = "dark" | "light";
-export type ThemeTokens = Record<LegacyThemeToken, string> & Partial<Record<SemanticSurfaceToken | ForegroundToken | ShapeTypographyToken, string>>;
+export type ThemeTokens = Record<LegacyThemeToken, string> & Partial<Record<SemanticSurfaceToken | ForegroundToken | ShapeTypographyToken | MessageRoleToken, string>>;
 export interface ThemeContribution {
     id: LocalContributionId;
+    /** Prefer this available concrete theme; tokens remain the fallback for other hosts. */
+    replacedBy?: QualifiedContributionId;
     name: string;
     description?: string;
     order?: number;

package/dist/server-plugin-api.d.ts

@@ -20,6 +20,14 @@ export interface ServerPluginActivationContext {
     readonly packageRoot: string;
     readonly logger: ServerPluginLogger;
     readonly settings: JsonObject;
+    /**
+     * A JSON copy of this plugin's own private `plugins.<id>.serverSettings` block, taken at
+     * activation; `{}` when none is configured. No browser receives it, and no other plugin's block
+     * is ever here. Undefined means the host is older and does not supply private settings at all,
+     * which is not the same as none configured: a plugin that needs a key should report that host
+     * as unable to provide it rather than as unconfigured.
+     */
+    readonly serverSettings?: JsonObject;
     /**
      * Durable per-plugin storage. Missing is not empty: `read` answers
      * undefined for a key that was never written, and a corrupt document reads

package/dist/shared/apiTypes.d.ts

@@ -61,8 +61,17 @@ export type PiWebPluginConfigMap = Record<string, PiWebPluginConfig>;
 export interface PiWebPluginConfig {
     enabled?: boolean;
     settings?: PiWebPluginSettings;
+    /** Raw file/server configuration only; public responses omit this block. */
+    serverSettings?: PiWebPluginSettings;
     [key: string]: unknown;
 }
+/** Explicit private-settings operations by plugin id; a plugin the map omits keeps its stored block. */
+export type PiWebServerSettingsUpdates = Record<string, {
+    operation: "replace";
+    value: PiWebPluginSettings;
+} | {
+    operation: "clear";
+}>;
 export interface PiWebPathAccessConfig {
     allowedPaths?: string[];
 }
@@ -100,6 +109,11 @@ export interface PiWebListTilesConfig {
     phone?: ListTilesPerRow;
     desktop?: ListTilesPerRow;
 }
+/** One theme choice, as a browser keeps it locally: a qualified theme id and whether it follows the system. */
+export interface PiWebSharedThemeConfig {
+    themeId: `${string}:${string}`;
+    auto: boolean;
+}
 export interface PiWebConfigValues {
     host?: string;
     port?: number;
@@ -122,6 +136,11 @@ export interface PiWebConfigValues {
     updateCommand?: string;
     /** Tiles per row in the Navigate lists, per layout; see PiWebListTilesConfig. */
     listTiles?: PiWebListTilesConfig;
+    /**
+     * The theme every browser of this PI WEB shares (owner, 2026-10-16); absent, each browser keeps
+     * its own. Written only through `PUT /api/config/theme`, so a general config save keeps it.
+     */
+    theme?: PiWebSharedThemeConfig;
     /**
      * When true, PI WEB appends environment facts to session system prompts:
      * the pi-web session nesting every session runs in, plus container facts in
@@ -259,6 +278,10 @@ export interface PiWebConfigResponse {
     config: PiWebConfigValues;
     effectiveConfig: PiWebConfigValues;
     envOverrides: PiWebConfigEnvOverrides;
+    /** Advertised only by the target that implements private settings preservation and explicit updates. */
+    serverSettingsProtocol?: 1;
+    /** Which plugins hold a `serverSettings` block (an empty block counts); presence only, never validity or a value. */
+    serverSettingsConfigured?: Record<string, boolean>;
 }
 export interface Project {
     id: string;
@@ -343,6 +366,8 @@ export declare const SESSION_UNREAD_COMPLETED_AT_MAX_LENGTH = 64;
 export declare const SESSION_NOT_FOUND_CODE = "session-not-found";
 /** The code the web and the daemon answer with for a route they do not have: the machine is older than the page (B16). */
 export declare const ROUTE_MISSING_CODE = "route-missing";
+/** The code the project-folder listing answers with for a new folder name the machine cannot use. */
+export declare const PROJECT_FOLDER_NAME_REFUSED_CODE = "folder-name-refused";
 /**
  * What a failed answer says about the link (B16), in the `transport` field of its error body: the
  * web process found nothing listening where its session daemon should be (the daemon is restarting,
@@ -686,6 +711,13 @@ export interface QueuedSessionMessage {
      * existed, by another client, or by a non-browser caller.
      */
     clientMessageId?: string;
+    /**
+     * How many images the message carries. A device handed the message back (Stop, Clear queue,
+     * Take back) without its own copy of them can say so instead of returning the words as if
+     * that were all. Absent when the daemon does not know: one from before this field existed, or
+     * an entry an extension put in pi's queue directly.
+     */
+    imageCount?: number;
 }
 /** Length bound for extension-dialog ids. */
 export declare const EXTENSION_DIALOG_ID_MAX_LENGTH = 128;
@@ -1272,7 +1304,7 @@ export interface SlashCommand {
     description?: string;
     source: "extension" | "prompt" | "skill" | "builtin";
 }
-export type { FileSuggestion } from "./pluginApiTypes.js";
+export type { FileSuggestion, ProjectFolderContents, ProjectFolderCrumb, ProjectFolderEntry, ProjectFolderListing, ProjectFolderListingRequest, ProjectFolderUnreadableCause } from "./pluginApiTypes.js";
 export interface TerminalInfo {
     id: string;
     cwd: string;

package/dist/shared/apiTypes.js

@@ -18,6 +18,8 @@ export const SESSION_UNREAD_COMPLETED_AT_MAX_LENGTH = 64;
 export const SESSION_NOT_FOUND_CODE = "session-not-found";
 /** The code the web and the daemon answer with for a route they do not have: the machine is older than the page (B16). */
 export const ROUTE_MISSING_CODE = "route-missing";
+/** The code the project-folder listing answers with for a new folder name the machine cannot use. */
+export const PROJECT_FOLDER_NAME_REFUSED_CODE = "folder-name-refused";
 /**
  * What a failed answer says about the link (B16), in the `transport` field of its error body: the
  * web process found nothing listening where its session daemon should be (the daemon is restarting,

package/dist/shared/pluginApiTypes.d.ts

@@ -50,6 +50,60 @@ export interface FileSuggestion {
     path: string;
     kind: "tracked" | "untracked" | "other";
 }
+/**
+ * One folder to list for the add-project folder browser: a path as the reader entered or chose it
+ * (empty means the machine's home folder), or, with `child`, a new folder's name under that path.
+ * The machine resolves and joins it with its own path rules; the page never splits or joins paths.
+ */
+export interface ProjectFolderListingRequest {
+    readonly path: string;
+    readonly child?: string;
+}
+/** One step of an absolute path, root first, spelled the way the machine spells it. */
+export interface ProjectFolderCrumb {
+    readonly name: string;
+    readonly path: string;
+}
+/** A subfolder the folder browser can enter. */
+export interface ProjectFolderEntry {
+    readonly name: string;
+    readonly path: string;
+}
+/** Why a folder that exists, or might, could not be listed. None of these means the folder is empty. */
+export type ProjectFolderUnreadableCause = "not-a-folder" | "denied" | "timed-out" | "failed";
+/**
+ * What one listing found. `complete` is every subfolder; `truncated` is the first `folders` of
+ * `total`; `incomplete` stopped before every linked folder was checked; `missing` is a folder that
+ * does not exist yet, which adding the project creates; `unreadable` names why it could not be read.
+ */
+export type ProjectFolderContents = {
+    readonly kind: "complete";
+    readonly folders: readonly ProjectFolderEntry[];
+} | {
+    readonly kind: "truncated";
+    readonly folders: readonly ProjectFolderEntry[];
+    readonly total: number;
+} | {
+    readonly kind: "incomplete";
+    readonly folders: readonly ProjectFolderEntry[];
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "unreadable";
+    readonly cause: ProjectFolderUnreadableCause;
+    readonly detail?: string;
+};
+/**
+ * The machine's answer for one folder: its absolute path, its parent (null at a filesystem root),
+ * the path's steps root first, the machine's path separator, and what is inside.
+ */
+export interface ProjectFolderListing {
+    readonly path: string;
+    readonly parent: string | null;
+    readonly crumbs: readonly ProjectFolderCrumb[];
+    readonly separator: string;
+    readonly contents: ProjectFolderContents;
+}
 export interface FileContentResponse {
     path: string;
     language?: string;
@@ -214,13 +268,20 @@ export interface PiWebStatusResponse extends PiWebVersionResponse {
  */
 /**
  * Shape and typography stops a theme may pin. Optional by design: a theme
- * that omits them inherits the core's current shape - which since the pro
- * redesign is the flat mono TUI look, so a soft theme MUST set these to keep
- * its rounded sans rendering. Radii follow the published scale; there is no
+ * that omits them inherits the core's current shape - the rounded sans
+ * Material scale - so a flat or mono theme MUST set these to keep its look. Radii follow the published scale; there is no
  * density or border-width token yet.
  */
 export type ShapeTypographyToken = "--pi-font-ui" | "--pi-font-display" | "--pi-font-mono" | "--pi-radius-xs" | "--pi-radius-sm" | "--pi-radius-md" | "--pi-radius-lg" | "--pi-radius-xl";
-export type ThemeToken = LegacyThemeToken | SemanticSurfaceToken | ForegroundToken | ShapeTypographyToken;
+export type ThemeToken = LegacyThemeToken | SemanticSurfaceToken | ForegroundToken | ShapeTypographyToken | MessageRoleToken;
+/**
+ * Conversation message colours by who wrote the message. Optional: a theme that omits one gets it
+ * derived from its own tokens when it is applied (user from the selection colour and accent border,
+ * assistant from the surface, system from the purple family), so packs written before these tokens
+ * keep their user and assistant look and still get a system message that reads apart from the
+ * assistant's (owner, 2026-10-16).
+ */
+export type MessageRoleToken = "--pi-msg-user-bg" | "--pi-msg-user-border" | "--pi-msg-user-header-bg" | "--pi-msg-assistant-bg" | "--pi-msg-assistant-border" | "--pi-msg-assistant-header-bg" | "--pi-msg-system-bg" | "--pi-msg-system-border" | "--pi-msg-system-header-bg";
 /**
  * Foregrounds a theme may name for a filled surface it owns. Optional by
  * design: a theme that omits one keeps the previous fallback, which is why

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gang-of-beads/pi-web-plugin-api",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "description": "Lightweight PI WEB browser and server plugin contracts, with TypeScript declarations and public runtime helpers.",
   "license": "MIT",
   "author": "Gang of Beads",