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

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

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+/** 本 Host 实现的 Agent 配置接口版本；白名单与写操作授权由 Host 保持。 */
+export declare const HOST_AGENT_CONFIG_API_VERSION = "1.0.0";
+/** Agent 配置 SHA-256 的十六进制编码。 */
+export declare const AgentConfigSha256: z.ZodString;
+/** 内置 Workspace 种类；不含路径分隔符。 */
+export declare const WorkspaceKind: z.ZodString;
+/** @param value - 完整 Agent 配置版本。 @returns 是否为保留构建元数据的规范 SemVer；优先级由 semver 按规范比较。 */
+export declare function isAgentConfigVersion(value: string): boolean;
+/** server 分配中可公开的包信息，未携带商家凭据。 */
+export declare const AgentConfigDescriptorSchema: z.ZodObject<{
+    workspaceKind: z.ZodString;
+    version: z.ZodString;
+    sha256: z.ZodString;
+    sizeBytes: z.ZodNumber;
+    downloadUrl: z.ZodURL;
+    hostAgentConfigApiRange: z.ZodString;
+    releaseNotes: z.ZodString;
+}, z.core.$strict>;
+/** 经解析的 server 分配。 */
+export type AgentConfigDescriptor = z.infer<typeof AgentConfigDescriptorSchema>;
+/** 包内逐文件摘要与字节数，文件路径相对版本目录。 */
+export declare const AgentConfigManifestSchema: z.ZodObject<{
+    formatVersion: z.ZodLiteral<1>;
+    workspaceKind: z.ZodString;
+    version: z.ZodString;
+    hostAgentConfigApiRange: z.ZodString;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        sizeBytes: z.ZodNumber;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** 确定性 gzip JSON Agent 配置：清单和按同序排列的 base64 文件。 */
+export declare const AgentConfigDocumentSchema: z.ZodObject<{
+    manifest: z.ZodObject<{
+        formatVersion: z.ZodLiteral<1>;
+        workspaceKind: z.ZodString;
+        version: z.ZodString;
+        hostAgentConfigApiRange: z.ZodString;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            sizeBytes: z.ZodNumber;
+            sha256: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        base64: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** 包内文件清单。 */
+export type AgentConfigManifest = z.infer<typeof AgentConfigManifestSchema>;
+/** 已解码并校验的文件。 */
+export interface AgentConfigFile {
+    readonly path: string;
+    readonly bytes: Buffer;
+}
+/** 内容更新失败类型；报告不包含下载 URL、响应正文或凭据。 */
+export type AgentConfigErrorCode = 'AGENT_CONFIG_QUERY_FAILED' | 'AGENT_CONFIG_INVALID' | 'AGENT_CONFIG_INCOMPATIBLE' | 'AGENT_CONFIG_DIGEST_MISMATCH' | 'AGENT_CONFIG_DOWNLOAD_FAILED' | 'AGENT_CONFIG_APPLY_FAILED' | 'AGENT_CONFIG_SCOPE_CHANGED';
+/** 有界内容更新的结构化失败。 */
+export declare class AgentConfigError extends Error {
+    readonly code: AgentConfigErrorCode;
+    /** @param code - 失败类别。 */
+    constructor(code: AgentConfigErrorCode);
+}
+/** @param bytes - 完整文件字节。 @returns SHA-256 小写十六进制编码。 */
+export declare function agentConfigSha256(bytes: Uint8Array): string;
+/**
+ * 拒绝无法在各 Host 文件系统安全表达的相对路径。
+ * @param path - 包内 POSIX 路径。
+ * @returns 原始路径。
+ */
+export declare function contentPath(path: string): string;
+/**
+ * 同时认证压缩包和逐文件字节，任何失败均发生在版本目录写入前。
+ * @param bytes - 下载的完整 gzip 字节。
+ * @param descriptor - server 经鉴权查询给出的登记信息。
+ * @param maxExpandedBytes - 解压 JSON 和文件总字节上限。
+ * @returns 清单和已校验文件。
+ */
+export declare function decodeAgentConfig(bytes: Buffer, descriptor: AgentConfigDescriptor, maxExpandedBytes: number): {
+    readonly manifest: AgentConfigManifest;
+    readonly files: readonly AgentConfigFile[];
+};

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

@@ -0,0 +1,116 @@
+/** 内置 Workspace Agent 配置的文件校验；目录和压缩字节的大小均由部署配置限制。 */
+import { createHash } from 'node:crypto';
+import { gunzipSync } from 'node:zlib';
+import semver from 'semver';
+import { z } from 'zod';
+import { assertTemplateRelativePath } from "./paths.js";
+/** 本 Host 实现的 Agent 配置接口版本；白名单与写操作授权由 Host 保持。 */
+export const HOST_AGENT_CONFIG_API_VERSION = '1.0.0';
+/** Agent 配置 SHA-256 的十六进制编码。 */
+export const AgentConfigSha256 = z.string().regex(/^[a-f0-9]{64}$/u);
+/** 内置 Workspace 种类；不含路径分隔符。 */
+export const WorkspaceKind = z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u).max(80);
+/** @param value - 完整 Agent 配置版本。 @returns 是否为保留构建元数据的规范 SemVer；优先级由 semver 按规范比较。 */
+export function isAgentConfigVersion(value) {
+    const parsed = semver.parse(value);
+    return parsed !== null && `${parsed.version}${parsed.build.length === 0 ? '' : `+${parsed.build.join('.')}`}` === value;
+}
+/** server 分配中可公开的包信息，未携带商家凭据。 */
+export const AgentConfigDescriptorSchema = z.strictObject({
+    workspaceKind: WorkspaceKind,
+    version: z.string().refine(isAgentConfigVersion),
+    sha256: AgentConfigSha256,
+    sizeBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    downloadUrl: z.url(),
+    hostAgentConfigApiRange: z.string().refine(value => semver.validRange(value) !== null),
+    releaseNotes: z.string().min(1).max(20000),
+});
+/** 包内逐文件摘要与字节数，文件路径相对版本目录。 */
+export const AgentConfigManifestSchema = z.strictObject({
+    formatVersion: z.literal(1), workspaceKind: WorkspaceKind,
+    version: z.string().refine(isAgentConfigVersion),
+    hostAgentConfigApiRange: z.string().refine(value => semver.validRange(value) !== null),
+    files: z.array(z.strictObject({ path: z.string(), sizeBytes: z.number().int().nonnegative(), sha256: AgentConfigSha256 })).min(1).max(10000),
+});
+/** 确定性 gzip JSON Agent 配置：清单和按同序排列的 base64 文件。 */
+export const AgentConfigDocumentSchema = z.strictObject({
+    manifest: AgentConfigManifestSchema,
+    files: z.array(z.strictObject({ path: z.string(), base64: z.string() })).min(1).max(10000),
+});
+/** 有界内容更新的结构化失败。 */
+export class AgentConfigError extends Error {
+    code;
+    /** @param code - 失败类别。 */
+    constructor(code) {
+        const messages = {
+            AGENT_CONFIG_QUERY_FAILED: 'Agent 配置版本查询失败，保留当前版本；请检查服务器连接。',
+            AGENT_CONFIG_INVALID: 'Agent 配置文件或清单无效，保留当前版本；请重新打包发布。',
+            AGENT_CONFIG_INCOMPATIBLE: 'Agent 配置不兼容当前 Host，保留当前版本；请分配兼容版本或升级客户端。',
+            AGENT_CONFIG_DIGEST_MISMATCH: 'Agent 配置摘要不匹配，保留当前版本；请核对发布登记。',
+            AGENT_CONFIG_DOWNLOAD_FAILED: 'Agent 配置下载失败，保留当前版本；请检查文件服务连接。',
+            AGENT_CONFIG_APPLY_FAILED: 'Agent 配置应用失败；请检查工作区恢复状态后再继续。',
+            AGENT_CONFIG_SCOPE_CHANGED: 'Agent 配置版本来源已变更，已丢弃旧候选；保留当前版本并重新查询。',
+        };
+        super(messages[code]);
+        this.code = code;
+        this.name = 'AgentConfigError';
+    }
+}
+/** @param bytes - 完整文件字节。 @returns SHA-256 小写十六进制编码。 */
+export function agentConfigSha256(bytes) { return createHash('sha256').update(bytes).digest('hex'); }
+/**
+ * 拒绝无法在各 Host 文件系统安全表达的相对路径。
+ * @param path - 包内 POSIX 路径。
+ * @returns 原始路径。
+ */
+export function contentPath(path) {
+    assertTemplateRelativePath(path);
+    if (path === 'manifest.json' || path.split('/').some(part => /[<>:"|?*\x00-\x1f]/u.test(part)
+        || /[. ]$/u.test(part) || /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/iu.test(part)))
+        throw new AgentConfigError('AGENT_CONFIG_INVALID');
+    return path;
+}
+/**
+ * 同时认证压缩包和逐文件字节，任何失败均发生在版本目录写入前。
+ * @param bytes - 下载的完整 gzip 字节。
+ * @param descriptor - server 经鉴权查询给出的登记信息。
+ * @param maxExpandedBytes - 解压 JSON 和文件总字节上限。
+ * @returns 清单和已校验文件。
+ */
+export function decodeAgentConfig(bytes, descriptor, maxExpandedBytes) {
+    if (bytes.length !== descriptor.sizeBytes || agentConfigSha256(bytes) !== descriptor.sha256)
+        throw new AgentConfigError('AGENT_CONFIG_DIGEST_MISMATCH');
+    if (!semver.satisfies(HOST_AGENT_CONFIG_API_VERSION, descriptor.hostAgentConfigApiRange, { includePrerelease: true }))
+        throw new AgentConfigError('AGENT_CONFIG_INCOMPATIBLE');
+    let document;
+    try {
+        document = AgentConfigDocumentSchema.parse(JSON.parse(gunzipSync(bytes, { maxOutputLength: maxExpandedBytes }).toString('utf8')));
+    }
+    catch (error) {
+        throw new AgentConfigError('AGENT_CONFIG_INVALID');
+    }
+    const { manifest } = document;
+    if (manifest.workspaceKind !== descriptor.workspaceKind || manifest.version !== descriptor.version
+        || manifest.hostAgentConfigApiRange !== descriptor.hostAgentConfigApiRange || document.files.length !== manifest.files.length)
+        throw new AgentConfigError('AGENT_CONFIG_INVALID');
+    const seen = new Set();
+    let total = 0;
+    let previous = '';
+    const files = document.files.map((file, index) => {
+        const entry = manifest.files[index];
+        const path = contentPath(file.path);
+        const normalized = path.toLowerCase();
+        if (entry.path !== path || path <= previous || seen.has(normalized)
+            || [...seen].some(parent => normalized.startsWith(`${parent}/`) || parent.startsWith(`${normalized}/`)))
+            throw new AgentConfigError('AGENT_CONFIG_INVALID');
+        seen.add(normalized);
+        previous = path;
+        const data = Buffer.from(file.base64, 'base64');
+        total += data.length;
+        if (total > maxExpandedBytes || data.toString('base64') !== file.base64 || data.length !== entry.sizeBytes
+            || agentConfigSha256(data) !== entry.sha256)
+            throw new AgentConfigError('AGENT_CONFIG_DIGEST_MISMATCH');
+        return { path, bytes: data };
+    });
+    return { manifest, files };
+}

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

@@ -0,0 +1,52 @@
+import { AgentConfigError } from './agent-config-format.ts';
+import type { WorkspaceAgentConfigRegistration, WorkspaceAgentConfigState } from './agent-config-types.ts';
+import type { WorkspaceBundlesSpec, WorkspaceTemplate, WorkspaceTemplateDigest } from './types.ts';
+/** 一个注册来源的缓存、轮询和候选版本；卸载必须等待所有网络与文件工作结束。 */
+export declare class WorkspaceAgentConfigSourceOwner {
+    readonly registration: WorkspaceAgentConfigRegistration;
+    private readonly spec;
+    private readonly report;
+    private readonly download;
+    private readonly lifetime;
+    private inFlight;
+    private requestAbort;
+    private requestRevision;
+    private readonly preparedRevisions;
+    private timer;
+    private selected;
+    private candidate;
+    private failure;
+    private readonly root;
+    /** @param registration - 内置模板及鉴权查询回调。 @param spec - 部署预算。 @param report - 固定失败诊断的报告者。 @param download - 文件 HTTP 传输。 */
+    constructor(registration: WorkspaceAgentConfigRegistration, spec: WorkspaceBundlesSpec, report: (error: AgentConfigError) => void, download?: typeof fetch);
+    /** @returns 已应用版本、候选版本和最近一次失败。 */
+    state(): WorkspaceAgentConfigState;
+    /**
+     * 从 journal 已提交的摘要定位只读缓存，不从 server 的无分配回答推导降级。
+     * @param digest - 已提交 Workspace 模板摘要；undefined 表示首次使用。
+     * @param version - 已提交完整版本，包括构建元数据。
+     * @param sha256 - 已提交包摘要；undefined 支持旧内置记录。
+     * @returns 对应完整模板；缺失已安装缓存时拒绝继续。
+     */
+    recover(digest: WorkspaceTemplateDigest | undefined, version?: string, sha256?: string | null): Promise<WorkspaceTemplate>;
+    /** 注册者调用一次以启动查询，并按配置间隔继续。 */
+    start(): void;
+    /** @returns 本次查询和完整候选下载结束；失败通过 state 与 report 保留可观察诊断。 */
+    refresh(): Promise<void>;
+    /** @returns 下一个 turn 可应用的候选；没有候选时使用已安装版本。 */
+    template(): WorkspaceTemplate;
+    /** @param template - 即将整体替换的候选。 @throws 来源代次已经改变或已撤销时拒绝应用。 */
+    assertApplicable(template: WorkspaceTemplate): void;
+    /** @param template - 已通过 Workspace 整体替换提交的模板。 */
+    committed(template: WorkspaceTemplate): Promise<void>;
+    /**
+     * 清除未提交候选，报告整体替换失败；已提交状态由 journal 恢复结果决定。
+     * @param template - 未能完成提交的模板。
+     * @param cause - 保留来源失效分类；其他原因报告固定应用失败诊断。
+     */
+    failedApply(template: WorkspaceTemplate, cause: unknown): void;
+    /** 撤销查询、清除后续定时器，并等待下载和目录写入完成。 */
+    dispose(): Promise<void>;
+    private versionDirectory;
+    private fetchCandidate;
+}

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

@@ -0,0 +1,268 @@
+/** 内容来源的有界拉取和只读版本缓存；此模块不替换运行中的 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 { 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";
+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;
+    lifetime = new AbortController();
+    inFlight;
+    requestAbort;
+    requestRevision;
+    preparedRevisions = new WeakMap();
+    timer;
+    selected;
+    candidate;
+    failure = null;
+    root;
+    /** @param registration - 内置模板及鉴权查询回调。 @param spec - 部署预算。 @param report - 固定失败诊断的报告者。 @param download - 文件 HTTP 传输。 */
+    constructor(registration, spec, report, download = fetch) {
+        this.registration = registration;
+        this.spec = spec;
+        this.report = report;
+        this.download = download;
+        this.selected = { template: registration.template, sha256: 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;
+        return { current: publicVersion(this.selected.template, this.selected.sha256),
+            pending: this.candidate === undefined ? null : publicVersion(this.candidate.template, this.candidate.sha256), failure: this.failure };
+    }
+    /**
+     * 从 journal 已提交的摘要定位只读缓存，不从 server 的无分配回答推导降级。
+     * @param digest - 已提交 Workspace 模板摘要；undefined 表示首次使用。
+     * @param version - 已提交完整版本，包括构建元数据。
+     * @param sha256 - 已提交包摘要；undefined 支持旧内置记录。
+     * @returns 对应完整模板；缺失已安装缓存时拒绝继续。
+     */
+    async recover(digest, version, sha256) {
+        if (digest === undefined || sha256 === undefined || sha256 === null) {
+            this.selected = { template: this.registration.template, sha256: null };
+            return this.selected.template;
+        }
+        if (digest === this.selected.template.manifest.digest
+            && (version === undefined || version === this.selected.template.manifest.pluginVersion)
+            && sha256 === this.selected.sha256)
+            return this.selected.template;
+        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');
+        this.selected = { template: { ...this.registration.template, sourceRoot: join(directory, receipt.version), manifest,
+                agentConfigSha256: receipt.sha256 }, sha256: receipt.sha256 };
+        if (this.candidate?.sha256 === receipt.sha256)
+            this.candidate = undefined;
+        return this.selected.template;
+    }
+    /** 注册者调用一次以启动查询，并按配置间隔继续。 */
+    start() {
+        const tick = async () => {
+            await this.refresh();
+            if (!this.lifetime.signal.aborted)
+                this.timer = setTimeout(() => { void tick(); }, this.spec.agentConfigPollIntervalMs);
+        };
+        void tick();
+    }
+    /** @returns 本次查询和完整候选下载结束；失败通过 state 与 report 保留可观察诊断。 */
+    refresh() {
+        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 run = this.fetchCandidate(revision, abort.signal).catch((error) => {
+            if (this.lifetime.signal.aborted || abort.signal.aborted || revision !== this.registration.source.revision())
+                return;
+            this.candidate = undefined;
+            const failure = error instanceof AgentConfigError ? error : new AgentConfigError('AGENT_CONFIG_INVALID');
+            this.failure = { code: failure.code, message: failure.message };
+            this.report(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;
+        return this.candidate?.template ?? this.selected.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, template.agentConfigSha256 ?? null);
+    }
+    /**
+     * 清除未提交候选，报告整体替换失败；已提交状态由 journal 恢复结果决定。
+     * @param template - 未能完成提交的模板。
+     * @param cause - 保留来源失效分类；其他原因报告固定应用失败诊断。
+     */
+    failedApply(template, cause) {
+        if (this.candidate?.template === template)
+            this.candidate = undefined;
+        const error = cause instanceof AgentConfigError && cause.code === 'AGENT_CONFIG_SCOPE_CHANGED'
+            ? cause : new AgentConfigError('AGENT_CONFIG_APPLY_FAILED');
+        this.failure = { code: error.code, message: error.message };
+        this.report(error);
+    }
+    /** 撤销查询、清除后续定时器，并等待下载和目录写入完成。 */
+    async dispose() {
+        this.lifetime.abort();
+        this.candidate = undefined;
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        await this.inFlight;
+        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);
+    }
+    async fetchCandidate(revision, requestSignal) {
+        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 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;
+            return;
+        }
+        const descriptor = assignment.data.agentConfig;
+        if (descriptor.workspaceKind !== assignment.data.workspaceKind)
+            throw new AgentConfigError('AGENT_CONFIG_INVALID');
+        if (descriptor.sha256 === this.selected.sha256) {
+            this.candidate = undefined;
+            this.failure = null;
+            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 template = { ...this.registration.template, sourceRoot: tree, manifest, agentConfigSha256: descriptor.sha256 };
+        this.preparedRevisions.set(template, revision);
+        this.candidate = { template, sha256: descriptor.sha256, revision };
+        this.failure = null;
+    }
+}

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

@@ -0,0 +1,34 @@
+/** Workspace Agent 配置版本来源和 turn 记录的 Host 接口。 */
+import type { WorkspaceBundleIdentity, WorkspaceTemplate } from './types.ts';
+import type { AgentConfigErrorCode } from './agent-config-format.ts';
+/** 调用方负责通过自身鉴权能力查询 server，不向此服务交出凭据。 */
+export interface WorkspaceAgentConfigSource {
+    readonly identity: WorkspaceBundleIdentity;
+    /** @returns 随登录、租户或其他分配身份改变的进程内代次。 */
+    revision(): number;
+    /** @param signal - 源卸载或请求超时取消。 @returns #86 的 builtin / registry 分配。 */
+    query(signal: AbortSignal): Promise<unknown>;
+}
+/** 下一个 turn 可使用的完整 Agent 配置版本，路径指向已经校验的不可变文件。 */
+export interface WorkspaceAgentConfigVersion {
+    readonly workspaceKind: string;
+    readonly version: string;
+    readonly sha256: string | null;
+    readonly hostAgentConfigApiVersion: string;
+    readonly templateDigest: string;
+    readonly sourceRoot: string;
+}
+/** 内容更新的当前可观察状态；错误只包含固定诊断。 */
+export interface WorkspaceAgentConfigState {
+    readonly current: WorkspaceAgentConfigVersion;
+    readonly pending: WorkspaceAgentConfigVersion | null;
+    readonly failure: {
+        readonly code: AgentConfigErrorCode;
+        readonly message: 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/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,
+    };
+}