@gestaltrun/dsh-workspace-bundle 0.1.0 → 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

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 /** 本 Host 实现的 Agent 配置接口版本；白名单与写操作授权由 Host 保持。 */
-export declare const HOST_AGENT_CONFIG_API_VERSION = "1.0.0";
+export declare const HOST_AGENT_CONFIG_API_VERSION = "2.0.0";
 /** Agent 配置 SHA-256 的十六进制编码。 */
 export declare const AgentConfigSha256: z.ZodString;
 /** 内置 Workspace 种类；不含路径分隔符。 */
@@ -15,6 +15,7 @@ export declare const AgentConfigDescriptorSchema: z.ZodObject<{
     sizeBytes: z.ZodNumber;
     downloadUrl: z.ZodURL;
     hostAgentConfigApiRange: z.ZodString;
+    runtimeApiRange: z.ZodOptional<z.ZodString>;
     releaseNotes: z.ZodString;
 }, z.core.$strict>;
 /** 经解析的 server 分配。 */
@@ -61,8 +62,8 @@ export type AgentConfigErrorCode = 'AGENT_CONFIG_QUERY_FAILED' | 'AGENT_CONFIG_I
 /** 有界内容更新的结构化失败。 */
 export declare class AgentConfigError extends Error {
     readonly code: AgentConfigErrorCode;
-    /** @param code - 失败类别。 */
-    constructor(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;
@@ -79,7 +80,7 @@ export declare function contentPath(path: string): string;
  * @param maxExpandedBytes - 解压 JSON 和文件总字节上限。
  * @returns 清单和已校验文件。
  */
-export declare function decodeAgentConfig(bytes: Buffer, descriptor: AgentConfigDescriptor, maxExpandedBytes: number): {
+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

@@ -5,7 +5,7 @@ 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';
+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 种类；不含路径分隔符。 */
@@ -23,6 +23,7 @@ export const AgentConfigDescriptorSchema = z.strictObject({
     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),
 });
 /** 包内逐文件摘要与字节数，文件路径相对版本目录。 */
@@ -40,8 +41,8 @@ export const AgentConfigDocumentSchema = z.strictObject({
 /** 有界内容更新的结构化失败。 */
 export class AgentConfigError extends Error {
     code;
-    /** @param code - 失败类别。 */
-    constructor(code) {
+    /** @param code - 失败类别。 @param disposition - candidate 保留当前版本；blocked 表示已提交内容不可执行。 */
+    constructor(code, disposition = 'candidate') {
         const messages = {
             AGENT_CONFIG_QUERY_FAILED: 'Agent 配置版本查询失败，保留当前版本；请检查服务器连接。',
             AGENT_CONFIG_INVALID: 'Agent 配置文件或清单无效，保留当前版本；请重新打包发布。',
@@ -51,7 +52,9 @@ export class AgentConfigError extends Error {
             AGENT_CONFIG_APPLY_FAILED: 'Agent 配置应用失败；请检查工作区恢复状态后再继续。',
             AGENT_CONFIG_SCOPE_CHANGED: 'Agent 配置版本来源已变更，已丢弃旧候选；保留当前版本并重新查询。',
         };
-        super(messages[code]);
+        super(disposition === 'blocked'
+            ? '已提交的 Agent 配置未通过执行校验，自动客服已阻断；保留工作区与缓存，请重新分配兼容且完整的配置版本后再继续。'
+            : messages[code]);
         this.code = code;
         this.name = 'AgentConfigError';
     }

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;