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

package/lib/types/agent-config-source.js

@@ -0,0 +1,411 @@
+/** 内容来源的有界拉取和只读版本缓存；此模块不替换运行中的 Workspace。 */
+import { chmod, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { brandString } from '@deepseek-ai/dsh-brand';
+import { z } from 'zod';
+import semver from 'semver';
+import { WorkspaceBundleError } from "./errors.js";
+import { AgentConfigDescriptorSchema, AgentConfigError, HOST_AGENT_CONFIG_API_VERSION, decodeAgentConfig } from "./agent-config-format.js";
+import { loadVerifiedManifest, overallDigest } from "./digest.js";
+import { createNodeFs } from "./filesystem.js";
+import { bundledDirectory } from "./paths.js";
+import { journalAgentConfigSha256 } from "./bundled-agent-config.js";
+const AssignmentSchema = z.discriminatedUnion('source', [
+    z.object({ source: z.literal('builtin'), workspaceKind: z.string() }),
+    z.object({ source: z.literal('registry'), workspaceKind: z.string(), agentConfig: AgentConfigDescriptorSchema }),
+]);
+const ReceiptSchema = AgentConfigDescriptorSchema.omit({ downloadUrl: true, releaseNotes: true });
+function publicVersion(template, sha256) {
+    return { workspaceKind: template.bundleId, version: template.manifest.pluginVersion, sha256,
+        hostAgentConfigApiVersion: HOST_AGENT_CONFIG_API_VERSION, templateDigest: template.manifest.digest, sourceRoot: template.sourceRoot };
+}
+async function freezeTree(root) {
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        const path = join(root, entry.name);
+        if (entry.isDirectory())
+            await freezeTree(path);
+        else
+            await chmod(path, 0o444);
+    }
+    await chmod(root, 0o555);
+}
+/** 一个注册来源的缓存、轮询和候选版本；卸载必须等待所有网络与文件工作结束。 */
+export class WorkspaceAgentConfigSourceOwner {
+    registration;
+    spec;
+    report;
+    download;
+    recoverIdle;
+    lifetime = new AbortController();
+    inFlight;
+    requestAbort;
+    requestRevision;
+    preparedRevisions = new WeakMap();
+    timer;
+    selected;
+    candidate;
+    failure = null;
+    rejection;
+    admissionFailure;
+    root;
+    observation;
+    startup = Promise.resolve();
+    blockedVersion;
+    /** @param registration - 内置模板及鉴权查询回调。 @param spec - 部署预算。 @param report - 固定失败诊断的报告者。 @param download - 文件 HTTP 传输。 @param recoverIdle - Provider 串行检查活动租约后恢复已阻断的配置；省略时保留候选等待获取工作区。 */
+    constructor(registration, spec, report, download = fetch, recoverIdle = async () => { }) {
+        this.registration = registration;
+        this.spec = spec;
+        this.report = report;
+        this.download = download;
+        this.recoverIdle = recoverIdle;
+        this.selected = { template: registration.template, sha256: registration.template.agentConfigSha256 ?? null };
+        this.root = bundledDirectory(join(spec.templateCacheRoot, 'agent-config-versions'), registration.source.identity);
+    }
+    /** @returns 已应用/候选版本、执行阻断及当前作用域的最近失败和拒绝。 */
+    state() {
+        if (this.candidate !== undefined && this.candidate.revision !== this.registration.source.revision())
+            this.candidate = undefined;
+        if (this.lifetime.signal.aborted || this.rejection?.revision !== this.registration.source.revision())
+            this.rejection = undefined;
+        return { lastRejection: this.rejection?.value ?? null, blocked: this.admissionFailure !== undefined,
+            blockingFailure: this.admissionFailure === undefined ? null : { code: this.admissionFailure.code }, current: this.blockedVersion ?? publicVersion(this.selected.template, this.selected.sha256),
+            pending: this.candidate === undefined ? null : publicVersion(this.candidate.template, this.candidate.sha256),
+            failure: this.admissionFailure === undefined ? this.failure : { code: this.admissionFailure.code, message: this.admissionFailure.message } };
+    }
+    /**
+     * 从 journal 已提交的摘要定位只读缓存，不从 server 的无分配回答推导降级。
+     * @param digest - 已提交 Workspace 模板摘要；undefined 表示首次使用。
+     * @param version - 已提交完整版本，包括构建元数据。
+     * @param sha256 - 已提交包摘要；undefined 支持旧内置记录。
+     * @returns 对应完整模板；缺失已安装缓存时拒绝继续。
+     */
+    async recover(digest, version, sha256) {
+        const revision = this.registration.source.revision();
+        try {
+            const template = await this.recoverExecution(digest, version, sha256);
+            if (this.rejection?.revision === revision && this.rejection.value.version === template.manifest.pluginVersion)
+                this.rejection = undefined;
+            return template;
+        }
+        catch (error) {
+            if (digest !== undefined && version !== undefined)
+                this.blockedVersion = {
+                    ...publicVersion(this.registration.template, sha256 ?? null), version, templateDigest: digest,
+                };
+            const failure = new AgentConfigError(this.configError(error).code, 'blocked');
+            const previous = this.admissionFailure;
+            this.admissionFailure = failure;
+            this.rememberRejection(failure, version, revision, sha256 ?? undefined);
+            if (previous?.code !== failure.code)
+                this.reportFailure(failure);
+            throw failure;
+        }
+    }
+    async recoverExecution(digest, version, sha256) {
+        const restored = await this.restoredTemplate(digest, version, sha256);
+        this.assertCompatible(restored.range, restored.runtimeApiRange);
+        await this.registration.source.validate?.(restored.template, this.lifetime.signal);
+        this.selected = { template: restored.template, sha256: restored.template.agentConfigSha256 ?? null };
+        this.blockedVersion = undefined;
+        this.admissionFailure = undefined;
+        if (this.candidate?.sha256 === this.selected.sha256)
+            this.candidate = undefined;
+        return restored.template;
+    }
+    /**
+     * Load a complete old/new tree only for physical swap recovery; this grants no execution permission.
+     * @param digest - Journal template digest.
+     * @param version - Journal release version, when recorded.
+     * @param sha256 - Journal package digest, absent for builtin.
+     * @returns Physically verified template; consumers must subsequently call recover for execution validation.
+     */
+    async recoverPhysical(digest, version, sha256) {
+        return (await this.restoredTemplate(digest, version, sha256)).template;
+    }
+    async restoredTemplate(digest, version, sha256) {
+        if (digest === undefined || sha256 === undefined || sha256 === null) {
+            const template = this.registration.template;
+            return { template, range: template.agentConfigReceipt?.hostAgentConfigApiRange,
+                ...(template.agentConfigReceipt?.runtimeApiRange === undefined ? {} : { runtimeApiRange: template.agentConfigReceipt.runtimeApiRange }) };
+        }
+        if (!/^[0-9a-f]{64}$/u.test(sha256))
+            throw new AgentConfigError('AGENT_CONFIG_INVALID');
+        const fs = createNodeFs();
+        const receipt = ReceiptSchema.parse(JSON.parse(await readFile(join(this.root, sha256, 'receipt.json'), 'utf8')));
+        const directory = this.versionDirectory(receipt.version, receipt.sha256);
+        if (receipt.sha256 !== sha256 || receipt.workspaceKind !== this.registration.template.bundleId
+            || (await fs.lstat(directory)).isSymbolicLink() || (await fs.lstat(join(directory, receipt.version))).isSymbolicLink())
+            throw new AgentConfigError('AGENT_CONFIG_INVALID');
+        const manifest = await loadVerifiedManifest(fs, join(directory, receipt.version));
+        if (manifest.digest !== digest || version !== undefined && receipt.version !== version
+            || manifest.pluginVersion !== receipt.version)
+            throw new AgentConfigError('AGENT_CONFIG_INVALID');
+        const { bundleId, workspaceKey, title } = this.registration.template;
+        return { template: { bundleId, workspaceKey, title, sourceRoot: join(directory, receipt.version), manifest,
+                agentConfigSha256: receipt.sha256 }, range: receipt.hostAgentConfigApiRange,
+            ...(receipt.runtimeApiRange === undefined ? {} : { runtimeApiRange: receipt.runtimeApiRange }) };
+    }
+    assertCompatible(range, runtimeApiRange) {
+        if (range !== undefined && !semver.satisfies(HOST_AGENT_CONFIG_API_VERSION, range, { includePrerelease: true }))
+            throw new AgentConfigError('AGENT_CONFIG_INCOMPATIBLE');
+        const runtime = this.registration.source.runtimeApiVersion;
+        if (runtimeApiRange !== undefined && (runtime === undefined || !semver.satisfies(runtime, runtimeApiRange, { includePrerelease: true })))
+            throw new AgentConfigError('AGENT_CONFIG_INCOMPATIBLE');
+    }
+    configError(error) {
+        return error instanceof AgentConfigError ? error : new AgentConfigError(error instanceof WorkspaceBundleError
+            && error.code === 'WORKSPACE_BUNDLE_DIGEST_MISMATCH' ? 'AGENT_CONFIG_DIGEST_MISMATCH' : 'AGENT_CONFIG_INVALID');
+    }
+    reportFailure(error) {
+        try {
+            this.report(error);
+        }
+        catch (reportError) {
+            // stderr remains available if the Cordis reporter has already been released.
+            process.stderr.write(`${error.code}: ${error.message}\n`);
+        }
+    }
+    /** @param restore - Restore this identity's committed journal before starting reports or queries; omission is for an owner without a journal. */
+    start(restore = async () => { }) {
+        this.startup = restore().then(() => {
+            if (!this.lifetime.signal.aborted)
+                this.observation = this.registration.source.observation?.(() => this.state());
+        });
+        const tick = async () => {
+            try {
+                await this.refresh();
+            }
+            catch (error) {
+                this.reportFailure(this.configError(error));
+            }
+            if (!this.lifetime.signal.aborted)
+                this.timer = setTimeout(() => { void tick(); }, this.spec.agentConfigPollIntervalMs);
+        };
+        void tick();
+    }
+    /** @returns 本次查询和完整候选下载结束；失败通过 state 与 report 保留可观察诊断。 */
+    refresh() {
+        return this.startup.then(() => this.refreshReady());
+    }
+    refreshReady() {
+        if (this.lifetime.signal.aborted)
+            return Promise.resolve();
+        const revision = this.registration.source.revision();
+        if (this.candidate !== undefined && this.candidate.revision !== revision)
+            this.candidate = undefined;
+        if (this.inFlight !== undefined) {
+            if (revision === this.requestRevision && !this.requestAbort?.signal.aborted)
+                return this.inFlight;
+            this.requestAbort?.abort();
+            this.failure = null;
+            return this.inFlight.then(() => this.refresh());
+        }
+        const abort = new AbortController();
+        this.requestAbort = abort;
+        this.requestRevision = revision;
+        const attempt = {};
+        const run = this.fetchCandidate(revision, abort.signal, attempt).then(async () => {
+            if (this.lifetime.signal.aborted || abort.signal.aborted || revision !== this.registration.source.revision())
+                return;
+            if (this.admissionFailure !== undefined && this.candidate !== undefined)
+                await this.recoverIdle();
+            if (!this.lifetime.signal.aborted)
+                await this.observation?.refresh();
+        }).catch((error) => {
+            if (this.lifetime.signal.aborted || abort.signal.aborted || revision !== this.registration.source.revision())
+                return;
+            this.candidate = undefined;
+            const failure = this.configError(error);
+            this.failure = { code: failure.code, message: failure.message };
+            this.rememberRejection(failure, attempt.version, revision, attempt.sha256);
+            this.reportFailure(failure);
+        }).finally(() => { this.inFlight = undefined; this.requestAbort = undefined; this.requestRevision = undefined; });
+        this.inFlight = run;
+        return run;
+    }
+    /** @returns 下一个 turn 可应用的候选；没有候选时使用已安装版本。 */
+    template() {
+        if (this.candidate !== undefined && this.candidate.revision !== this.registration.source.revision())
+            this.candidate = undefined;
+        if (this.candidate === undefined && this.admissionFailure !== undefined)
+            throw this.admissionFailure;
+        return this.candidate?.template ?? this.selected.template;
+    }
+    /** @throws AgentConfigError while committed content is blocked, including when another lease remains active. */
+    assertExecutionAllowed() {
+        if (this.admissionFailure !== undefined)
+            throw this.admissionFailure;
+    }
+    /** @param template - Pending template. @returns After compatibility and consumer validation, without selecting it. */
+    async prepare(template) {
+        try {
+            await this.prepareValidated(template);
+        }
+        catch (error) {
+            throw this.configError(error);
+        }
+    }
+    async prepareValidated(template) {
+        this.assertApplicable(template);
+        const restored = await this.restoredTemplate(template.manifest.digest, template.manifest.pluginVersion, journalAgentConfigSha256(template, this.registration.template));
+        this.assertCompatible(restored.range, restored.runtimeApiRange);
+        await this.registration.source.validate?.(restored.template, this.lifetime.signal);
+        this.assertApplicable(template);
+    }
+    /** @param template - 即将整体替换的候选。 @throws 来源代次已经改变或已撤销时拒绝应用。 */
+    assertApplicable(template) {
+        const revision = this.preparedRevisions.get(template);
+        if (this.lifetime.signal.aborted || revision !== undefined && revision !== this.registration.source.revision())
+            throw new AgentConfigError('AGENT_CONFIG_SCOPE_CHANGED');
+    }
+    /** @param template - 已通过 Workspace 整体替换提交的模板。 */
+    async committed(template) {
+        await this.recover(template.manifest.digest, template.manifest.pluginVersion, journalAgentConfigSha256(template, this.registration.template));
+    }
+    /**
+     * 清除未提交候选，报告整体替换失败；已提交状态由 journal 恢复结果决定。
+     * @param template - 未能完成提交的模板。
+     * @param cause - 保留来源失效分类；其他原因报告固定应用失败诊断。
+     */
+    failedApply(template, cause) {
+        if (this.candidate?.template === template)
+            this.candidate = undefined;
+        const error = cause instanceof AgentConfigError ? cause : new AgentConfigError('AGENT_CONFIG_APPLY_FAILED');
+        this.failure = { code: error.code, message: error.message };
+        const revision = this.preparedRevisions.get(template) ?? this.registration.source.revision();
+        this.rememberRejection(error, template.manifest.pluginVersion, revision, template.agentConfigSha256);
+        this.reportFailure(error);
+    }
+    /** 撤销查询、清除后续定时器，并等待下载和目录写入完成。 */
+    async dispose() {
+        this.lifetime.abort();
+        this.rejection = undefined;
+        this.candidate = undefined;
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        await Promise.all([this.startup, this.inFlight, this.observation?.dispose()]);
+        this.candidate = undefined;
+    }
+    versionDirectory(version, sha256) {
+        if (!AgentConfigDescriptorSchema.shape.version.safeParse(version).success
+            || !/^[0-9a-f]{64}$/u.test(sha256))
+            throw new AgentConfigError('AGENT_CONFIG_INVALID');
+        return join(this.root, sha256);
+    }
+    rememberRejection(error, version, revision, sha256) {
+        if (this.lifetime.signal.aborted || revision !== this.registration.source.revision())
+            return;
+        if (error.code === 'AGENT_CONFIG_SCOPE_CHANGED') {
+            this.rejection = undefined;
+            return;
+        }
+        if (error.code === 'AGENT_CONFIG_QUERY_FAILED')
+            return;
+        this.rejection = { revision, value: { code: error.code, ...(version === undefined ? {} : { version }), ...(sha256 === undefined ? {} : { sha256 }) } };
+    }
+    async fetchCandidate(revision, requestSignal, attempt) {
+        const signal = AbortSignal.any([this.lifetime.signal, requestSignal, AbortSignal.timeout(this.spec.agentConfigRequestTimeoutMs)]);
+        let value;
+        try {
+            value = await this.registration.source.query(signal);
+        }
+        catch (error) {
+            throw error instanceof AgentConfigError ? error : new AgentConfigError('AGENT_CONFIG_QUERY_FAILED');
+        }
+        const assignment = AssignmentSchema.safeParse(value);
+        if (!assignment.success || assignment.data.workspaceKind !== this.registration.template.bundleId)
+            throw new AgentConfigError('AGENT_CONFIG_INVALID');
+        if (assignment.data.source === 'builtin') {
+            this.candidate = undefined;
+            this.failure = null;
+            this.rejection = undefined;
+            return;
+        }
+        const descriptor = assignment.data.agentConfig;
+        attempt.version = descriptor.version;
+        attempt.sha256 = descriptor.sha256;
+        if (this.rejection?.value.version !== descriptor.version || this.rejection?.value.sha256 !== descriptor.sha256)
+            this.rejection = undefined;
+        if (descriptor.workspaceKind !== assignment.data.workspaceKind)
+            throw new AgentConfigError('AGENT_CONFIG_INVALID');
+        this.assertCompatible(descriptor.hostAgentConfigApiRange, descriptor.runtimeApiRange);
+        // Blocked journal content remains current even when the registered template has a newer digest.
+        if (descriptor.sha256 === (this.blockedVersion?.sha256 ?? this.selected.sha256)) {
+            this.candidate = undefined;
+            this.failure = null;
+            this.rejection = undefined;
+            return;
+        }
+        if (descriptor.sizeBytes > this.spec.agentConfigMaxDownloadBytes)
+            throw new AgentConfigError('AGENT_CONFIG_INVALID');
+        const url = new URL(descriptor.downloadUrl);
+        if (url.username !== '' || url.password !== '' || url.protocol !== 'https:'
+            && !(this.spec.allowLoopbackAgentConfigHttp && url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))
+            throw new AgentConfigError('AGENT_CONFIG_INVALID');
+        let bytes;
+        try {
+            const response = await this.download(url, { signal, redirect: 'error' });
+            if (!response.ok || response.body === null || response.headers.get('content-length') !== null
+                && Number(response.headers.get('content-length')) !== descriptor.sizeBytes)
+                throw new AgentConfigError('AGENT_CONFIG_DOWNLOAD_FAILED');
+            const chunks = [];
+            let count = 0;
+            for await (const chunk of response.body) {
+                count += chunk.byteLength;
+                if (count > descriptor.sizeBytes) {
+                    await response.body.cancel().catch(() => undefined);
+                    throw new AgentConfigError('AGENT_CONFIG_DOWNLOAD_FAILED');
+                }
+                chunks.push(chunk);
+            }
+            bytes = Buffer.concat(chunks);
+        }
+        catch (error) {
+            throw new AgentConfigError('AGENT_CONFIG_DOWNLOAD_FAILED');
+        }
+        const content = decodeAgentConfig(bytes, descriptor, this.spec.agentConfigMaxExpandedBytes);
+        if (signal.aborted || revision !== this.registration.source.revision())
+            return;
+        await mkdir(this.root, { recursive: true });
+        const directory = this.versionDirectory(descriptor.version, descriptor.sha256);
+        const tree = join(directory, descriptor.version);
+        const fs = createNodeFs();
+        if (!await fs.exists(directory)) {
+            const staging = await mkdtemp(join(this.root, '.staging-'));
+            try {
+                const stagingTree = join(staging, descriptor.version);
+                await mkdir(stagingTree);
+                for (const file of content.files) {
+                    const path = join(stagingTree, ...file.path.split('/'));
+                    await mkdir(dirname(path), { recursive: true });
+                    await writeFile(path, file.bytes, { flag: 'wx' });
+                }
+                const files = content.manifest.files.map(file => ({ path: file.path, bytes: file.sizeBytes, digest: brandString(file.sha256) }));
+                await writeFile(join(stagingTree, 'manifest.json'), JSON.stringify({ formatVersion: 1, pluginVersion: descriptor.version, files, digest: overallDigest(files) }) + '\n');
+                const { downloadUrl: _downloadUrl, releaseNotes: _releaseNotes, ...receipt } = descriptor;
+                await writeFile(join(staging, 'receipt.json'), JSON.stringify(ReceiptSchema.parse(receipt)) + '\n');
+                await rename(staging, directory);
+                await freezeTree(tree);
+                await chmod(join(directory, 'receipt.json'), 0o444);
+            }
+            finally {
+                await rm(staging, { recursive: true, force: true });
+            }
+        }
+        const manifest = await loadVerifiedManifest(fs, tree);
+        const files = content.manifest.files.map(file => ({ path: file.path, bytes: file.sizeBytes, digest: brandString(file.sha256) }));
+        if (manifest.pluginVersion !== descriptor.version || manifest.digest !== overallDigest(files))
+            throw new AgentConfigError('AGENT_CONFIG_DIGEST_MISMATCH');
+        if (signal.aborted || revision !== this.registration.source.revision())
+            return;
+        const { bundleId, workspaceKey, title } = this.registration.template;
+        const template = { bundleId, workspaceKey, title, sourceRoot: tree, manifest, agentConfigSha256: descriptor.sha256 };
+        await this.registration.source.validate?.(template, signal);
+        if (signal.aborted || revision !== this.registration.source.revision())
+            return;
+        this.preparedRevisions.set(template, revision);
+        this.candidate = { template, sha256: descriptor.sha256, revision };
+        this.failure = null;
+        this.rejection = undefined;
+    }
+}

package/lib/types/agent-config-types.d.ts

@@ -0,0 +1,67 @@
+/** Workspace Agent 配置版本来源和 turn 记录的 Host 接口。 */
+import type { WorkspaceBundleIdentity, WorkspaceTemplate } from './types.ts';
+import type { AgentConfigErrorCode } from './agent-config-format.ts';
+import type { WorkspaceAgentConfigObservation } from './agent-config-observation.ts';
+import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types';
+/** 调用方负责通过自身鉴权能力查询 server，不向此服务交出凭据。 */
+export interface WorkspaceAgentConfigSource {
+    readonly identity: WorkspaceBundleIdentity;
+    /** Fixed consumer runtime API, when this module accepts descriptors with runtime requirements. */
+    readonly runtimeApiVersion?: string;
+    /** Optional authenticated module reporter; its lifetime is owned by this source registration. */
+    readonly observation?: (read: () => WorkspaceAgentConfigState) => WorkspaceAgentConfigObservation;
+    /** @returns 随登录、租户或其他分配身份改变的进程内代次。 */
+    revision(): number;
+    /** @param signal - 源卸载或请求超时取消。 @returns #86 的 builtin / registry 分配。 */
+    query(signal: AbortSignal): Promise<unknown>;
+    /**
+     * Consumer validation before candidate publication, adoption and restored execution; omission keeps generic archive checks.
+     * @param template - Verified template within this source's controlled tree.
+     * @param signal - Source disposal or request deadline.
+     * @throws AgentConfigError for invalid consumer metadata or bytes; no content may execute after failure.
+     */
+    validate?(template: WorkspaceTemplate, signal: AbortSignal): void | Promise<void>;
+}
+/** 下一个 turn 可使用的完整 Agent 配置版本，路径指向已经校验的不可变文件。 */
+export interface WorkspaceAgentConfigVersion {
+    readonly workspaceKind: string;
+    readonly version: string;
+    readonly sha256: string | null;
+    readonly hostAgentConfigApiVersion: string;
+    readonly templateDigest: string;
+    readonly sourceRoot: string;
+}
+/** Verified content held by one activity; each retained handle owns a separate release. */
+export interface WorkspaceAgentConfigHandle extends WorkspaceAgentConfigVersion {
+    readonly workspaceId: WorkspaceId;
+    /** @returns another synchronous lease of these exact bytes, including after the parent activity ends. @throws WorkspaceBundleError when this handle was released or the Provider is unloading. */
+    retain(): WorkspaceAgentConfigHandle;
+    /** Release this activity once; retained consumers keep the content leased. */
+    release(): void;
+}
+/** 内容更新的当前可观察状态；错误只包含固定诊断。 */
+export interface WorkspaceAgentConfigState {
+    /** True when committed content has failed execution validation; current is diagnostic only until compatible replacement. */
+    readonly blocked: boolean;
+    /** Execution refusal for current content; candidate and query failures cannot clear it. */
+    readonly blockingFailure: {
+        readonly code: AgentConfigErrorCode;
+    } | null;
+    readonly current: WorkspaceAgentConfigVersion;
+    readonly pending: WorkspaceAgentConfigVersion | null;
+    readonly failure: {
+        readonly code: AgentConfigErrorCode;
+        readonly message: string;
+    } | null;
+    /** Latest same-scope content refusal; query/scope failures are excluded. Null means no applicable refusal. */
+    readonly lastRejection: {
+        readonly code: AgentConfigErrorCode;
+        readonly version?: string;
+        readonly sha256?: string;
+    } | null;
+}
+/** 注册时固定的内置版本；源查询失败不能使它不可用。 */
+export interface WorkspaceAgentConfigRegistration {
+    readonly template: WorkspaceTemplate;
+    readonly source: WorkspaceAgentConfigSource;
+}

package/lib/types/agent-config-types.js

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

package/lib/types/bundled-agent-config.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import type { WorkspaceTemplate } from './types.ts';
+/** Public metadata of the exact published gzip installed as a bundled template. */
+export declare const BundledAgentConfigReceiptSchema: z.ZodObject<{
+    workspaceKind: z.ZodString;
+    version: z.ZodString;
+    sha256: z.ZodString;
+    sizeBytes: z.ZodNumber;
+    hostAgentConfigApiRange: z.ZodString;
+    runtimeApiRange: z.ZodOptional<z.ZodString>;
+    formatVersion: z.ZodLiteral<1>;
+    templateDigest: z.ZodString;
+}, z.core.$strict>;
+/** Parsed identity and compatibility of a published bundled template. */
+export type BundledAgentConfigReceipt = z.infer<typeof BundledAgentConfigReceiptSchema>;
+/**
+ * Attach the adjacent publication receipt to a verified packaged template.
+ * @param template - Template whose file catalog has already been verified.
+ * @returns The original template when no receipt exists, otherwise its published identity and receipt.
+ * @throws AgentConfigError when an existing receipt is unreadable, invalid or identifies different content.
+ */
+export declare function loadBundledAgentConfigSync(template: WorkspaceTemplate): WorkspaceTemplate;
+/**
+ * Identify downloaded content in journals while registered content follows the installation.
+ * @param template - Selected template, including a possible downloaded copy.
+ * @param registered - This identity's exact registered object, or undefined during recovery without a registration.
+ * @returns Null for the registered object or a template without a package digest; otherwise the package digest.
+ */
+export declare function journalAgentConfigSha256(template: WorkspaceTemplate, registered: WorkspaceTemplate | undefined): string | null;

package/lib/types/bundled-agent-config.js

@@ -0,0 +1,47 @@
+/** Published package receipts beside shipped templates, separate from model-visible files. */
+import { readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { z } from 'zod';
+import { AgentConfigDescriptorSchema, AgentConfigError, AgentConfigSha256 } from "./agent-config-format.js";
+/** Public metadata of the exact published gzip installed as a bundled template. */
+export const BundledAgentConfigReceiptSchema = AgentConfigDescriptorSchema.omit({ downloadUrl: true, releaseNotes: true }).extend({
+    formatVersion: z.literal(1),
+    templateDigest: AgentConfigSha256,
+});
+/**
+ * Attach the adjacent publication receipt to a verified packaged template.
+ * @param template - Template whose file catalog has already been verified.
+ * @returns The original template when no receipt exists, otherwise its published identity and receipt.
+ * @throws AgentConfigError when an existing receipt is unreadable, invalid or identifies different content.
+ */
+export function loadBundledAgentConfigSync(template) {
+    let bytes;
+    try {
+        bytes = readFileSync(join(dirname(template.sourceRoot), `${basename(template.sourceRoot)}.agent-config.json`));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return template;
+        throw new AgentConfigError('AGENT_CONFIG_INVALID');
+    }
+    let receipt;
+    try {
+        receipt = BundledAgentConfigReceiptSchema.parse(JSON.parse(bytes.toString('utf8')));
+    }
+    catch (error) {
+        throw new AgentConfigError('AGENT_CONFIG_INVALID');
+    }
+    if (receipt.workspaceKind !== template.bundleId || receipt.version !== template.manifest.pluginVersion
+        || receipt.templateDigest !== template.manifest.digest)
+        throw new AgentConfigError('AGENT_CONFIG_INVALID');
+    return { ...template, agentConfigSha256: receipt.sha256, agentConfigReceipt: receipt };
+}
+/**
+ * Identify downloaded content in journals while registered content follows the installation.
+ * @param template - Selected template, including a possible downloaded copy.
+ * @param registered - This identity's exact registered object, or undefined during recovery without a registration.
+ * @returns Null for the registered object or a template without a package digest; otherwise the package digest.
+ */
+export function journalAgentConfigSha256(template, registered) {
+    return template === registered ? null : template.agentConfigSha256 ?? null;
+}

package/lib/types/config.d.ts

@@ -0,0 +1,34 @@
+import Schema from '@deepseek-ai/schemastery';
+import type { WorkspaceBundlesSpec } from './types.ts';
+/** Raw cordis.yml settings of the workspace-bundle row. */
+export interface Config {
+    /** Parent of `{bundleId}/{workspaceKey}` Workspace roots; required absolute path. */
+    readonly materializeRoot?: string;
+    /** Parent of immutable template copies; required absolute path. */
+    readonly templateCacheRoot?: string;
+    /** Parent of per-Workspace journals; required absolute path. */
+    readonly journalRoot?: string;
+    /** Upgrade lease drain deadline, 1000–600000 ms. */
+    readonly quiesceTimeoutMs?: number;
+    /** Backup recycle delay after a successful commit, 0–600000 ms. */
+    readonly recycleTimeoutMs?: number;
+    readonly agentConfigPollIntervalMs?: number;
+    readonly agentConfigRequestTimeoutMs?: number;
+    readonly agentConfigMaxDownloadBytes?: number;
+    readonly agentConfigMaxExpandedBytes?: number;
+    readonly allowLoopbackAgentConfigHttp?: boolean;
+}
+/** Settings after {@link Config} applies its defaults; path fields may still be absent. */
+export type ResolvedConfig = Required<Omit<Config, 'materializeRoot' | 'templateCacheRoot' | 'journalRoot'>> & Pick<Config, 'materializeRoot' | 'templateCacheRoot' | 'journalRoot'>;
+/**
+ * Field types and bounds. Path fields are optional here so a missing value reaches
+ * {@link resolveWorkspaceBundlesSpec} and fails with its named diagnostic.
+ */
+export declare const Config: Schema<Config, ResolvedConfig>;
+/**
+ * Resolve raw settings into the Spec the Provider runs with.
+ * @param config - raw row settings.
+ * @returns every field set, with roots normalized.
+ * @throws {WorkspaceBundlesConfigError} When a required path is missing or not absolute.
+ */
+export declare function resolveWorkspaceBundlesSpec(config?: Config): WorkspaceBundlesSpec;

package/lib/types/config.js

@@ -0,0 +1,53 @@
+/** workspace-bundle Config: Schemastery field validation and explicit resolution into a Spec. */
+import { isAbsolute, normalize, sep } from 'node:path';
+import Schema from '@deepseek-ai/schemastery';
+import { WorkspaceBundlesConfigError } from "./errors.js";
+/**
+ * Field types and bounds. Path fields are optional here so a missing value reaches
+ * {@link resolveWorkspaceBundlesSpec} and fails with its named diagnostic.
+ */
+export const Config = Schema.object({
+    materializeRoot: Schema.string().description('Absolute parent of bundled Workspace roots'),
+    templateCacheRoot: Schema.string().description('Absolute parent of immutable template copies'),
+    journalRoot: Schema.string().description('Absolute parent of upgrade journals'),
+    quiesceTimeoutMs: Schema.number().min(1_000).max(600_000).step(1).default(30_000),
+    recycleTimeoutMs: Schema.number().min(0).max(600_000).step(1).default(60_000),
+    agentConfigPollIntervalMs: Schema.number().min(1_000).max(86_400_000).step(1).default(300_000),
+    agentConfigRequestTimeoutMs: Schema.number().min(100).max(600_000).step(1).default(30_000),
+    agentConfigMaxDownloadBytes: Schema.number().min(1_024).max(268_435_456).step(1).default(67_108_864),
+    agentConfigMaxExpandedBytes: Schema.number().min(1_024).max(536_870_912).step(1).default(134_217_728),
+    allowLoopbackAgentConfigHttp: Schema.boolean().default(false),
+});
+function absoluteDirectory(value, field) {
+    if (value === undefined || value.trim() === '') {
+        const code = field === 'materializeRoot' ? 'WORKSPACE_BUNDLES_MATERIALIZE_ROOT_MISSING'
+            : field === 'templateCacheRoot' ? 'WORKSPACE_BUNDLES_TEMPLATE_CACHE_ROOT_MISSING'
+                : 'WORKSPACE_BUNDLES_JOURNAL_ROOT_MISSING';
+        throw new WorkspaceBundlesConfigError(code, `${field} is required`);
+    }
+    if (!isAbsolute(value) || value.includes('\0') || normalize(value).includes(`..${sep}`) || normalize(value).endsWith(`${sep}..`)) {
+        throw new WorkspaceBundlesConfigError('WORKSPACE_BUNDLES_PATH_INVALID', `${field} ${JSON.stringify(value)} must be an absolute path without parent segments`);
+    }
+    return normalize(value);
+}
+/**
+ * Resolve raw settings into the Spec the Provider runs with.
+ * @param config - raw row settings.
+ * @returns every field set, with roots normalized.
+ * @throws {WorkspaceBundlesConfigError} When a required path is missing or not absolute.
+ */
+export function resolveWorkspaceBundlesSpec(config = {}) {
+    const resolved = Config(config);
+    return {
+        materializeRoot: absoluteDirectory(resolved.materializeRoot, 'materializeRoot'),
+        templateCacheRoot: absoluteDirectory(resolved.templateCacheRoot, 'templateCacheRoot'),
+        journalRoot: absoluteDirectory(resolved.journalRoot, 'journalRoot'),
+        quiesceTimeoutMs: resolved.quiesceTimeoutMs,
+        recycleTimeoutMs: resolved.recycleTimeoutMs,
+        agentConfigPollIntervalMs: resolved.agentConfigPollIntervalMs,
+        agentConfigRequestTimeoutMs: resolved.agentConfigRequestTimeoutMs,
+        agentConfigMaxDownloadBytes: resolved.agentConfigMaxDownloadBytes,
+        agentConfigMaxExpandedBytes: resolved.agentConfigMaxExpandedBytes,
+        allowLoopbackAgentConfigHttp: resolved.allowLoopbackAgentConfigHttp,
+    };
+}