@ct-agents/worker 0.0.1

package/src/resources/database/index.ts

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

package/src/resources/database/postgres.ts

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import type {
+  Database,
+  ResourceDefinition,
+} from '@ct-agents/protocol';
+
+export type PostgresQueryResult = {
+  rows: unknown[];
+  rowCount: number;
+};
+
+export type PostgresConnectionExecutor = {
+  query(
+    sql: string,
+    params?: readonly unknown[],
+    options?: { readOnly?: boolean; maxRows?: number },
+  ): Promise<PostgresQueryResult>;
+};
+
+export type PostgresQueryFunction = (
+  sql: string,
+  params?: readonly unknown[],
+  options?: { readOnly?: boolean; maxRows?: number },
+) => Promise<PostgresQueryResult>;
+
+export type PostgresConnection = PostgresConnectionExecutor & {
+  withConnection?<T>(callback: (connection: PostgresConnectionExecutor) => Promise<T>): Promise<T>;
+};
+
+export type PostgresConnectionFactory = (
+  connectionString: string,
+  options: Pick<PostgresDatabaseOptions, 'allowWrite' | 'maxRows'>,
+) => PostgresConnection;
+
+export type PostgresDatabaseOptions = {
+  connectionString: string;
+  allowWrite?: boolean;
+  maxRows?: number;
+};
+
+export type CreatePostgresDatabaseResourceDefinitionInput = {
+  createConnection: PostgresConnectionFactory;
+};
+
+export const postgresDatabaseOptionsSchema = z.object({
+  connectionString: z.string().trim().min(1, 'connectionString 为必填字段'),
+  allowWrite: z.boolean().optional(),
+  maxRows: z.number().int().positive().optional(),
+}).strict();
+
+export function createPostgresDatabaseResourceDefinition(
+  input: CreatePostgresDatabaseResourceDefinitionInput,
+): ResourceDefinition<Database, PostgresDatabaseOptions> {
+  return {
+    id: 'database',
+    title: '数据库',
+    description: 'worker 侧 PostgreSQL database resource。',
+    implementations: [
+      {
+        id: 'postgres',
+        title: 'PostgreSQL',
+        description: '通过 worker 本地注入的 PostgreSQL 查询函数访问数据库。',
+        optionsSchema: postgresDatabaseOptionsSchema,
+        optionsJsonSchema: z.toJSONSchema(postgresDatabaseOptionsSchema),
+        factory: (options) => {
+          const parsed = postgresDatabaseOptionsSchema.parse(options);
+          const connection = input.createConnection(parsed.connectionString, {
+            allowWrite: parsed.allowWrite ?? false,
+            maxRows: parsed.maxRows,
+          });
+          if (!connection.withConnection) {
+            throw new Error('PostgreSQL database resource 需要提供 withConnection，不能使用无状态 pool.query');
+          }
+          return createPostgresDatabase({
+            ...parsed,
+            connection,
+          });
+        },
+      },
+    ],
+  };
+}
+
+export function createPostgresDatabase(input: PostgresDatabaseOptions & {
+  query?: PostgresQueryFunction;
+  withConnection?: PostgresConnection['withConnection'];
+  connection?: PostgresConnection;
+}): Database {
+  postgresDatabaseOptionsSchema.parse({
+    connectionString: input.connectionString,
+    allowWrite: input.allowWrite,
+    maxRows: input.maxRows,
+  });
+  return {
+    query: async (sql, params, options) => {
+      const query = input.connection?.query ?? input.query;
+      const withConnection = input.connection?.withConnection ?? input.withConnection;
+      if (!query) {
+        throw new Error('PostgreSQL database resource 缺少 query 实现');
+      }
+      if (!options?.readOnly) {
+        if (input.allowWrite !== true) {
+          throw new Error('当前 database resource 未允许写 SQL');
+        }
+        return query(sql, params, options);
+      }
+
+      if (!withConnection) {
+        throw new Error('readOnly 查询需要同连接 withConnection 实现，不能使用无状态 pool.query');
+      }
+      return withConnection(async (connection) => executeReadOnlyQuery(connection, sql, params, options.maxRows));
+    },
+  };
+}
+
+async function executeReadOnlyQuery(
+  connection: PostgresConnectionExecutor,
+  sql: string,
+  params: readonly unknown[] | undefined,
+  maxRows: number | undefined,
+): Promise<PostgresQueryResult> {
+  await connection.query('BEGIN READ ONLY', [], { readOnly: true });
+  try {
+    const result = await connection.query(wrapReadOnlyQuery(sql, maxRows), params, { readOnly: true, maxRows });
+    await connection.query('ROLLBACK', [], { readOnly: true });
+    return result;
+  } catch (error) {
+    await connection.query('ROLLBACK', [], { readOnly: true }).catch(() => undefined);
+    throw error;
+  }
+}
+
+function wrapReadOnlyQuery(sql: string, maxRows: number | undefined): string {
+  if (maxRows === undefined || !Number.isFinite(maxRows)) {
+    return sql;
+  }
+  return `select * from (${sql}) as ct_agents_limited_query limit ${Math.max(1, Math.trunc(maxRows))}`;
+}

package/src/resources/index.ts

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

package/src/resources/platform-proxy.ts

@@ -0,0 +1,169 @@
+import type { Database } from '@ct-agents/protocol';
+
+export type PlatformResourceProxyInput = {
+  baseUrl: string;
+  environmentId: string;
+  environmentKey: string;
+  slot: string;
+  implementationId?: string;
+  audit: {
+    workId: string;
+    sessionId: string;
+    toolCallEventId: string;
+  };
+  timeoutMs?: number;
+  requestTimeoutMs?: number;
+  signal?: AbortSignal;
+  fetchImpl?: typeof fetch;
+};
+
+export type PlatformDatabaseProxyResourceInput = Omit<PlatformResourceProxyInput, 'slot'> & {
+  slot?: string;
+};
+
+export type InvokePlatformResourceProxyInput = PlatformResourceProxyInput & {
+  method: string;
+  args?: unknown[] | Record<string, unknown>;
+};
+
+export class PlatformResourceProxyError extends Error {
+  readonly status: number;
+  readonly code?: string;
+
+  constructor(input: { message: string; status: number; code?: string }) {
+    super(input.message);
+    this.name = 'PlatformResourceProxyError';
+    this.status = input.status;
+    this.code = input.code;
+  }
+}
+
+function trimTrailingSlash(value: string): string {
+  return value.endsWith('/') ? value.slice(0, -1) : value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function expectRecord(value: unknown, message: string): Record<string, unknown> {
+  if (!isRecord(value)) {
+    throw new Error(message);
+  }
+  return value;
+}
+
+async function parseProxyEnvelope(response: Response): Promise<unknown> {
+  const body = await response.json().catch(() => null) as unknown;
+  const envelope = expectRecord(body, `平台 resource proxy 响应不是 JSON 对象：${response.status}`);
+  if (!response.ok || envelope.success !== true) {
+    const error = isRecord(envelope.error) ? envelope.error : {};
+    throw new PlatformResourceProxyError({
+      message: typeof error.message === 'string' ? error.message : `平台 resource proxy 请求失败：${response.status}`,
+      status: response.status,
+      ...(typeof error.code === 'string' ? { code: error.code } : {}),
+    });
+  }
+  const data = expectRecord(envelope.data, 'resource proxy 响应缺少 data');
+  return data.result;
+}
+
+/**
+ * 通过平台 Resource proxy 调用一个 resource method。
+ *
+ * worker 只持有 environment key，不持有平台内置 resource 的原始密钥。
+ */
+export async function invokePlatformResourceProxy(input: InvokePlatformResourceProxyInput): Promise<unknown> {
+  const baseUrl = trimTrailingSlash(input.baseUrl);
+  const fetchImpl = input.fetchImpl ?? fetch;
+  const headers = new Headers();
+  headers.set('x-api-key', input.environmentKey);
+  headers.set('content-type', 'application/json');
+  const body = {
+    ...(input.implementationId ? { implementationId: input.implementationId } : {}),
+    method: input.method,
+    ...(input.audit ? { audit: input.audit } : {}),
+    args: input.args ?? [],
+    ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+  };
+  const controller = new AbortController();
+  const abortHandler = () => controller.abort();
+  input.signal?.addEventListener('abort', abortHandler, { once: true });
+  const requestTimeoutMs = input.requestTimeoutMs ?? (input.timeoutMs ? input.timeoutMs + 5_000 : 35_000);
+  const timer = setTimeout(() => controller.abort(), requestTimeoutMs);
+  try {
+    const response = await fetchImpl(`${baseUrl}/v1/environments/${encodeURIComponent(input.environmentId)}/resources/${encodeURIComponent(input.slot)}/invoke`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    return await parseProxyEnvelope(response);
+  } catch (error) {
+    if (isAbortError(error)) {
+      throw new Error('平台 resource proxy 请求超时');
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    input.signal?.removeEventListener('abort', abortHandler);
+  }
+}
+
+/**
+ * 创建一个通过平台 Resource proxy 访问的动态 resource。
+ *
+ * 该代理不暴露给业务仓；真实 method 是否存在由平台 route 在运行时校验。
+ */
+export function createPlatformResourceProxy<TResource extends object>(
+  input: PlatformResourceProxyInput,
+): TResource {
+  const methods = new Map<string, (...args: unknown[]) => Promise<unknown>>();
+  return new Proxy({}, {
+    get(_target, property) {
+      if (typeof property !== 'string' || property === 'then' || property === 'dispose') {
+        return undefined;
+      }
+      let method = methods.get(property);
+      if (!method) {
+        method = async (...args: unknown[]) => invokePlatformResourceProxy({
+          ...input,
+          method: property,
+          args,
+        });
+        methods.set(property, method);
+      }
+      return method;
+    },
+  }) as TResource;
+}
+
+/**
+ * 创建通过平台 Resource proxy 访问的 database resource。
+ *
+ * worker 只持有 environment key，不持有平台内置 resource 的原始密钥。
+ */
+export function createPlatformDatabaseProxyResource(input: PlatformDatabaseProxyResourceInput): Database {
+  const slot = input.slot?.trim() || 'database';
+
+  return {
+    async query(sql, params, options) {
+      const timeoutMs = options?.timeoutMs ?? input.timeoutMs;
+      return invokePlatformResourceProxy({
+        ...input,
+        slot,
+        method: 'query',
+        args: {
+          sql,
+          ...(params !== undefined ? { params: Array.from(params) } : {}),
+          ...(options !== undefined ? { options } : {}),
+        },
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+      });
+    },
+  };
+}
+
+function isAbortError(error: unknown) {
+  return error instanceof DOMException && error.name === 'AbortError';
+}