feat(plugins): add host.storage bridge and document sidecar data dir

This commit is contained in:
t8y2 committed 2026-09-21 11:41:58 +08:00
1 parent d3b3a4dbd6
commit 865b9fba84
18 files changed
+700 -8

No files matched your search

@@ -78,6 +78,15 @@ export interface PluginFileWriteResult {
/** Chunk size the host advertises for streamed saves; fits the bridge payload cap after base64. */
export const PLUGIN_SAVE_CHUNK_BYTES = 1024 * 1024;
/**
* Per-value cap for `host.storage` entries. The whole store is additionally
* capped by the native host; both bounds keep this a UI-state store — bulk
* data belongs to the sidecar's data directory.
*/
export const MAX_PLUGIN_STORAGE_VALUE_BYTES = 256 * 1024;
/** Longest accepted `host.storage` key, mirroring the native host's bound. */
export const MAX_PLUGIN_STORAGE_KEY_CHARS = 256;
export interface PluginHostBridgeApi {
invoke<T = unknown>(pluginId: string, method: string, params?: unknown, timeoutMs?: number): Promise<T>;
notify(pluginId: string, method: string, params?: unknown): Promise<void>;
@@ -117,6 +126,10 @@ export interface PluginHostBridgeApi {
finishFileSave?(pluginId: string, handleId: string): Promise<void>;
/** Close any file handle, discarding unsaved state. */
closeFileHandle?(pluginId: string, handleId: string): Promise<void>;
/** Persistent per-plugin key-value storage for sandboxed UIs; resolves null when the key is unset. */
storageGet?(pluginId: string, key: string): Promise<unknown>;
storageSet?(pluginId: string, key: string, value: unknown): Promise<void>;
storageDelete?(pluginId: string, key: string): Promise<void>;
}
interface PluginRequestMessage {
@@ -231,7 +244,11 @@ export class PluginHostBridge {
permissions: [...(this.plugin.manifest.permissions || [])],
// Additive capability advertisement: an older host omits `planApi`, and a
// plugin must treat the absence as "unsupported" rather than probing.
capabilities: { downloadFile: !!this.api.downloadFile, planApi: !!this.api.getPlanCapabilities && !!this.api.explainPlan },
capabilities: {
downloadFile: !!this.api.downloadFile,
planApi: !!this.api.getPlanCapabilities && !!this.api.explainPlan,
storage: !!this.api.storageGet && !!this.api.storageSet && !!this.api.storageDelete,
},
context: snapshotPluginWorkbenchContext(this.context),
});
}
@@ -440,6 +457,33 @@ export class PluginHostBridge {
await this.api.closeFileHandle(this.plugin.manifest.id, requireHandleId(input.handleId));
return null;
}
if (method === "host.storageGet") {
this.requirePermission("host.storage");
if (!this.api.storageGet) throw new Error("Host storage is unavailable");
const input = requireRecord(params, "host.storageGet params");
return this.api.storageGet(this.plugin.manifest.id, requireStorageKey(input.key));
}
if (method === "host.storageSet") {
this.requirePermission("host.storage");
if (!this.api.storageSet) throw new Error("Host storage is unavailable");
const input = requireRecord(params, "host.storageSet params");
const key = requireStorageKey(input.key);
// Sized before the structured clone reaches the host implementation, so
// the native host and the web fallback enforce the same bound.
const bytes = new TextEncoder().encode(JSON.stringify(input.value ?? null)).byteLength;
if (bytes > MAX_PLUGIN_STORAGE_VALUE_BYTES) {
throw new Error(`host.storage value exceeds ${MAX_PLUGIN_STORAGE_VALUE_BYTES} bytes`);
}
await this.api.storageSet(this.plugin.manifest.id, key, input.value ?? null);
return null;
}
if (method === "host.storageDelete") {
this.requirePermission("host.storage");
if (!this.api.storageDelete) throw new Error("Host storage is unavailable");
const input = requireRecord(params, "host.storageDelete params");
await this.api.storageDelete(this.plugin.manifest.id, requireStorageKey(input.key));
return null;
}
throw new Error(`Unsupported plugin host method '${method}'`);
}
@@ -769,6 +813,13 @@ export function pluginSdkSource(initialTheme?: PluginBridgeTheme): string {
return request('host.saveFile', options, { transfer: bytes });
},
copy: (text) => request('host.copy', { text }),
// Persistent per-plugin key-value state; gate on capabilities.storage
// (older hosts omit it) and declare the host.storage permission.
storage: Object.freeze({
get: (key) => request('host.storageGet', { key }),
set: (key, value) => request('host.storageSet', { key, value: value === undefined ? null : value }),
delete: (key) => request('host.storageDelete', { key }),
}),
fileTransfer: Object.freeze({
pick: (options) => request('host.pickFiles', options || {}),
read: (handleId, offset, length) => request('host.readFileChunk', { handleId, offset, length }),
@@ -936,6 +987,14 @@ function requireChunkLength(value: unknown): number {
return Math.min(8 * 1024 * 1024, Math.floor(value));
}
/** A `host.storage` key: bounded, non-empty, no control characters. */
function requireStorageKey(value: unknown): string {
if (typeof value !== "string" || !value || value.length > MAX_PLUGIN_STORAGE_KEY_CHARS || /[\u0000-\u001f]/.test(value)) {
throw new Error("storage key is invalid");
}
return value;
}
function base64ToBytes(value: string): ArrayBuffer {
const binary = atob(value);
const bytes = new Uint8Array(binary.length);