@gestaltrun/dsh-workspace-bundle 0.0.0-stage → 0.1.0

package/lib/types/provider.js

@@ -0,0 +1,462 @@
+/**
+ * Host Provider of `WorkspaceBundles`: register a packaged template, materialize a stable
+ * hidden Workspace, and replace its tree as a whole with crash recovery.
+ */
+import { join } from 'node:path';
+import { brandString } from '@deepseek-ai/dsh-brand';
+import { Config, resolveWorkspaceBundlesSpec } from "./config.js";
+import { WorkspaceBundles } from "./definition.js";
+import { loadVerifiedManifest, verifyTemplateTree } from "./digest.js";
+import { WorkspaceBundleError } from "./errors.js";
+import { crashableFs, createNodeFs } from "./filesystem.js";
+import { assertRecordPaths, committedRecord, idleJournal, readRecord, recordPath, writeJournal, writeRecord } from "./journal.js";
+import { bundledDirectory, identityOf } from "./paths.js";
+import { WorkspaceAgentConfigSourceOwner } from "./agent-config-source.js";
+import { AgentConfigError } from "./agent-config-format.js";
+function keyOf(identity) {
+    return `${identity.bundleId}/${identity.workspaceKey}`;
+}
+function originOf(identity) {
+    return { kind: 'bundle', bundleId: identity.bundleId, workspaceKey: identity.workspaceKey };
+}
+async function copyTree(fs, from, to, files) {
+    await fs.rm(to, { recursive: true });
+    await fs.mkdir(to);
+    for (const file of files) {
+        const relative = file.path.split('/');
+        const destination = join(to, ...relative);
+        await fs.mkdir(join(destination, '..'));
+        await fs.copyFile(join(from, ...relative), destination);
+    }
+}
+/** Provider for packaged Workspace templates. */
+export class GestaltWorkspaceBundles extends WorkspaceBundles {
+    static inject = ['workspaceRegistry'];
+    static Config = Config;
+    /** Deployment settings resolved at load. */
+    spec;
+    fs;
+    templates = new Map();
+    agentConfigSources = new Map();
+    records = new Map();
+    leases = new Map();
+    waiters = new Map();
+    chain = Promise.resolve();
+    recycle = new Map();
+    recycleWork = new Map();
+    closed = false;
+    download;
+    /**
+     * @param ctx - Host context with the Workspace registry.
+     * @param config - raw row settings.
+     * @param options.fs - filesystem; tests inject crashes through `crashAt`.
+     * @param options.crashAt - single crash point; production omits it.
+     * @param options.fetch - 文件 HTTP 传输；默认使用 Host fetch。
+     */
+    constructor(ctx, config = {}, options = {}) {
+        super(ctx);
+        this.spec = resolveWorkspaceBundlesSpec(config);
+        this.fs = crashableFs(options.fs ?? createNodeFs(), options.crashAt);
+        this.download = options.fetch ?? fetch;
+        ctx.effect(() => async () => {
+            this.closed = true;
+            for (const timer of this.recycle.values())
+                clearTimeout(timer);
+            this.recycle.clear();
+            await Promise.all([...this.agentConfigSources.values()].map(source => source.dispose()));
+            await this.chain;
+            await Promise.all(this.recycleWork.values());
+            this.agentConfigSources.clear();
+        }, 'workspace-bundle: recycle timers');
+    }
+    /** @inheritdoc */
+    register(template) {
+        if (this.closed)
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', 'Workspace 内容服务已停止');
+        identityOf(template.bundleId, template.workspaceKey);
+        const key = keyOf(template);
+        this.templates.set(key, template);
+        const record = this.records.get(key);
+        if (record !== undefined)
+            this.records.set(key, { ...record, registered: true });
+        return () => {
+            if (this.templates.get(key) !== template)
+                return;
+            this.templates.delete(key);
+            const current = this.records.get(key);
+            if (current !== undefined)
+                this.records.set(key, { ...current, registered: false });
+        };
+    }
+    /** @inheritdoc */
+    ensure(identity) {
+        if (this.closed)
+            return Promise.reject(new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', 'Workspace 内容服务已停止'));
+        identityOf(identity.bundleId, identity.workspaceKey);
+        return this.enqueue(() => this.ensureOne(identity));
+    }
+    /** @inheritdoc */
+    registerAgentConfigSource(source) {
+        if (this.closed)
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', 'Workspace 内容服务已停止');
+        const key = keyOf(source.identity);
+        const template = this.requireTemplate(source.identity);
+        if (this.agentConfigSources.has(key))
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', 'Agent 配置版本来源已注册');
+        const owner = new WorkspaceAgentConfigSourceOwner({ template, source }, this.spec, error => {
+            this.ctx.logger.warn('%s：%s', error.code, error.message);
+        }, this.download);
+        this.agentConfigSources.set(key, owner);
+        owner.start();
+        return async () => {
+            await owner.dispose();
+            if (this.agentConfigSources.get(key) === owner)
+                this.agentConfigSources.delete(key);
+        };
+    }
+    /** @inheritdoc */
+    agentConfig(identity) {
+        return this.agentConfigSources.get(keyOf(identity))?.state();
+    }
+    /** @inheritdoc */
+    async refreshAgentConfig(identity) {
+        const source = this.agentConfigSources.get(keyOf(identity));
+        if (source === undefined)
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', 'Agent 配置版本来源未注册');
+        await source.refresh();
+    }
+    /** @inheritdoc */
+    async acquire(workspaceId) {
+        if (this.closed)
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', 'Workspace 内容服务已停止');
+        if ([...this.records.values()].some(record => record.workspaceId === workspaceId && record.journal.phase === 'updating')) {
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', `workspace ${workspaceId} is updating`);
+        }
+        return this.enqueue(() => this.acquireOne(workspaceId));
+    }
+    async acquireOne(workspaceId) {
+        const record = [...this.records.values()].find(item => item.workspaceId === workspaceId);
+        if (record === undefined || !record.registered) {
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', `workspace ${workspaceId} is not an acquired bundle Workspace`);
+        }
+        if (record.journal.phase === 'updating') {
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', `workspace ${workspaceId} is updating`);
+        }
+        if ((this.leases.get(workspaceId)?.size ?? 0) === 0 && this.agentConfigSources.has(keyOf(record))) {
+            await this.ensureOne(record);
+        }
+        const token = Symbol('workspace-bundle-lease');
+        let leases = this.leases.get(workspaceId);
+        if (leases === undefined) {
+            leases = new Set();
+            this.leases.set(workspaceId, leases);
+        }
+        leases.add(token);
+        return () => {
+            leases.delete(token);
+            if (leases.size === 0)
+                this.leases.delete(workspaceId);
+            const waiters = this.waiters.get(workspaceId);
+            if (waiters !== undefined)
+                for (const waiter of waiters)
+                    waiter();
+        };
+    }
+    /** @inheritdoc */
+    record(identity) {
+        return this.records.get(keyOf(identity));
+    }
+    /** @inheritdoc */
+    pathOf(identity) {
+        identityOf(identity.bundleId, identity.workspaceKey);
+        return bundledDirectory(this.spec.materializeRoot, identity);
+    }
+    /**
+     * Replay an interrupted journal before serving the Workspace.
+     * @param identity - branded pair.
+     * @throws {WorkspaceBundleError} Before any rename or deletion if stored paths differ from this identity's controlled paths.
+     */
+    async recover(identity) {
+        return this.enqueue(() => this.recoverOne(identity));
+    }
+    enqueue(work) {
+        const run = this.chain.then(work, work);
+        this.chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async ensureOne(identity) {
+        let template = this.requireTemplate(identity);
+        const source = this.agentConfigSources.get(keyOf(identity));
+        const stored = this.records.get(keyOf(identity)) ?? await this.loadStored(identity);
+        if (source !== undefined) {
+            template = await source.recover(stored?.templateDigest, stored?.pluginVersion, stored?.agentConfigSha256);
+        }
+        const recovered = await this.recoverOne(identity);
+        const record = this.records.get(keyOf(identity));
+        if (source !== undefined)
+            template = await source.recover(record?.templateDigest, record?.pluginVersion, record?.agentConfigSha256);
+        if (source !== undefined && (record?.workspaceId === null || record?.workspaceId === undefined
+            || (this.leases.get(record.workspaceId)?.size ?? 0) === 0))
+            template = source.template();
+        if (recovered !== undefined && record !== undefined
+            && record.templateDigest === template.manifest.digest && record.pluginVersion === template.manifest.pluginVersion
+            && (record.agentConfigSha256 ?? null) === (template.agentConfigSha256 ?? null) && record.journal.phase === 'idle') {
+            return recovered;
+        }
+        try {
+            const workspace = await this.replace(template, record, source === undefined ? undefined : () => source.assertApplicable(template));
+            await source?.committed(template);
+            return workspace;
+        }
+        catch (error) {
+            if (source === undefined)
+                throw error;
+            if (error instanceof AgentConfigError && error.code === 'AGENT_CONFIG_SCOPE_CHANGED') {
+                await this.rollbackAgentConfig(identity, record);
+            }
+            else
+                await this.recoverOne(identity);
+            const restored = this.records.get(keyOf(identity));
+            await source.recover(restored?.templateDigest, restored?.pluginVersion, restored?.agentConfigSha256);
+            source.failedApply(template, error);
+            if (error instanceof AgentConfigError && error.code === 'AGENT_CONFIG_SCOPE_CHANGED' && !this.closed) {
+                const workspace = restored === undefined || !await this.fs.exists(this.pathOf(identity))
+                    ? undefined : await this.workspaceOf(restored);
+                return workspace ?? this.replace(this.requireTemplate(identity), restored);
+            }
+            this.ctx.logger.warn('Agent 配置应用失败，已尝试按 journal 恢复；当前版本未确认。');
+            throw error;
+        }
+    }
+    async rollbackAgentConfig(identity, previous) {
+        const current = this.records.get(keyOf(identity));
+        if (current === undefined) {
+            await this.fs.rm(this.stagingOf(identity), { recursive: true });
+            return;
+        }
+        if (current === previous && current.journal.phase === 'idle') {
+            await this.fs.rm(this.stagingOf(identity), { recursive: true });
+            return;
+        }
+        const builtin = this.requireTemplate(identity);
+        const base = previous ?? { ...current, pluginVersion: builtin.manifest.pluginVersion,
+            templateDigest: brandString('0'.repeat(64)), agentConfigSha256: null };
+        const rollback = { ...base, journal: { ...current.journal, phase: 'updating',
+                fromDigest: previous?.templateDigest ?? null, toDigest: current.templateDigest,
+                backupPath: await this.fs.exists(this.backupOf(identity)) ? this.backupOf(identity) : null,
+                stagingPath: this.stagingOf(identity), swapComplete: false } };
+        this.records.set(keyOf(identity), rollback);
+        await writeRecord(this.fs, this.recordFile(identity), rollback);
+        await this.restoreOld(identity, rollback);
+    }
+    requireTemplate(identity) {
+        const template = this.templates.get(keyOf(identity));
+        if (template === undefined) {
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', `${keyOf(identity)} is not registered`);
+        }
+        return template;
+    }
+    stagingOf(identity) {
+        return `${this.pathOf(identity)}.staging`;
+    }
+    backupOf(identity) {
+        return `${this.pathOf(identity)}.backup`;
+    }
+    recordFile(identity) {
+        return recordPath(this.spec.journalRoot, identity);
+    }
+    async loadStored(identity) {
+        const stored = await readRecord(this.fs, this.recordFile(identity));
+        if (stored !== undefined)
+            this.records.set(keyOf(identity), stored);
+        return stored;
+    }
+    async recoverOne(identity) {
+        const stored = this.records.get(keyOf(identity)) ?? await this.loadStored(identity);
+        if (stored === undefined)
+            return undefined;
+        await assertRecordPaths(this.fs, stored, this.pathOf(identity));
+        if (stored.journal.phase === 'idle')
+            return this.workspaceOf(stored);
+        return stored.journal.swapComplete ? this.finishNew(identity, stored) : this.restoreOld(identity, stored);
+    }
+    async workspaceOf(record) {
+        if (record.workspaceId === null)
+            return undefined;
+        return this.ctx.workspaceRegistry.get(record.workspaceId)
+            ?? await this.ctx.workspaceRegistry.create(record.path, undefined, originOf({
+                bundleId: record.bundleId, workspaceKey: record.workspaceKey,
+            }));
+    }
+    async restoreOld(identity, record) {
+        const root = this.pathOf(identity);
+        const backup = record.journal.backupPath ?? this.backupOf(identity);
+        const staging = record.journal.stagingPath ?? this.stagingOf(identity);
+        if (await this.fs.exists(backup)) {
+            if (await this.fs.exists(root))
+                await this.fs.rm(root, { recursive: true });
+            await this.fs.rename(backup, root);
+        }
+        else if (record.journal.fromDigest === null && await this.fs.exists(root))
+            await this.fs.rm(root, { recursive: true });
+        if (await this.fs.exists(staging))
+            await this.fs.rm(staging, { recursive: true });
+        const next = {
+            ...record,
+            journal: idleJournal(),
+            lastFailure: record.lastFailure,
+        };
+        await writeRecord(this.fs, this.recordFile(identity), next);
+        this.records.set(keyOf(identity), next);
+        return this.workspaceOf(next);
+    }
+    async finishNew(identity, record) {
+        let template = this.templates.get(keyOf(identity));
+        const root = this.pathOf(identity);
+        const toDigest = record.journal.toDigest;
+        try {
+            const source = this.agentConfigSources.get(keyOf(identity));
+            if (source !== undefined && toDigest !== null)
+                template = await source.recover(toDigest, record.journal.pluginVersion ?? undefined, record.journal.agentConfigSha256);
+            if (template !== undefined && toDigest === template.manifest.digest) {
+                await verifyTemplateTree(this.fs, root, template.manifest);
+                return this.commit(identity, record, template);
+            }
+            if (toDigest !== null && template === undefined) {
+                const cached = bundledDirectory(this.spec.templateCacheRoot, identity);
+                const manifest = await loadVerifiedManifest(this.fs, cached);
+                if (manifest.digest === toDigest) {
+                    await verifyTemplateTree(this.fs, root, manifest);
+                    const synthetic = {
+                        bundleId: identity.bundleId, workspaceKey: identity.workspaceKey, title: 'Workspace',
+                        sourceRoot: cached, manifest,
+                    };
+                    return this.commit(identity, record, synthetic);
+                }
+            }
+        }
+        catch {
+            // Fall through to restore the backup; the tree must be wholly old or wholly new.
+        }
+        return this.restoreOld(identity, record);
+    }
+    async replace(template, existing, assertApplicable) {
+        const identity = identityOf(template.bundleId, template.workspaceKey);
+        assertApplicable?.();
+        await loadVerifiedManifest(this.fs, template.sourceRoot);
+        const cache = bundledDirectory(this.spec.templateCacheRoot, identity);
+        await copyTree(this.fs, template.sourceRoot, cache, [...template.manifest.files, { path: 'manifest.json' }]);
+        const staging = this.stagingOf(identity);
+        await copyTree(this.fs, template.sourceRoot, staging, template.manifest.files);
+        assertApplicable?.();
+        this.fs.crash('after-staging');
+        const root = this.pathOf(identity);
+        const backup = this.backupOf(identity);
+        await this.prepareBackup(backup);
+        if (await this.fs.exists(backup))
+            await this.fs.rm(backup, { recursive: true });
+        const record = existing ?? {
+            version: 1,
+            bundleId: identity.bundleId,
+            workspaceKey: identity.workspaceKey,
+            workspaceId: null,
+            path: root,
+            pluginVersion: template.manifest.pluginVersion,
+            templateDigest: brandString('0'.repeat(64)),
+            registered: true,
+            journal: idleJournal(),
+            lastFailure: null,
+        };
+        const journal = {
+            phase: 'updating',
+            fromDigest: existing?.templateDigest ?? null,
+            toDigest: template.manifest.digest,
+            pluginVersion: template.manifest.pluginVersion,
+            stagingPath: staging,
+            backupPath: await this.fs.exists(root) ? backup : null,
+            swapComplete: false,
+            ...(template.agentConfigSha256 === undefined ? {} : { agentConfigSha256: template.agentConfigSha256 }),
+        };
+        const updating = await writeJournal(this.fs, this.recordFile(identity), { ...record, registered: true, path: root }, journal);
+        this.records.set(keyOf(identity), updating);
+        this.fs.crash('after-journal-updating');
+        if (updating.workspaceId !== null)
+            await this.ctx.serial('workspace-bundle/quiesce', updating.workspaceId);
+        await this.quiesce(updating.workspaceId);
+        assertApplicable?.();
+        this.fs.crash('after-quiesce');
+        await this.fs.mkdir(join(root, '..'));
+        if (await this.fs.exists(root)) {
+            if (await this.fs.exists(backup))
+                await this.fs.rm(backup, { recursive: true });
+            await this.fs.rename(root, backup);
+        }
+        this.fs.crash('after-rename-backup');
+        assertApplicable?.();
+        await this.fs.rename(staging, root);
+        const swapped = await writeJournal(this.fs, this.recordFile(identity), updating, { ...journal, swapComplete: true, stagingPath: null });
+        this.records.set(keyOf(identity), swapped);
+        this.fs.crash('after-rename-staging');
+        await verifyTemplateTree(this.fs, root, template.manifest);
+        this.fs.crash('after-verify');
+        assertApplicable?.();
+        const workspace = await this.commit(identity, swapped, template);
+        assertApplicable?.();
+        this.fs.crash('after-journal-commit');
+        this.scheduleRecycle(backup);
+        return workspace;
+    }
+    async commit(identity, record, template) {
+        const workspace = await this.ctx.workspaceRegistry.create(record.path, template.title, originOf(identity));
+        const next = committedRecord({ ...record, workspaceId: workspace.id, path: workspace.path, registered: true,
+            ...(this.agentConfigSources.has(keyOf(identity)) ? { agentConfigSha256: template.agentConfigSha256 ?? null } : {}),
+        }, template.manifest.digest, template.manifest.pluginVersion);
+        await writeRecord(this.fs, this.recordFile(identity), next);
+        this.records.set(keyOf(identity), next);
+        return workspace;
+    }
+    async quiesce(workspaceId) {
+        if (workspaceId === null)
+            return;
+        const deadline = Date.now() + this.spec.quiesceTimeoutMs;
+        while ((this.leases.get(workspaceId)?.size ?? 0) > 0) {
+            if (Date.now() >= deadline) {
+                throw new WorkspaceBundleError('WORKSPACE_BUNDLE_QUIESCE_TIMEOUT', `workspace ${workspaceId} still has active leases`);
+            }
+            await new Promise(resolve => {
+                let waiters = this.waiters.get(workspaceId);
+                if (waiters === undefined) {
+                    waiters = new Set();
+                    this.waiters.set(workspaceId, waiters);
+                }
+                const timer = setTimeout(resolve, 25);
+                const waiter = () => {
+                    clearTimeout(timer);
+                    waiters.delete(waiter);
+                    resolve();
+                };
+                waiters.add(waiter);
+            });
+        }
+    }
+    scheduleRecycle(backup) {
+        if (this.closed)
+            return;
+        const timer = setTimeout(() => {
+            this.recycle.delete(backup);
+            const work = this.fs.rm(backup, { recursive: true }).catch((error) => {
+                this.ctx.logger.warn('旧 Workspace 备份清理失败，请检查磁盘；当前版本保持可用。');
+            }).finally(() => { this.recycleWork.delete(backup); });
+            this.recycleWork.set(backup, work);
+        }, this.spec.recycleTimeoutMs);
+        this.recycle.set(backup, timer);
+    }
+    async prepareBackup(backup) {
+        const timer = this.recycle.get(backup);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        this.recycle.delete(backup);
+        await this.recycleWork.get(backup);
+    }
+}
+export default GestaltWorkspaceBundles;

package/lib/types/session-events.d.ts

@@ -0,0 +1,23 @@
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { WorkspaceAgentConfigVersion } from './agent-config-types.ts';
+/** 一个 turn 使用的 Agent 配置版本；不含商家身份、地址或凭据。 */
+export interface WorkspaceAgentConfigVersionEvent {
+    readonly workspaceKind: string;
+    readonly version: string;
+    readonly previousVersion: string | null;
+    readonly templateDigest: string;
+    readonly agentConfigSha256: string | null;
+    readonly hostAgentConfigApiVersion: string;
+}
+/**
+ * 在每个 Session 首次使用一个不同 Agent 配置版本的 turn 写入身份，重复 step 不重复记录。
+ * @param session - 即将请求模型的 Session。
+ * @param current - 当前租约固定的完整版本。
+ */
+export declare function recordWorkspaceAgentConfigVersion(session: Session, current: WorkspaceAgentConfigVersion): void;
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /** Session 开始使用一个不同的内置 Workspace Agent 配置版本；旧 reader 必须拒绝未知的必读事件。 */
+        'workspace-bundle/agent-config-version': WorkspaceAgentConfigVersionEvent;
+    }
+}

package/lib/types/session-events.js

@@ -0,0 +1,14 @@
+/**
+ * 在每个 Session 首次使用一个不同 Agent 配置版本的 turn 写入身份，重复 step 不重复记录。
+ * @param session - 即将请求模型的 Session。
+ * @param current - 当前租约固定的完整版本。
+ */
+export function recordWorkspaceAgentConfigVersion(session, current) {
+    const previous = session.snapshotEvents().findLast(event => event.type === 'workspace-bundle/agent-config-version');
+    if (previous?.type === 'workspace-bundle/agent-config-version' && previous.data.version === current.version
+        && previous.data.agentConfigSha256 === current.sha256 && previous.data.templateDigest === current.templateDigest)
+        return;
+    session.append('workspace-bundle/agent-config-version', { workspaceKind: current.workspaceKind,
+        version: current.version, previousVersion: previous?.type === 'workspace-bundle/agent-config-version' ? previous.data.version : null,
+        templateDigest: current.templateDigest, agentConfigSha256: current.sha256, hostAgentConfigApiVersion: current.hostAgentConfigApiVersion });
+}

package/lib/types/types.d.ts

@@ -0,0 +1,123 @@
+/** Client-safe types of the WorkspaceBundles seam; importing them loads no Host code. */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+import type { WorkspaceBundleId, WorkspaceBundleKey, WorkspaceId, WorkspaceOrigin } from '@deepseek-ai/dsh-workspace/types';
+export type { WorkspaceBundleId, WorkspaceBundleKey, WorkspaceId, WorkspaceOrigin };
+/** SHA-256 hex digest of one template file. */
+export type WorkspaceTemplateFileDigest = Branded<'WorkspaceTemplateFileDigest'>;
+/** SHA-256 hex digest of the ordered path+file-digest catalog. */
+export type WorkspaceTemplateDigest = Branded<'WorkspaceTemplateDigest'>;
+/** One file listed in a template manifest. */
+export interface WorkspaceTemplateFile {
+    readonly path: string;
+    readonly bytes: number;
+    readonly digest: WorkspaceTemplateFileDigest;
+}
+/** Repository and commit of the packaged customer-service instruction files. */
+export interface WorkspaceTemplateSource {
+    readonly repository: string;
+    readonly commit: string;
+}
+/** Verified catalog of a packaged Workspace template. */
+export interface WorkspaceTemplateManifest {
+    readonly formatVersion: 1;
+    readonly pluginVersion: string;
+    readonly source?: WorkspaceTemplateSource;
+    readonly files: readonly WorkspaceTemplateFile[];
+    readonly digest: WorkspaceTemplateDigest;
+}
+/** A registered template the Host can materialize. */
+export interface WorkspaceTemplate {
+    readonly bundleId: WorkspaceBundleId;
+    readonly workspaceKey: WorkspaceBundleKey;
+    readonly title: string;
+    readonly sourceRoot: string;
+    readonly manifest: WorkspaceTemplateManifest;
+    /** 已下载包的整体摘要；内置模板不携带此字段。 */
+    readonly agentConfigSha256?: string;
+}
+/** Deployment settings the Provider resolves once at load. */
+export interface WorkspaceBundlesSpec {
+    /** Parent of each `{bundleId}/{workspaceKey}` Workspace root. */
+    readonly materializeRoot: string;
+    /** Parent of the immutable template copies used when the package source is gone. */
+    readonly templateCacheRoot: string;
+    /** Parent of per-Workspace journal files. */
+    readonly journalRoot: string;
+    /** How long upgrade waits for acquired leases to drain, in milliseconds. */
+    readonly quiesceTimeoutMs: number;
+    /** How long a successful upgrade waits before deleting the backup, in milliseconds. */
+    readonly recycleTimeoutMs: number;
+    /** 内容分配查询间隔，单位毫秒。 */
+    readonly agentConfigPollIntervalMs: number;
+    /** 每次查询和下载共享的超时，单位毫秒。 */
+    readonly agentConfigRequestTimeoutMs: number;
+    /** 压缩Agent 配置字节上限。 */
+    readonly agentConfigMaxDownloadBytes: number;
+    /** 解压 JSON 和文件总字节上限。 */
+    readonly agentConfigMaxExpandedBytes: number;
+    /** 仅允许显式配置的本地测试文件服务使用 HTTP。 */
+    readonly allowLoopbackAgentConfigHttp: boolean;
+}
+/** Named configuration failure. */
+export type WorkspaceBundlesConfigErrorCode = 'WORKSPACE_BUNDLES_MATERIALIZE_ROOT_MISSING' | 'WORKSPACE_BUNDLES_TEMPLATE_CACHE_ROOT_MISSING' | 'WORKSPACE_BUNDLES_JOURNAL_ROOT_MISSING' | 'WORKSPACE_BUNDLES_PATH_INVALID' | 'WORKSPACE_BUNDLES_TIMEOUT_INVALID';
+/** Named runtime failure of template access, materialize, or upgrade. */
+export type WorkspaceBundleErrorCode = 'WORKSPACE_BUNDLE_NOT_REGISTERED' | 'WORKSPACE_BUNDLE_TEMPLATE_INVALID' | 'WORKSPACE_BUNDLE_PATH_TRAVERSAL' | 'WORKSPACE_BUNDLE_SYMLINK_REJECTED' | 'WORKSPACE_BUNDLE_MISSING_ASSET' | 'WORKSPACE_BUNDLE_DIGEST_MISMATCH' | 'WORKSPACE_BUNDLE_QUIESCE_TIMEOUT' | 'WORKSPACE_BUNDLE_CRASH_INJECTED' | 'WORKSPACE_BUNDLE_IDENTITY_INVALID';
+/** Observable upgrade barrier: consumers must not read a half-replaced tree. */
+export type WorkspaceBundleBarrier = 'open' | 'updating';
+/** Durable upgrade journal. `updating` means consumers are barred. */
+export interface WorkspaceBundleJournal {
+    readonly phase: 'idle' | 'updating';
+    readonly fromDigest: WorkspaceTemplateDigest | null;
+    readonly toDigest: WorkspaceTemplateDigest | null;
+    readonly pluginVersion: string | null;
+    readonly stagingPath: string | null;
+    readonly backupPath: string | null;
+    readonly swapComplete: boolean;
+    /** 新Agent 配置身份；旧 journal 没有此字段。 */
+    readonly agentConfigSha256?: string | null;
+}
+/** Durable product record for one bundled Workspace. */
+export interface WorkspaceBundleRecord {
+    readonly version: 1;
+    readonly bundleId: WorkspaceBundleId;
+    readonly workspaceKey: WorkspaceBundleKey;
+    readonly workspaceId: WorkspaceId | null;
+    readonly path: string;
+    readonly pluginVersion: string;
+    readonly templateDigest: WorkspaceTemplateDigest;
+    /** 已提交Agent 配置身份；旧 record 缺失时表示内置模板。 */
+    readonly agentConfigSha256?: string | null;
+    readonly registered: boolean;
+    readonly journal: WorkspaceBundleJournal;
+    readonly lastFailure: {
+        readonly code: WorkspaceBundleErrorCode;
+        readonly message: string;
+        readonly at: string;
+    } | null;
+}
+/** Points where tests inject a crash; production never sets them. */
+export type WorkspaceBundleCrashPoint = 'after-staging' | 'after-journal-updating' | 'after-quiesce' | 'after-rename-backup' | 'after-rename-staging' | 'after-verify' | 'after-journal-commit';
+/** Filesystem operations the materializer uses so tests can inject crashes. */
+export interface WorkspaceBundleFs {
+    mkdir(path: string): Promise<void>;
+    writeFile(path: string, data: Uint8Array | string): Promise<void>;
+    readFile(path: string): Promise<Buffer>;
+    rename(from: string, to: string): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    lstat(path: string): Promise<{
+        isFile(): boolean;
+        isDirectory(): boolean;
+        isSymbolicLink(): boolean;
+    }>;
+    readdir(path: string): Promise<readonly string[]>;
+    realpath(path: string): Promise<string>;
+    copyFile(from: string, to: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+}
+/** Identity of one bundled Workspace. */
+export interface WorkspaceBundleIdentity {
+    readonly bundleId: WorkspaceBundleId;
+    readonly workspaceKey: WorkspaceBundleKey;
+}

package/lib/types/types.js

@@ -0,0 +1 @@
+export {};

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Workspace templates",
+    "description": "Register, materialize, and wholly replace packaged Workspace templates"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "工作区模板",
+    "description": "内置工作区模板的注册、物化与整体升级"
+  }
+}