@ct-agents/tools 0.0.1

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@ct-agents/tools",
+  "version": "0.0.1",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./builtin-tools": "./src/builtin-tools/index.ts",
+    "./sandbox-tools": "./src/sandbox-tools/index.ts"
+  },
+  "dependencies": {
+    "zod": "4.4.3",
+    "@ct-agents/protocol": "0.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/builtin-tools/ask-user.ts

@@ -0,0 +1,115 @@
+import { z } from 'zod';
+import type {
+  AgentActionRequestedPayload,
+  ToolExecution,
+  ToolHandler,
+} from '@ct-agents/protocol';
+
+export const askUserToolInputSchema = z.object({
+  question: z.string().trim().min(1, 'question 为必填字段'),
+  options: z.array(z.string().trim().min(1)).optional(),
+  multiSelect: z.boolean().optional(),
+}).strict();
+
+export type AskUserToolInput = z.infer<typeof askUserToolInputSchema>;
+export type AskUserToolResult = {
+  answer: unknown;
+};
+
+export const askUserToolResultSchema = z.object({
+  answer: z.unknown(),
+}).strict().refine(
+  (value) => Object.prototype.hasOwnProperty.call(value, 'answer'),
+  { message: 'answer 为必填字段' },
+) as z.ZodType<AskUserToolResult>;
+
+function createAskUserActionPayload(input: AskUserToolInput): AgentActionRequestedPayload {
+  const payload: AgentActionRequestedPayload = {
+    kind: 'ask_user',
+    prompt: input.question,
+  };
+
+  if (input.options && input.options.length > 0) {
+    payload.allowedResults = input.options;
+  }
+
+  if (input.multiSelect !== undefined) {
+    payload.input = { multiSelect: input.multiSelect };
+  }
+
+  return payload;
+}
+
+function resolveAskUserAnswer(result: unknown): unknown {
+  if (result && typeof result === 'object' && !Array.isArray(result)) {
+    const record = result as Record<string, unknown>;
+    if ('answer' in record) {
+      return record.answer;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 人机交互提问工具。
+ *
+ * handler 只描述“需要用户回答”和“回答如何回到模型上下文”；
+ * action 事件和 tool.completed 仍由 Environment 统一写入，避免工具绕开生命周期边界。
+ */
+export function createAskUserToolHandler(): ToolHandler<AskUserToolInput, AskUserToolResult> {
+  return {
+    descriptor: {
+      name: 'ask-user',
+      title: '询问用户',
+      description: [
+        '当分析需要用户补充判断或选择下一步方向时使用。',
+        '问题应具体可执行；如果存在明确选项，应通过 options 传入。',
+      ].join('\n'),
+      inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['question'],
+        properties: {
+          question: { type: 'string', minLength: 1, description: '要询问用户的问题。' },
+          options: { type: 'array', items: { type: 'string', minLength: 1 }, description: '可选答案列表。' },
+          multiSelect: { type: 'boolean', description: '用户是否可以选择多个答案。' },
+        },
+      },
+      resultSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['answer'],
+        properties: {
+          answer: {
+            description: '用户回答，供模型继续推理。',
+          },
+        },
+      },
+      annotations: {
+        readOnly: true,
+        idempotent: false,
+        openWorld: true,
+        destructive: false,
+      },
+    },
+    inputSchema: askUserToolInputSchema,
+    resultSchema: askUserToolResultSchema,
+    execute: async (input): Promise<ToolExecution<AskUserToolResult>> => ({
+      status: 'paused',
+      effects: [
+        {
+          type: 'agent.action.request',
+          payload: createAskUserActionPayload(input),
+        },
+      ],
+    }),
+    resume: async ({ resolvedEvent }) => ({
+      status: 'completed',
+      modelResult: askUserToolResultSchema.parse({
+        answer: resolveAskUserAnswer(resolvedEvent.payload.result),
+      }),
+      effects: [],
+    }),
+  };
+}

package/src/builtin-tools/index.ts

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

package/src/index.ts

@@ -0,0 +1,75 @@
+import type {
+  ToolDescriptor,
+  ToolHandler,
+  ToolRegistry,
+} from '@ct-agents/protocol';
+
+export class ToolNotFoundError extends Error {
+  constructor(toolName: string) {
+    super(`Tool not found: ${toolName}`);
+    this.name = 'ToolNotFoundError';
+  }
+}
+
+export class InMemoryToolRegistry implements ToolRegistry {
+  private readonly handlers = new Map<string, ToolHandler<unknown, unknown>>();
+
+  constructor(handlers: ToolHandler[]) {
+    for (const handler of handlers) {
+      const name = handler.descriptor.name;
+      if (this.handlers.has(name)) {
+        throw new Error(`Duplicate tool name: ${name}`);
+      }
+
+      this.handlers.set(name, handler as ToolHandler<unknown, unknown>);
+    }
+  }
+
+  getTool(toolName: string) {
+    const handler = this.handlers.get(toolName);
+    if (!handler) {
+      throw new ToolNotFoundError(toolName);
+    }
+
+    return handler;
+  }
+
+  listTools(): ToolDescriptor[] {
+    return Array.from(this.handlers.values())
+      .map((handler) => handler.descriptor)
+      .sort((left, right) => left.name.localeCompare(right.name));
+  }
+}
+
+export class CompositeToolRegistry implements ToolRegistry {
+  private readonly extra = new Map<string, ToolHandler<unknown, unknown>>();
+
+  constructor(private readonly base: ToolRegistry) {}
+
+  addTool(handler: ToolHandler) {
+    const name = handler.descriptor.name;
+    if (this.extra.has(name)) {
+      return;
+    }
+
+    this.extra.set(name, handler as ToolHandler<unknown, unknown>);
+  }
+
+  getTool(toolName: string) {
+    const extraHandler = this.extra.get(toolName);
+    if (extraHandler) {
+      return extraHandler;
+    }
+
+    return this.base.getTool(toolName);
+  }
+
+  listTools() {
+    return [
+      ...this.base.listTools(),
+      ...Array.from(this.extra.values()).map((handler) => handler.descriptor),
+    ];
+  }
+}
+
+export * from './sandbox-tools/index.js';

package/src/sandbox-tools/approval.ts

@@ -0,0 +1,120 @@
+import type {
+  AgentActionRequestedPayload,
+  ToolExecution,
+  ToolResumeInput,
+} from '@ct-agents/protocol';
+
+export const TOOL_APPROVAL_DENIED = 'TOOL_APPROVAL_DENIED';
+export const APPROVAL_ALLOWED = '批准';
+export const APPROVAL_DENIED = '拒绝';
+
+export type ApprovalOptions = {
+  requireApproval?: boolean;
+  allowedCommands?: readonly string[];
+};
+
+export type ApprovalRequestInput = {
+  subject: string;
+  summary: string;
+};
+
+export function needsApproval(input: {
+  requireApproval: boolean;
+  commandName?: string | null;
+  command?: string;
+  allowedCommands?: ReadonlySet<string>;
+}): boolean {
+  if (!input.requireApproval) {
+    return false;
+  }
+
+  if (!input.commandName || !input.allowedCommands || input.allowedCommands.size === 0) {
+    return true;
+  }
+
+  const normalizedCommandName = normalizeCommandName(input.commandName);
+  return isShellMetaCommand(normalizedCommandName)
+    || !input.allowedCommands.has(normalizedCommandName)
+    || hasShellControlOperator(input.command ?? input.commandName);
+}
+
+export function pausedForApproval(input: ApprovalRequestInput): ToolExecution<never> {
+  return {
+    status: 'paused',
+    effects: [
+      {
+        type: 'agent.action.request',
+        payload: createApprovalPayload(input),
+      },
+    ],
+  };
+}
+
+export function approvalDenied<TResult>(): ToolExecution<TResult> {
+  return {
+    status: 'failed',
+    error: {
+      code: TOOL_APPROVAL_DENIED,
+      message: '用户拒绝执行该工具操作',
+      retryable: false,
+    },
+  };
+}
+
+export function isApprovalGranted(input: ToolResumeInput<unknown>): boolean {
+  const result = input.resolvedEvent.payload.result;
+  if (typeof result === 'string') {
+    return result === APPROVAL_ALLOWED;
+  }
+
+  if (isRecord(result)) {
+    const answer = result.answer;
+    return answer === APPROVAL_ALLOWED || answer === true;
+  }
+
+  return result === true;
+}
+
+function createApprovalPayload(input: ApprovalRequestInput): AgentActionRequestedPayload {
+  return {
+    kind: 'ask_user',
+    prompt: `是否批准执行 ${input.subject}？\n${input.summary}`,
+    input: {
+      subject: input.subject,
+      summary: input.summary,
+    },
+    allowedResults: [APPROVAL_ALLOWED, APPROVAL_DENIED],
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasShellControlOperator(command: string): boolean {
+  return /[;&|<>`\r\n]|[$][(]/.test(command);
+}
+
+function normalizeCommandName(commandName: string): string {
+  const normalized = commandName.toLowerCase().replace(/\\/g, '/');
+  return normalized.split('/').filter(Boolean).at(-1) ?? normalized;
+}
+
+function isShellMetaCommand(commandName: string): boolean {
+  return commandName === '.'
+    || commandName === 'eval'
+    || commandName === 'exec'
+    || commandName === 'source'
+    || commandName === 'sh'
+    || commandName === 'bash'
+    || commandName === 'node'
+    || commandName === 'python'
+    || commandName === 'python3'
+    || commandName === 'perl'
+    || commandName === 'ruby'
+    || commandName === 'php'
+    || commandName === 'lua'
+    || commandName === 'busybox'
+    || commandName === 'env'
+    || commandName === 'xargs';
+}

package/src/sandbox-tools/bash.ts

@@ -0,0 +1,231 @@
+import { z } from 'zod';
+import type {
+  ExecResult,
+  ToolExecution,
+  ToolHandler,
+  ToolHandlerContext,
+} from '@ct-agents/protocol';
+import {
+  approvalDenied,
+  isApprovalGranted,
+  needsApproval,
+  pausedForApproval,
+} from './approval.js';
+import { truncateText } from './truncate.js';
+import {
+  DEFAULT_TEXT_MAX_BYTES,
+  HARD_MAX_TEXT_BYTES,
+  HARD_MAX_TIMEOUT_MS,
+  failed,
+  normalizeLimit,
+  requireSandbox,
+} from './shared.js';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export type BashToolOptions = {
+  defaultTimeoutMs?: number;
+  defaultMaxBytes?: number;
+  deniedCommands?: readonly string[];
+  requireApproval?: boolean;
+  allowedCommands?: readonly string[];
+};
+
+export const bashInputSchema = z.object({
+  command: z.string().trim().min(1, 'command 为必填字段'),
+  timeoutMs: z.number().int().positive().optional(),
+  maxBytes: z.number().int().positive().optional(),
+}).strict();
+
+export type BashInput = z.infer<typeof bashInputSchema>;
+
+export type BashResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  timedOut: boolean;
+  truncated: boolean;
+  totalStdoutBytes?: number;
+  totalStderrBytes?: number;
+};
+
+export const bashResultSchema = z.object({
+  stdout: z.string(),
+  stderr: z.string(),
+  exitCode: z.number().int(),
+  timedOut: z.boolean(),
+  truncated: z.boolean(),
+  totalStdoutBytes: z.number().int().nonnegative().optional(),
+  totalStderrBytes: z.number().int().nonnegative().optional(),
+}).strict() as z.ZodType<BashResult>;
+
+export function createBashToolHandler(options: BashToolOptions = {}): ToolHandler<BashInput, BashResult> {
+  const defaultTimeoutMs = normalizeLimit(options.defaultTimeoutMs, DEFAULT_TIMEOUT_MS, HARD_MAX_TIMEOUT_MS);
+  const defaultMaxBytes = normalizeLimit(options.defaultMaxBytes, DEFAULT_TEXT_MAX_BYTES, HARD_MAX_TEXT_BYTES);
+  const deniedCommands = new Set((options.deniedCommands ?? []).map(normalizeCommandName));
+  const allowedCommands = new Set((options.allowedCommands ?? []).map(normalizeCommandName));
+  const requireApproval = options.requireApproval ?? true;
+
+  return {
+    descriptor: {
+      name: 'bash',
+      title: '执行沙箱命令',
+      description: '在会话沙箱内执行 shell 命令，并返回截断后的 stdout/stderr。',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['command'],
+        properties: {
+          command: { type: 'string', minLength: 1, description: '要执行的 shell 命令。' },
+          timeoutMs: { type: 'integer', minimum: 1, description: '命令超时时间。' },
+          maxBytes: { type: 'integer', minimum: 1, description: 'stdout/stderr 各自最大返回字节数。' },
+        },
+      },
+      resultSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['stdout', 'stderr', 'exitCode', 'timedOut', 'truncated'],
+        properties: {
+          stdout: { type: 'string' },
+          stderr: { type: 'string' },
+          exitCode: { type: 'integer' },
+          timedOut: { type: 'boolean' },
+          truncated: { type: 'boolean' },
+          totalStdoutBytes: { type: 'integer', minimum: 0 },
+          totalStderrBytes: { type: 'integer', minimum: 0 },
+        },
+      },
+      requiredResources: ['sandbox'],
+      annotations: {
+        readOnly: false,
+        idempotent: false,
+        openWorld: true,
+        destructive: true,
+      },
+    },
+    inputSchema: bashInputSchema,
+    resultSchema: bashResultSchema,
+    execute: async (input, context): Promise<ToolExecution<BashResult>> => {
+      const commandName = parseCommandName(input.command);
+      const deniedCommand = resolveDeniedCommandName(input.command, deniedCommands);
+      if (deniedCommand) {
+        return failed('BASH_COMMAND_DENIED', `命令被拒绝执行：${deniedCommand}`);
+      }
+
+      if (needsApproval({
+        requireApproval,
+        commandName,
+        command: input.command,
+        allowedCommands,
+      })) {
+        return pausedForApproval({
+          subject: 'bash',
+          summary: input.command,
+        });
+      }
+
+      return executeBash(input, context, { defaultTimeoutMs, defaultMaxBytes, requireApproval });
+    },
+    resume: async (input, context) => {
+      const commandName = parseCommandName(input.originalInput.command);
+      const deniedCommand = resolveDeniedCommandName(input.originalInput.command, deniedCommands);
+      if (deniedCommand) {
+        return failed('BASH_COMMAND_DENIED', `命令被拒绝执行：${deniedCommand}`);
+      }
+
+      if (!isApprovalGranted(input)) {
+        return approvalDenied();
+      }
+
+      return executeBash(input.originalInput, context, { defaultTimeoutMs, defaultMaxBytes, requireApproval });
+    },
+  };
+}
+
+async function executeBash(
+  input: BashInput,
+  context: ToolHandlerContext,
+  defaults: { defaultTimeoutMs: number; defaultMaxBytes: number; requireApproval: boolean },
+): Promise<ToolExecution<BashResult>> {
+  const sandbox = requireSandbox(context);
+  if (isToolExecution(sandbox)) {
+    return sandbox;
+  }
+  if (!defaults.requireApproval && !sandbox.isolated) {
+    return failed('BASH_SANDBOX_NOT_ISOLATED', 'requireApproval=false 时必须使用隔离 sandbox');
+  }
+
+  try {
+    const timeoutMs = normalizeLimit(input.timeoutMs, defaults.defaultTimeoutMs, HARD_MAX_TIMEOUT_MS);
+    const maxBytes = normalizeLimit(input.maxBytes, defaults.defaultMaxBytes, HARD_MAX_TEXT_BYTES);
+    const result = await sandbox.exec(input.command, {
+      timeoutMs,
+      maxOutputBytes: maxBytes,
+    });
+    return {
+      status: 'completed',
+      modelResult: truncateExecResult(result, maxBytes),
+    };
+  } catch (error) {
+    return failed('BASH_EXEC_FAILED', error instanceof Error ? error.message : String(error));
+  }
+}
+
+function truncateExecResult(result: ExecResult, maxBytes: number): BashResult {
+  const stdout = truncateText(result.stdout, maxBytes);
+  const stderr = truncateText(result.stderr, maxBytes);
+  const stdoutTruncated = stdout.truncated || result.stdoutTruncated === true;
+  const stderrTruncated = stderr.truncated || result.stderrTruncated === true;
+  return {
+    stdout: stdout.text,
+    stderr: stderr.text,
+    exitCode: result.exitCode,
+    timedOut: result.timedOut,
+    truncated: stdoutTruncated || stderrTruncated,
+    ...(stdout.totalBytes !== undefined || result.totalStdoutBytes !== undefined
+      ? { totalStdoutBytes: result.totalStdoutBytes ?? stdout.totalBytes }
+      : {}),
+    ...(stderr.totalBytes !== undefined || result.totalStderrBytes !== undefined
+      ? { totalStderrBytes: result.totalStderrBytes ?? stderr.totalBytes }
+      : {}),
+  };
+}
+
+function parseCommandName(command: string): string | null {
+  const tokens = command.trim().match(/[^\s;&|()<>]+/g) ?? [];
+  for (const token of tokens) {
+    const cleaned = token.replace(/^["']|["']$/g, '');
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(cleaned)) {
+      continue;
+    }
+    return normalizeCommandName(cleaned);
+  }
+  return null;
+}
+
+function resolveDeniedCommandName(command: string, deniedCommands: ReadonlySet<string>): string | null {
+  const commandName = parseCommandName(command);
+  if (commandName && deniedCommands.has(commandName)) {
+    return commandName;
+  }
+
+  if (deniedCommands.size > 0 && hasShellJoinedCommandToken(command)) {
+    return commandName ?? 'shell-joined-command';
+  }
+
+  return null;
+}
+
+function hasShellJoinedCommandToken(command: string): boolean {
+  const firstToken = command.trim().match(/^([^\s;&|()<>]+)/)?.[1];
+  return Boolean(firstToken && /["'\\$]/.test(firstToken));
+}
+
+function normalizeCommandName(commandName: string): string {
+  const normalized = commandName.toLowerCase().replace(/\\/g, '/');
+  return normalized.split('/').filter(Boolean).at(-1) ?? normalized;
+}
+
+function isToolExecution<T>(value: unknown): value is ToolExecution<T> {
+  return value !== null && typeof value === 'object' && 'status' in value;
+}