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

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

@@ -0,0 +1,68 @@
+/** 内置 workspace Agent 配置：查询本人当前店铺租户的分配，兼容性由 Host 检查。 @module */
+import { z } from 'zod';
+import { AgentConfigSemver, AgentConfigErrorCode } from "./cs-hosting.js";
+import { TenantId, UserId } from "./ids.js";
+/** 可扩展的内置 workspace 种类；首个种类为 cs-hosting。 */
+export const WorkspaceKind = z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/).max(80).meta({ id: 'WorkspaceKind' });
+/** Agent 配置登记的完整元数据；sha256 来自经 PR 审阅的规则文件。 */
+export const AgentConfig = z.object({ workspaceKind: WorkspaceKind, version: z.string().min(1), sha256: z.string().regex(/^[a-f0-9]{64}$/), sizeBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER), downloadUrl: z.url({ protocol: /^https$/ }), hostContentApiRange: z.string().min(1), releaseNotes: z.string().min(1).max(20000) }).meta({ id: 'AgentConfig' });
+/** builtin 表示没有分配：已有下载版本时保留当前版本，从未下载时使用安装包内置版本。 */
+export const AgentConfigAssignment = z.discriminatedUnion('source', [
+    z.object({ source: z.literal('builtin'), tenantId: TenantId, userId: UserId, workspaceKind: WorkspaceKind }),
+    z.object({ source: z.literal('registry'), tenantId: TenantId, userId: UserId, workspaceKind: WorkspaceKind, agentConfig: AgentConfig }),
+]).meta({ id: 'AgentConfigAssignment' });
+/** 路径中的租户必须是会话当前租户；用户由会话确定，不接受调用方指定。 */
+export const AgentConfigParams = z.object({ tenantId: TenantId, workspaceKind: WorkspaceKind }).meta({ id: 'AgentConfigParams' });
+/** Host 在启动和轮询时查询；不按版本大小排序，回退可返回更低版本；服务不可达时保留当前版本。 */
+export const getAgentConfigAssignment = {
+    method: 'get', path: '/v1/tenants/{tenantId}/agent-configs/{workspaceKind}', summary: '查询本人内置 workspace Agent 配置分配', auth: 'tenant',
+    request: { params: AgentConfigParams, query: z.strictObject({}) },
+    responses: { 200: { description: '分配版本或使用内置版本；Host 检查兼容范围并核对下载字节的 sha256', schema: AgentConfigAssignment, headers: { 'Cache-Control': { description: '每次读取当前分配，及时观察回退', schema: z.literal('no-store') } } } },
+    problems: { 401: ['SESSION_REQUIRED', 'SESSION_EXPIRED'], 403: ['NO_CURRENT_TENANT', 'NOT_A_MEMBER', 'AGENT_CONFIGS_UNAVAILABLE'], 409: ['TENANT_NOT_CURRENT'] },
+};
+/** 双模块观测与控制仅支持已实现的模块；不设默认种类。 */
+export const AgentConfigModule = z.enum(['cs-hosting', 'resource-intake']).meta({ id: 'AgentConfigModule' });
+export const AgentConfigDigest = z.string().regex(/^[a-f0-9]{64}$/);
+const sequence = z.number().int().min(1).max(Number.MAX_SAFE_INTEGER);
+const generation = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+/** 完整身份包括 build metadata；builtin 没有远端归档摘要。 */
+export const AgentConfigCommitted = z.discriminatedUnion('source', [
+    z.strictObject({ source: z.literal('builtin'), version: AgentConfigSemver, sha256: z.null() }),
+    z.strictObject({ source: z.literal('registry'), version: AgentConfigSemver, sha256: AgentConfigDigest }),
+]).meta({ id: 'AgentConfigCommitted' });
+export const AgentConfigTarget = z.strictObject({ version: AgentConfigSemver, sha256: AgentConfigDigest }).meta({ id: 'AgentConfigTarget' });
+/** 已提交版本恢复/采用的独立阻断原因；不随候选目标拒绝变化，不含诊断正文。 */
+export const AgentConfigBlockingFailure = z.strictObject({ code: AgentConfigErrorCode, committed: AgentConfigCommitted }).meta({ id: 'AgentConfigBlockingFailure' });
+/** 固定码与精确目标归因；查询失败不能作为采用拒绝。 */
+export const ModuleAgentConfigSnapshot = z.strictObject({
+    hostAgentConfigApiVersion: AgentConfigSemver, runtimeApiVersion: AgentConfigSemver.nullable(),
+    current: AgentConfigCommitted, pending: AgentConfigTarget.nullable(), blocked: z.boolean(),
+    lastRejection: z.strictObject({ code: AgentConfigErrorCode, target: AgentConfigTarget.nullable() }).nullable(),
+    blockingFailure: AgentConfigBlockingFailure.nullable().optional(),
+}).meta({ id: 'ModuleAgentConfigSnapshot' });
+/** 服务端从当前有效 sandbox 会话和活动 placement key 解析的绑定；不是调用方可指定的身份。 */
+export const AgentConfigSandboxBinding = z.strictObject({ sandboxId: z.uuid(), instanceId: z.string().min(1).max(200), sandboxGeneration: generation }).meta({ id: 'AgentConfigSandboxBinding' });
+/** 云端读回只要求现有 sandbox/instance 配置；代次由服务端提供。 */
+export const ReadAgentConfigSandboxHostQuery = AgentConfigSandboxBinding.pick({ sandboxId: true, instanceId: true }).meta({ id: 'ReadAgentConfigSandboxHostQuery' });
+/** 外层绑定为本次认证的当前实例；内层为已存注册，可来自旧实例。null 表示尚无注册。 */
+export const AgentConfigSandboxHostReadback = z.strictObject({
+    tenantId: TenantId, userId: UserId, workspaceKind: AgentConfigModule, sandboxBinding: AgentConfigSandboxBinding,
+    registration: z.strictObject({ hostId: z.uuid(), generation: sequence, bootSequence: sequence, sandboxBinding: AgentConfigSandboxBinding }).nullable(),
+}).meta({ id: 'AgentConfigSandboxHostReadback' });
+/** bootSequence 随 device 持久递增；sandbox 丢失状态时先在本地锁内读回，再携带绑定与明确代次 CAS，不盲目重试。 */
+export const RegisterAgentConfigHostRequest = z.strictObject({ hostId: z.uuid(), bootId: z.uuid(), requestId: z.uuid(), bootSequence: sequence, expectedGeneration: generation, explicitActivation: z.boolean().optional(), sandboxBinding: AgentConfigSandboxBinding.optional() }).meta({ id: 'RegisterAgentConfigHostRequest' });
+export const AgentConfigHostRegistration = z.strictObject({ workspaceKind: AgentConfigModule, hostId: z.uuid(), generation: sequence, holder: z.strictObject({ kind: z.enum(['installation', 'sandbox']), id: z.uuid() }) }).meta({ id: 'AgentConfigHostRegistration' });
+export const ReportAgentConfigHostRequest = ModuleAgentConfigSnapshot.extend({ generation: sequence, sequence }).meta({ id: 'ReportAgentConfigHostRequest' });
+export const AgentConfigHostReceipt = z.strictObject({ generation: sequence, sequence, reportedAt: z.iso.datetime() }).meta({ id: 'AgentConfigHostReceipt' });
+const hostProblems = { 401: ['SESSION_REQUIRED', 'SESSION_EXPIRED'], 403: ['NO_CURRENT_TENANT', 'NOT_A_MEMBER', 'AGENT_CONFIGS_UNAVAILABLE', 'SANDBOX_SESSION_UNBOUND'], 404: ['NOT_FOUND'], 409: ['TENANT_NOT_CURRENT', 'VERSION_CONFLICT', 'OPERATION_CONFLICT', 'LOCAL_HOST_REPLACED'], 503: ['SERVICE_UNAVAILABLE'] };
+const hostHeaders = { 'Cache-Control': { description: '观测与回执不得缓存', schema: z.literal('no-store') } };
+export const getAgentConfigSandboxHost = { method: 'get', path: '/v1/tenants/{tenantId}/agent-configs/{workspaceKind}/hosts/current', summary: '只读本人当前沙箱模块 Host 注册，不允许本机安装调用', auth: 'tenant', request: { params: AgentConfigParams, query: ReadAgentConfigSandboxHostQuery }, responses: { 200: { description: 'sandboxId/instanceId 须匹配当前已认证 sandbox；返回服务端代次及已存注册，读回不授予业务权限，重新注册须携带完整 sandboxBinding 和明确 expectedGeneration', schema: AgentConfigSandboxHostReadback, headers: hostHeaders } }, problems: hostProblems };
+export const registerAgentConfigHost = { method: 'post', path: '/v1/tenants/{tenantId}/agent-configs/{workspaceKind}/hosts/register', summary: '注册本人模块 Host 运行，不取得业务写权限', auth: 'tenant', request: { params: AgentConfigParams, body: RegisterAgentConfigHostRequest }, responses: { 200: { description: '服务端绑定 holder；提供 sandboxBinding 时须在事务内匹配当前 sandbox/instance/代次，installation 不接受该字段；新运行以 bootSequence 和 expectedGeneration 比较更新，旧运行不可复活', schema: AgentConfigHostRegistration, headers: hostHeaders } }, problems: hostProblems };
+export const reportAgentConfigHost = { method: 'put', path: '/v1/tenants/{tenantId}/agent-configs/{workspaceKind}/hosts/{hostId}/observation', summary: '上报本人模块 Host 的完整采用快照', auth: 'tenant', request: { params: AgentConfigParams.extend({ hostId: z.uuid() }), body: ReportAgentConfigHostRequest }, responses: { 200: { description: '同序同内容返回原接收时间，同序异内容或旧代次冲突；时间由服务端确定', schema: AgentConfigHostReceipt, headers: hostHeaders } }, problems: hostProblems };
+/** 仅新模块契约暴露可选runtime要求；旧assignment显式投影原AgentConfig。 */
+export const ModuleAgentConfigMetadata = AgentConfig.extend({ runtimeApiRange: z.string().min(1).optional() }).meta({ id: 'ModuleAgentConfigMetadata' });
+export const ModuleAgentConfigAssignment = z.discriminatedUnion('source', [
+    z.object({ source: z.literal('builtin'), tenantId: TenantId, userId: UserId, workspaceKind: AgentConfigModule }),
+    z.object({ source: z.literal('registry'), tenantId: TenantId, userId: UserId, workspaceKind: AgentConfigModule, agentConfig: ModuleAgentConfigMetadata }),
+]).meta({ id: 'ModuleAgentConfigAssignment' });
+export const getModuleAgentConfigAssignment = { ...getAgentConfigAssignment, path: '/v1/tenants/{tenantId}/agent-configs/{workspaceKind}/module', summary: '查询显式模块分配与runtime要求', responses: { 200: { ...getAgentConfigAssignment.responses[200], schema: ModuleAgentConfigAssignment } }, problems: hostProblems };