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

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

@@ -0,0 +1,448 @@
+import { brandString } from '@deepseek-ai/dsh-brand';
+import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { HOST_AGENT_CONFIG_API_VERSION } from "./agent-config-format.js";
+import { LocalHostReplacementWriteError } from "./local-host-replacement.js";
+import { ModuleAgentConfigSnapshot, RegisterAgentConfigHostRequest, ReportAgentConfigHostRequest, registerAgentConfigHost, reportAgentConfigHost, getAgentConfigSandboxHost } from "./agent-config-contract/agent-configs.js";
+const sequence = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+const ScopeState = z.strictObject({ generation: sequence, replaced: z.boolean().optional(),
+    running: z.strictObject({ bootId: z.uuid(), bootSequence: sequence, sequence }).nullable(),
+    pendingRegistration: RegisterAgentConfigHostRequest.nullable(), pendingReport: ReportAgentConfigHostRequest.nullable(),
+});
+const State = z.strictObject({ version: z.literal(1), hostId: z.uuid(), bootSequence: sequence, scopes: z.record(z.string().regex(/^[a-f0-9]{64}$/u), ScopeState) });
+function sameSandbox(left, right) {
+    return left?.sandboxId === right.sandboxId && left.instanceId === right.instanceId && left.sandboxGeneration === right.sandboxGeneration;
+}
+class ObservationError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+/**
+ * Build the observation owner when its source is registered; the server owns holder attestation.
+ * @param ctx - authenticated merchant transport and scope-change events.
+ * @param options - module identity, private persistent directory and resolved scheduling limits.
+ * @returns factory bound to the source's actual committed state.
+ */
+export function agentConfigHostObservation(ctx, options) {
+    return read => new ModuleHostObservation(ctx, options, read);
+}
+/**
+ * Cloud-only factory; importing this export rejects older packages that cannot enforce sandbox identity.
+ * @param ctx - Authenticated merchant transport and scope-change events.
+ * @param options - Required sandbox deployment identity and private reporter settings.
+ * @returns factory whose registrations require authenticated sandbox readback.
+ */
+export function sandboxAgentConfigHostObservation(ctx, options) {
+    return read => new ModuleHostObservation(ctx, options, read);
+}
+class ModuleHostObservation {
+    ctx;
+    options;
+    read;
+    lifetime = new AbortController();
+    active;
+    run;
+    stopped;
+    chain = Promise.resolve();
+    timer;
+    stopScope;
+    stopActivation;
+    stopActivated;
+    preparedRevision;
+    preparedHostId;
+    activationRequest = false;
+    stopReplacement;
+    migrated = new Set();
+    member() { return this.ctx.merchantAccount.captureIdentity()?.identity; }
+    get replaced() { if (this.options.sandbox !== undefined)
+        return false; const member = this.member(); return member !== undefined && this.options.replacementState.isReplaced(member); }
+    stopIdentity;
+    hostId() { return typeof this.options.hostId === 'function' ? this.options.hostId() : this.options.hostId; }
+    constructor(ctx, options, read) {
+        this.ctx = ctx;
+        this.options = options;
+        this.read = read;
+        this.stopReplacement = options.sandbox === undefined ? options.replacementState.subscribe(() => {
+            if (!this.replaced)
+                return;
+            if (!this.activationRequest)
+                this.active?.abort();
+            this.options.onReplaced?.(this.hostId());
+            void this.refresh();
+        }) : () => { };
+        this.stopScope = ctx.on('merchant-account/scope-changed', () => { this.active?.abort(); void this.refresh(); });
+        this.stopIdentity = options.sandbox === undefined ? ctx.on('workspace-bundle/local-host-identity-changed', () => { this.active?.abort(); this.stopped = undefined; return this.refresh(); }) : () => { };
+        this.stopActivation = options.sandbox === undefined ? ctx.on('workspace-bundle/activate-local-host', async (revision, registered) => { await this.activate(revision); registered.add(this.options.workspaceKind); }) : () => { };
+        this.stopActivated = options.sandbox === undefined ? ctx.on('workspace-bundle/local-host-activated', revision => {
+            if (this.preparedRevision !== revision || this.preparedHostId !== this.hostId())
+                return Promise.reject(new ObservationError('AGENT_CONFIG_HOST_UNAVAILABLE'));
+            const work = this.chain.then(() => this.report(revision, false, true));
+            this.chain = work.catch((error) => { void error; });
+            return work;
+        }) : () => { };
+        void this.cycle();
+    }
+    async cycle() {
+        await this.refresh();
+        if (this.lifetime.signal.aborted)
+            return;
+        this.timer = setTimeout(() => { void this.cycle(); }, this.options.intervalMs);
+        this.timer.unref();
+    }
+    refresh() {
+        if (this.lifetime.signal.aborted)
+            return this.chain;
+        const revision = this.ctx.merchantAccount.getScopeRevision();
+        this.chain = this.chain.then(() => this.report(revision)).catch((error) => {
+            if (this.lifetime.signal.aborted || revision !== this.ctx.merchantAccount.getScopeRevision())
+                return;
+            // The identity-changed listener cancelled this run; its failure must not stop the run for the new identity.
+            if (this.run !== undefined && this.run.hostId !== this.hostId())
+                return;
+            const code = error instanceof LocalHostReplacementWriteError ? 'LOCAL_HOST_REPLACEMENT_WRITE_FAILED' : error instanceof ObservationError ? error.code : 'AGENT_CONFIG_HOST_STATE_INVALID';
+            if (code === 'LOCAL_HOST_REPLACEMENT_WRITE_FAILED') {
+                this.ctx.logger.warn('workspace-bundle: %s replacement state could not be saved; reporting remains stopped; check disk space and directory permissions before retrying', this.options.workspaceKind);
+                return;
+            }
+            if (code !== 'LOCAL_HOST_REPLACED' && code !== 'AGENT_CONFIG_HOST_UNAVAILABLE' && this.run !== undefined)
+                this.stopped = { key: this.run.key, revision };
+            this.ctx.logger.warn('workspace-bundle: %s module observation failed (%s); %s', this.options.workspaceKind, code, code === 'AGENT_CONFIG_HOST_UNAVAILABLE' ? 'the exact pending request is retained for retry' : 'reporting is stopped; restore matching Host state before restarting');
+        });
+        return this.chain;
+    }
+    activate(revision) {
+        if (this.lifetime.signal.aborted || revision !== this.ctx.merchantAccount.getScopeRevision())
+            return Promise.reject(new ObservationError('AGENT_CONFIG_HOST_UNAVAILABLE'));
+        const work = this.chain.then(() => this.report(revision, true));
+        this.chain = work.catch((error) => { void error; });
+        return work;
+    }
+    scope(revision) {
+        const state = this.ctx.merchantAccount.getState();
+        const identity = state.status === 'signed-in' ? state.identity : null;
+        const tenantId = identity?.currentTenantId;
+        if (identity === null || tenantId == null || !identity.memberships.some(member => member.tenantId === tenantId && member.kind === 'shop'))
+            return undefined;
+        if (revision !== this.ctx.merchantAccount.getScopeRevision())
+            return undefined;
+        const userId = identity.user.id;
+        const key = createHash('sha256').update(JSON.stringify(this.options.sandbox === undefined ? [tenantId, userId, this.options.workspaceKind]
+            : [this.member()?.serverOrigin, tenantId, userId, this.options.workspaceKind, this.options.sandbox.sandboxId, this.options.sandbox.instanceId])).digest('hex');
+        if (this.stopped?.key === key && this.stopped.revision === revision)
+            return undefined;
+        if (this.run?.key !== key || this.run.revision !== revision || this.run.hostId !== this.hostId()) {
+            this.run = { key, tenantId, userId, revision, hostId: this.hostId(), bootId: brandString(randomUUID()), started: false };
+        }
+        return this.run;
+    }
+    current(run, signal) {
+        signal.throwIfAborted();
+        const state = this.ctx.merchantAccount.getState();
+        if (run.hostId !== this.hostId() || run.revision !== this.ctx.merchantAccount.getScopeRevision() || state.status !== 'signed-in'
+            || state.identity?.currentTenantId !== run.tenantId || state.identity.user.id !== run.userId)
+            throw new ObservationError('AGENT_CONFIG_HOST_UNAVAILABLE');
+    }
+    async load(hostId) {
+        let text;
+        try {
+            text = await readFile(join(this.options.stateRoot, `agent-config-${this.options.workspaceKind}-${hostId}.json`), 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw new ObservationError('AGENT_CONFIG_HOST_STATE_INVALID');
+            try {
+                text = await readFile(join(this.options.stateRoot, `agent-config-${this.options.workspaceKind}-host.json`), 'utf8');
+            }
+            catch (legacyError) {
+                if (legacyError.code !== 'ENOENT')
+                    throw new ObservationError('AGENT_CONFIG_HOST_STATE_INVALID');
+                return { version: 1, hostId: hostId, bootSequence: 0, scopes: {} };
+            }
+            const legacy = State.parse(JSON.parse(text));
+            if (legacy.hostId !== hostId)
+                return { version: 1, hostId: hostId, bootSequence: 0, scopes: {} };
+        }
+        const parsed = State.safeParse(JSON.parse(text));
+        if (!parsed.success || parsed.data.hostId !== hostId)
+            throw new ObservationError('AGENT_CONFIG_HOST_STATE_INVALID');
+        return parsed.data;
+    }
+    async migrate(run, member, explicitActivation) {
+        if (!explicitActivation && this.migrated.has(run.key))
+            return;
+        await mkdir(this.options.stateRoot, { recursive: true, mode: 0o700 });
+        const paths = (await readdir(this.options.stateRoot)).filter(path => path.startsWith(`agent-config-${this.options.workspaceKind}-`) && path.endsWith('.json'));
+        const legacy = await Promise.all(paths.map(async (path) => ({ path, state: State.parse(JSON.parse(await readFile(join(this.options.stateRoot, path), 'utf8'))) })));
+        await this.options.replacementState.importLegacy(member, this.options.workspaceKind, legacy.some(({ state }) => state.scopes[run.key]?.replaced === true));
+        for (const { path, state } of legacy) {
+            const record = state.scopes[run.key];
+            if (record?.replaced === undefined)
+                continue;
+            delete record.replaced;
+            await writeFileAtomic(join(this.options.stateRoot, path), JSON.stringify(state) + '\n', { mode: 0o600, dirMode: 0o700 });
+        }
+        this.migrated.add(run.key);
+    }
+    async save(state) {
+        await writeFileAtomic(join(this.options.stateRoot, `agent-config-${this.options.workspaceKind}-${state.hostId}.json`), JSON.stringify(state) + '\n', { mode: 0o600, dirMode: 0o700 });
+    }
+    async rememberReplacement(state, record, member) {
+        const saveModule = record.replaced !== true;
+        record.replaced = true;
+        const writes = await Promise.allSettled([
+            saveModule ? this.save(state) : Promise.resolve(),
+            this.options.replacementState.markReplaced(member),
+        ]);
+        for (const write of writes)
+            if (write.status === 'rejected')
+                throw new LocalHostReplacementWriteError(write.reason);
+    }
+    failure(failure) {
+        if (failure.kind === 'server' && failure.status === 409 && failure.code === 'LOCAL_HOST_REPLACED')
+            return new ObservationError(this.options.sandbox === undefined ? 'LOCAL_HOST_REPLACED' : 'AGENT_CONFIG_HOST_PROTOCOL');
+        if (failure.kind === 'server' && failure.status === 409 && failure.code === 'VERSION_CONFLICT')
+            return new ObservationError('AGENT_CONFIG_HOST_GENERATION_CONFLICT');
+        if (failure.kind === 'contract')
+            return new ObservationError('AGENT_CONFIG_HOST_PROTOCOL');
+        // An unbound sandbox session is retried: the cloud Host binds its placement instance after the reporter starts.
+        return new ObservationError(failure.kind === 'server' && (failure.status === 409 || failure.status === 404) ? 'AGENT_CONFIG_HOST_CONFLICT' : 'AGENT_CONFIG_HOST_UNAVAILABLE');
+    }
+    async attestSandbox(state, record, run, signal) {
+        const expected = this.options.sandbox;
+        if (expected === undefined)
+            return;
+        this.current(run, signal);
+        const result = await this.ctx.merchantAccount.request(getAgentConfigSandboxHost, {
+            params: { tenantId: run.tenantId, workspaceKind: this.options.workspaceKind },
+            query: { sandboxId: expected.sandboxId, instanceId: expected.instanceId }, tenantContextReload: 'caller',
+        }, signal).catch(() => { throw new ObservationError('AGENT_CONFIG_HOST_UNAVAILABLE'); });
+        this.current(run, signal);
+        if (!result.ok)
+            throw this.failure(result.failure);
+        const value = result.value;
+        if (String(value.tenantId) !== run.tenantId || String(value.userId) !== run.userId || value.workspaceKind !== this.options.workspaceKind
+            || value.sandboxBinding.sandboxId !== expected.sandboxId || value.sandboxBinding.instanceId !== expected.instanceId)
+            throw new ObservationError('AGENT_CONFIG_HOST_PROTOCOL');
+        if (run.started && !sameSandbox(run.sandboxBinding, value.sandboxBinding))
+            throw new ObservationError('AGENT_CONFIG_HOST_CONFLICT');
+        run.sandboxBinding = value.sandboxBinding;
+        if (record.pendingRegistration !== null && !sameSandbox(record.pendingRegistration.sandboxBinding, value.sandboxBinding)) {
+            record.pendingRegistration = null;
+            record.pendingReport = null;
+            record.running = null;
+        }
+        if (run.started)
+            return;
+        const registration = value.registration;
+        if (record.pendingReport !== null && (registration?.hostId !== run.hostId || registration.generation !== record.pendingReport.generation
+            || !sameSandbox(registration.sandboxBinding, value.sandboxBinding)))
+            record.pendingReport = null;
+        if (record.pendingRegistration === null)
+            record.generation = registration?.generation ?? 0;
+        state.bootSequence = Math.max(state.bootSequence, registration?.bootSequence ?? 0);
+        await this.save(state);
+    }
+    async registration(state, record, run, signal) {
+        const body = record.pendingRegistration;
+        if (body === null)
+            return;
+        if (this.options.sandbox !== undefined && (run.sandboxBinding === undefined || !sameSandbox(body.sandboxBinding, run.sandboxBinding)))
+            throw new ObservationError('AGENT_CONFIG_HOST_PROTOCOL');
+        this.current(run, signal);
+        const response = await this.ctx.merchantAccount.request(registerAgentConfigHost, { params: { tenantId: run.tenantId, workspaceKind: this.options.workspaceKind }, body, tenantContextReload: 'caller' }, signal)
+            .catch(() => { throw new ObservationError('AGENT_CONFIG_HOST_UNAVAILABLE'); });
+        this.current(run, signal);
+        if (!response.ok)
+            throw this.failure(response.failure);
+        const receipt = response.value;
+        if (receipt.workspaceKind !== this.options.workspaceKind || receipt.hostId !== run.hostId
+            || receipt.generation !== body.expectedGeneration + 1 || receipt.holder.kind === 'installation' && receipt.holder.id !== run.hostId
+            || this.options.sandbox !== undefined && (receipt.holder.kind !== 'sandbox' || receipt.holder.id !== this.options.sandbox.sandboxId))
+            throw new ObservationError('AGENT_CONFIG_HOST_PROTOCOL');
+        run.holder = receipt.holder.kind;
+        record.generation = receipt.generation;
+        record.running = { bootId: body.bootId, bootSequence: body.bootSequence, sequence: 0 };
+        record.pendingRegistration = null;
+        await this.save(state);
+    }
+    async observation(state, record, run, signal) {
+        const body = record.pendingReport;
+        if (body === null)
+            return;
+        this.current(run, signal);
+        const response = await this.ctx.merchantAccount.request(reportAgentConfigHost, {
+            params: { tenantId: run.tenantId, workspaceKind: this.options.workspaceKind, hostId: run.hostId }, body, tenantContextReload: 'caller',
+        }, signal).catch(() => { throw new ObservationError('AGENT_CONFIG_HOST_UNAVAILABLE'); });
+        this.current(run, signal);
+        if (!response.ok)
+            throw this.failure(response.failure);
+        const receipt = response.value;
+        if (receipt.generation !== body.generation || receipt.sequence !== body.sequence || record.running === null)
+            throw new ObservationError('AGENT_CONFIG_HOST_PROTOCOL');
+        record.running.sequence = receipt.sequence;
+        record.pendingReport = null;
+        await this.save(state);
+    }
+    /**
+     * Pending reports from an earlier run can be discarded on a generation conflict.
+     * Reporters without an explicit sandbox identity can also rebind a server-attested sandbox run.
+     * An explicitly bound live sandbox run stops on conflict.
+     * @returns whether the report was discarded and the run needs a new registration.
+     */
+    async replay(state, record, run, signal) {
+        try {
+            await this.observation(state, record, run, signal);
+        }
+        catch (error) {
+            if (!(error instanceof ObservationError) || error.code !== 'AGENT_CONFIG_HOST_GENERATION_CONFLICT'
+                || run.started && (this.options.sandbox !== undefined || run.holder !== 'sandbox'))
+                throw error;
+            record.pendingReport = null;
+            if (run.started) {
+                run.bootId = brandString(randomUUID());
+                run.started = false;
+            }
+            await this.save(state);
+            return true;
+        }
+        return false;
+    }
+    snapshot() {
+        const state = this.read();
+        const rejected = state.lastRejection;
+        const current = state.current.sha256 === null ? { source: 'builtin', version: state.current.version, sha256: null }
+            : { source: 'registry', version: state.current.version, sha256: state.current.sha256 };
+        return ModuleAgentConfigSnapshot.parse({ hostAgentConfigApiVersion: HOST_AGENT_CONFIG_API_VERSION, runtimeApiVersion: this.options.runtimeApiVersion,
+            current, ...(this.options.sandbox === undefined ? {} : { blockingFailure: state.blockingFailure === null ? null : { code: state.blockingFailure.code, committed: current } }),
+            pending: state.pending === null ? null : { version: state.pending.version, sha256: state.pending.sha256 }, blocked: state.blocked,
+            lastRejection: rejected === null ? null : { code: rejected.code,
+                target: rejected.version === undefined || rejected.sha256 === undefined ? null : { version: rejected.version, sha256: rejected.sha256 } },
+        });
+    }
+    async report(revision, explicitActivation = false, activated = false) {
+        if (this.lifetime.signal.aborted)
+            return;
+        if (explicitActivation)
+            this.stopped = undefined;
+        const run = this.scope(revision);
+        if (run === undefined) {
+            if (explicitActivation)
+                throw new ObservationError('AGENT_CONFIG_HOST_UNAVAILABLE');
+            return;
+        }
+        const member = this.member();
+        if (member === undefined)
+            return;
+        if (this.options.sandbox === undefined)
+            await this.migrate(run, member, explicitActivation);
+        if (explicitActivation)
+            await this.options.replacementState.markReplaced(member);
+        else if (activated && this.preparedHostId !== run.hostId)
+            throw new ObservationError('AGENT_CONFIG_HOST_UNAVAILABLE');
+        this.activationRequest = explicitActivation || activated;
+        const active = this.active = new AbortController();
+        const signal = AbortSignal.any([active.signal, this.lifetime.signal, AbortSignal.timeout(this.options.requestTimeoutMs)]);
+        try {
+            await mkdir(this.options.stateRoot, { recursive: true, mode: 0o700 });
+            await withFileLock(join(this.options.stateRoot, `agent-config-${this.options.workspaceKind}-${run.hostId}.json`), async () => {
+                this.current(run, signal);
+                const state = await this.load(run.hostId);
+                this.current(run, signal);
+                const record = state.scopes[run.key] ??= { generation: 0, running: null, pendingRegistration: null, pendingReport: null };
+                await this.attestSandbox(state, record, run, signal);
+                const uncertainGeneration = record.pendingRegistration?.expectedGeneration;
+                if (explicitActivation) {
+                    this.preparedRevision = undefined;
+                    this.preparedHostId = undefined;
+                    record.pendingRegistration = null;
+                    record.pendingReport = null;
+                    run.bootId = brandString(randomUUID());
+                    run.started = false;
+                }
+                else if (!activated && (this.replaced || record.pendingRegistration?.explicitActivation === true)) {
+                    await this.rememberReplacement(state, record, member);
+                    this.options.onReplaced?.(run.hostId);
+                    return;
+                }
+                try {
+                    if (run.started && record.running?.bootId !== run.bootId)
+                        throw new ObservationError('AGENT_CONFIG_HOST_CONFLICT');
+                    await this.registration(state, record, run, signal);
+                    await this.replay(state, record, run, signal);
+                    if (record.running?.bootId === run.bootId)
+                        run.started = true;
+                    // A discarded sandbox report registers again under this lock, so no other process sharing the file takes the Host in between.
+                    for (let rebinds = 0;; rebinds++) {
+                        if (!run.started) {
+                            if (state.bootSequence >= Number.MAX_SAFE_INTEGER)
+                                throw new ObservationError('AGENT_CONFIG_HOST_STATE_INVALID');
+                            state.bootSequence++;
+                            record.pendingRegistration = { hostId: run.hostId, bootId: run.bootId, requestId: randomUUID(), bootSequence: state.bootSequence, expectedGeneration: explicitActivation ? uncertainGeneration ?? record.generation : record.generation,
+                                ...(run.sandboxBinding === undefined ? {} : { sandboxBinding: run.sandboxBinding }), ...(explicitActivation ? { explicitActivation: true } : {}) };
+                            await this.save(state);
+                            try {
+                                await this.registration(state, record, run, signal);
+                            }
+                            catch (error) {
+                                if (!explicitActivation || uncertainGeneration === undefined || !(error instanceof ObservationError) || error.code !== 'AGENT_CONFIG_HOST_GENERATION_CONFLICT')
+                                    throw error;
+                                // An unacknowledged registration can have advanced the server by exactly one generation.
+                                const pending = record.pendingRegistration;
+                                record.pendingRegistration = { ...pending, requestId: randomUUID(), expectedGeneration: pending.expectedGeneration + 1 };
+                                await this.save(state);
+                                await this.registration(state, record, run, signal);
+                            }
+                            run.started = true;
+                        }
+                        if (explicitActivation) {
+                            this.preparedRevision = revision;
+                            this.preparedHostId = run.hostId;
+                            return;
+                        }
+                        if (record.running === null || record.running.sequence >= Number.MAX_SAFE_INTEGER)
+                            throw new ObservationError('AGENT_CONFIG_HOST_STATE_INVALID');
+                        record.pendingReport = { ...this.snapshot(), generation: record.generation, sequence: record.running.sequence + 1 };
+                        await this.save(state);
+                        if (!await this.replay(state, record, run, signal))
+                            break;
+                        if (rebinds > 0)
+                            throw new ObservationError('AGENT_CONFIG_HOST_UNAVAILABLE');
+                    }
+                    delete record.replaced;
+                    if (activated)
+                        await this.save(state);
+                }
+                catch (error) {
+                    if (this.options.sandbox === undefined && (explicitActivation || error instanceof ObservationError && error.code === 'LOCAL_HOST_REPLACED')) {
+                        await this.rememberReplacement(state, record, member);
+                        this.options.onReplaced?.(run.hostId);
+                    }
+                    throw error;
+                }
+            }, { signal, waitMs: this.options.requestTimeoutMs });
+        }
+        finally {
+            this.activationRequest = false;
+            if (this.active === active)
+                this.active = undefined;
+        }
+    }
+    async dispose() {
+        this.lifetime.abort();
+        this.active?.abort();
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.stopScope();
+        this.stopActivation();
+        this.stopActivated();
+        this.stopIdentity();
+        this.stopReplacement();
+        await this.chain;
+    }
+}

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

@@ -0,0 +1,78 @@
+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 recoverIdle;
+    private readonly lifetime;
+    private inFlight;
+    private requestAbort;
+    private requestRevision;
+    private readonly preparedRevisions;
+    private timer;
+    private selected;
+    private candidate;
+    private failure;
+    private rejection;
+    private admissionFailure;
+    private readonly root;
+    private observation;
+    private startup;
+    private blockedVersion;
+    /** @param registration - 内置模板及鉴权查询回调。 @param spec - 部署预算。 @param report - 固定失败诊断的报告者。 @param download - 文件 HTTP 传输。 @param recoverIdle - Provider 串行检查活动租约后恢复已阻断的配置；省略时保留候选等待获取工作区。 */
+    constructor(registration: WorkspaceAgentConfigRegistration, spec: WorkspaceBundlesSpec, report: (error: AgentConfigError) => void, download?: typeof fetch, recoverIdle?: () => Promise<void>);
+    /** @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>;
+    private recoverExecution;
+    /**
+     * 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.
+     */
+    recoverPhysical(digest: WorkspaceTemplateDigest | undefined, version?: string, sha256?: string | null): Promise<WorkspaceTemplate>;
+    private restoredTemplate;
+    private assertCompatible;
+    private configError;
+    private reportFailure;
+    /** @param restore - Restore this identity's committed journal before starting reports or queries; omission is for an owner without a journal. */
+    start(restore?: () => Promise<void>): void;
+    /** @returns 本次查询和完整候选下载结束；失败通过 state 与 report 保留可观察诊断。 */
+    refresh(): Promise<void>;
+    private refreshReady;
+    /** @returns 下一个 turn 可应用的候选；没有候选时使用已安装版本。 */
+    template(): WorkspaceTemplate;
+    /** @throws AgentConfigError while committed content is blocked, including when another lease remains active. */
+    assertExecutionAllowed(): void;
+    /** @param template - Pending template. @returns After compatibility and consumer validation, without selecting it. */
+    prepare(template: WorkspaceTemplate): Promise<void>;
+    private prepareValidated;
+    /** @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 rememberRejection;
+    private fetchCandidate;
+}