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

package/lib/types/provider.js

@@ -0,0 +1,560 @@
+/**
+ * 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 { journalAgentConfigSha256 } from "./bundled-agent-config.js";
+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, HOST_AGENT_CONFIG_API_VERSION } 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();
+    contentDrains = new Set();
+    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 = {}) {
+        const spec = resolveWorkspaceBundlesSpec(config);
+        super(ctx, join(spec.journalRoot, 'local-host-replacement.json'), join(spec.journalRoot, 'local-host-identity.json'));
+        this.spec = spec;
+        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.contentDrains);
+            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.enqueue(async () => {
+            if (this.closed || this.agentConfigSources.get(key) !== owner)
+                return;
+            const state = owner.state();
+            const record = this.records.get(key);
+            if (!state.blocked || state.pending === null || record?.workspaceId != null && (this.leases.get(record.workspaceId)?.size ?? 0) > 0)
+                return;
+            await this.ensureOne(source.identity);
+        }));
+        this.agentConfigSources.set(key, owner);
+        owner.start(() => this.enqueue(async () => {
+            await this.recoverOne(source.identity);
+            const record = this.records.get(key);
+            try {
+                await owner.recover(record?.templateDigest, record?.pluginVersion, record?.agentConfigSha256);
+            }
+            catch (error) {
+                // A refused committed version remains reportable, but cannot grant execution.
+                if (!(error instanceof AgentConfigError))
+                    throw error;
+            }
+        }));
+        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));
+    }
+    /** @inheritdoc */
+    acquireAgentConfig(identity) {
+        if (this.closed)
+            return Promise.reject(new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', 'Workspace content service is stopped'));
+        identityOf(identity.bundleId, identity.workspaceKey);
+        return this.enqueue(async () => {
+            if (this.closed)
+                throw new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', 'Workspace content service is stopped');
+            const registered = this.requireTemplate(identity);
+            const source = this.agentConfigSources.get(keyOf(identity));
+            const revision = source?.registration.source.revision();
+            const workspace = await this.ensureOne(identity);
+            const record = this.records.get(keyOf(identity));
+            const template = source === undefined ? this.requireTemplate(identity)
+                : await source.recover(record.templateDigest, record.pluginVersion, record.agentConfigSha256);
+            await verifyTemplateTree(this.fs, template.sourceRoot, template.manifest);
+            if (this.closed)
+                throw new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', 'Workspace content service is stopped');
+            if (this.requireTemplate(identity) !== registered || this.agentConfigSources.get(keyOf(identity)) !== source
+                || source?.registration.source.revision() !== revision) {
+                throw new AgentConfigError('AGENT_CONFIG_SCOPE_CHANGED');
+            }
+            if (template.manifest.digest !== record.templateDigest || template.manifest.pluginVersion !== record.pluginVersion) {
+                throw new AgentConfigError('AGENT_CONFIG_INVALID');
+            }
+            const version = { workspaceKind: identity.bundleId, workspaceId: workspace.id, version: record.pluginVersion,
+                sha256: template.agentConfigSha256 ?? null, hostAgentConfigApiVersion: HOST_AGENT_CONFIG_API_VERSION,
+                templateDigest: record.templateDigest, sourceRoot: template.sourceRoot };
+            return this.contentHandle(version, this.holdLease(workspace.id));
+        });
+    }
+    contentHandle(version, release) {
+        let references = 0;
+        const drained = Promise.withResolvers();
+        this.contentDrains.add(drained.promise);
+        const retain = () => {
+            references++;
+            let released = false;
+            return Object.freeze({ ...version,
+                retain: () => {
+                    if (released || this.closed)
+                        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_NOT_REGISTERED', 'The content activity is closed');
+                    return retain();
+                },
+                release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    if (--references === 0) {
+                        release();
+                        this.contentDrains.delete(drained.promise);
+                        drained.resolve();
+                    }
+                },
+            });
+        };
+        return retain();
+    }
+    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);
+        }
+        this.agentConfigSources.get(keyOf(record))?.assertExecutionAllowed();
+        return this.holdLease(workspaceId);
+    }
+    holdLease(workspaceId) {
+        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.
+     * @throws {AgentConfigError} After physical recovery when committed content fails compatibility or consumer validation.
+     */
+    async recover(identity) {
+        return this.enqueue(async () => {
+            const workspace = await this.recoverOne(identity);
+            const record = this.records.get(keyOf(identity));
+            await this.agentConfigSources.get(keyOf(identity))?.recover(record?.templateDigest, record?.pluginVersion, record?.agentConfigSha256);
+            return workspace;
+        });
+    }
+    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 recovered = await this.recoverOne(identity);
+        const record = this.records.get(keyOf(identity));
+        if (source !== undefined) {
+            try {
+                template = await source.recover(record?.templateDigest, record?.pluginVersion, record?.agentConfigSha256);
+            }
+            catch (error) {
+                // An unusable committed tree stays on disk; only a validated candidate may replace it.
+                if (!(error instanceof AgentConfigError) || record?.workspaceId !== null && record?.workspaceId !== undefined
+                    && (this.leases.get(record.workspaceId)?.size ?? 0) > 0)
+                    throw error;
+                template = source.template();
+            }
+        }
+        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) === journalAgentConfigSha256(template, this.requireTemplate(identity)) && record.journal.phase === 'idle') {
+            return recovered;
+        }
+        try {
+            await source?.prepare(template);
+            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.recoverPhysical(toDigest, record.journal.pluginVersion ?? undefined, record.journal.agentConfigSha256);
+            if (template !== undefined && toDigest === template.manifest.digest) {
+                await verifyTemplateTree(this.fs, root, template.manifest);
+                return await 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 await this.commit(identity, record, synthetic);
+                }
+            }
+        }
+        catch (error) {
+            // 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,
+            agentConfigSha256: journalAgentConfigSha256(template, this.requireTemplate(identity)),
+        };
+        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,
+            agentConfigSha256: journalAgentConfigSha256(template, this.templates.get(keyOf(identity))),
+        }, 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 });
+}