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

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

@@ -0,0 +1,65 @@
+/**
+ * Branded identifiers. Each is a UUID string; the brand keeps ids of different entities apart at compile time.
+ * @module
+ */
+import { z } from 'zod';
+/** Identifier of a user. */
+export declare const UserId: z.core.$ZodBranded<z.ZodUUID, "UserId", "out">;
+/** Identifier of a user. */
+export type UserId = z.infer<typeof UserId>;
+/** Identifier of a tenant. */
+export declare const TenantId: z.core.$ZodBranded<z.ZodUUID, "TenantId", "out">;
+/** Identifier of a tenant. */
+export type TenantId = z.infer<typeof TenantId>;
+/** Identifier of a login attempt. */
+export declare const LoginAttemptId: z.core.$ZodBranded<z.ZodUUID, "LoginAttemptId", "out">;
+/** Identifier of a login attempt. */
+export type LoginAttemptId = z.infer<typeof LoginAttemptId>;
+/** Identifier of a role defined by a tenant. */
+export declare const RoleId: z.core.$ZodBranded<z.ZodUUID, "RoleId", "out">;
+/** Identifier of a role defined by a tenant. */
+export type RoleId = z.infer<typeof RoleId>;
+/** Identifier of a supplier. */
+export declare const SupplierId: z.core.$ZodBranded<z.ZodUUID, "SupplierId", "out">;
+/** Identifier of a supplier. */
+export type SupplierId = z.infer<typeof SupplierId>;
+/** Identifier of a supplier's contact. */
+export declare const ContactId: z.core.$ZodBranded<z.ZodUUID, "ContactId", "out">;
+/** Identifier of a supplier's contact. */
+export type ContactId = z.infer<typeof ContactId>;
+/** Identifier of a contract with a supplier. */
+export declare const ContractId: z.core.$ZodBranded<z.ZodUUID, "ContractId", "out">;
+/** Identifier of a contract with a supplier. */
+export type ContractId = z.infer<typeof ContractId>;
+/** Identifier of a supplier qualification, stable across updates and reordering. */
+export declare const QualificationId: z.core.$ZodBranded<z.ZodUUID, "QualificationId", "out">;
+/** Identifier of a supplier qualification. */
+export type QualificationId = z.infer<typeof QualificationId>;
+/** Identifier of a resource. */
+export declare const ResourceId: z.core.$ZodBranded<z.ZodUUID, "ResourceId", "out">;
+/** Identifier of a resource. */
+export type ResourceId = z.infer<typeof ResourceId>;
+/** Identifier of a sub-resource. */
+export declare const SubResourceId: z.core.$ZodBranded<z.ZodUUID, "SubResourceId", "out">;
+/** Identifier of a sub-resource. */
+export type SubResourceId = z.infer<typeof SubResourceId>;
+/** Identifier of an invite link. */
+export declare const InviteId: z.core.$ZodBranded<z.ZodUUID, "InviteId", "out">;
+/** Identifier of an invite link. */
+export type InviteId = z.infer<typeof InviteId>;
+/** Identifier of a sub-resource price rule. */
+export declare const PriceRuleId: z.core.$ZodBranded<z.ZodUUID, "PriceRuleId", "out">;
+/** Identifier of a price rule. */
+export type PriceRuleId = z.infer<typeof PriceRuleId>;
+/** Identifier of an object-storage file (an asset). */
+export declare const AssetId: z.core.$ZodBranded<z.ZodUUID, "AssetId", "out">;
+/** Identifier of an asset. */
+export type AssetId = z.infer<typeof AssetId>;
+/** Identifier of a source material. */
+export declare const MaterialId: z.core.$ZodBranded<z.ZodUUID, "MaterialId", "out">;
+/** Identifier of a source material. */
+export type MaterialId = z.infer<typeof MaterialId>;
+/** Identifier of a material reference. */
+export declare const MaterialReferenceId: z.core.$ZodBranded<z.ZodUUID, "MaterialReferenceId", "out">;
+/** Identifier of a material reference. */
+export type MaterialReferenceId = z.infer<typeof MaterialReferenceId>;

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

@@ -0,0 +1,35 @@
+/**
+ * Branded identifiers. Each is a UUID string; the brand keeps ids of different entities apart at compile time.
+ * @module
+ */
+import { z } from 'zod';
+/** Identifier of a user. */
+export const UserId = z.uuid().brand();
+/** Identifier of a tenant. */
+export const TenantId = z.uuid().brand();
+/** Identifier of a login attempt. */
+export const LoginAttemptId = z.uuid().brand();
+/** Identifier of a role defined by a tenant. */
+export const RoleId = z.uuid().brand();
+/** Identifier of a supplier. */
+export const SupplierId = z.uuid().brand();
+/** Identifier of a supplier's contact. */
+export const ContactId = z.uuid().brand();
+/** Identifier of a contract with a supplier. */
+export const ContractId = z.uuid().brand();
+/** Identifier of a supplier qualification, stable across updates and reordering. */
+export const QualificationId = z.uuid().brand();
+/** Identifier of a resource. */
+export const ResourceId = z.uuid().brand();
+/** Identifier of a sub-resource. */
+export const SubResourceId = z.uuid().brand();
+/** Identifier of an invite link. */
+export const InviteId = z.uuid().brand();
+/** Identifier of a sub-resource price rule. */
+export const PriceRuleId = z.uuid().brand();
+/** Identifier of an object-storage file (an asset). */
+export const AssetId = z.uuid().brand();
+/** Identifier of a source material. */
+export const MaterialId = z.uuid().brand();
+/** Identifier of a material reference. */
+export const MaterialReferenceId = z.uuid().brand();

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

@@ -0,0 +1,56 @@
+/**
+ * Framework-free route descriptions: the server binds them to handlers, clients read them to build requests.
+ * @module
+ */
+import type { z } from 'zod';
+import type { ErrorCode } from './errors.ts';
+/** A response of one status code: a JSON body described by `schema`, or no body when `schema` is absent. */
+export interface ResponseDefinition {
+    readonly description: string;
+    readonly schema?: z.ZodType;
+    readonly headers?: Readonly<Record<string, {
+        readonly description: string;
+        readonly schema: z.ZodType;
+    }>>;
+}
+/** Path parameters, query parameters and JSON request body of one endpoint. */
+export interface RequestDefinition {
+    readonly params?: z.ZodObject;
+    readonly query?: z.ZodObject;
+    readonly headers?: z.ZodObject;
+    readonly body?: z.ZodType;
+}
+/**
+ * Who may call an endpoint. `session`: the request carries `Authorization: Bearer <session token>`,
+ * and a missing token answers 401 `SESSION_REQUIRED`, an unknown, expired or revoked one 401
+ * `SESSION_EXPIRED`. `tenant`: a `session` route under `/v1/tenants/{tenantId}` that acts in the
+ * session's current tenant; after the session checks, the server answers 403 `NO_CURRENT_TENANT`
+ * when the session has no current tenant (personal use), 409 `TENANT_NOT_CURRENT` when `tenantId`
+ * is not the current tenant (a request sent before the client switched), and 403 `NOT_A_MEMBER`
+ * when the user is no longer a member of it. Each of the three means the client's view of the
+ * current tenant is stale (a switch in another window, or removal from the tenant, which also
+ * clears the session's current tenant): the client reloads `GET /v1/me` and closes pages that no
+ * longer apply before it shows anything; for 409 it shows no failure at all. The codes are
+ * `TENANT_CONTEXT_CODES`. `none`: callable without a session.
+ */
+/** `operator`：独立运维令牌，缺少时 OPERATOR_SESSION_REQUIRED，失效时 OPERATOR_SESSION_EXPIRED；与商家会话互不替代。 */
+/** `service`：server 签发的服务凭据，`Authorization: Bearer`。缺少时 401 `SERVICE_CREDENTIAL_REQUIRED`，不匹配时 401 `SERVICE_CREDENTIAL_REJECTED`。 */
+/** `space`：WeKnora 数据源保存的空间令牌，`Authorization: Bearer`。缺少时 401 `SPACE_TOKEN_REQUIRED`，不匹配时 401 `SPACE_TOKEN_REJECTED`。令牌绑定的主账号没有店铺租户时 403 `SEGMENT_SPACE_FORBIDDEN`。 */
+export type RouteAuth = 'session' | 'tenant' | 'operator' | 'service' | 'space' | 'none';
+/** Method, path, request, success responses and route-specific problem codes of one v1 endpoint. */
+export interface RouteDefinition {
+    readonly method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    /** OpenAPI path template, such as `/v1/tenants/{tenantId}`. */
+    readonly path: string;
+    readonly summary: string;
+    readonly auth: RouteAuth;
+    readonly request?: RequestDefinition;
+    readonly responses: Readonly<Record<number, ResponseDefinition>>;
+    /**
+     * Problem codes this route answers, by HTTP status, besides the ones every `/v1` route can answer
+     * (422 `VALIDATION_FAILED`, 426 `CLIENT_UPGRADE_REQUIRED`, 500 `INTERNAL`).
+     */
+    /** 错误响应的可选头；请求与响应声明仍由契约包拥有。 */
+    readonly problemHeaders?: Readonly<Record<number, NonNullable<ResponseDefinition['headers']>>>;
+    readonly problems?: Readonly<Record<number, readonly ErrorCode[]>>;
+}

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

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

package/lib/types/agent-config-contract/test-account-claim.d.ts

@@ -0,0 +1,24 @@
+/** 测试账号当前占用；不自动过期，Issue 仓库与编号共同标识持有方。 */
+import { z } from 'zod';
+export declare const TestAccountIssue: z.ZodObject<{
+    repo: z.ZodDefault<z.ZodString>;
+    number: z.ZodNumber;
+}, z.core.$strict>;
+export declare const TestAccountClaim: z.ZodObject<{
+    issue: z.ZodObject<{
+        repo: z.ZodDefault<z.ZodString>;
+        number: z.ZodNumber;
+    }, z.core.$strict>;
+    demandName: z.ZodString;
+    claimedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type TestAccountClaim = z.infer<typeof TestAccountClaim>;
+export declare const SandboxUpgradeHold: z.ZodObject<{
+    issue: z.ZodObject<{
+        repo: z.ZodDefault<z.ZodString>;
+        number: z.ZodNumber;
+    }, z.core.$strict>;
+    demandName: z.ZodString;
+    claimedAt: z.ZodISODateTime;
+    targetVersion: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;

package/lib/types/agent-config-contract/test-account-claim.js

@@ -0,0 +1,5 @@
+/** 测试账号当前占用；不自动过期，Issue 仓库与编号共同标识持有方。 */
+import { z } from 'zod';
+export const TestAccountIssue = z.strictObject({ repo: z.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/).max(201).default('gestaltrun/deepseek-harness'), number: z.number().int().positive().max(Number.MAX_SAFE_INTEGER) });
+export const TestAccountClaim = z.strictObject({ issue: TestAccountIssue, demandName: z.string().trim().min(1).max(300), claimedAt: z.iso.datetime() }).meta({ id: 'TestAccountClaim' });
+export const SandboxUpgradeHold = TestAccountClaim.extend({ targetVersion: z.string().nullable().describe('当前因占用被跳过的自动升级版本；尚未跳过为 null') }).meta({ id: 'SandboxUpgradeHold' });

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

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+/** 本 Host 实现的 Agent 配置接口版本；白名单与写操作授权由 Host 保持。 */
+export declare const HOST_AGENT_CONFIG_API_VERSION = "2.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;
+    runtimeApiRange: z.ZodOptional<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 - 失败类别。 @param disposition - candidate 保留当前版本；blocked 表示已提交内容不可执行。 */
+    constructor(code: AgentConfigErrorCode, disposition?: 'candidate' | 'blocked');
+}
+/** @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<D extends Pick<AgentConfigDescriptor, 'workspaceKind' | 'version' | 'sha256' | 'sizeBytes' | 'hostAgentConfigApiRange'>>(bytes: Buffer, descriptor: D, maxExpandedBytes: number): {
+    readonly manifest: AgentConfigManifest;
+    readonly files: readonly AgentConfigFile[];
+};

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

@@ -0,0 +1,119 @@
+/** 内置 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 = '2.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),
+    runtimeApiRange: z.string().refine(value => semver.validRange(value) !== null).optional(),
+    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 - 失败类别。 @param disposition - candidate 保留当前版本；blocked 表示已提交内容不可执行。 */
+    constructor(code, disposition = 'candidate') {
+        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(disposition === 'blocked'
+            ? '已提交的 Agent 配置未通过执行校验，自动客服已阻断；保留工作区与缓存，请重新分配兼容且完整的配置版本后再继续。'
+            : 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-observation.d.ts

@@ -0,0 +1,64 @@
+/** Durable, authenticated module observations independent of tasks and business leases. */
+import type { Context } from '@deepseek-ai/cordis';
+import { type Branded } from '@deepseek-ai/dsh-brand';
+import { type LocalHostReplacement } from './local-host-replacement.ts';
+import type { WorkspaceAgentConfigState } from './agent-config-types.ts';
+import { type AgentConfigModule } from './agent-config-contract/agent-configs.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /** Explicitly register each composed module for the same authenticated scope. @mode parallel @param revision - merchant scope at the user's click. @param registered - modules whose registration succeeded. */
+        'workspace-bundle/activate-local-host'(revision: number, registered: Set<AgentConfigModule>): Promise<void>;
+        /** Resume observations after every module registration succeeded. @mode parallel @param revision - authenticated activation scope. */
+        'workspace-bundle/local-host-activated'(revision: number): Promise<void>;
+        /** Re-read each module's installation identity before its next registration. @mode parallel */
+        'workspace-bundle/local-host-identity-changed'(): Promise<void>;
+    }
+}
+/** Deployment identity verified against the authenticated sandbox before any registration or report. */
+export interface WorkspaceAgentConfigSandbox {
+    readonly sandboxId: Branded<'SandboxId'>;
+    readonly instanceId: Branded<'SandboxHostInstanceId'>;
+}
+/** Per-source reporter lifetime. */
+export interface WorkspaceAgentConfigObservation {
+    /** This authenticated module is stopped until explicit activation. */
+    readonly replaced: boolean;
+    /** @returns after the current authenticated report or its contained failure. */
+    refresh(): Promise<void>;
+    /** Cancel requests and timers, then wait for file and transport work. @returns after no callback can report again. */
+    dispose(): Promise<void>;
+}
+/** Persistent identity reused by an installation across module observation runs. */
+export type WorkspaceAgentConfigHostId = Branded<'WorkspaceAgentConfigHostId'>;
+/** Settings resolved by the module owning its persistent Host identity. */
+export interface WorkspaceAgentConfigObservationOptions {
+    readonly workspaceKind: AgentConfigModule;
+    /** Shared member fence owned by WorkspaceBundles. */
+    readonly replacementState: LocalHostReplacement;
+    /** Fixed identity or the module's current installation getter; emit local-host-identity-changed after binding changes. */
+    readonly hostId: WorkspaceAgentConfigHostId | (() => WorkspaceAgentConfigHostId);
+    readonly stateRoot: string;
+    readonly runtimeApiVersion: string | null;
+    readonly intervalMs: number;
+    readonly requestTimeoutMs: number;
+    /** Explicit cloud deployment; omission retains installation activation and replacement handling. */
+    readonly sandbox?: WorkspaceAgentConfigSandbox;
+    /** Notify the owning module when the shared replacement fence is set; omission leaves the status available on the reporter. @param hostId - identity of the rejected run. */
+    readonly onReplaced?: (hostId: WorkspaceAgentConfigHostId) => void;
+}
+/**
+ * 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 declare function agentConfigHostObservation(ctx: Context, options: WorkspaceAgentConfigObservationOptions): (read: () => WorkspaceAgentConfigState) => WorkspaceAgentConfigObservation;
+/**
+ * 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 declare function sandboxAgentConfigHostObservation(ctx: Context, options: WorkspaceAgentConfigObservationOptions & {
+    readonly sandbox: WorkspaceAgentConfigSandbox;
+}): (read: () => WorkspaceAgentConfigState) => WorkspaceAgentConfigObservation;