@ct-agents/worker 0.1.8 → 0.2.0

package/src/index.ts

@@ -1,8 +1,8 @@
 import type {
   ContextResolveQueue,
+  ContextResolveQueueClaimInput,
   ContextResolveResult,
   ContextResolveWorkItem,
-  Database,
   EnvironmentId,
   EnvironmentExecutionMode,
   EnvironmentHostedPolicy,
@@ -10,6 +10,7 @@ import type {
   HarnessId,
   ResourceSlots,
   SessionEvent,
+  SessionEventActor,
   SessionId,
   SessionRecord,
   ToolExecution,
@@ -19,12 +20,15 @@ import type {
   ToolHandlerContext,
   ToolRegistry,
   ToolWorkItem,
-  WorkQueue,
-  WorkStats,
-  CompleteWorkItemScope,
-  RenewWorkItemLeaseInput,
+  WorkerCapabilityRegistration,
+  WorkerCompleteWorkItemScope,
+  WorkerRenewWorkItemLeaseInput,
+  WorkerWorkQueue,
 } from '@ct-agents/protocol';
+import type { ToolExecutionContract } from '@ct-agents/protocol';
+import { digestToolExecutionContract, normalizeToolExecutionContract } from '@ct-agents/environment';
 import type { MemoryResource, SkillResource } from '@ct-agents/protocol';
+import { assertToolResultWireValue } from '@ct-agents/protocol';
 import { createLoadMemoryToolHandler, createUpdateMemoryToolHandler } from '@ct-agents/memory';
 import { createLoadSkillToolHandler } from '@ct-agents/prompts';
 import { createSandboxTools } from '@ct-agents/tools';
@@ -34,15 +38,22 @@ import {
   createWebSearchToolHandler,
 } from '@ct-agents/tools/builtin-tools';
 import { z } from 'zod';
-import {
-  createPlatformDatabaseProxyResource,
-  createPlatformResourceProxy,
-} from './resources/platform-proxy.js';
+import { createPlatformResourceProxy } from './resources/platform-proxy.js';
+import { WorkerHttpTransport } from './worker-http-transport.js';
+import { runLeasedItem } from './leased-item-runner.js';
+
+export { WorkerHttpError } from './worker-http-transport.js';
+export { DEFAULT_WORK_LEASE_RENEW_INTERVAL_MS } from './leased-item-runner.js';
 
 export type ResolveResources = (item: ToolWorkItem) => Promise<ResourceSlots> | ResourceSlots;
 export type ResolvePromptContext = (item: ContextResolveWorkItem) =>
   Promise<Record<string, unknown>> | Record<string, unknown>;
 
+export type WorkerContextResolveQueue = Pick<
+  ContextResolveQueue,
+  'claim' | 'renew' | 'complete'
+>;
+
 export type ResourceOptionsParser = {
   parse(value: unknown): Record<string, unknown>;
 };
@@ -86,9 +97,7 @@ export type WorkerSandboxManager = {
 };
 
 export type EnvironmentWorkerInput = {
-  appId: string;
-  environmentId: string;
-  workQueue: WorkQueue;
+  workQueue: WorkerWorkQueue;
   toolRegistry: ToolRegistry;
   resources?: ResourceSlots;
   resolveResources?: ResolveResources;
@@ -97,7 +106,7 @@ export type EnvironmentWorkerInput = {
   abortSignal?: AbortSignal;
   /** 单进程持续允许的最大 active Tool work 数。 */
   maxConcurrency?: number;
-  /** active Tool lease 的续租周期，必须小于 loop 的 reclaimOlderThanMs。 */
+  /** active Tool lease 的续租周期。 */
   leaseRenewIntervalMs?: number;
   onError?: (error: unknown) => void | Promise<void>;
   harness?: {
@@ -118,37 +127,30 @@ export type RunEnvironmentWorkerLoopInput = EnvironmentWorkerInput & {
   blockMs?: number;
   idleDelayMs?: number;
   errorDelayMs?: number;
-  reclaimOlderThanMs?: number;
-  reclaimIntervalMs?: number;
   sandboxManager?: WorkerSandboxManager;
   sandboxIdleTtlMs?: number;
   onError?: (error: unknown) => void | Promise<void>;
 };
 
 export type ContextResolverWorkerInput = {
-  appId: string;
-  environmentId: string;
-  contextResolveQueue: ContextResolveQueue;
+  /** 本地/内存队列可选的不透明路由句柄；HTTP client 已由 Environment Key 绑定。 */
+  scope?: ExecutionScope;
+  contextResolveQueue: WorkerContextResolveQueue;
   resolvePromptContext: ResolvePromptContext;
   maxBatchSize?: number;
   executionMode?: EnvironmentExecutionMode;
+  leaseRenewIntervalMs?: number;
+  onError?: (error: unknown) => void | Promise<void>;
 };
 
 export type RunContextResolverWorkerLoopInput = ContextResolverWorkerInput & {
   abortSignal?: AbortSignal;
   idleDelayMs?: number;
   errorDelayMs?: number;
-  reclaimOlderThanMs?: number;
-  reclaimIntervalMs?: number;
-  onError?: (error: unknown) => void | Promise<void>;
 };
 
-export const DEFAULT_RECLAIM_OLDER_THAN_MS = 300_000;
-export const DEFAULT_RECLAIM_INTERVAL_MS = 60_000;
 export const DEFAULT_CLAIM_BLOCK_MS = 15_000;
-export const DEFAULT_WORK_LEASE_RENEW_INTERVAL_MS = 60_000;
-
-const PLATFORM_PROXY_RESOURCE_SLOTS = new Set(['database', 'skills', 'memory']);
+const PLATFORM_PROXY_RESOURCE_SLOTS = new Set(['skills', 'memory']);
 
 export function createPlatformBuiltinToolHandlers(): ToolHandler[] {
   return [
@@ -166,6 +168,40 @@ function withPlatformBuiltinTools(registry: ToolRegistry): ToolRegistry {
   return new PlatformBuiltinToolRegistry(registry, createPlatformBuiltinToolHandlers());
 }
 
+export function createWorkerCapabilityRegistration(input: {
+  workerInstanceId: string;
+  implementationReleaseId: string;
+  toolRegistry: ToolRegistry;
+  resourceImpls: EnvironmentWorkerResourceImplementations;
+}): WorkerCapabilityRegistration {
+  const toolRegistry = withPlatformBuiltinTools(input.toolRegistry);
+  const toolCapabilities = toolRegistry.listTools().map((descriptor) => {
+    const contract = normalizeToolExecutionContract({
+      contractFormatVersion: 1,
+      toolName: descriptor.name,
+      inputSchema: descriptor.inputSchema,
+      requiredResources: descriptor.requiredResources ?? [],
+      annotations: descriptor.annotations,
+      compatibilityGeneration: descriptor.compatibilityGeneration ?? 1,
+    } satisfies ToolExecutionContract);
+    return {
+      contractDigest: digestToolExecutionContract(contract),
+      contract,
+      toolName: descriptor.name,
+      implementationId: `${input.implementationReleaseId}:${descriptor.name}`,
+    };
+  });
+  const resourceCapabilities = Object.entries(input.resourceImpls).flatMap(([slot, implementations]) => (
+    Object.keys(implementations).map((implementationId) => ({ slot, implementationId }))
+  ));
+  return {
+    workerInstanceId: input.workerInstanceId,
+    implementationReleaseId: input.implementationReleaseId,
+    toolCapabilities,
+    resourceCapabilities,
+  };
+}
+
 function normalizeNonNegativeInteger(value: number | undefined, fallback: number): number {
   if (value === undefined || !Number.isFinite(value)) {
     return fallback;
@@ -214,10 +250,14 @@ class PlatformBuiltinToolRegistry implements ToolRegistry {
   }
 }
 
+type EnvironmentWorkExecution =
+  | { kind: 'completed'; result: ToolExecutionResult }
+  | { kind: 'failed'; result: ToolExecutionResult; cause: unknown };
+
 /**
  * 独立执行面 worker。
  *
- * worker 只通过 WorkQueue 认领当前 app/environment 的业务 tool 工作项，并在本地
+ * worker 只通过 Environment Key 绑定的队列认领业务 Tool Work，并在本地
  * ToolRegistry/ResourceSlots 中执行 handler。它不持消费端 key，也不直接创建或读取 session。
  */
 export class EnvironmentWorker {
@@ -241,11 +281,7 @@ export class EnvironmentWorker {
   }
 
   public async claim(max: number, options: DrainOnceOptions = {}): Promise<ToolWorkItem[]> {
-    const executionMode = this.input.executionMode ?? 'self_hosted';
     return this.input.workQueue.claim({
-      appId: this.input.appId,
-      environmentId: this.input.environmentId,
-      executionMode,
       max: normalizePositiveInteger(max, 1),
       blockMs: options.blockMs,
     });
@@ -255,74 +291,46 @@ export class EnvironmentWorker {
     if (!item.leaseId) {
       throw new Error(`claimed work item 缺少 leaseId：${item.workId}`);
     }
-    const renewController = new AbortController();
-    const renewal = this.renewLeaseUntilStopped(item, renewController.signal);
-    try {
-      let result: ToolExecutionResult;
-      const disposers: Array<() => Promise<void>> = [];
-      try {
-        const handler = this.input.toolRegistry.getTool(item.toolName);
-        const execution = await this.executeHandler(handler, item, disposers);
-        result = toToolExecutionResult(item.workId, handler, execution);
-      } catch (error) {
-        const accepted = await this.input.workQueue.complete({
-          workId: item.workId,
-          status: 'failed',
-          error: toWorkerErrorPayload(error),
-        }, this.buildCompleteScope(item));
-        if (!accepted) {
-          throw new Error(`work complete 未被接受：${item.workId}`);
-        }
-        return;
-      } finally {
-        await Promise.all(disposers.map(async (dispose) => {
-          await dispose().catch(() => undefined);
-        }));
-      }
-
-      const accepted = await this.input.workQueue.complete(result, this.buildCompleteScope(item));
-      if (!accepted) {
-        throw new Error(`work complete 未被接受：${item.workId}`);
-      }
-    } finally {
-      renewController.abort();
-      await renewal;
-    }
-  }
-
-  private async renewLeaseUntilStopped(item: ToolWorkItem, signal: AbortSignal): Promise<void> {
     const leaseId = item.leaseId;
-    if (!leaseId) {
-      return;
-    }
-    const intervalMs = normalizePositiveInteger(
-      this.input.leaseRenewIntervalMs,
-      DEFAULT_WORK_LEASE_RENEW_INTERVAL_MS,
-    );
-    while (!signal.aborted) {
-      await delay(intervalMs, signal);
-      if (signal.aborted) {
-        return;
-      }
-      try {
-        const renewed = await this.input.workQueue.renew({
+    await runLeasedItem<EnvironmentWorkExecution>({
+      renewal: {
+        intervalMs: this.input.leaseRenewIntervalMs,
+        renew: () => this.input.workQueue.renew({
           workId: item.workId,
           leaseId,
-          appId: this.input.appId,
-          environmentId: this.input.environmentId,
-          executionMode: this.input.executionMode ?? item.executionMode ?? 'self_hosted',
-        });
-        if (!renewed) {
-          return;
-        }
-      } catch (error) {
+        }),
+        onError: this.input.onError,
+      },
+      execute: async () => {
+        const disposers: Array<() => Promise<void>> = [];
         try {
-          await this.input.onError?.(error);
-        } catch {
-          // 观测回调失败不能终止仍持有 lease 的业务 handler；下一周期继续 renew。
+          const handler = this.input.toolRegistry.getTool(item.toolName);
+          const execution = await this.executeHandler(handler, item, disposers);
+          return {
+            kind: 'completed',
+            result: toToolExecutionResult(item.workId, execution),
+          };
+        } catch (error) {
+          return {
+            kind: 'failed',
+            result: {
+              workId: item.workId,
+              status: 'failed',
+              error: toWorkerErrorPayload(error),
+            },
+            cause: error,
+          };
+        } finally {
+          await Promise.all(disposers.map(async (dispose) => {
+            await dispose().catch(() => undefined);
+          }));
         }
-      }
-    }
+      },
+      complete: ({ result }) => this.input.workQueue.complete(result, { leaseId }),
+      completeRejectedError: (execution) => execution.kind === 'failed'
+        ? new Error(`work complete 未被接受：${item.workId}`, { cause: execution.cause })
+        : new Error(`work complete 未被接受：${item.workId}`),
+    });
   }
 
   private async executeHandler(
@@ -367,7 +375,7 @@ export class EnvironmentWorker {
     };
 
     return {
-      session: buildSyntheticSession(item, harness.id, harness.version),
+      session: buildSyntheticSession(item, harness.id, item.environmentId),
       harness: {
         id: harness.id,
         version: harness.version,
@@ -437,7 +445,7 @@ export class EnvironmentWorker {
     };
     const common = {
       baseUrl: proxy.baseUrl,
-      environmentId: this.input.environmentId,
+      environmentId: item.environmentId,
       environmentKey: proxy.environmentKey,
       implementationId,
       audit,
@@ -445,9 +453,6 @@ export class EnvironmentWorker {
       signal: proxy.signal,
       requestTimeoutMs: proxy.requestTimeoutMs,
     };
-    if (slotName === 'database') {
-      return createPlatformDatabaseProxyResource(common) as Database;
-    }
     if (slotName === 'skills') {
       return createPlatformResourceProxy<SkillResource>({
         ...common,
@@ -463,17 +468,6 @@ export class EnvironmentWorker {
     throw new Error(`platform resource proxy 不支持 slot：${slotName}`);
   }
 
-  private buildCompleteScope(item: ToolWorkItem) {
-    if (!item.leaseId) {
-      throw new Error(`claimed work item 缺少 leaseId：${item.workId}`);
-    }
-    return {
-      appId: this.input.appId,
-      environmentId: this.input.environmentId,
-      executionMode: this.input.executionMode ?? item.executionMode ?? 'self_hosted',
-      leaseId: item.leaseId,
-    } satisfies CompleteWorkItemScope;
-  }
 }
 
 /**
@@ -488,8 +482,7 @@ export class ContextResolverWorker {
   public async drainOnce(): Promise<number> {
     const executionMode = this.input.executionMode ?? 'self_hosted';
     const items = await this.input.contextResolveQueue.claim({
-      appId: this.input.appId,
-      environmentId: this.input.environmentId,
+      scope: this.input.scope ?? {},
       executionMode,
       max: this.input.maxBatchSize ?? 1,
     });
@@ -499,36 +492,52 @@ export class ContextResolverWorker {
   }
 
   private async handleItem(item: ContextResolveWorkItem): Promise<void> {
-    let result: ContextResolveResult;
-    try {
-      result = {
-        workId: item.workId,
-        ...(item.leaseId ? { leaseId: item.leaseId } : {}),
-        status: 'completed',
-        snapshot: await this.input.resolvePromptContext(item),
-      };
-    } catch (error) {
-      result = {
-        workId: item.workId,
-        ...(item.leaseId ? { leaseId: item.leaseId } : {}),
-        status: 'failed',
-        error: {
-          message: normalizeContextResolverError(error),
-          retryable: false,
+    const renew = this.input.contextResolveQueue.renew;
+    const leaseId = item.leaseId;
+    await runLeasedItem<ContextResolveResult>({
+      ...(leaseId && renew ? {
+        renewal: {
+          intervalMs: this.input.leaseRenewIntervalMs,
+          renew: () => renew({
+            workId: item.workId,
+            leaseId,
+            scope: item.scope,
+            executionMode: this.input.executionMode ?? item.executionMode ?? 'self_hosted',
+          }),
+          onError: this.input.onError,
         },
-      };
-    }
-
-    const accepted = await this.input.contextResolveQueue.complete(result, this.buildCompleteScope(item));
-    if (!accepted) {
-      throw new Error(`context work complete 未被接受：${item.workId}`);
-    }
+      } : {}),
+      execute: async () => {
+        try {
+          return {
+            workId: item.workId,
+            ...(item.leaseId ? { leaseId: item.leaseId } : {}),
+            status: 'completed',
+            snapshot: await this.input.resolvePromptContext(item),
+          };
+        } catch (error) {
+          return {
+            workId: item.workId,
+            ...(item.leaseId ? { leaseId: item.leaseId } : {}),
+            status: 'failed',
+            error: {
+              message: normalizeContextResolverError(error),
+              retryable: false,
+            },
+          };
+        }
+      },
+      complete: (result) => this.input.contextResolveQueue.complete(
+        result,
+        this.buildCompleteScope(item),
+      ),
+      completeRejectedError: () => new Error(`context work complete 未被接受：${item.workId}`),
+    });
   }
 
   private buildCompleteScope(item: ContextResolveWorkItem) {
     return {
-      appId: this.input.appId,
-      environmentId: this.input.environmentId,
+      scope: item.scope,
       executionMode: this.input.executionMode ?? item.executionMode ?? 'self_hosted',
       leaseId: item.leaseId,
     };
@@ -539,22 +548,9 @@ export async function runContextResolverWorkerLoop(input: RunContextResolverWork
   const worker = new ContextResolverWorker(input);
   const idleDelayMs = input.idleDelayMs ?? 250;
   const errorDelayMs = input.errorDelayMs ?? 1000;
-  const reclaimOlderThanMs = input.reclaimOlderThanMs ?? DEFAULT_RECLAIM_OLDER_THAN_MS;
-  const reclaimIntervalMs = normalizeNonNegativeInteger(input.reclaimIntervalMs, DEFAULT_RECLAIM_INTERVAL_MS);
-  let nextReclaimAtMs = 0;
 
   while (!input.abortSignal?.aborted) {
     try {
-      if (Date.now() >= nextReclaimAtMs) {
-        await input.contextResolveQueue.reclaim({
-          appId: input.appId,
-          environmentId: input.environmentId,
-          executionMode: input.executionMode ?? 'self_hosted',
-          olderThanMs: reclaimOlderThanMs,
-        });
-        nextReclaimAtMs = Date.now() + reclaimIntervalMs;
-      }
-
       const drained = await worker.drainOnce();
       if (drained === 0) {
         await delay(idleDelayMs, input.abortSignal);
@@ -570,23 +566,12 @@ export async function runEnvironmentWorkerLoop(input: RunEnvironmentWorkerLoopIn
   const worker = new EnvironmentWorker(input);
   const idleDelayMs = input.idleDelayMs ?? 250;
   const errorDelayMs = input.errorDelayMs ?? 1000;
-  const reclaimOlderThanMs = input.reclaimOlderThanMs ?? DEFAULT_RECLAIM_OLDER_THAN_MS;
-  const reclaimIntervalMs = normalizeNonNegativeInteger(input.reclaimIntervalMs, DEFAULT_RECLAIM_INTERVAL_MS);
   const blockMs = normalizeNonNegativeInteger(input.blockMs, DEFAULT_CLAIM_BLOCK_MS);
   const maxConcurrency = normalizePositiveInteger(input.maxConcurrency, 1);
-  const leaseRenewIntervalMs = normalizePositiveInteger(
-    input.leaseRenewIntervalMs,
-    DEFAULT_WORK_LEASE_RENEW_INTERVAL_MS,
-  );
-  if (leaseRenewIntervalMs >= reclaimOlderThanMs) {
-    throw new Error('leaseRenewIntervalMs 必须小于 reclaimOlderThanMs');
-  }
-  let nextReclaimAtMs = 0;
   const active = new Set<Promise<void>>();
 
   const startWork = (item: ToolWorkItem) => {
-    let tracked: Promise<void>;
-    tracked = worker.handleItem(item)
+    const tracked = worker.handleItem(item)
       .catch(async (error) => {
         await input.onError?.(error);
       })
@@ -599,23 +584,13 @@ export async function runEnvironmentWorkerLoop(input: RunEnvironmentWorkerLoopIn
   try {
     while (!input.abortSignal?.aborted) {
       try {
-        if (Date.now() >= nextReclaimAtMs) {
-          await input.workQueue.reclaim({
-            appId: input.appId,
-            environmentId: input.environmentId,
-            executionMode: input.executionMode ?? 'self_hosted',
-            olderThanMs: reclaimOlderThanMs,
-          });
-          nextReclaimAtMs = Date.now() + reclaimIntervalMs;
-        }
-
         if (input.sandboxManager && input.sandboxIdleTtlMs !== undefined) {
           await input.sandboxManager.sweepIdle(input.sandboxIdleTtlMs);
         }
 
         const availableSlots = maxConcurrency - active.size;
         if (availableSlots <= 0) {
-          await waitForActiveWorkOrDeadline(active, nextReclaimAtMs, input.abortSignal);
+          await waitForActiveWorkOrDelay(active, idleDelayMs, input.abortSignal);
           continue;
         }
 
@@ -643,13 +618,14 @@ export async function runEnvironmentWorkerLoop(input: RunEnvironmentWorkerLoopIn
 
 export type HttpWorkQueueClientInput = {
   baseUrl: string;
-  environmentId: string;
   environmentKey: string;
-  appId?: string;
+  workerInstanceId: string;
   fetchImpl?: typeof fetch;
   signal?: AbortSignal;
 };
 
+export type HttpContextResolveQueueClientInput = Omit<HttpWorkQueueClientInput, 'workerInstanceId'>;
+
 export function zodObjectToJsonSchema(schema: z.ZodType<unknown>): Record<string, unknown> {
   const jsonSchema = z.toJSONSchema(schema) as Record<string, unknown>;
   const normalized = normalizeCatalogJsonSchema(jsonSchema, true);
@@ -698,59 +674,60 @@ function preserveCatalogUiMetadata(
   return target;
 }
 
-export class HttpWorkQueueClient implements WorkQueue {
-  private readonly baseUrl: string;
-  private readonly fetchImpl: typeof fetch;
+export class HttpWorkQueueClient implements WorkerWorkQueue {
+  private readonly transport: WorkerHttpTransport;
+  private identityPromise?: Promise<{ branchId: string; environmentId: string }>;
 
   public constructor(private readonly input: HttpWorkQueueClientInput) {
-    this.baseUrl = trimTrailingSlash(input.baseUrl);
-    this.fetchImpl = input.fetchImpl ?? fetch;
-  }
-
-  public async enqueue(): Promise<void> {
-    throw new Error('HTTP worker client 不能 enqueue；enqueue 只能由平台 Environment 执行');
+    this.transport = new WorkerHttpTransport(input);
   }
 
-  public async claim(input: { appId: string; environmentId: string; blockMs?: number; max?: number; executionMode?: EnvironmentExecutionMode }) {
-    this.assertScope(input.appId, input.environmentId);
-    const data = await this.requestJson('/work/claim', {
+  public async claim(input: { blockMs?: number; max?: number }) {
+    const identity = await this.identity();
+    const data = await this.transport.requestJson('/work/claim', {
       method: 'POST',
       signal: this.input.signal,
       body: JSON.stringify({
+        workerInstanceId: this.input.workerInstanceId,
         blockMs: input.blockMs,
         max: input.max,
-        executionMode: input.executionMode,
       }),
-    });
+    }, '平台工作队列响应不是 JSON 对象');
 
     const record = expectRecord(data, 'claim 响应缺少 data');
     const items = record.items;
     if (!Array.isArray(items)) {
       throw new Error('claim 响应缺少 items 数组');
     }
-    return items.map(parseToolWorkItem);
+    return items.map((item) => parseToolWorkItem(item, identity.environmentId));
   }
 
-  public async renew(input: RenewWorkItemLeaseInput): Promise<boolean> {
-    this.assertScope(input.appId, input.environmentId);
-    const data = await this.requestJson('/work/renew', {
+  public async renew(input: WorkerRenewWorkItemLeaseInput): Promise<boolean> {
+    const data = await this.transport.requestJson('/work/renew', {
       method: 'POST',
       signal: this.input.signal,
-      body: JSON.stringify({ workId: input.workId, leaseId: input.leaseId }),
-    });
+      body: JSON.stringify({
+        workId: input.workId,
+        leaseId: input.leaseId,
+        workerInstanceId: this.input.workerInstanceId,
+      }),
+    }, '平台工作队列响应不是 JSON 对象');
     const record = expectRecord(data, 'renew 响应缺少 data');
     return record.renewed === true;
   }
 
-  public async complete(result: ToolExecutionResult, scope?: CompleteWorkItemScope): Promise<boolean> {
-    if (!scope?.leaseId) {
+  public async complete(result: ToolExecutionResult, scope: WorkerCompleteWorkItemScope): Promise<boolean> {
+    if (!scope.leaseId) {
       throw new Error(`work complete 缺少 leaseId：${result.workId}`);
     }
-    this.assertScope(scope.appId, scope.environmentId);
-    const data = await this.requestJson('/work/complete', {
+    const data = await this.transport.requestJson('/work/complete', {
       method: 'POST',
-      body: JSON.stringify({ ...result, leaseId: scope.leaseId }),
-    });
+      body: JSON.stringify({
+        ...result,
+        leaseId: scope.leaseId,
+        workerInstanceId: this.input.workerInstanceId,
+      }),
+    }, '平台工作队列响应不是 JSON 对象');
     const record = expectRecord(data, 'complete 响应缺少 data');
     if (record.accepted !== true) {
       throw new Error(`work complete 未被接受：${result.workId}`);
@@ -758,76 +735,70 @@ export class HttpWorkQueueClient implements WorkQueue {
     return true;
   }
 
-  public async reclaim(input: { appId: string; environmentId: string; olderThanMs: number; executionMode?: EnvironmentExecutionMode }): Promise<number> {
-    this.assertScope(input.appId, input.environmentId);
-    const data = await this.requestJson('/work/reclaim', {
-      method: 'POST',
+  public async register(registration: WorkerCapabilityRegistration) {
+    if (registration.workerInstanceId !== this.input.workerInstanceId) {
+      throw new Error('Worker 注册身份与 client 实例不一致');
+    }
+    const { workerInstanceId: _workerInstanceId, ...body } = registration;
+    const data = await this.transport.requestJson(`/instances/${encodeURIComponent(this.input.workerInstanceId)}`, {
+      method: 'PUT',
       signal: this.input.signal,
-      body: JSON.stringify({ olderThanMs: input.olderThanMs, executionMode: input.executionMode }),
-    });
-
-    const record = expectRecord(data, 'reclaim 响应缺少 data');
-    return typeof record.reclaimed === 'number' ? record.reclaimed : 0;
-  }
-
-  public async stats(input: { appId: string; environmentId: string; executionMode?: EnvironmentExecutionMode }): Promise<WorkStats> {
-    this.assertScope(input.appId, input.environmentId);
-    const query = input.executionMode ? `?executionMode=${encodeURIComponent(input.executionMode)}` : '';
-    const data = await this.requestJson(`/work/stats${query}`, { method: 'GET', signal: this.input.signal });
-    const record = expectRecord(data, 'stats 响应缺少 data');
-    return parseWorkStats(record.stats);
+      body: JSON.stringify(body),
+    }, '平台工作队列响应不是 JSON 对象');
+    const record = expectRecord(data, 'Worker 注册响应缺少 data');
+    return {
+      workerInstanceId: expectString(record.workerInstanceId, 'workerInstanceId'),
+      expiresAt: expectString(record.expiresAt, 'expiresAt'),
+    };
   }
 
-  private assertScope(appId: string, environmentId: string): void {
-    if (this.input.appId && appId !== this.input.appId) {
-      throw new Error(`worker appId 不匹配：${appId}`);
-    }
-    if (environmentId !== this.input.environmentId) {
-      throw new Error(`worker environmentId 不匹配：${environmentId}`);
+  public async heartbeat(workerInstanceId: string) {
+    if (workerInstanceId !== this.input.workerInstanceId) {
+      throw new Error('Worker 心跳身份与 client 实例不一致');
     }
+    const data = await this.transport.requestJson(`/instances/${encodeURIComponent(workerInstanceId)}/heartbeat`, {
+      method: 'POST',
+      signal: this.input.signal,
+    }, '平台工作队列响应不是 JSON 对象');
+    const record = expectRecord(data, 'Worker 心跳响应缺少 data');
+    return {
+      workerInstanceId: expectString(record.workerInstanceId, 'workerInstanceId'),
+      expiresAt: expectString(record.expiresAt, 'expiresAt'),
+    };
   }
 
-  private async requestJson(path: string, init: RequestInit): Promise<unknown> {
-    const headers = new Headers(init.headers);
-    headers.set('x-api-key', this.input.environmentKey);
-    if (init.body && !headers.has('content-type')) {
-      headers.set('content-type', 'application/json');
-    }
-
-    const response = await this.fetchImpl(this.buildUrl(path), {
-      ...init,
-      headers,
+  public identity() {
+    this.identityPromise ??= this.transport.requestJson('/identity', {
+      method: 'GET',
+      signal: this.input.signal,
+    }, '平台工作队列响应不是 JSON 对象').then((data) => {
+      const record = expectRecord(data, 'Worker identity 响应缺少 data');
+      const identity = expectRecord(record.identity, 'Worker identity 响应缺少 identity');
+      return {
+        branchId: expectString(identity.branchId, 'identity.branchId'),
+        environmentId: expectString(identity.environmentId, 'identity.environmentId'),
+      };
     });
-    return parseApiEnvelope(response, `平台工作队列响应不是 JSON 对象：${response.status}`);
+    return this.identityPromise;
   }
 
-  private buildUrl(path: string): string {
-    return `${this.baseUrl}/v1/environments/${encodeURIComponent(this.input.environmentId)}${path}`;
-  }
 }
 
-export class HttpContextResolveQueueClient implements ContextResolveQueue {
-  private readonly baseUrl: string;
-  private readonly fetchImpl: typeof fetch;
-
-  public constructor(private readonly input: HttpWorkQueueClientInput) {
-    this.baseUrl = trimTrailingSlash(input.baseUrl);
-    this.fetchImpl = input.fetchImpl ?? fetch;
-  }
+export class HttpContextResolveQueueClient implements WorkerContextResolveQueue {
+  private readonly transport: WorkerHttpTransport;
 
-  public async enqueue(): Promise<void> {
-    throw new Error('HTTP context resolver client 不能 enqueue；enqueue 只能由平台 Harness 执行');
+  public constructor(private readonly input: HttpContextResolveQueueClientInput) {
+    this.transport = new WorkerHttpTransport(input);
   }
 
-  public async claim(input: { appId: string; environmentId: string; max?: number }) {
-    this.assertScope(input.appId, input.environmentId);
-    const data = await this.requestJson('/context-work/claim', {
+  public async claim(input: ContextResolveQueueClaimInput) {
+    const data = await this.transport.requestJson('/context-work/claim', {
       method: 'POST',
       signal: this.input.signal,
       body: JSON.stringify({
         max: input.max,
       }),
-    });
+    }, '平台 context 工作队列响应不是 JSON 对象');
 
     const record = expectRecord(data, 'context claim 响应缺少 data');
     const items = record.items;
@@ -838,10 +809,10 @@ export class HttpContextResolveQueueClient implements ContextResolveQueue {
   }
 
   public async complete(result: ContextResolveResult): Promise<boolean> {
-    const data = await this.requestJson('/context-work/complete', {
+    const data = await this.transport.requestJson('/context-work/complete', {
       method: 'POST',
       body: JSON.stringify(result),
-    });
+    }, '平台 context 工作队列响应不是 JSON 对象');
     const record = expectRecord(data, 'context complete 响应缺少 data');
     if (record.accepted !== true) {
       throw new Error(`context complete 未被接受：${result.workId}`);
@@ -849,69 +820,20 @@ export class HttpContextResolveQueueClient implements ContextResolveQueue {
     return true;
   }
 
-  public async reclaim(input: { appId: string; environmentId: string; olderThanMs: number }): Promise<number> {
-    this.assertScope(input.appId, input.environmentId);
-    const data = await this.requestJson('/context-work/reclaim', {
+  public async renew(input: { workId: string; leaseId: string }): Promise<boolean> {
+    const data = await this.transport.requestJson('/context-work/renew', {
       method: 'POST',
       signal: this.input.signal,
-      body: JSON.stringify({ olderThanMs: input.olderThanMs }),
-    });
-
-    const record = expectRecord(data, 'context reclaim 响应缺少 data');
-    return typeof record.reclaimed === 'number' ? record.reclaimed : 0;
-  }
-
-  public async stats(input: { appId: string; environmentId: string }) {
-    this.assertScope(input.appId, input.environmentId);
-    const data = await this.requestJson('/context-work/stats', { method: 'GET', signal: this.input.signal });
-    const record = expectRecord(data, 'context stats 响应缺少 data');
-    return parseContextResolveStats(record.stats);
-  }
-
-  private assertScope(appId: string, environmentId: string): void {
-    if (this.input.appId && appId !== this.input.appId) {
-      throw new Error(`context resolver appId 不匹配：${appId}`);
-    }
-    if (environmentId !== this.input.environmentId) {
-      throw new Error(`context resolver environmentId 不匹配：${environmentId}`);
-    }
-  }
-
-  private async requestJson(path: string, init: RequestInit): Promise<unknown> {
-    const headers = new Headers(init.headers);
-    headers.set('x-api-key', this.input.environmentKey);
-    if (init.body && !headers.has('content-type')) {
-      headers.set('content-type', 'application/json');
-    }
-
-    const response = await this.fetchImpl(this.buildUrl(path), {
-      ...init,
-      headers,
-    });
-    return parseApiEnvelope(response, `平台 context 工作队列响应不是 JSON 对象：${response.status}`);
-  }
-
-  private buildUrl(path: string): string {
-    return `${this.baseUrl}/v1/environments/${encodeURIComponent(this.input.environmentId)}${path}`;
+      body: JSON.stringify({ workId: input.workId, leaseId: input.leaseId }),
+    }, '平台 context 工作队列响应不是 JSON 对象');
+    const record = expectRecord(data, 'context renew 响应缺少 data');
+    return record.renewed === true;
   }
-}
 
-async function parseApiEnvelope(response: Response, fallbackMessage: string): Promise<unknown> {
-  const body = await response.json().catch(() => null) as unknown;
-  const envelope = expectRecord(body, fallbackMessage);
-  if (!response.ok || envelope.success !== true) {
-    const error = isRecord(envelope.error) ? envelope.error : {};
-    const message = typeof error.message === 'string'
-      ? error.message
-      : `平台请求失败：${response.status}`;
-    throw new Error(message);
-  }
-  return envelope.data;
 }
 
 function toToolExecutionResult(
   workId: string,
-  handler: ToolHandler<unknown, unknown>,
   execution: ToolExecution<unknown>,
 ): ToolExecutionResult {
   if (execution.status === 'failed') {
@@ -934,24 +856,22 @@ function toToolExecutionResult(
   return {
     workId,
     status: 'completed',
-    modelResult: handler.resultSchema.parse(execution.modelResult),
+    modelResult: assertToolResultWireValue(execution.modelResult),
     effects: execution.effects,
   };
 }
 
-function buildSyntheticSession(item: ToolWorkItem, harnessId: string, harnessVersion: number): SessionRecord {
+function buildSyntheticSession(item: ToolWorkItem, harnessId: string, environmentId: string): SessionRecord {
   const now = new Date().toISOString();
   return {
     id: item.sessionId as SessionId,
-    appId: item.appId,
     scope: item.scope,
+    configuration: { status: 'available', configVersionId: item.configVersionId },
     rootSessionId: item.rootSessionId as SessionId,
     harnessId: harnessId as HarnessId,
-    harnessVersion,
-    environmentId: item.environmentId as EnvironmentId,
-    environmentUpdatedAt: now,
+    environmentId: environmentId as EnvironmentId,
     title: item.sessionId,
-    metadata: {},
+    metadata: item.sessionMetadata ?? {},
     createdAt: now,
     updatedAt: now,
   };
@@ -988,14 +908,35 @@ function hasDispose(value: unknown): value is { dispose(): Promise<void> | void
   return isRecord(value) && typeof value.dispose === 'function';
 }
 
-function parseToolWorkItem(value: unknown): ToolWorkItem {
+function parseToolWorkItem(value: unknown, environmentId: string): ToolWorkItem {
   const record = expectRecord(value, 'work item 不是对象');
   const workId = expectString(record.workId, 'workId');
   const leaseId = typeof record.leaseId === 'string' && record.leaseId.trim()
     ? record.leaseId.trim()
     : undefined;
-  const appId = expectString(record.appId, 'appId');
-  const environmentId = expectString(record.environmentId, 'environmentId');
+  const configVersionId = expectString(record.configVersionId, 'configVersionId');
+  const requiredContractDigest = expectString(record.requiredContractDigest, 'requiredContractDigest');
+  if (!Array.isArray(record.requiredResourceCapabilities)) {
+    throw new Error('requiredResourceCapabilities 必须是数组');
+  }
+  const requiredResourceCapabilities = record.requiredResourceCapabilities.map((value, index) => {
+    const capability = expectRecord(value, `requiredResourceCapabilities[${index}]`);
+    return {
+      slot: expectString(capability.slot, `requiredResourceCapabilities[${index}].slot`),
+      implementationId: expectString(
+        capability.implementationId,
+        `requiredResourceCapabilities[${index}].implementationId`,
+      ),
+    };
+  });
+  const workerKind = record.workerKind;
+  if (workerKind !== 'self_hosted' && workerKind !== 'platform_builtin') {
+    throw new Error('workerKind 无效');
+  }
+  if (Object.prototype.hasOwnProperty.call(record, 'environmentId')
+    || Object.prototype.hasOwnProperty.call(record, 'appId')) {
+    throw new Error('work item wire 不得携带服务端隔离字段');
+  }
   const sessionId = expectString(record.sessionId, 'sessionId');
   const rootSessionId = expectString(record.rootSessionId, 'rootSessionId');
   const scope = parseExecutionScope(record.scope);
@@ -1006,7 +947,10 @@ function parseToolWorkItem(value: unknown): ToolWorkItem {
   const item: ToolWorkItem = {
     workId,
     ...(leaseId ? { leaseId } : {}),
-    appId,
+    configVersionId: configVersionId as ToolWorkItem['configVersionId'],
+    requiredContractDigest,
+    requiredResourceCapabilities,
+    workerKind,
     environmentId,
     sessionId,
     rootSessionId,
@@ -1022,6 +966,10 @@ function parseToolWorkItem(value: unknown): ToolWorkItem {
     item.resume = parseToolResumeWorkPayload(record.resume);
   }
 
+  if (record.sessionMetadata !== undefined) {
+    item.sessionMetadata = expectRecord(record.sessionMetadata, 'sessionMetadata 必须是对象');
+  }
+
   if (isRecord(record.resourceBindings)) {
     item.resourceBindings = record.resourceBindings;
   }
@@ -1050,35 +998,139 @@ function parseExecutionMode(value: unknown): ToolWorkItem['executionMode'] | und
 
 function parseToolResumeWorkPayload(value: unknown): NonNullable<ToolWorkItem['resume']> {
   const record = expectRecord(value, 'resume 工作项缺少 resume payload');
-  const actionEvent = parseResumeEvent(record.actionEvent, 'agent.action.requested', 'resume.actionEvent');
-  const resolvedEvent = parseResumeEvent(record.resolvedEvent, 'user.action.resolved', 'resume.resolvedEvent');
+  const actionEvent = parseActionRequestedEvent(record.actionEvent, 'resume.actionEvent');
+  const resolvedEvent = parseActionResolvedEvent(record.resolvedEvent, 'resume.resolvedEvent');
+  if (actionEvent.payload.kind !== resolvedEvent.payload.kind) {
+    throw new Error('resume action kind 不一致');
+  }
   return {
     actionEvent,
     resolvedEvent,
   };
 }
 
-function parseResumeEvent<TType extends NonNullable<ToolWorkItem['resume']>['actionEvent']['type'] | NonNullable<ToolWorkItem['resume']>['resolvedEvent']['type']>(
+function parseActionRequestedEvent(
+  value: unknown,
+  field: string,
+): NonNullable<ToolWorkItem['resume']>['actionEvent'] {
+  const event = expectRecord(value, `${field} 必须是对象`);
+  if (event.type !== 'agent.action.requested') {
+    throw new Error(`${field} 类型必须是 agent.action.requested`);
+  }
+  const payload = expectRecord(event.payload, `${field}.payload 必须是对象`);
+  const display = payload.display === undefined
+    ? undefined
+    : parseActionDisplay(payload.display, `${field}.payload.display`);
+  const allowedResults = parseOptionalArray(
+    payload.allowedResults,
+    `${field}.payload.allowedResults`,
+  );
+  return {
+    ...parseResumeEventCore(event, field),
+    type: 'agent.action.requested',
+    payload: {
+      kind: parseActionKind(payload.kind, `${field}.payload.kind`),
+      ...(payload.prompt === undefined
+        ? {}
+        : { prompt: expectOptionalString(payload.prompt, `${field}.payload.prompt`) }),
+      ...(Object.prototype.hasOwnProperty.call(payload, 'input') ? { input: payload.input } : {}),
+      ...(allowedResults ? { allowedResults } : {}),
+      ...(display ? { display } : {}),
+      ...(payload.expiresAt === undefined
+        ? {}
+        : { expiresAt: expectOptionalString(payload.expiresAt, `${field}.payload.expiresAt`) }),
+    },
+  };
+}
+
+function parseActionResolvedEvent(
   value: unknown,
-  type: TType,
   field: string,
-): Extract<NonNullable<ToolWorkItem['resume']>['actionEvent'] | NonNullable<ToolWorkItem['resume']>['resolvedEvent'], { type: TType }> {
+): NonNullable<ToolWorkItem['resume']>['resolvedEvent'] {
   const event = expectRecord(value, `${field} 必须是对象`);
-  if (event.type !== type) {
-    throw new Error(`${field} 类型必须是 ${type}`);
+  if (event.type !== 'user.action.resolved') {
+    throw new Error(`${field} 类型必须是 user.action.resolved`);
   }
-  expectString(event.id, `${field}.id`);
-  if (typeof event.seq !== 'number' || !Number.isFinite(event.seq)) {
-    throw new Error(`${field}.seq 必须是有限数字`);
+  const payload = expectRecord(event.payload, `${field}.payload 必须是对象`);
+  if (!Object.prototype.hasOwnProperty.call(payload, 'result')) {
+    throw new Error(`${field}.payload.result 缺失`);
   }
-  expectRecord(event.actor, `${field}.actor 必须是对象`);
-  expectString(event.createdAt, `${field}.createdAt`);
-  expectRecord(event.payload, `${field}.payload 必须是对象`);
+  return {
+    ...parseResumeEventCore(event, field),
+    type: 'user.action.resolved',
+    payload: {
+      kind: parseActionKind(payload.kind, `${field}.payload.kind`),
+      result: payload.result,
+    },
+  };
+}
+
+function parseResumeEventCore(event: Record<string, unknown>, field: string) {
+  return {
+    id: expectString(event.id, `${field}.id`),
+    seq: expectNumber(event.seq, `${field}.seq`),
+    ...(event.globalSeq === undefined
+      ? {}
+      : { globalSeq: expectNumber(event.globalSeq, `${field}.globalSeq`) }),
+    ...(event.turnId === undefined
+      ? {}
+      : { turnId: expectString(event.turnId, `${field}.turnId`) }),
+    ...(event.parentEventId === undefined
+      ? {}
+      : { parentEventId: expectString(event.parentEventId, `${field}.parentEventId`) }),
+    actor: parseSessionEventActor(event.actor, `${field}.actor`),
+    createdAt: expectString(event.createdAt, `${field}.createdAt`),
+  };
+}
+
+function parseActionDisplay(value: unknown, field: string) {
+  const display = expectRecord(value, `${field} 必须是对象`);
+  return {
+    ...(display.title === undefined
+      ? {}
+      : { title: expectOptionalString(display.title, `${field}.title`) }),
+    ...(display.summary === undefined
+      ? {}
+      : { summary: expectOptionalString(display.summary, `${field}.summary`) }),
+  };
+}
 
-  if (type === 'agent.action.requested') {
-    return event as unknown as Extract<NonNullable<ToolWorkItem['resume']>['actionEvent'], { type: TType }>;
+function parseSessionEventActor(value: unknown, field: string): SessionEventActor {
+  const actor = expectRecord(value, `${field} 必须是对象`);
+  if (actor.type !== 'user'
+    && actor.type !== 'assistant'
+    && actor.type !== 'tool'
+    && actor.type !== 'system') {
+    throw new Error(`${field}.type 无效`);
   }
-  return event as unknown as Extract<NonNullable<ToolWorkItem['resume']>['resolvedEvent'], { type: TType }>;
+  return {
+    type: actor.type,
+    ...(actor.id === undefined ? {} : { id: expectString(actor.id, `${field}.id`) }),
+  };
+}
+
+function parseActionKind(value: unknown, field: string) {
+  if (value !== 'ask_user' && value !== 'tool_confirmation' && value !== 'custom_tool_result') {
+    throw new Error(`${field} 无效`);
+  }
+  return value;
+}
+
+function expectOptionalString(value: unknown, field: string) {
+  if (typeof value !== 'string') {
+    throw new Error(`${field} 必须是字符串`);
+  }
+  return value;
+}
+
+function parseOptionalArray(value: unknown, field: string): unknown[] | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${field} 必须是数组`);
+  }
+  return value;
 }
 
 function parseExecutionScope(value: unknown): ExecutionScope {
@@ -1098,8 +1150,6 @@ function parseContextResolveWorkItem(value: unknown): ContextResolveWorkItem {
   const leaseId = typeof record.leaseId === 'string' && record.leaseId.trim()
     ? record.leaseId.trim()
     : undefined;
-  const appId = expectString(record.appId, 'appId');
-  const environmentId = expectString(record.environmentId, 'environmentId');
   const sessionId = expectString(record.sessionId, 'sessionId');
   const rootSessionId = expectString(record.rootSessionId, 'rootSessionId');
   const request = expectRecord(record.request, 'request 必须是对象');
@@ -1121,8 +1171,6 @@ function parseContextResolveWorkItem(value: unknown): ContextResolveWorkItem {
   return {
     workId,
     ...(leaseId ? { leaseId } : {}),
-    appId,
-    environmentId,
     sessionId,
     rootSessionId,
     scope: parseExecutionScope(record.scope),
@@ -1134,27 +1182,6 @@ function parseContextResolveWorkItem(value: unknown): ContextResolveWorkItem {
   };
 }
 
-function parseWorkStats(value: unknown): WorkStats {
-  const record = expectRecord(value, 'stats 不是对象');
-  const oldestQueuedAt = record.oldestQueuedAt;
-  return {
-    depth: expectNumber(record.depth, 'depth'),
-    pending: expectNumber(record.pending, 'pending'),
-    oldestQueuedAt: typeof oldestQueuedAt === 'string' ? oldestQueuedAt : null,
-    workersPolling: expectNumber(record.workersPolling, 'workersPolling'),
-  };
-}
-
-function parseContextResolveStats(value: unknown) {
-  const record = expectRecord(value, 'context stats 不是对象');
-  const oldestQueuedAt = record.oldestQueuedAt;
-  return {
-    depth: expectNumber(record.depth, 'depth'),
-    pending: expectNumber(record.pending, 'pending'),
-    oldestQueuedAt: typeof oldestQueuedAt === 'string' ? oldestQueuedAt : null,
-  };
-}
-
 function normalizeWorkerError(error: unknown): string {
   if (error instanceof Error) {
     return `工具执行失败：${error.message}`;
@@ -1186,10 +1213,6 @@ function normalizeContextResolverError(error: unknown): string {
   return `context resolve 失败：${String(error)}`;
 }
 
-function trimTrailingSlash(value: string): string {
-  return value.endsWith('/') ? value.slice(0, -1) : value;
-}
-
 function expectString(value: unknown, field: string): string {
   if (typeof value !== 'string' || !value.trim()) {
     throw new Error(`字段 ${field} 必须是非空字符串`);
@@ -1231,18 +1254,6 @@ function delay(ms: number, signal?: AbortSignal): Promise<void> {
   });
 }
 
-function waitForActiveWorkOrDeadline(
-  active: Set<Promise<void>>,
-  deadlineMs: number,
-  signal?: AbortSignal,
-): Promise<void> {
-  const waitMs = Math.max(1, deadlineMs - Date.now());
-  return Promise.race([
-    ...active,
-    delay(waitMs, signal),
-  ]).then(() => undefined);
-}
-
 function waitForActiveWorkOrDelay(
   active: Set<Promise<void>>,
   delayMs: number,