@ct-agents/worker 0.0.1

package/src/index.ts

@@ -0,0 +1,1134 @@
+import type {
+  ContextResolveQueue,
+  ContextResolveResult,
+  ContextResolveWorkItem,
+  Database,
+  EnvironmentId,
+  EnvironmentExecutionMode,
+  EnvironmentHostedPolicy,
+  EnvironmentResourceSlotRegistrationDto,
+  ExecutionScope,
+  HarnessId,
+  ResourceSlots,
+  SessionEvent,
+  SessionId,
+  SessionRecord,
+  ToolExecution,
+  ToolExecutionResult,
+  ToolDescriptor,
+  ToolHandler,
+  ToolHandlerContext,
+  ToolRegistry,
+  ToolWorkItem,
+  WorkQueue,
+  WorkStats,
+} from '@ct-agents/protocol';
+import type { MemoryResource, SkillResource } from '@ct-agents/protocol';
+import { createLoadMemoryToolHandler, createUpdateMemoryToolHandler } from '@ct-agents/memory';
+import { createLoadSkillToolHandler } from '@ct-agents/prompts';
+import { createSandboxTools } from '@ct-agents/tools';
+import { createAskUserToolHandler } from '@ct-agents/tools/builtin-tools';
+import { z } from 'zod';
+import {
+  createPlatformDatabaseProxyResource,
+  createPlatformResourceProxy,
+} from './resources/platform-proxy.js';
+
+export type ResolveResources = (item: ToolWorkItem) => Promise<ResourceSlots> | ResourceSlots;
+export type ResolvePromptContext = (item: ContextResolveWorkItem) =>
+  Promise<Record<string, unknown>> | Record<string, unknown>;
+
+export type ResourceOptionsParser = {
+  parse(value: unknown): Record<string, unknown>;
+};
+
+export type EnvironmentWorkerResourceFactoryContext = {
+  item: ToolWorkItem;
+};
+
+export type EnvironmentWorkerResourceImplementation<
+  TResource = unknown,
+  TOptions extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  title: string;
+  description?: string;
+  options?: {
+    parse(value: unknown): TOptions;
+  };
+  factory: (
+    options: TOptions,
+    context: EnvironmentWorkerResourceFactoryContext,
+  ) => Promise<TResource> | TResource;
+};
+
+export type EnvironmentWorkerResourceImplementations = Record<
+  string,
+  Record<string, EnvironmentWorkerResourceImplementation>
+>;
+
+export type EnvironmentWorkerPlatformResourceProxy = {
+  baseUrl: string;
+  environmentKey: string;
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+  requestTimeoutMs?: number;
+};
+
+export type WorkerSandboxManager = {
+  sweepIdle(ttlMs: number): Promise<number>;
+  disposeAll(): Promise<void>;
+};
+
+export type EnvironmentWorkerInput = {
+  appId: string;
+  environmentId: string;
+  workQueue: WorkQueue;
+  toolRegistry: ToolRegistry;
+  resources?: ResourceSlots;
+  resolveResources?: ResolveResources;
+  resourceImpls?: EnvironmentWorkerResourceImplementations;
+  platformResourceProxy?: EnvironmentWorkerPlatformResourceProxy;
+  maxBatchSize?: number;
+  harness?: {
+    id: string;
+    version: number;
+    metadata?: Record<string, unknown>;
+  };
+  executionMode?: EnvironmentExecutionMode;
+  hostedPolicy?: EnvironmentHostedPolicy;
+};
+
+export type DrainOnceOptions = {
+  blockMs?: number;
+};
+
+export type RunEnvironmentWorkerLoopInput = EnvironmentWorkerInput & {
+  abortSignal?: AbortSignal;
+  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;
+  resolvePromptContext: ResolvePromptContext;
+  maxBatchSize?: number;
+  executionMode?: EnvironmentExecutionMode;
+};
+
+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;
+
+const PLATFORM_PROXY_RESOURCE_SLOTS = new Set(['database', 'skills', 'memory']);
+
+export function createPlatformBuiltinToolHandlers(): ToolHandler[] {
+  return [
+    createAskUserToolHandler(),
+    createLoadSkillToolHandler(),
+    createLoadMemoryToolHandler(),
+    createUpdateMemoryToolHandler(),
+    ...createSandboxTools(),
+  ];
+}
+
+function withPlatformBuiltinTools(registry: ToolRegistry): ToolRegistry {
+  return new PlatformBuiltinToolRegistry(registry, createPlatformBuiltinToolHandlers());
+}
+
+function normalizeNonNegativeInteger(value: number | undefined, fallback: number): number {
+  if (value === undefined || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.max(0, Math.trunc(value));
+}
+
+class PlatformBuiltinToolRegistry implements ToolRegistry {
+  private readonly builtinHandlers = new Map<string, ToolHandler<unknown, unknown>>();
+
+  public constructor(
+    private readonly delegate: ToolRegistry,
+    handlers: ToolHandler[],
+  ) {
+    for (const handler of handlers) {
+      this.builtinHandlers.set(handler.descriptor.name, handler as ToolHandler<unknown, unknown>);
+    }
+  }
+
+  public getTool(toolName: string): ToolHandler<unknown, unknown> {
+    return this.builtinHandlers.get(toolName) ?? this.delegate.getTool(toolName);
+  }
+
+  public listTools(): ToolDescriptor[] {
+    const descriptors = new Map<string, ToolDescriptor>();
+    for (const handler of this.builtinHandlers.values()) {
+      descriptors.set(handler.descriptor.name, handler.descriptor);
+    }
+    for (const descriptor of this.delegate.listTools()) {
+      if (!descriptors.has(descriptor.name)) {
+        descriptors.set(descriptor.name, descriptor);
+      }
+    }
+    return Array.from(descriptors.values());
+  }
+
+  public addTool(handler: ToolHandler): void {
+    this.delegate.addTool?.(handler);
+  }
+}
+
+/**
+ * 独立执行面 worker。
+ *
+ * worker 只通过 WorkQueue 认领当前 app/environment 的业务 tool 工作项，并在本地
+ * ToolRegistry/ResourceSlots 中执行 handler。它不持消费端 key，也不直接创建或读取 session。
+ */
+export class EnvironmentWorker {
+  private readonly input: EnvironmentWorkerInput;
+
+  public constructor(input: EnvironmentWorkerInput) {
+    this.input = {
+      ...input,
+      toolRegistry: withPlatformBuiltinTools(input.toolRegistry),
+    };
+  }
+
+  public async drainOnce(options: DrainOnceOptions = {}): Promise<number> {
+    const executionMode = this.input.executionMode ?? 'self_hosted';
+    const items = await this.input.workQueue.claim({
+      appId: this.input.appId,
+      environmentId: this.input.environmentId,
+      executionMode,
+      max: this.input.maxBatchSize ?? 1,
+      blockMs: options.blockMs,
+    });
+
+    await Promise.all(items.map((item) => this.handleItem(item)));
+    return items.length;
+  }
+
+  private async handleItem(item: ToolWorkItem): Promise<void> {
+    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}`);
+    }
+  }
+
+  private async executeHandler(
+    handler: ToolHandler<unknown, unknown>,
+    item: ToolWorkItem,
+    disposers: Array<() => Promise<void>>,
+  ): Promise<ToolExecution<unknown>> {
+    const parsedInput = handler.inputSchema.parse(item.input);
+    if ((item.mode ?? 'execute') === 'resume') {
+      if (!handler.resume) {
+        throw new Error(`工具不支持 resume：${item.toolName}`);
+      }
+      if (!item.resume) {
+        throw new Error(`resume 工作项缺少 action 快照：${item.workId}`);
+      }
+      return handler.resume({
+        originalInput: parsedInput,
+        actionEvent: item.resume.actionEvent,
+        resolvedEvent: item.resume.resolvedEvent,
+      }, await this.buildContext(item, disposers));
+    }
+
+    return handler.execute(parsedInput, await this.buildContext(item, disposers));
+  }
+
+  private async buildContext(
+    item: ToolWorkItem,
+    disposers: Array<() => Promise<void>>,
+  ): Promise<ToolHandlerContext> {
+    const harness = this.input.harness ?? {
+      id: 'environment-worker',
+      version: 1,
+      metadata: {},
+    };
+    const baseResources = this.input.resolveResources
+      ? await this.input.resolveResources(item)
+      : this.input.resources ?? {};
+    const boundResources = await this.instantiateBoundResources(item, disposers);
+    const resources = {
+      ...baseResources,
+      ...boundResources,
+    };
+
+    return {
+      session: buildSyntheticSession(item, harness.id, harness.version),
+      harness: {
+        id: harness.id,
+        version: harness.version,
+        metadata: harness.metadata ?? {},
+      },
+      executionMode: this.input.executionMode ?? item.executionMode ?? 'self_hosted',
+      hostedPolicy: this.input.hostedPolicy,
+      resources,
+      toolCallEvent: buildToolCallEvent(item),
+    };
+  }
+
+  private async instantiateBoundResources(
+    item: ToolWorkItem,
+    disposers: Array<() => Promise<void>>,
+  ): Promise<ResourceSlots> {
+    if (!isRecord(item.resourceBindings)) {
+      return {};
+    }
+
+    const resources: ResourceSlots = {};
+    for (const [slotName, bindingValue] of Object.entries(item.resourceBindings)) {
+      const binding = parseResourceBinding(slotName, bindingValue);
+      const implementations = this.input.resourceImpls?.[slotName];
+      const implementation = implementations?.[binding.implementationId];
+      if (!implementation) {
+        if (PLATFORM_PROXY_RESOURCE_SLOTS.has(slotName)) {
+          resources[slotName] = this.createPlatformResourceProxy(slotName, binding.implementationId, item);
+          continue;
+        }
+        if (!implementations) {
+          throw new Error(`worker 缺少 resource slot factory：${slotName}`);
+        }
+        throw new Error(`worker 缺少 resource implementation factory：${slotName}.${binding.implementationId}`);
+      }
+      const parsedOptions = implementation.options
+        ? implementation.options.parse(binding.options)
+        : binding.options;
+      const instance = await implementation.factory(parsedOptions, { item });
+      resources[slotName] = instance;
+      if (hasDispose(instance)) {
+        disposers.push(async () => {
+          await instance.dispose();
+        });
+      }
+    }
+    return resources;
+  }
+
+  private createPlatformResourceProxy(
+    slotName: string,
+    implementationId: string,
+    item: ToolWorkItem,
+  ): unknown {
+    const proxy = this.input.platformResourceProxy;
+    if (!proxy) {
+      throw new Error(`worker 缺少 platform resource proxy 配置：${slotName}.${implementationId}`);
+    }
+    const audit = {
+      workId: item.workId,
+      sessionId: item.sessionId,
+      toolCallEventId: item.toolCallEventId,
+    };
+    const common = {
+      baseUrl: proxy.baseUrl,
+      environmentId: this.input.environmentId,
+      environmentKey: proxy.environmentKey,
+      implementationId,
+      audit,
+      fetchImpl: proxy.fetchImpl,
+      signal: proxy.signal,
+      requestTimeoutMs: proxy.requestTimeoutMs,
+    };
+    if (slotName === 'database') {
+      return createPlatformDatabaseProxyResource(common) as Database;
+    }
+    if (slotName === 'skills') {
+      return createPlatformResourceProxy<SkillResource>({
+        ...common,
+        slot: slotName,
+      });
+    }
+    if (slotName === 'memory') {
+      return createPlatformResourceProxy<MemoryResource>({
+        ...common,
+        slot: slotName,
+      });
+    }
+    throw new Error(`platform resource proxy 不支持 slot：${slotName}`);
+  }
+
+  private buildCompleteScope(item: ToolWorkItem) {
+    return {
+      appId: this.input.appId,
+      environmentId: this.input.environmentId,
+      executionMode: this.input.executionMode ?? item.executionMode ?? 'self_hosted',
+    };
+  }
+}
+
+/**
+ * 独立 context resolver worker。
+ *
+ * 它只处理 context.resolve 工作项，把接入方或平台托管 Resource 物化成 prompt snapshot。
+ * 该闭环不执行 tool handler，也不会写 tool.called/tool-result 事件。
+ */
+export class ContextResolverWorker {
+  public constructor(private readonly input: ContextResolverWorkerInput) {}
+
+  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,
+      executionMode,
+      max: this.input.maxBatchSize ?? 1,
+    });
+
+    await Promise.all(items.map((item) => this.handleItem(item)));
+    return items.length;
+  }
+
+  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 accepted = await this.input.contextResolveQueue.complete(result, this.buildCompleteScope(item));
+    if (!accepted) {
+      throw new Error(`context work complete 未被接受：${item.workId}`);
+    }
+  }
+
+  private buildCompleteScope(item: ContextResolveWorkItem) {
+    return {
+      appId: this.input.appId,
+      environmentId: this.input.environmentId,
+      executionMode: this.input.executionMode ?? item.executionMode ?? 'self_hosted',
+      leaseId: item.leaseId,
+    };
+  }
+}
+
+export async function runContextResolverWorkerLoop(input: RunContextResolverWorkerLoopInput): Promise<void> {
+  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);
+      }
+    } catch (error) {
+      await input.onError?.(error);
+      await delay(errorDelayMs, input.abortSignal);
+    }
+  }
+}
+
+export async function runEnvironmentWorkerLoop(input: RunEnvironmentWorkerLoopInput): Promise<void> {
+  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);
+  let nextReclaimAtMs = 0;
+
+  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 drained = await worker.drainOnce({ blockMs });
+        if (drained === 0) {
+          await delay(idleDelayMs, input.abortSignal);
+        }
+      } catch (error) {
+        await input.onError?.(error);
+        await delay(errorDelayMs, input.abortSignal);
+      }
+    }
+  } finally {
+    await input.sandboxManager?.disposeAll();
+  }
+}
+
+export type HttpWorkQueueClientInput = {
+  baseUrl: string;
+  environmentId: string;
+  environmentKey: string;
+  appId?: string;
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+};
+
+export type RegisterEnvironmentCatalogInput = {
+  baseUrl: string;
+  environmentKey: string;
+  tools: ToolDescriptor[];
+  resourceSlots?: EnvironmentResourceSlotRegistrationDto[];
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+};
+
+export async function registerEnvironmentCatalog(input: RegisterEnvironmentCatalogInput): Promise<{
+  registered: number;
+  resourceSlots: number;
+}> {
+  const fetchImpl = input.fetchImpl ?? fetch;
+  const headers = new Headers();
+  headers.set('x-api-key', input.environmentKey);
+  headers.set('content-type', 'application/json');
+  const body = {
+    tools: input.tools,
+    ...(input.resourceSlots ? { resourceSlots: input.resourceSlots } : {}),
+  };
+  const response = await fetchImpl(`${trimTrailingSlash(input.baseUrl)}/v1/tools/registrations`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+    signal: input.signal,
+  });
+  const data = await parseApiEnvelope(response, '平台工具目录上报失败');
+  const record = expectRecord(data, '工具目录上报响应缺少 data');
+  return {
+    registered: expectNumber(record.registered, 'registered'),
+    resourceSlots: expectNumber(record.resourceSlots, 'resourceSlots'),
+  };
+}
+
+export function zodObjectToJsonSchema(schema: z.ZodType<unknown>): Record<string, unknown> {
+  const jsonSchema = z.toJSONSchema(schema) as Record<string, unknown>;
+  const normalized = normalizeCatalogJsonSchema(jsonSchema, true);
+  if (normalized.type !== 'object') {
+    throw new Error('resource options schema 必须使用 z.object(...) 作为根 schema');
+  }
+  return normalized;
+}
+
+function normalizeCatalogJsonSchema(schema: Record<string, unknown>, isRoot = false): Record<string, unknown> {
+  if (!isRoot && shouldDowngradeToJsonControl(schema)) {
+    return preserveCatalogUiMetadata(schema, { type: 'json' });
+  }
+
+  const normalized: Record<string, unknown> = { ...schema };
+  if (Array.isArray(schema.enum) && schema.enum.every((item) => typeof item === 'string')) {
+    normalized.enumValues = [...schema.enum];
+  }
+  if (isRecord(schema.properties)) {
+    normalized.properties = Object.fromEntries(
+      Object.entries(schema.properties).map(([key, child]) => [
+        key,
+        isRecord(child) ? normalizeCatalogJsonSchema(child) : child,
+      ]),
+    );
+  }
+  return normalized;
+}
+
+function shouldDowngradeToJsonControl(schema: Record<string, unknown>): boolean {
+  return schema.type === 'array'
+    || isRecord(schema.propertyNames)
+    || Array.isArray(schema.anyOf)
+    || Array.isArray(schema.oneOf);
+}
+
+function preserveCatalogUiMetadata(
+  source: Record<string, unknown>,
+  target: Record<string, unknown>,
+): Record<string, unknown> {
+  for (const key of ['title', 'description', 'default', 'examples', 'secret', 'multiline']) {
+    if (source[key] !== undefined) {
+      target[key] = source[key];
+    }
+  }
+  return target;
+}
+
+export class HttpWorkQueueClient implements WorkQueue {
+  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;
+  }
+
+  public async enqueue(): Promise<void> {
+    throw new Error('HTTP worker client 不能 enqueue；enqueue 只能由平台 Environment 执行');
+  }
+
+  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', {
+      method: 'POST',
+      signal: this.input.signal,
+      body: JSON.stringify({
+        blockMs: input.blockMs,
+        max: input.max,
+        executionMode: input.executionMode,
+      }),
+    });
+
+    const record = expectRecord(data, 'claim 响应缺少 data');
+    const items = record.items;
+    if (!Array.isArray(items)) {
+      throw new Error('claim 响应缺少 items 数组');
+    }
+    return items.map(parseToolWorkItem);
+  }
+
+  public async complete(result: ToolExecutionResult): Promise<boolean> {
+    const data = await this.requestJson('/work/complete', {
+      method: 'POST',
+      body: JSON.stringify(result),
+    });
+    const record = expectRecord(data, 'complete 响应缺少 data');
+    if (record.accepted !== true) {
+      throw new Error(`work complete 未被接受：${result.workId}`);
+    }
+    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',
+      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);
+  }
+
+  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}`);
+    }
+  }
+
+  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, `平台工作队列响应不是 JSON 对象：${response.status}`);
+  }
+
+  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;
+  }
+
+  public async enqueue(): Promise<void> {
+    throw new Error('HTTP context resolver client 不能 enqueue；enqueue 只能由平台 Harness 执行');
+  }
+
+  public async claim(input: { appId: string; environmentId: string; max?: number }) {
+    this.assertScope(input.appId, input.environmentId);
+    const data = await this.requestJson('/context-work/claim', {
+      method: 'POST',
+      signal: this.input.signal,
+      body: JSON.stringify({
+        max: input.max,
+      }),
+    });
+
+    const record = expectRecord(data, 'context claim 响应缺少 data');
+    const items = record.items;
+    if (!Array.isArray(items)) {
+      throw new Error('context claim 响应缺少 items 数组');
+    }
+    return items.map(parseContextResolveWorkItem);
+  }
+
+  public async complete(result: ContextResolveResult): Promise<boolean> {
+    const data = await this.requestJson('/context-work/complete', {
+      method: 'POST',
+      body: JSON.stringify(result),
+    });
+    const record = expectRecord(data, 'context complete 响应缺少 data');
+    if (record.accepted !== true) {
+      throw new Error(`context complete 未被接受：${result.workId}`);
+    }
+    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', {
+      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}`;
+  }
+}
+
+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') {
+    return {
+      workId,
+      status: 'failed',
+      error: execution.error,
+      effects: execution.effects,
+    };
+  }
+
+  if (execution.status === 'paused') {
+    return {
+      workId,
+      status: 'paused',
+      effects: execution.effects,
+    };
+  }
+
+  return {
+    workId,
+    status: 'completed',
+    modelResult: handler.resultSchema.parse(execution.modelResult),
+    effects: execution.effects,
+  };
+}
+
+function buildSyntheticSession(item: ToolWorkItem, harnessId: string, harnessVersion: number): SessionRecord {
+  const now = new Date().toISOString();
+  return {
+    id: item.sessionId as SessionId,
+    appId: item.appId,
+    scope: item.scope,
+    rootSessionId: item.rootSessionId as SessionId,
+    harnessId: harnessId as HarnessId,
+    harnessVersion,
+    environmentId: item.environmentId as EnvironmentId,
+    environmentUpdatedAt: now,
+    title: item.sessionId,
+    metadata: {},
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+function buildToolCallEvent(item: ToolWorkItem): SessionEvent<'tool.called'> {
+  return {
+    id: item.toolCallEventId,
+    seq: 0,
+    type: 'tool.called',
+    actor: { type: 'assistant', id: 'environment-worker' },
+    createdAt: new Date().toISOString(),
+    payload: {
+      toolName: item.toolName,
+      input: item.input,
+    },
+  };
+}
+
+function parseResourceBinding(slotName: string, value: unknown): {
+  implementationId: string;
+  options: Record<string, unknown>;
+} {
+  const record = expectRecord(value, `resource binding ${slotName} 必须是对象`);
+  const implementationId = expectString(record.implementationId, `${slotName}.implementationId`);
+  const options = record.options === undefined ? {} : expectRecord(record.options, `${slotName}.options 必须是对象`);
+  return {
+    implementationId,
+    options,
+  };
+}
+
+function hasDispose(value: unknown): value is { dispose(): Promise<void> | void } {
+  return isRecord(value) && typeof value.dispose === 'function';
+}
+
+function parseToolWorkItem(value: unknown): 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 sessionId = expectString(record.sessionId, 'sessionId');
+  const rootSessionId = expectString(record.rootSessionId, 'rootSessionId');
+  const scope = parseExecutionScope(record.scope);
+  const toolCallEventId = expectString(record.toolCallEventId, 'toolCallEventId');
+  const toolName = expectString(record.toolName, 'toolName');
+  const mode = parseToolWorkItemMode(record.mode);
+  const executionMode = parseExecutionMode(record.executionMode);
+  const item: ToolWorkItem = {
+    workId,
+    ...(leaseId ? { leaseId } : {}),
+    appId,
+    environmentId,
+    sessionId,
+    rootSessionId,
+    scope,
+    toolCallEventId,
+    toolName,
+    ...(executionMode ? { executionMode } : {}),
+    ...(mode ? { mode } : {}),
+    input: record.input,
+  };
+
+  if (mode === 'resume') {
+    item.resume = parseToolResumeWorkPayload(record.resume);
+  }
+
+  if (isRecord(record.resourceBindings)) {
+    item.resourceBindings = record.resourceBindings;
+  }
+  return item;
+}
+
+function parseToolWorkItemMode(value: unknown): ToolWorkItem['mode'] | undefined {
+  if (value === undefined || value === null || value === 'execute') {
+    return undefined;
+  }
+  if (value === 'resume') {
+    return 'resume';
+  }
+  throw new Error('work item mode 必须是 execute 或 resume');
+}
+
+function parseExecutionMode(value: unknown): ToolWorkItem['executionMode'] | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (value === 'hosted' || value === 'self_hosted') {
+    return value;
+  }
+  throw new Error('work item executionMode 必须是 hosted 或 self_hosted');
+}
+
+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');
+  return {
+    actionEvent,
+    resolvedEvent,
+  };
+}
+
+function parseResumeEvent<TType extends NonNullable<ToolWorkItem['resume']>['actionEvent']['type'] | NonNullable<ToolWorkItem['resume']>['resolvedEvent']['type']>(
+  value: unknown,
+  type: TType,
+  field: string,
+): Extract<NonNullable<ToolWorkItem['resume']>['actionEvent'] | NonNullable<ToolWorkItem['resume']>['resolvedEvent'], { type: TType }> {
+  const event = expectRecord(value, `${field} 必须是对象`);
+  if (event.type !== type) {
+    throw new Error(`${field} 类型必须是 ${type}`);
+  }
+  expectString(event.id, `${field}.id`);
+  if (typeof event.seq !== 'number' || !Number.isFinite(event.seq)) {
+    throw new Error(`${field}.seq 必须是有限数字`);
+  }
+  expectRecord(event.actor, `${field}.actor 必须是对象`);
+  expectString(event.createdAt, `${field}.createdAt`);
+  expectRecord(event.payload, `${field}.payload 必须是对象`);
+
+  if (type === 'agent.action.requested') {
+    return event as unknown as Extract<NonNullable<ToolWorkItem['resume']>['actionEvent'], { type: TType }>;
+  }
+  return event as unknown as Extract<NonNullable<ToolWorkItem['resume']>['resolvedEvent'], { type: TType }>;
+}
+
+function parseExecutionScope(value: unknown): ExecutionScope {
+  const record = expectRecord(value, 'scope 必须是对象');
+  const entries = Object.entries(record).map(([key, entry]) => {
+    if (typeof entry !== 'string') {
+      throw new Error(`scope.${key} 必须是字符串`);
+    }
+    return [key, entry] as const;
+  });
+  return Object.fromEntries(entries);
+}
+
+function parseContextResolveWorkItem(value: unknown): ContextResolveWorkItem {
+  const record = expectRecord(value, 'context 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 sessionId = expectString(record.sessionId, 'sessionId');
+  const rootSessionId = expectString(record.rootSessionId, 'rootSessionId');
+  const request = expectRecord(record.request, 'request 必须是对象');
+  const kind = expectString(request.kind, 'request.kind');
+  if (kind !== 'prompt_context') {
+    throw new Error('request.kind 必须是 prompt_context');
+  }
+  const rawKeys = request.keys;
+  const keys = Array.isArray(rawKeys)
+    ? rawKeys
+      .filter((key): key is string => typeof key === 'string')
+      .map((key) => key.trim())
+      .filter(Boolean)
+    : [];
+  if (!Array.isArray(rawKeys) || keys.length === 0 || keys.length !== rawKeys.length) {
+    throw new Error('request.keys 必须是非空字符串数组');
+  }
+  const executionMode = parseExecutionMode(record.executionMode);
+  return {
+    workId,
+    ...(leaseId ? { leaseId } : {}),
+    appId,
+    environmentId,
+    sessionId,
+    rootSessionId,
+    scope: parseExecutionScope(record.scope),
+    request: {
+      kind: 'prompt_context',
+      keys,
+    },
+    ...(executionMode ? { executionMode } : {}),
+  };
+}
+
+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}`;
+  }
+  return `工具执行失败：${String(error)}`;
+}
+
+function toWorkerErrorPayload(error: unknown): NonNullable<ToolExecutionResult['error']> {
+  const record = isRecord(error) ? error : {};
+  const code = typeof record.code === 'string' ? record.code : undefined;
+  const status = typeof record.status === 'number' && Number.isSafeInteger(record.status)
+    ? record.status
+    : undefined;
+  const retryable = status === undefined
+    ? false
+    : status === 408 || status === 429 || status === 504 || status >= 500;
+  return {
+    ...(code ? { code } : {}),
+    message: normalizeWorkerError(error),
+    retryable,
+    ...(status !== undefined ? { details: { status } } : {}),
+  };
+}
+
+function normalizeContextResolverError(error: unknown): string {
+  if (error instanceof Error) {
+    return `context resolve 失败：${error.message}`;
+  }
+  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} 必须是非空字符串`);
+  }
+  return value;
+}
+
+function expectNumber(value: unknown, field: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(`字段 ${field} 必须是有限数字`);
+  }
+  return value;
+}
+
+function expectRecord(value: unknown, message: string): Record<string, unknown> {
+  if (!isRecord(value)) {
+    throw new Error(message);
+  }
+  return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  if (ms <= 0 || signal?.aborted) {
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(timer);
+      resolve();
+    }, { once: true });
+  });
+}