@ct-agents/worker 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ct-agents/worker",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "files": [
     "src"
@@ -12,10 +12,10 @@
   },
   "dependencies": {
     "zod": "4.4.3",
-    "@ct-agents/memory": "0.0.1",
-    "@ct-agents/prompts": "0.0.1",
-    "@ct-agents/tools": "0.0.1",
-    "@ct-agents/protocol": "0.0.1"
+    "@ct-agents/memory": "0.0.2",
+    "@ct-agents/prompts": "0.0.2",
+    "@ct-agents/tools": "0.0.2",
+    "@ct-agents/protocol": "0.0.2"
   },
   "optionalDependencies": {
     "dockerode": "4.0.9"

package/src/index.ts

@@ -27,7 +27,7 @@ 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 { createAskUserToolHandler, createWebSearchToolHandler } from '@ct-agents/tools/builtin-tools';
 import { z } from 'zod';
 import {
   createPlatformDatabaseProxyResource,
@@ -44,6 +44,7 @@ export type ResourceOptionsParser = {
 
 export type EnvironmentWorkerResourceFactoryContext = {
   item: ToolWorkItem;
+  abortSignal?: AbortSignal;
 };
 
 export type EnvironmentWorkerResourceImplementation<
@@ -88,6 +89,7 @@ export type EnvironmentWorkerInput = {
   resolveResources?: ResolveResources;
   resourceImpls?: EnvironmentWorkerResourceImplementations;
   platformResourceProxy?: EnvironmentWorkerPlatformResourceProxy;
+  abortSignal?: AbortSignal;
   maxBatchSize?: number;
   harness?: {
     id: string;
@@ -144,6 +146,7 @@ export function createPlatformBuiltinToolHandlers(): ToolHandler[] {
     createLoadSkillToolHandler(),
     createLoadMemoryToolHandler(),
     createUpdateMemoryToolHandler(),
+    createWebSearchToolHandler(),
     ...createSandboxTools(),
   ];
 }
@@ -304,6 +307,7 @@ export class EnvironmentWorker {
       hostedPolicy: this.input.hostedPolicy,
       resources,
       toolCallEvent: buildToolCallEvent(item),
+      abortSignal: this.input.abortSignal,
     };
   }
 
@@ -333,7 +337,10 @@ export class EnvironmentWorker {
       const parsedOptions = implementation.options
         ? implementation.options.parse(binding.options)
         : binding.options;
-      const instance = await implementation.factory(parsedOptions, { item });
+      const instance = await implementation.factory(parsedOptions, {
+        item,
+        ...(this.input.abortSignal ? { abortSignal: this.input.abortSignal } : {}),
+      });
       resources[slotName] = instance;
       if (hasDispose(instance)) {
         disposers.push(async () => {

package/src/resources/index.ts

@@ -1,2 +1,3 @@
 export * from './database/index.js';
 export * from './platform-proxy.js';
+export * from './web-search/index.js';

package/src/resources/web-search/index.ts

@@ -0,0 +1 @@
+export * from './tavily.js';

package/src/resources/web-search/tavily.ts

@@ -0,0 +1,408 @@
+import { z } from 'zod';
+import type {
+  ResourceDefinition,
+  WebSearchErrorCode,
+  WebSearchInput,
+  WebSearchResource,
+  WebSearchResult,
+  WebSearchWarning,
+} from '@ct-agents/protocol';
+import type {
+  EnvironmentWorkerResourceImplementation,
+} from '../../index.js';
+
+const TAVILY_SEARCH_ENDPOINT = 'https://api.tavily.com/search';
+const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+const MAX_SNIPPET_BYTES = 8 * 1024;
+const MAX_CONTENT_BYTES = 64 * 1024;
+const MAX_TOTAL_TEXT_BYTES = 512 * 1024;
+const MAX_TITLE_BYTES = 8 * 1024;
+const MAX_URL_BYTES = 16 * 1024;
+const MAX_PUBLISHED_AT_BYTES = 1024;
+const MAX_REQUEST_ID_BYTES = 1024;
+const RESULT_BUDGET_RESERVE_BYTES = 4 * 1024;
+
+export type TavilyWebSearchOptions = {
+  apiKey: string;
+  timeoutMs: number;
+};
+
+export const tavilyWebSearchOptionsSchema = z.object({
+  apiKey: z.string().trim().min(1).meta({ secret: true }),
+  timeoutMs: z.number().int().min(1_000).max(120_000).default(30_000),
+}).strict();
+
+const tavilyResultSchema = z.object({
+  title: z.string(),
+  url: z.url(),
+  content: z.string().nullable().optional(),
+  raw_content: z.string().nullable().optional(),
+  score: z.number().optional(),
+  published_date: z.string().nullable().optional(),
+  favicon: z.string().nullable().optional(),
+}).strict();
+
+const tavilyResponseSchema = z.object({
+  query: z.string().optional(),
+  answer: z.string().nullable().optional(),
+  images: z.array(z.unknown()).optional(),
+  follow_up_questions: z.array(z.string()).nullable().optional(),
+  request_id: z.string().max(MAX_REQUEST_ID_BYTES).optional(),
+  response_time: z.number().optional(),
+  results: z.array(tavilyResultSchema),
+}).strict();
+
+export type TavilyWebSearchDependencies = {
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+  dateNow?: () => Date;
+};
+
+function durationSince(startedAt: number, now: () => number): number {
+  return Math.max(0, Math.round(now() - startedAt));
+}
+
+function failure(
+  input: WebSearchInput,
+  startedAt: number,
+  now: () => number,
+  dateNow: () => Date,
+  code: WebSearchErrorCode,
+  message: string,
+  retryable: boolean,
+  providerRequestId?: string,
+): WebSearchResult {
+  return {
+    success: false,
+    query: input.query,
+    searchedAt: dateNow().toISOString(),
+    durationMs: durationSince(startedAt, now),
+    ...(providerRequestId ? { providerRequestId } : {}),
+    error: { code, message, retryable },
+  };
+}
+
+function httpFailure(
+  status: number,
+): { code: WebSearchErrorCode; message: string; retryable: boolean } {
+  if (status === 400) return { code: 'WEB_SEARCH_INVALID_REQUEST', message: '搜索请求被供应商拒绝，请检查输入', retryable: false };
+  if (status === 401) return { code: 'WEB_SEARCH_AUTH_FAILED', message: '搜索服务认证失败，请检查 Environment 密钥', retryable: false };
+  if (status === 429) return { code: 'WEB_SEARCH_RATE_LIMITED', message: '搜索服务请求过于频繁，请稍后重试', retryable: true };
+  if (status === 432 || status === 433) return { code: 'WEB_SEARCH_QUOTA_EXCEEDED', message: '搜索服务额度不足，请检查订阅', retryable: false };
+  if (status >= 500) return { code: 'WEB_SEARCH_PROVIDER_UNAVAILABLE', message: '搜索服务暂时不可用，请稍后重试', retryable: true };
+  return { code: 'WEB_SEARCH_PROVIDER_ERROR', message: '搜索服务返回了非预期响应', retryable: false };
+}
+
+function buildRequest(input: WebSearchInput): { body: Record<string, unknown>; warnings: WebSearchWarning[] } {
+  const topic = input.topic ?? 'general';
+  const warnings: WebSearchWarning[] = [];
+  const body: Record<string, unknown> = {
+    query: input.query,
+    topic,
+    search_depth: (input.depth ?? 'standard') === 'deep' ? 'advanced' : 'basic',
+    max_results: input.maxResults ?? 5,
+    include_raw_content: input.contentFormat && input.contentFormat !== 'none' ? input.contentFormat : false,
+    include_answer: false,
+    include_images: false,
+    include_image_descriptions: false,
+    include_favicon: false,
+    include_usage: false,
+    auto_parameters: false,
+  };
+  if (input.includeDomains) body.include_domains = input.includeDomains;
+  if (input.excludeDomains) body.exclude_domains = input.excludeDomains;
+  if (input.timeFilter?.type === 'relative') {
+    if (topic === 'finance') {
+      warnings.push({ code: 'TIME_FILTER_NOT_APPLIED', message: 'finance 主题不支持相对时间过滤，已忽略该条件' });
+    } else {
+      body.time_range = input.timeFilter.range;
+    }
+  } else if (input.timeFilter?.type === 'absolute') {
+    if (input.timeFilter.from) body.start_date = input.timeFilter.from;
+    if (input.timeFilter.to) body.end_date = input.timeFilter.to;
+  }
+  if (input.region) {
+    if (topic === 'general') {
+      body.country = new Intl.DisplayNames(['en'], { type: 'region' }).of(input.region) ?? input.region;
+    } else {
+      warnings.push({ code: 'REGION_NOT_APPLIED', message: `${topic} 主题不支持地区过滤，已忽略该条件` });
+    }
+  }
+  return { body, warnings };
+}
+
+async function readBoundedBody(response: Response): Promise<string> {
+  const declaredLength = Number(response.headers.get('content-length'));
+  if (Number.isFinite(declaredLength) && declaredLength > MAX_RESPONSE_BYTES) {
+    await cancelResponseBody(response);
+    throw new ResponseTooLargeError();
+  }
+  if (!response.body) return '';
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > MAX_RESPONSE_BYTES) {
+        await reader.cancel().catch(() => undefined);
+        throw new ResponseTooLargeError();
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    throw new InvalidResponseEncodingError();
+  }
+}
+
+class ResponseTooLargeError extends Error {}
+class InvalidResponseEncodingError extends Error {}
+class ProviderSecurityError extends Error {}
+
+async function cancelResponseBody(response: Response): Promise<void> {
+  try {
+    await response.body?.cancel();
+  } catch {
+    // 释放连接是 best-effort，不能覆盖原始 HTTP 或响应预算错误。
+  }
+}
+
+function containsSecret(value: string | null | undefined, apiKey: string): boolean {
+  return typeof value === 'string' && value.includes(apiKey);
+}
+
+function assertNoSecret(value: string | null | undefined, apiKey: string): void {
+  if (containsSecret(value, apiKey)) {
+    throw new ProviderSecurityError('供应商响应包含搜索服务密钥');
+  }
+}
+
+function normalizeProviderRequestId(value: string | null | undefined, apiKey: string): string | undefined {
+  if (!value) return undefined;
+  assertNoSecret(value, apiKey);
+  if (new TextEncoder().encode(value).byteLength > MAX_REQUEST_ID_BYTES) {
+    throw new ProviderSecurityError('供应商 request id 超过限制');
+  }
+  return value;
+}
+
+function truncateUtf8(value: string, maxBytes: number): { value: string; truncated: boolean; bytes: number } {
+  const encoded = new TextEncoder().encode(value);
+  if (encoded.byteLength <= maxBytes) return { value, truncated: false, bytes: encoded.byteLength };
+  let end = Math.max(0, maxBytes);
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  while (end > 0) {
+    try {
+      const result = decoder.decode(encoded.subarray(0, end));
+      return { value: result, truncated: true, bytes: end };
+    } catch {
+      end -= 1;
+    }
+  }
+  return { value: '', truncated: true, bytes: 0 };
+}
+
+function normalizeSuccess(
+  input: WebSearchInput,
+  response: z.infer<typeof tavilyResponseSchema>,
+  warnings: WebSearchWarning[],
+  startedAt: number,
+  now: () => number,
+  dateNow: () => Date,
+  apiKey: string,
+): WebSearchResult {
+  const searchedAt = dateNow().toISOString();
+  const encoder = new TextEncoder();
+  const fixedBytes = encoder.encode(input.query).byteLength
+    + encoder.encode(searchedAt).byteLength
+    + encoder.encode('tavily').byteLength
+    + RESULT_BUDGET_RESERVE_BYTES;
+  const budget = {
+    remaining: Math.max(0, MAX_TOTAL_TEXT_BYTES - fixedBytes),
+    truncated: false,
+  };
+  const takeText = (value: string, maxBytes: number) => {
+    const result = truncateUtf8(value, Math.min(maxBytes, budget.remaining));
+    budget.remaining -= result.bytes;
+    budget.truncated ||= result.truncated;
+    return result.value;
+  };
+
+  const rawRequestId = normalizeProviderRequestId(response.request_id, apiKey);
+  const providerRequestId = rawRequestId ? takeText(rawRequestId, MAX_REQUEST_ID_BYTES) : undefined;
+  const maxResults = input.maxResults ?? 5;
+  if (response.results.length > maxResults) budget.truncated = true;
+  const results = response.results.slice(0, maxResults).flatMap((item) => {
+    assertNoSecret(item.title, apiKey);
+    assertNoSecret(item.url, apiKey);
+    assertNoSecret(item.content, apiKey);
+    assertNoSecret(item.raw_content, apiKey);
+    assertNoSecret(item.published_date, apiKey);
+    const url = new URL(item.url);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new Error('搜索结果 URL 协议无效');
+    const source = url.hostname.toLowerCase();
+    const urlBytes = encoder.encode(item.url).byteLength;
+    const sourceBytes = encoder.encode(source).byteLength;
+    if (urlBytes > MAX_URL_BYTES || urlBytes + sourceBytes > budget.remaining) {
+      budget.truncated = true;
+      return [];
+    }
+    budget.remaining -= urlBytes + sourceBytes;
+    const title = takeText(item.title, MAX_TITLE_BYTES);
+    const publishedAt = item.published_date ? takeText(item.published_date, MAX_PUBLISHED_AT_BYTES) : undefined;
+    const snippet = takeText(item.content ?? '', MAX_SNIPPET_BYTES);
+    const content = input.contentFormat && input.contentFormat !== 'none' && item.raw_content !== null && item.raw_content !== undefined
+      ? takeText(item.raw_content, MAX_CONTENT_BYTES)
+      : undefined;
+    return [{
+      title,
+      url: item.url,
+      source,
+      ...(publishedAt ? { publishedAt } : {}),
+      snippet,
+      ...(content !== undefined ? { content } : {}),
+      ...(item.score !== undefined ? { relevanceScore: item.score } : {}),
+    }];
+  });
+  const finalWarnings = [...warnings];
+  if (budget.truncated) finalWarnings.push({ code: 'CONTENT_TRUNCATED', message: '搜索结果内容已按平台响应预算裁剪' });
+  return {
+    success: true,
+    query: input.query,
+    searchedAt,
+    provider: 'tavily',
+    ...(providerRequestId ? { providerRequestId } : {}),
+    durationMs: durationSince(startedAt, now),
+    results,
+    ...(finalWarnings.length > 0 ? { warnings: finalWarnings } : {}),
+  };
+}
+
+export function createTavilyWebSearchResource(
+  rawOptions: { apiKey: string; timeoutMs?: number },
+  dependencies: TavilyWebSearchDependencies = {},
+): WebSearchResource {
+  const options = tavilyWebSearchOptionsSchema.parse(rawOptions);
+  const fetchImpl = dependencies.fetchImpl ?? fetch;
+  const now = dependencies.now ?? (() => performance.now());
+  const dateNow = dependencies.dateNow ?? (() => new Date());
+  return {
+    async search(input, context) {
+      const startedAt = now();
+      const { body, warnings } = buildRequest(input);
+      const controller = new AbortController();
+      let abortSource: 'timeout' | 'upstream' | undefined;
+      const abortRequest = (source: 'timeout' | 'upstream') => {
+        if (controller.signal.aborted) return;
+        abortSource = source;
+        controller.abort();
+      };
+      const onUpstreamAbort = () => abortRequest('upstream');
+      if (context?.abortSignal?.aborted) {
+        throw new DOMException('搜索请求已中断', 'AbortError');
+      }
+      context?.abortSignal?.addEventListener('abort', onUpstreamAbort, { once: true });
+      const timer = setTimeout(() => abortRequest('timeout'), options.timeoutMs);
+      try {
+        const response = await fetchImpl(TAVILY_SEARCH_ENDPOINT, {
+          method: 'POST',
+          redirect: 'error',
+          headers: {
+            authorization: `Bearer ${options.apiKey}`,
+            'content-type': 'application/json',
+          },
+          body: JSON.stringify(body),
+          signal: controller.signal,
+        });
+        let headerRequestId: string | undefined;
+        try {
+          headerRequestId = normalizeProviderRequestId(response.headers.get('x-request-id'), options.apiKey);
+        } catch {
+          await cancelResponseBody(response);
+          return failure(input, startedAt, now, dateNow, 'WEB_SEARCH_PROVIDER_ERROR', '搜索服务响应包含不安全的 request id', false);
+        }
+        if (!response.ok) {
+          await cancelResponseBody(response);
+          const mapped = httpFailure(response.status);
+          return failure(input, startedAt, now, dateNow, mapped.code, mapped.message, mapped.retryable, headerRequestId);
+        }
+        const text = await readBoundedBody(response);
+        let json: unknown;
+        try {
+          json = JSON.parse(text) as unknown;
+        } catch {
+          return failure(input, startedAt, now, dateNow, 'WEB_SEARCH_PROVIDER_ERROR', '搜索服务返回了无法解析的响应', false, headerRequestId);
+        }
+        const parsed = tavilyResponseSchema.safeParse(json);
+        if (!parsed.success) {
+          return failure(input, startedAt, now, dateNow, 'WEB_SEARCH_PROVIDER_ERROR', '搜索服务响应格式不符合预期', false, headerRequestId);
+        }
+        try {
+          return normalizeSuccess(input, parsed.data, warnings, startedAt, now, dateNow, options.apiKey);
+        } catch {
+          return failure(input, startedAt, now, dateNow, 'WEB_SEARCH_PROVIDER_ERROR', '搜索服务响应包含无效结果', false, headerRequestId);
+        }
+      } catch (error) {
+        if (error instanceof ResponseTooLargeError) {
+          return failure(input, startedAt, now, dateNow, 'WEB_SEARCH_RESPONSE_TOO_LARGE', '搜索服务响应超过 2 MiB 限制', false);
+        }
+        if (error instanceof InvalidResponseEncodingError) {
+          return failure(input, startedAt, now, dateNow, 'WEB_SEARCH_PROVIDER_ERROR', '搜索服务响应不是有效的 UTF-8', false);
+        }
+        if (abortSource === 'upstream') {
+          throw new DOMException('搜索请求已中断', 'AbortError');
+        }
+        if (abortSource === 'timeout') {
+          return failure(input, startedAt, now, dateNow, 'WEB_SEARCH_TIMEOUT', '搜索服务请求超时，请稍后重试', true);
+        }
+        return failure(input, startedAt, now, dateNow, 'WEB_SEARCH_PROVIDER_UNAVAILABLE', '无法连接搜索服务，请稍后重试', true);
+      } finally {
+        clearTimeout(timer);
+        context?.abortSignal?.removeEventListener('abort', onUpstreamAbort);
+      }
+    },
+  };
+}
+
+export function createTavilyWebSearchResourceImplementation(
+  dependencies: TavilyWebSearchDependencies = {},
+): EnvironmentWorkerResourceImplementation<WebSearchResource, TavilyWebSearchOptions> {
+  return {
+    title: 'Tavily',
+    description: '通过 Tavily 官方 Search API 搜索公开互联网内容。',
+    options: tavilyWebSearchOptionsSchema,
+    factory: (options) => createTavilyWebSearchResource(options, dependencies),
+  };
+}
+
+export function createTavilyWebSearchResourceDefinition(
+  dependencies: TavilyWebSearchDependencies = {},
+): ResourceDefinition<WebSearchResource, TavilyWebSearchOptions> {
+  return {
+    id: 'webSearch',
+    title: '互联网搜索',
+    description: '供应商无关的互联网搜索资源。',
+    implementations: [{
+      id: 'tavily',
+      title: 'Tavily',
+      description: '通过 Tavily 官方 Search API 搜索公开互联网内容。',
+      supportedExecutionModes: ['hosted', 'self_hosted'],
+      optionsSchema: tavilyWebSearchOptionsSchema,
+      optionsJsonSchema: z.toJSONSchema(tavilyWebSearchOptionsSchema),
+      factory: (options) => createTavilyWebSearchResource(tavilyWebSearchOptionsSchema.parse(options), dependencies),
+    }],
+  };
+}