@ct-agents/tools 0.0.1

package/src/sandbox-tools/index.ts

@@ -0,0 +1,39 @@
+import type { ToolHandler } from '@ct-agents/protocol';
+import { createBashToolHandler, type BashToolOptions } from './bash.js';
+import { createDbExecuteToolHandler, type DbExecuteToolOptions } from './db-execute.js';
+import { createDbQueryToolHandler, type DbQueryToolOptions } from './db-query.js';
+import { createFsReadToolHandler, type FsReadToolOptions } from './fs-read.js';
+import { createFsWriteToolHandler, type FsWriteToolOptions } from './fs-write.js';
+
+export type CreateSandboxToolsOptions = {
+  dbQuery?: DbQueryToolOptions;
+  fsRead?: FsReadToolOptions;
+  fsWrite?: FsWriteToolOptions;
+  bash?: BashToolOptions;
+  allowDbWrite?: boolean;
+  dbExecute?: Omit<DbExecuteToolOptions, 'allowWrite'>;
+};
+
+export function createSandboxTools(options: CreateSandboxToolsOptions = {}): ToolHandler[] {
+  return [
+    createDbQueryToolHandler(options.dbQuery),
+    createFsReadToolHandler(options.fsRead),
+    createFsWriteToolHandler(options.fsWrite),
+    createBashToolHandler(options.bash),
+    createDbExecuteToolHandler({
+      ...options.dbExecute,
+      allowWrite: options.allowDbWrite ?? false,
+    }),
+  ];
+}
+
+export * from './approval.js';
+export * from './bash.js';
+export * from './db-execute.js';
+export * from './db-query.js';
+export * from './fs-read.js';
+export * from './fs-write.js';
+export * from './path-jail.js';
+export * from './shared.js';
+export * from './sql-guard.js';
+export * from './truncate.js';

package/src/sandbox-tools/path-jail.ts

@@ -0,0 +1,36 @@
+import { isAbsolute, normalize } from 'node:path';
+import { isAbsolute as isPosixAbsolute, normalize as normalizePosix } from 'node:path/posix';
+import { isAbsolute as isWinAbsolute, normalize as normalizeWin } from 'node:path/win32';
+
+export const SANDBOX_PATH_OUT_OF_JAIL = 'SANDBOX_PATH_OUT_OF_JAIL';
+
+/**
+ * 工具层只处理词法级路径 jail：拒绝绝对路径和 `..` 逃逸，并把路径规范成 sandbox 内相对路径。
+ * symlink/真实路径逃逸必须由具体 SandboxHandle 在执行读写时继续兜底。
+ */
+export function resolveSandboxPath(path: string): string {
+  const trimmed = path.trim();
+  if (!trimmed) {
+    throw new Error('路径不能为空');
+  }
+
+  if (isAbsolute(trimmed) || isPosixAbsolute(trimmed) || isWinAbsolute(trimmed)) {
+    throw new Error(`路径越界：${path}`);
+  }
+
+  const slashPath = trimmed.replace(/\\/g, '/');
+  const normalized = normalizePosix(slashPath);
+  const nativeNormalized = normalize(trimmed);
+  const winNormalized = normalizeWin(trimmed);
+  if (isEscaping(normalized) || isEscaping(nativeNormalized) || isEscaping(winNormalized)) {
+    throw new Error(`路径越界：${path}`);
+  }
+
+  return normalized === '.' ? '' : normalized;
+}
+
+function isEscaping(path: string): boolean {
+  return path === '..'
+    || path.startsWith('../')
+    || path.startsWith('..\\');
+}

package/src/sandbox-tools/shared.ts

@@ -0,0 +1,64 @@
+import type {
+  SandboxHandle,
+  ToolExecution,
+} from '@ct-agents/protocol';
+import { SANDBOX_PATH_OUT_OF_JAIL, resolveSandboxPath } from './path-jail.js';
+
+export const DEFAULT_TEXT_MAX_BYTES = 128_000;
+export const DEFAULT_MAX_ROWS = 100;
+export const HARD_MAX_TEXT_BYTES = 1_048_576;
+export const HARD_MAX_ROWS = 1_000;
+export const HARD_MAX_TIMEOUT_MS = 300_000;
+
+export function normalizeLimit(value: number | undefined, fallback: number, hardMax?: number): number {
+  if (value === undefined || !Number.isFinite(value)) {
+    return clampPositiveInteger(fallback, hardMax);
+  }
+  return clampPositiveInteger(value, hardMax);
+}
+
+export function normalizeBoolean(value: boolean | undefined, fallback: boolean): boolean {
+  return value ?? fallback;
+}
+
+export function countUtf8Bytes(text: string): number {
+  return new TextEncoder().encode(text).byteLength;
+}
+
+export function requireSandbox(context: { resources: { sandbox?: SandboxHandle } }): SandboxHandle | ToolExecution<never> {
+  const sandbox = context.resources.sandbox;
+  if (!sandbox) {
+    return failed('SANDBOX_RESOURCE_MISSING', '当前工具上下文缺少 sandbox resource');
+  }
+  return sandbox;
+}
+
+export function normalizePathOrFailed<T>(path: string): string | ToolExecution<T> {
+  try {
+    return resolveSandboxPath(path);
+  } catch (error) {
+    return failed(
+      SANDBOX_PATH_OUT_OF_JAIL,
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+}
+
+export function failed<T>(code: string, message: string): ToolExecution<T> {
+  return {
+    status: 'failed',
+    error: {
+      code,
+      message,
+      retryable: false,
+    },
+  };
+}
+
+function clampPositiveInteger(value: number, hardMax: number | undefined): number {
+  const normalized = Math.max(1, Math.trunc(value));
+  if (hardMax === undefined) {
+    return normalized;
+  }
+  return Math.min(normalized, Math.max(1, Math.trunc(hardMax)));
+}

package/src/sandbox-tools/sql-guard.ts

@@ -0,0 +1,128 @@
+export type SqlStructureScan = {
+  structureSql: string;
+  hasStatementSeparator: boolean;
+};
+
+export function scanSqlStructure(sql: string): SqlStructureScan {
+  let output = '';
+  let blockDepth = 0;
+  let inLineComment = false;
+  let index = 0;
+  let hasStatementSeparator = false;
+
+  while (index < sql.length) {
+    const current = sql[index];
+    const next = sql[index + 1];
+
+    if (inLineComment) {
+      if (current === '\n' || current === '\r') {
+        inLineComment = false;
+        output += current;
+      }
+      index += 1;
+      continue;
+    }
+
+    if (blockDepth > 0) {
+      if (current === '/' && next === '*') {
+        blockDepth += 1;
+        index += 2;
+        continue;
+      }
+      if (current === '*' && next === '/') {
+        blockDepth -= 1;
+        index += 2;
+        continue;
+      }
+      index += 1;
+      continue;
+    }
+
+    if (current === '\'') {
+      output += ' ';
+      index = consumeSingleQuotedString(sql, index);
+      continue;
+    }
+
+    const dollarQuoteTag = readDollarQuoteTag(sql, index);
+    if (dollarQuoteTag) {
+      output += ' ';
+      index = consumeDollarQuotedString(sql, index, dollarQuoteTag);
+      continue;
+    }
+
+    if (current === '-' && next === '-') {
+      inLineComment = true;
+      index += 2;
+      continue;
+    }
+
+    if (current === '/' && next === '*') {
+      blockDepth = 1;
+      index += 2;
+      continue;
+    }
+
+    if (current === ';') {
+      hasStatementSeparator = true;
+      index += 1;
+      continue;
+    }
+
+    output += current;
+    index += 1;
+  }
+
+  return {
+    structureSql: output,
+    hasStatementSeparator,
+  };
+}
+
+export function containsDangerousPostgresCapability(sql: string): boolean {
+  return /\b(pg_read_file|pg_read_binary_file|pg_ls_dir|pg_ls_logdir|pg_ls_waldir|pg_stat_file|pg_stat_directory|lo_import|lo_export|lo_get|lo_put|loread|lowrite|pg_sleep|pg_sleep_for|pg_sleep_until|pg_notify|pg_advisory_lock|pg_advisory_lock_shared|pg_advisory_xact_lock|pg_advisory_xact_lock_shared|pg_try_advisory_lock|pg_try_advisory_lock_shared|pg_try_advisory_xact_lock|pg_try_advisory_xact_lock_shared|pg_advisory_unlock|pg_advisory_unlock_shared|pg_advisory_unlock_all|pg_terminate_backend|pg_cancel_backend|pg_signal_backend|pg_reload_conf|pg_rotate_logfile|pg_logdir_ls|pg_largeobject|pg_get_functiondef|pg_get_viewdef|pg_get_ruledef|pg_get_triggerdef|set_config|dblink|dblink_connect|dblink_exec|dblink_send_query)\b/i.test(sql)
+    || /\b(from|join)\s+(?:pg_catalog\.)?(pg_stat_activity|pg_shadow|pg_roles|pg_database|pg_authid|pg_hba_file_rules|pg_db_role_setting)\b/i.test(sql)
+    || /\b(from|join)\s+information_schema\.(role_table_grants|applicable_roles|enabled_roles|administrable_role_authorizations)\b/i.test(sql);
+}
+
+export function containsWriteOrDdlKeyword(sql: string): boolean {
+  return /\b(insert|update|delete|merge|truncate|drop|alter|create|grant|revoke|vacuum|copy|call|set|reset|into|analyze|cluster|reindex|refresh)\b/i.test(sql)
+    || /\bcomment\s+on\b/i.test(sql);
+}
+
+export function containsDdlDclOrMaintenanceKeyword(sql: string): boolean {
+  return /\b(truncate|drop|alter|create|grant|revoke|vacuum|copy|call|reset|analyze|cluster|reindex|refresh)\b/i.test(sql)
+    || /\bcomment\s+on\b/i.test(sql);
+}
+
+function consumeSingleQuotedString(sql: string, startIndex: number): number {
+  let index = startIndex + 1;
+  while (index < sql.length) {
+    const current = sql[index];
+    const next = sql[index + 1];
+    if (current === '\'' && next === '\'') {
+      index += 2;
+      continue;
+    }
+    if (current === '\'') {
+      return index + 1;
+    }
+    index += 1;
+  }
+  return index;
+}
+
+function readDollarQuoteTag(sql: string, startIndex: number): string | null {
+  if (sql[startIndex] !== '$') {
+    return null;
+  }
+
+  const rest = sql.slice(startIndex);
+  const match = rest.match(/^\$[A-Za-z_][A-Za-z0-9_]*\$|^\$\$/);
+  return match?.[0] ?? null;
+}
+
+function consumeDollarQuotedString(sql: string, startIndex: number, tag: string): number {
+  const endIndex = sql.indexOf(tag, startIndex + tag.length);
+  return endIndex === -1 ? sql.length : endIndex + tag.length;
+}

package/src/sandbox-tools/truncate.ts

@@ -0,0 +1,63 @@
+export type TruncatedRows<T> = {
+  rows: T[];
+  truncated: boolean;
+  totalRows?: number;
+};
+
+export type TruncatedText = {
+  text: string;
+  truncated: boolean;
+  totalBytes?: number;
+};
+
+export function truncateRows<T>(rows: readonly T[], maxRows: number): TruncatedRows<T> {
+  const normalizedMaxRows = normalizeLimit(maxRows, 1);
+  if (rows.length <= normalizedMaxRows) {
+    return {
+      rows: [...rows],
+      truncated: false,
+    };
+  }
+
+  return {
+    rows: rows.slice(0, normalizedMaxRows),
+    truncated: true,
+    totalRows: rows.length,
+  };
+}
+
+export function truncateText(text: string, maxBytes: number): TruncatedText {
+  const normalizedMaxBytes = normalizeLimit(maxBytes, 1);
+  const bytes = new TextEncoder().encode(text);
+  if (bytes.byteLength <= normalizedMaxBytes) {
+    return { text, truncated: false };
+  }
+
+  const truncatedBytes = sliceCompleteUtf8(bytes, normalizedMaxBytes);
+  return {
+    text: new TextDecoder().decode(truncatedBytes),
+    truncated: true,
+    totalBytes: bytes.byteLength,
+  };
+}
+
+function sliceCompleteUtf8(bytes: Uint8Array, maxBytes: number): Uint8Array {
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  for (let end = Math.min(maxBytes, bytes.byteLength); end >= 0; end -= 1) {
+    const candidate = bytes.slice(0, end);
+    try {
+      decoder.decode(candidate);
+      return candidate;
+    } catch {
+      // 回退到上一个完整 UTF-8 字符边界。
+    }
+  }
+  return new Uint8Array();
+}
+
+function normalizeLimit(value: number, fallback: number): number {
+  if (!Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.max(1, Math.trunc(value));
+}