@chainingintention/pi-web-cn 1.202608.8 → 1.202608.10

package/dist/shared/pluginBackendProtocol.js

@@ -0,0 +1,110 @@
+/** Maximum UTF-8 JSON input accepted from a browser plugin. */
+export const PLUGIN_BACKEND_JSON_MAX_BYTES = 256 * 1024;
+/** Bounded result allowance demonstrated by Git's existing 2 MiB command-output limit. */
+export const PLUGIN_BACKEND_RESPONSE_JSON_MAX_BYTES = 8 * 1024 * 1024;
+/** Envelope allowance for the active backend revision and JSON field names. */
+export const PLUGIN_BACKEND_REQUEST_BODY_MAX_BYTES = PLUGIN_BACKEND_JSON_MAX_BYTES + 4 * 1024;
+/** Allowance for an attributed error envelope around a bounded result. */
+export const PLUGIN_BACKEND_RESPONSE_BODY_MAX_BYTES = PLUGIN_BACKEND_RESPONSE_JSON_MAX_BYTES + 4 * 1024;
+/** Bounded provider callback deadline inside sessiond. */
+export const PLUGIN_BACKEND_REQUEST_TIMEOUT_MS = 10_000;
+/** End-to-end sessiond deadline, including owner re-resolution and validation. */
+export const PLUGIN_BACKEND_DISPATCH_TIMEOUT_MS = 25_000;
+/** Remote gateway deadline, including workspace owner re-resolution. */
+export const PLUGIN_BACKEND_FEDERATION_TIMEOUT_MS = 30_000;
+export const PLUGIN_BACKEND_OPERATION_MAX_LENGTH = 128;
+export const PLUGIN_BACKEND_REVISION_MAX_LENGTH = 512;
+const OPERATION_PATTERN = /^[a-z][a-z0-9.-]*$/u;
+const MAX_JSON_DEPTH = 64;
+export function isPluginBackendOperation(value) {
+    return value.length <= PLUGIN_BACKEND_OPERATION_MAX_LENGTH && OPERATION_PATTERN.test(value);
+}
+export function requirePluginBackendOperation(value) {
+    if (!isPluginBackendOperation(value)) {
+        throw new Error(`Plugin backend operation must match ${String(OPERATION_PATTERN)} and be at most ${String(PLUGIN_BACKEND_OPERATION_MAX_LENGTH)} characters`);
+    }
+    return value;
+}
+export function requirePluginBackendRevision(value) {
+    if (typeof value !== "string" || value === "" || value.length > PLUGIN_BACKEND_REVISION_MAX_LENGTH) {
+        throw new Error(`Plugin backend revision must be a non-empty string of at most ${String(PLUGIN_BACKEND_REVISION_MAX_LENGTH)} characters`);
+    }
+    return value;
+}
+/** Clone and freeze a runtime value after enforcing the JSON and byte contract. */
+export function cloneBoundedPluginBackendJson(value, label, maxBytes = PLUGIN_BACKEND_JSON_MAX_BYTES) {
+    const cloned = cloneJsonValue(value, new Set(), label, 0);
+    const serialized = JSON.stringify(cloned);
+    if (utf8ByteLength(serialized) > maxBytes) {
+        throw new Error(`${label} exceeds the ${String(maxBytes)} byte limit`);
+    }
+    return cloned;
+}
+export function serializeBoundedPluginBackendJson(value, label, maxBytes = PLUGIN_BACKEND_JSON_MAX_BYTES) {
+    return JSON.stringify(cloneBoundedPluginBackendJson(value, label, maxBytes));
+}
+export function parseBoundedPluginBackendJson(text, label, maxBytes = PLUGIN_BACKEND_JSON_MAX_BYTES) {
+    if (utf8ByteLength(text) > maxBytes) {
+        throw new Error(`${label} exceeds the ${String(maxBytes)} byte limit`);
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`${label} must be valid JSON`, { cause: error });
+    }
+    return cloneBoundedPluginBackendJson(value, label, maxBytes);
+}
+export function parsePluginBackendRequestEnvelope(value) {
+    if (!isPlainRecord(value))
+        throw new Error("Plugin backend request body must be an object");
+    return Object.freeze({
+        revision: requirePluginBackendRevision(value["revision"]),
+        input: cloneBoundedPluginBackendJson(value["input"], "Plugin backend request input"),
+    });
+}
+export function utf8ByteLength(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
+function cloneJsonValue(value, ancestors, label, depth) {
+    if (depth > MAX_JSON_DEPTH)
+        throw new Error(`${label} exceeds the maximum JSON depth of ${String(MAX_JSON_DEPTH)}`);
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error(`${label} must contain only finite JSON numbers`);
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (ancestors.has(value))
+            throw new Error(`${label} must not contain cycles`);
+        ancestors.add(value);
+        const output = value.map((child) => cloneJsonValue(child, ancestors, label, depth + 1));
+        ancestors.delete(value);
+        Object.freeze(output);
+        return output;
+    }
+    if (!isPlainRecord(value))
+        throw new Error(`${label} must contain only JSON values`);
+    if (ancestors.has(value))
+        throw new Error(`${label} must not contain cycles`);
+    ancestors.add(value);
+    const output = {};
+    for (const [key, child] of Object.entries(value)) {
+        defineJsonProperty(output, key, cloneJsonValue(child, ancestors, label, depth + 1));
+    }
+    ancestors.delete(value);
+    return Object.freeze(output);
+}
+function defineJsonProperty(record, key, value) {
+    Object.defineProperty(record, key, { value, enumerable: true, configurable: true, writable: true });
+}
+function isPlainRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+//# sourceMappingURL=pluginBackendProtocol.js.map

package/dist/shared/pluginBackendProtocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginBackendProtocol.js","sourceRoot":"","sources":["../../src/shared/pluginBackendProtocol.ts"],"names":[],"mappings":"AAEA,+DAA+D;AAC/D,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,GAAG,IAAI,CAAC;AACxD,0FAA0F;AAC1F,MAAM,CAAC,MAAM,sCAAsC,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AACtE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,qCAAqC,GAAG,6BAA6B,GAAG,CAAC,GAAG,IAAI,CAAC;AAC9F,0EAA0E;AAC1E,MAAM,CAAC,MAAM,sCAAsC,GAAG,sCAAsC,GAAG,CAAC,GAAG,IAAI,CAAC;AACxG,0DAA0D;AAC1D,MAAM,CAAC,MAAM,iCAAiC,GAAG,MAAM,CAAC;AACxD,kFAAkF;AAClF,MAAM,CAAC,MAAM,kCAAkC,GAAG,MAAM,CAAC;AACzD,wEAAwE;AACxE,MAAM,CAAC,MAAM,oCAAoC,GAAG,MAAM,CAAC;AAC3D,MAAM,CAAC,MAAM,mCAAmC,GAAG,GAAG,CAAC;AACvD,MAAM,CAAC,MAAM,kCAAkC,GAAG,GAAG,CAAC;AAEtD,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AAChD,MAAM,cAAc,GAAG,EAAE,CAAC;AAO1B,MAAM,UAAU,wBAAwB,CAAC,KAAa;IACpD,OAAO,KAAK,CAAC,MAAM,IAAI,mCAAmC,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC9F,CAAC;AAED,MAAM,UAAU,6BAA6B,CAAC,KAAa;IACzD,IAAI,CAAC,wBAAwB,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,uCAAuC,MAAM,CAAC,iBAAiB,CAAC,mBAAmB,MAAM,CAAC,mCAAmC,CAAC,aAAa,CAAC,CAAC;IAC/J,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,KAAc;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,IAAI,KAAK,CAAC,MAAM,GAAG,kCAAkC,EAAE,CAAC;QACnG,MAAM,IAAI,KAAK,CAAC,iEAAiE,MAAM,CAAC,kCAAkC,CAAC,aAAa,CAAC,CAAC;IAC5I,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,6BAA6B,CAC3C,KAAc,EACd,KAAa,EACb,QAAQ,GAAG,6BAA6B;IAExC,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,EAAE,IAAI,GAAG,EAAU,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAClE,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,cAAc,CAAC,UAAU,CAAC,GAAG,QAAQ,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,gBAAgB,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,iCAAiC,CAC/C,KAAc,EACd,KAAa,EACb,QAAQ,GAAG,6BAA6B;IAExC,OAAO,IAAI,CAAC,SAAS,CAAC,6BAA6B,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,IAAY,EACZ,KAAa,EACb,QAAQ,GAAG,6BAA6B;IAExC,IAAI,cAAc,CAAC,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,gBAAgB,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,qBAAqB,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,6BAA6B,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,iCAAiC,CAAC,KAAc;IAC9D,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IAC5F,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,QAAQ,EAAE,4BAA4B,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACzD,KAAK,EAAE,6BAA6B,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,8BAA8B,CAAC;KACrF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC;AACpD,CAAC;AAED,SAAS,cAAc,CAAC,KAAc,EAAE,SAAsB,EAAE,KAAa,EAAE,KAAa;IAC1F,IAAI,KAAK,GAAG,cAAc;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,sCAAsC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;IACpH,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC5F,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,wCAAwC,CAAC,CAAC;QAC/F,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,0BAA0B,CAAC,CAAC;QAC9E,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrB,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;QACxF,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACxB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACtB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,gCAAgC,CAAC,CAAC;IACrF,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,0BAA0B,CAAC,CAAC;IAC9E,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACrB,MAAM,MAAM,GAA8B,EAAE,CAAC;IAC7C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,kBAAkB,CAAC,MAAM,EAAE,GAAG,EAAE,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IACtF,CAAC;IACD,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACxB,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAiC,EAAE,GAAW,EAAE,KAAgB;IAC1F,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;AACtG,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtF,MAAM,SAAS,GAAY,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACxD,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAC9D,CAAC"}

package/dist/shared/pluginIds.js

@@ -2,4 +2,7 @@ export const piWebPluginIdPattern = /^[a-z][a-z0-9.-]*$/u;
 export function isPiWebPluginId(value) {
     return piWebPluginIdPattern.test(value);
 }
+export function isReservedPiWebPluginId(value) {
+    return value === "core";
+}
 //# sourceMappingURL=pluginIds.js.map

package/dist/shared/pluginIds.js.map

@@ -1 +1 @@
-{"version":3,"file":"pluginIds.js","sourceRoot":"","sources":["../../src/shared/pluginIds.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AAE1D,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1C,CAAC"}
+{"version":3,"file":"pluginIds.js","sourceRoot":"","sources":["../../src/shared/pluginIds.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AAE1D,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,KAAa;IACnD,OAAO,KAAK,KAAK,MAAM,CAAC;AAC1B,CAAC"}

package/dist/shared/pluginRecoveryCommands.js

@@ -0,0 +1,14 @@
+import { isPiWebPluginId } from "./pluginIds.js";
+/** Secret-free commands accepted by the offline recovery CLI. */
+export const PI_WEB_PLUGIN_RECOVERY_COMMANDS = Object.freeze({
+    showSafeStart: "pi-web plugins safe-start show",
+    bundledOnly: "pi-web plugins safe-start set bundled-only --restart",
+    noServerPlugins: "pi-web plugins safe-start set none --restart",
+    clearSafeStart: "pi-web plugins safe-start clear --restart",
+});
+export function pluginDisableRecoveryCommand(pluginId) {
+    if (!isPiWebPluginId(pluginId))
+        throw new Error(`Invalid PI WEB plugin id: ${pluginId}`);
+    return `pi-web plugins disable ${pluginId} --restart`;
+}
+//# sourceMappingURL=pluginRecoveryCommands.js.map

package/dist/shared/pluginRecoveryCommands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginRecoveryCommands.js","sourceRoot":"","sources":["../../src/shared/pluginRecoveryCommands.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,iEAAiE;AACjE,MAAM,CAAC,MAAM,+BAA+B,GAA0C,MAAM,CAAC,MAAM,CAAC;IAClG,aAAa,EAAE,gCAAgC;IAC/C,WAAW,EAAE,sDAAsD;IACnE,eAAe,EAAE,8CAA8C;IAC/D,cAAc,EAAE,2CAA2C;CAC5D,CAAC,CAAC;AAEH,MAAM,UAAU,4BAA4B,CAAC,QAAgB;IAC3D,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,QAAQ,EAAE,CAAC,CAAC;IACzF,OAAO,0BAA0B,QAAQ,YAAY,CAAC;AACxD,CAAC"}

package/dist/shared/workspaceFiles.js

@@ -1,3 +1,42 @@
-export const MAX_IMAGE_PREVIEW_BYTES = 10 * 1024 * 1024;
-export const MAX_IMAGE_PREVIEW_LABEL = "10 MB";
+export const MAX_INLINE_PREVIEW_BYTES = 10 * 1024 * 1024;
+export const MAX_INLINE_PREVIEW_LABEL = "10 MB";
+export const MAX_WORKSPACE_FILE_CONTENT_BYTES = 512 * 1024;
+// Extension classification is shared by JSON source reads, streamed previews,
+// and proxy response policy. Keep this an allowlist: only classifications with
+// a preview MIME type may be served as browser-rendered bytes.
+//
+// `source` decides what a JSON file read carries: "text" formats keep capped
+// literal UTF-8 source so the viewer can offer Raw mode, while "stream" formats
+// stay out of JSON and are only ever served as preview bytes.
+const WORKSPACE_FILE_CLASSIFICATIONS = {
+    ".avif": { mediaType: "image", source: "stream", previewMimeType: "image/avif" },
+    ".bmp": { mediaType: "image", source: "stream", previewMimeType: "image/bmp" },
+    ".gif": { mediaType: "image", source: "stream", previewMimeType: "image/gif" },
+    ".ico": { mediaType: "image", source: "stream", previewMimeType: "image/x-icon" },
+    ".jpeg": { mediaType: "image", source: "stream", previewMimeType: "image/jpeg" },
+    ".jpg": { mediaType: "image", source: "stream", previewMimeType: "image/jpeg" },
+    ".png": { mediaType: "image", source: "stream", previewMimeType: "image/png" },
+    // SVG is markup: it previews as an image but also has readable source, so it
+    // keeps literal text for Raw mode.
+    ".svg": { mediaType: "image", source: "text", previewMimeType: "image/svg+xml" },
+    ".webp": { mediaType: "image", source: "stream", previewMimeType: "image/webp" },
+    ".htm": { mediaType: "html", source: "text", previewMimeType: "text/html; charset=utf-8" },
+    ".html": { mediaType: "html", source: "text", previewMimeType: "text/html; charset=utf-8" },
+    ".pdf": { mediaType: "pdf", source: "stream", previewMimeType: "application/pdf" },
+    ".md": { mediaType: "markdown", source: "text" },
+    ".markdown": { mediaType: "markdown", source: "text" },
+};
+export function classifyWorkspaceFile(path) {
+    const slashIndex = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+    const dotIndex = path.lastIndexOf(".");
+    if (dotIndex <= slashIndex)
+        return undefined;
+    const extension = path.slice(dotIndex).toLowerCase();
+    return WORKSPACE_FILE_CLASSIFICATIONS[extension];
+}
+/** Return the leaf filename for either POSIX or Windows-style workspace paths. */
+export function workspaceFileName(path) {
+    const separatorIndex = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+    return path.slice(separatorIndex + 1);
+}
 //# sourceMappingURL=workspaceFiles.js.map

package/dist/shared/workspaceFiles.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspaceFiles.js","sourceRoot":"","sources":["../../src/shared/workspaceFiles.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACxD,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAC"}
+{"version":3,"file":"workspaceFiles.js","sourceRoot":"","sources":["../../src/shared/workspaceFiles.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACzD,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAChD,MAAM,CAAC,MAAM,gCAAgC,GAAG,GAAG,GAAG,IAAI,CAAC;AAU3D,8EAA8E;AAC9E,+EAA+E;AAC/E,+DAA+D;AAC/D,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,8DAA8D;AAC9D,MAAM,8BAA8B,GAA0D;IAC5F,OAAO,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE;IAChF,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE;IAC9E,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE;IAC9E,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE;IACjF,OAAO,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE;IAChF,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE;IAC/E,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE;IAC9E,6EAA6E;IAC7E,mCAAmC;IACnC,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,eAAe,EAAE;IAChF,OAAO,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE;IAChF,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,0BAA0B,EAAE;IAC1F,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,0BAA0B,EAAE;IAC3F,MAAM,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,iBAAiB,EAAE;IAClF,KAAK,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE;IAChD,WAAW,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE;CACvD,CAAC;AAEF,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,QAAQ,IAAI,UAAU;QAAE,OAAO,SAAS,CAAC;IAC7C,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IACrD,OAAO,8BAA8B,CAAC,SAAS,CAAC,CAAC;AACnD,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/E,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC;AACxC,CAAC"}

package/dist/shared/workspaceRemovalProtocol.js

@@ -0,0 +1,24 @@
+/** Small JSON request carrying the host-issued confirmation precondition. */
+export const WORKSPACE_REMOVAL_REQUEST_BODY_MAX_BYTES = 4 * 1024;
+/** One sessiond-owned deadline across owner resolution, validation, and planning. */
+export const WORKSPACE_REMOVAL_OPERATION_TIMEOUT_MS = 25_000;
+/** Leaves time for cancellation to reach remote web/sessiond before gateway timeout. */
+export const WORKSPACE_REMOVAL_FEDERATION_TIMEOUT_MS = 30_000;
+export const WORKSPACE_REMOVAL_PRECONDITION_MAX_LENGTH = 256;
+export function parseWorkspaceRemovalRequest(value) {
+    if (!isRecord(value))
+        throw new Error("Workspace removal request must be an object");
+    return { precondition: requireWorkspaceRemovalPrecondition(value["precondition"]) };
+}
+export function requireWorkspaceRemovalPrecondition(value) {
+    if (typeof value !== "string"
+        || value === ""
+        || value.length > WORKSPACE_REMOVAL_PRECONDITION_MAX_LENGTH) {
+        throw new Error(`Workspace removal precondition must be a non-empty string of at most ${String(WORKSPACE_REMOVAL_PRECONDITION_MAX_LENGTH)} characters`);
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=workspaceRemovalProtocol.js.map

package/dist/shared/workspaceRemovalProtocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceRemovalProtocol.js","sourceRoot":"","sources":["../../src/shared/workspaceRemovalProtocol.ts"],"names":[],"mappings":"AAEA,6EAA6E;AAC7E,MAAM,CAAC,MAAM,wCAAwC,GAAG,CAAC,GAAG,IAAI,CAAC;AACjE,qFAAqF;AACrF,MAAM,CAAC,MAAM,sCAAsC,GAAG,MAAM,CAAC;AAC7D,wFAAwF;AACxF,MAAM,CAAC,MAAM,uCAAuC,GAAG,MAAM,CAAC;AAC9D,MAAM,CAAC,MAAM,yCAAyC,GAAG,GAAG,CAAC;AAE7D,MAAM,UAAU,4BAA4B,CAAC,KAAc;IACzD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACrF,OAAO,EAAE,YAAY,EAAE,mCAAmC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC;AACtF,CAAC;AAED,MAAM,UAAU,mCAAmC,CAAC,KAAc;IAChE,IACE,OAAO,KAAK,KAAK,QAAQ;WACtB,KAAK,KAAK,EAAE;WACZ,KAAK,CAAC,MAAM,GAAG,yCAAyC,EAC3D,CAAC;QACD,MAAM,IAAI,KAAK,CACb,wEAAwE,MAAM,CAAC,yCAAyC,CAAC,aAAa,CACvI,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/docs/config.md

@@ -40,7 +40,7 @@ defaults → global config file → environment overrides
 
 Supported project-local settings are then applied for that project's workspaces. For upload defaults, `<project>/.pi-web/config.json` overrides the global value.
 
-Environment overrides include `PI_WEB_HOST`, `PI_WEB_PORT` / `PORT`, `PI_WEB_ALLOWED_HOSTS`, `PI_WEB_MAX_UPLOAD_BYTES`, `PI_WEB_AGENT_COMMAND`, `PI_WEB_AGENT_DIR`, `PI_WEB_AGENT_SESSION_DIR`, `PI_CODING_AGENT_DIR` / `PI_CODING_AGENT_SESSION_DIR` for Pi compatibility, `PI_WEB_SPAWN_SESSIONS`, `PI_WEB_SUBSESSIONS`, and `PI_WEB_ASK_USER`.
+Environment overrides include `PI_WEB_HOST`, `PI_WEB_PORT` / `PORT`, `PI_WEB_ALLOWED_HOSTS`, `PI_WEB_MAX_UPLOAD_BYTES`, `PI_WEB_AGENT_COMMAND`, `PI_WEB_AGENT_DIR`, `PI_WEB_AGENT_SESSION_DIR`, `PI_CODING_AGENT_DIR` / `PI_CODING_AGENT_SESSION_DIR`, `PI_WEB_ENVIRONMENT_FACTS`, `PI_WEB_SPAWN_SESSIONS`, `PI_WEB_SUBSESSIONS`, and `PI_WEB_ASK_USER`.
 
 Process restarts depend on the key:
 
@@ -72,7 +72,7 @@ Process restarts depend on the key:
     "dir": "~/agent-profiles/research"
   },
   "spawnSessions": true,
-  "subsessions": false,
+  "subsessions": true,
   "askUser": true,
   "extensionDialogsTimeoutMs": 300000,
   "workbenchIntegration": {
@@ -147,8 +147,9 @@ Rows with JSON key `—` are runtime-only environment variables, not config-file
 | Companion CLI command | `agent.command` | `PI_WEB_AGENT_COMMAND` | Global/session daemon | Not supported locally | Restart session daemon on that machine; affects doctor/status/update checks |
 | Agent profile state directory | `agent.dir` | `PI_WEB_AGENT_DIR` (`PI_CODING_AGENT_DIR` for Pi compatibility) | Global/session daemon | Not supported locally | Restart session daemon on that machine; affects auth, models, settings, sessions, Pi packages, and Pi-package-backed PI WEB plugins |
 | Agent can spawn sessions | `spawnSessions` | `PI_WEB_SPAWN_SESSIONS` | Global/session daemon | Not supported locally | Restart session daemon on that machine |
-| Tracked subsessions (beta) | `subsessions` | `PI_WEB_SUBSESSIONS` | Global/session daemon | Not supported locally; also requires `spawnSessions` | Restart session daemon on that machine |
+| Tracked subsessions | `subsessions` | `PI_WEB_SUBSESSIONS` | Global/session daemon | Not supported locally; also requires `spawnSessions` | Restart session daemon on that machine |
 | Agent can post question forms | `askUser` | `PI_WEB_ASK_USER` | Global/session daemon | Not supported locally | Restart session daemon on that machine |
+| Ordinary-session environment facts | `environmentFacts` | `PI_WEB_ENVIRONMENT_FACTS` | Global/session daemon | Not supported locally | Restart session daemon on that machine; affects newly started sessions |
 | 扩展对话框自动取消超时 | `extensionDialogsTimeoutMs` | — | 全局/会话守护进程 | 不支持项目级配置 | 重启对应机器上的会话守护进程 |
 | Workbench/MCP integration | `workbenchIntegration.*` | `PI_WEB_WORKBENCH_URL`, `PI_WEB_MCP_URL`, `PI_WEB_WORKBENCH_TIMEOUT_MS`, `PI_WEB_MCP_TIMEOUT_MS`, `PI_WEB_SKILL_BUNDLE_MAX_BYTES`, `PI_WEB_SKILL_FILE_MAX_BYTES`, `PI_WEB_SKILL_FILE_COUNT_MAX` | Web/API + session daemon | Not supported locally | Restart web/API and session daemon; both must match |
 | Ordinary tool audit | `auditLog.normalMode.*` | — | Global/session daemon | Not supported locally | Restart session daemon |
@@ -264,6 +265,8 @@ The per-request size limit is still controlled by `maxUploadBytes` / `PI_WEB_MAX
 
 ### Pi-compatible agent profile and companion CLI
 
+PI WEB embeds Pi Coding Agent `0.84.x` or newer compatible runtime packages. The session daemon owns one resolved Pi state directory and refuses to start a second daemon against the same `PI_WEB_DATA_DIR`; use distinct data and endpoint variables for another instance.
+
 `agent.command` selects the Pi-compatible companion CLI used by `pi-web doctor` and, when it can be generated safely, package-managed update commands. It defaults to `pi`. This setting does **not** replace the embedded runtime: every session continues to use PI WEB's bundled Pi SDK.
 
 `agent.dir` selects the Pi-compatible state profile used for auth providers, models, settings, sessions, Pi packages, and Pi-package-backed PI WEB plugin discovery. It defaults to `~/.pi/agent` only for a canonical Pi companion command. The directory must use the data layout supported by the bundled Pi SDK; PI WEB does not load or convert incompatible fork formats, migrate profile data, or repartition PI WEB-managed archives when the profile changes.
@@ -279,7 +282,9 @@ The per-request size limit is still controlled by `maxUploadBytes` / `PI_WEB_MAX
 
 An alternate command always requires an explicit state directory. The command must be a safe bare executable name such as `pi-lab` or a host-absolute executable path such as `/opt/pi/bin/pi`; relative paths, shell expressions, and launcher strings are rejected. The state directory must be host-absolute or start with `~`. In a federated save, the gateway transports Unix and Windows absolute paths without reinterpreting them, and the target machine validates and returns the persisted profile.
 
-Environment variables take precedence over the config file. `PI_WEB_AGENT_COMMAND` selects the companion CLI, `PI_WEB_AGENT_DIR` sets the profile state directory, and `PI_WEB_AGENT_SESSION_DIR` overrides session storage separately from `agent.dir`. The legacy `PI_CODING_AGENT_DIR` and `PI_CODING_AGENT_SESSION_DIR` names apply only to a canonical Pi companion command; PI WEB never derives ambient environment-variable names from an arbitrary command. Use the explicit `PI_WEB_AGENT_*` names for alternate commands. `PI_WEB_AGENT_DIR` is an unconditional override, while a legacy `PI_CODING_AGENT_DIR` override stops applying when Settings selects an alternate command so the command and directory can transition together.
+Environment variables take precedence over the config file. For the state directory, precedence is `PI_WEB_AGENT_DIR` > `PI_CODING_AGENT_DIR` > `agent.dir` > the Pi default. For session storage, `PI_WEB_AGENT_SESSION_DIR` remains first for compatibility, followed by `PI_CODING_AGENT_SESSION_DIR`. The resolved directory is exported as `PI_CODING_AGENT_DIR` to embedded Pi processes.
+
+`environmentFacts` controls factual system-prompt sections appended only to ordinary sessions. These describe PI WEB session nesting and, when the daemon runs in Docker, the observed container filesystem, persistent mounts, host access, and development mount shape. `PI_WEB_ENVIRONMENT_FACTS` takes precedence and accepts `0|1|true|false`; the default is enabled. Set it to `false` to disable all such sections, restart the session daemon, and start a new session. Existing sessions retain the prompt they started with. Management-embed sessions do not receive these ordinary-session facts.
 
 The session daemon resolves the persisted desired values plus its environment once at startup. That secret-free active profile stays fixed for the daemon lifetime. **Settings → Session daemon** saves command and directory together as desired configuration and shows whether the profile is active, needs a restart, or cannot be compared. Until the daemon restarts, sessions, Pi package operations, Pi-package-backed PI WEB plugin discovery, status/install detection, and update planning continue to use the daemon-owned active profile; a web/API restart recovers that same active profile instead of applying the newly saved values.
 
@@ -335,10 +340,12 @@ To turn the background refresh off entirely, set `PI_WEB_OFFLINE` or `PI_OFFLINE
 
 `spawnSessions` controls whether agents receive the `spawn_session` tool. It defaults to `true`; set it to `false` if you do not want an agent to start independent PI WEB sessions.
 
-`subsessions` is beta and controls whether agents receive the tracked-subsession tools: `spawn_subsession`, `list_subsessions`, `check_subsession`, `read_subsession`, and `yield_to_subsessions`. It defaults to `false` and also requires `spawnSessions` to be enabled.
+`subsessions` controls whether agents receive the tracked-subsession tools: `spawn_subsession`, `list_subsessions`, `check_subsession`, `read_subsession`, and `yield_to_subsessions`. It defaults to `true` and also requires `spawnSessions` to be enabled.
 
 Tracked subsessions are join-oriented. Calling `spawn_subsession` returns immediately, so the parent can continue independent work while the child runs. Work whose result the parent does not need to join belongs in the fire-and-forget `spawn_session` tool instead.
 
+A tracked subsession always runs in the spawning session's working directory, so it stays in that workspace's session tree next to its parent. `spawn_subsession` takes no `cwd`. For work in another workspace, use `spawn_session` to create an independent session there.
+
 At a join point, after finishing its independent work, the parent calls `yield_to_subsessions` alone as the final action in its tool batch. Pi ends a tool batch early only when every result in that batch is terminating. If any tracked child is still working, the action ends the current agent run so the parent becomes idle. If none are working, it does not end the run and clearly reports that there is nothing to wait for.
 
 A completion notice wakes an idle parent or queues behind in-flight work. Each notice lists any other tracked children still working, so the parent can continue work or call `yield_to_subsessions` again at the next join point. Further notices arrive automatically; do not poll. The notice includes the child's final output when it fits. If that output is too long, PI WEB omits it entirely instead of adding a truncated duplicate to the parent's context and directs the parent to retrieve it with `check_subsession`.

package/docs/plugins.md

@@ -133,7 +133,7 @@ Module shape excerpt:
 
 ```js
 export default {
-  apiVersion: 1,
+  apiVersion: 2,
   name: "Info Plugin",
   activate: ({ html, svg }) => ({
     contributions: {
@@ -301,6 +301,8 @@ Review task configs before running them, especially in shared projects. Workspac
 
 A relay is a directory of markdown notes under `.pi-web/relays/<name>/` in the workspace root — the convention used by the Relay method for chaining agent sessions. The tab lists each relay's documents with `status.md`, `charter.md`, and `log.md` first (in that order), followed by any other files alphabetically, and opens `status.md` by default. Markdown documents render as sanitized HTML; other files render as preformatted text, and binary files have no preview. Truncated documents show a notice, and **Refresh** re-scans the workspace and reloads the open document.
 
+Documents in subfolders are listed too. Folders appear as chips in the document strip, and expanding one inserts its files inline after it. Expanding a folder collapses its siblings at the same level, while collapsing the folder that contains the open document keeps the selection and highlights that folder. Relay trees deeper than five levels, larger than 200 documents, or containing more than 50 folders are listed partially with a notice.
+
 With several relays, a picker pre-selects the most recently modified one; a single relay opens directly. A workspace without `.pi-web/relays/` shows an empty state explaining the convention. The tab never creates, edits, or deletes relay files.
 
 Relays is enabled by default. To hide it, disable `relays` in **Settings → PI WEB plugins** or set:
@@ -409,14 +411,15 @@ The entry module must default-export a plugin object:
 
 ```ts
 interface PiWebPlugin {
-  apiVersion: 1;
+  apiVersion: 2;
   name: string;
   activate: (context: PluginActivationContext) => PluginActivationResult;
 }
 
 interface PluginActivationContext {
-  apiVersion: 1;
+  apiVersion: 2;
   pluginId: string;
+  runtimePluginId?: string;
   html: typeof import("lit").html;
   svg: typeof import("lit").svg;
 }
@@ -430,7 +433,7 @@ Example:
 
 ```js
 export default {
-  apiVersion: 1,
+  apiVersion: 2,
   name: "My Plugin",
   activate: ({ pluginId, html }) => ({
     contributions: {
@@ -444,6 +447,8 @@ export default {
 
 `activate()` is called once when the UI loads the plugin. Keep it cheap: define contributions there, but move expensive or async work into actions, custom elements, or explicit user interactions.
 
+Browser API v2 is a deliberate compatibility break. PI WEB rejects browser API v1 modules instead of silently adapting them. Migrate by setting `apiVersion: 2`, using `pluginId` for the stable package/provider identity, and using `runtimePluginId` when a host-qualified contribution id is required. The former `@chainingintention/pi-web-cn/plugin-api/unstable` path is no longer exported; rely on the documented stable helpers instead.
+
 The plugin id comes from `package.json`, not from the JavaScript module. Contribution ids are local to the plugin and PI WEB qualifies them internally as:
 
 ```text
@@ -535,7 +540,7 @@ Notes:
 - `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 `@chainingintention/pi-web-cn/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 browser plugin API. Runtime-only fields and private HTTP routes are not compatibility surfaces.
 
 ### Prompt editor API
 
@@ -760,7 +765,7 @@ if (!customElements.get("my-workspace-badge")) {
 }
 
 export default {
-  apiVersion: 1,
+  apiVersion: 2,
   name: "My Plugin",
   activate: ({ html }) => ({
     contributions: {
@@ -995,18 +1000,7 @@ Review command strings carefully. They are trusted shell commands executed in th
 
 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.
 
-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:
-
-```ts
-import type { WorkspacePanelContext } from "@chainingintention/pi-web-cn/plugin-api";
-import type { UnstableWorkspacePanelContext } from "@chainingintention/pi-web-cn/plugin-api/unstable";
-
-function unstableContext(context: WorkspacePanelContext) {
-  return context as WorkspacePanelContext & UnstableWorkspacePanelContext;
-}
-```
-
-Unstable APIs are not covered by the v1 compatibility promise. Prefer documented helpers whenever they exist.
+The stable browser API is the documented helper surface and the type-only `@chainingintention/pi-web-cn/plugin-api` export. The stable server API is the separate type-only `@chainingintention/pi-web-cn/server-plugin-api` export. The former browser `plugin-api/unstable` entry is not part of API v2 and is no longer exported. Code that deliberately depends on another private runtime surface must keep that dependency local and expect to revisit it after PI WEB upgrades.
 
 ## Async data and caching
 
@@ -1024,7 +1018,7 @@ If you are an AI agent building or editing a PI WEB plugin, follow this checklis
 
 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, machineSpecific? }` entries.
-3. Default-export `{ apiVersion: 1, name, activate }` from the module.
+3. Default-export `{ apiVersion: 2, name, activate }` from a browser module. Server modules use server-plugin API v1.
 4. Return `{ contributions: { actions, workspacePanels, workspaceLabels } }` from `activate()`.
 5. Use ids matching `^[a-z][a-z0-9.-]*$`.
 6. Use the activation context's `html` function for Lit templates.
@@ -1034,7 +1028,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`, `state.piWebStatus`, and `prompt`.
-13. Do not fetch PI WEB `/api/...` endpoints directly unless you intentionally accept private API churn; prefer documented helpers. If an unstable runtime field is intentionally required, import the type from `@chainingintention/pi-web-cn/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 such as the paired workspace `backend` bridge.
 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.
 
@@ -1056,7 +1050,7 @@ Common issues:
 
 - invalid plugin id or contribution id;
 - missing default export;
-- missing `apiVersion: 1`, `name`, or `activate` function;
+- missing browser `apiVersion: 2`, `name`, or `activate` function;
 - missing `package.json` or incorrect `piWeb.plugins` metadata;
 - legacy shortcuts such as `piWeb.plugin`, string plugin entries, or no-`package.json` fallback;
 - duplicate plugin ids; later duplicates are skipped rather than renamed;

package/package.json

@@ -1,10 +1,28 @@
 {
   "name": "@chainingintention/pi-web-cn",
-  "version": "1.202608.8",
+  "version": "1.202608.10",
   "description": "Remote web UI and browser control plane for persistent Pi Coding Agent sessions.",
   "license": "MIT",
   "author": "Federico Jaramillo Martinez",
   "type": "module",
+  "exports": {
+    "./plugin-api": {
+      "types": "./dist/plugin-api.d.ts"
+    },
+    "./server-plugin-api": {
+      "types": "./dist/server-plugin-api.d.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "plugin-api": [
+        "dist/plugin-api.d.ts"
+      ],
+      "server-plugin-api": [
+        "dist/server-plugin-api.d.ts"
+      ]
+    }
+  },
   "bin": {
     "pi-web": "dist/cli.js",
     "pi-web-server": "dist/server/index.js",
@@ -16,12 +34,13 @@
     "install.sh",
     "README.md",
     "LICENSE",
+    "skills/relay/SKILL.md",
     "extensions",
     "docs/plugins.md",
     "docs/config.md",
     "docs/assets",
     "plugin-api.d.ts",
-    "plugin-api/unstable.d.ts"
+    "server-plugin-api.d.ts"
   ],
   "scripts": {
     "dev": "bash -c 'trap \"kill 0\" EXIT; npm run dev:sessiond & npm run dev:web & npm run dev:client & wait'",
@@ -84,9 +103,9 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
-    "@earendil-works/pi-agent-core": "^0.82.1",
-    "@earendil-works/pi-ai": "^0.82.1",
-    "@earendil-works/pi-coding-agent": "^0.82.1",
+    "@earendil-works/pi-agent-core": "^0.84.1",
+    "@earendil-works/pi-ai": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
     "@eslint/js": "^10.0.1",
     "@types/node": "^24.13.3",
     "@types/ws": "^8.18.1",
@@ -119,9 +138,9 @@
   "homepage": "https://github.com/nayuto-wakusei/pi-web-ChineseTranslation#readme",
   "packageManager": "npm@11.11.0",
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.82.1 <0.83",
-    "@earendil-works/pi-ai": ">=0.82.1 <0.83",
-    "@earendil-works/pi-coding-agent": ">=0.82.1 <0.83"
+    "@earendil-works/pi-agent-core": ">=0.84.0",
+    "@earendil-works/pi-ai": ">=0.84.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.0"
   },
   "keywords": [
     "pi-package",

package/server-plugin-api.d.ts

@@ -0,0 +1 @@
+export * from "./dist/server-plugin-api.js";

package/skills/README.md

@@ -0,0 +1,12 @@
+# skills
+
+Distributable agent skills developed alongside pi-web.
+
+## relay
+
+Execute a long or complex plan as a chain of independent sessions, each running
+one well-sized leg and handing off to the next via `spawn_session`.
+
+```bash
+npx skills add jmfederico/pi-web --skill relay -a pi -g
+```