@ct-agents/tools 0.0.1

package/src/sandbox-tools/db-execute.ts

@@ -0,0 +1,231 @@
+import { z } from 'zod';
+import type {
+  ToolExecution,
+  ToolHandler,
+  ToolHandlerContext,
+} from '@ct-agents/protocol';
+import {
+  approvalDenied,
+  isApprovalGranted,
+  pausedForApproval,
+} from './approval.js';
+import { truncateRows } from './truncate.js';
+import {
+  DEFAULT_MAX_ROWS,
+  DEFAULT_TEXT_MAX_BYTES,
+  HARD_MAX_ROWS,
+  HARD_MAX_TEXT_BYTES,
+  failed,
+  normalizeBoolean,
+  normalizeLimit,
+} from './shared.js';
+import {
+  containsDangerousPostgresCapability,
+  containsDdlDclOrMaintenanceKeyword,
+  scanSqlStructure,
+} from './sql-guard.js';
+
+export type DbExecuteToolOptions = {
+  allowWrite?: boolean;
+  defaultMaxRows?: number;
+  defaultMaxBytes?: number;
+  requireApproval?: boolean;
+};
+
+export const dbExecuteInputSchema = z.object({
+  sql: z.string().trim().min(1, 'sql 为必填字段'),
+  params: z.array(z.unknown()).optional(),
+  maxRows: z.number().int().positive().optional(),
+  maxBytes: z.number().int().positive().optional(),
+}).strict();
+
+export type DbExecuteInput = z.infer<typeof dbExecuteInputSchema>;
+
+export type DbExecuteResult = {
+  rows: unknown[];
+  rowCount: number;
+  truncated: boolean;
+  totalRows?: number;
+  totalBytes?: number;
+};
+
+export const dbExecuteResultSchema = z.object({
+  rows: z.array(z.unknown()),
+  rowCount: z.number().int().nonnegative(),
+  truncated: z.boolean(),
+  totalRows: z.number().int().nonnegative().optional(),
+  totalBytes: z.number().int().nonnegative().optional(),
+}).strict() as z.ZodType<DbExecuteResult>;
+
+type QueryLikeResult = {
+  rows?: unknown;
+  rowCount?: unknown;
+};
+
+export function createDbExecuteToolHandler(options: DbExecuteToolOptions = {}): ToolHandler<DbExecuteInput, DbExecuteResult> {
+  const allowWrite = normalizeBoolean(options.allowWrite, false);
+  const defaultMaxRows = normalizeLimit(options.defaultMaxRows, DEFAULT_MAX_ROWS, HARD_MAX_ROWS);
+  const defaultMaxBytes = normalizeLimit(options.defaultMaxBytes, DEFAULT_TEXT_MAX_BYTES, HARD_MAX_TEXT_BYTES);
+  const requireApproval = options.requireApproval ?? true;
+
+  return {
+    descriptor: {
+      name: 'db-execute',
+      title: '执行数据库写入',
+      description: '执行数据库变更 SQL，并返回截断后的结果集。',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['sql'],
+        properties: {
+          sql: { type: 'string', minLength: 1, description: '要执行的 SQL。' },
+          params: { type: 'array', description: 'SQL 参数。' },
+          maxRows: { type: 'integer', minimum: 1, description: '最多返回行数。' },
+          maxBytes: { type: 'integer', minimum: 1, description: '结果 JSON 的最大字节数。' },
+        },
+      },
+      resultSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['rows', 'rowCount', 'truncated'],
+        properties: {
+          rows: { type: 'array', items: {} },
+          rowCount: { type: 'integer', minimum: 0 },
+          truncated: { type: 'boolean' },
+          totalRows: { type: 'integer', minimum: 0 },
+          totalBytes: { type: 'integer', minimum: 0 },
+        },
+      },
+      requiredResources: ['database'],
+      annotations: {
+        readOnly: false,
+        idempotent: false,
+        openWorld: false,
+        destructive: true,
+      },
+    },
+    inputSchema: dbExecuteInputSchema,
+    resultSchema: dbExecuteResultSchema,
+    execute: async (input, context): Promise<ToolExecution<DbExecuteResult>> => {
+      if (!allowWrite) {
+        return failed('DB_EXECUTE_WRITE_DISABLED', '当前 database resource 未允许写 SQL');
+      }
+
+      if (requireApproval) {
+        return pausedForApproval({
+          subject: 'db-execute',
+          summary: input.sql,
+        });
+      }
+
+      return executeDb(input, context, { defaultMaxRows, defaultMaxBytes });
+    },
+    resume: async (input, context) => {
+      if (!allowWrite) {
+        return failed('DB_EXECUTE_WRITE_DISABLED', '当前 database resource 未允许写 SQL');
+      }
+
+      if (!isApprovalGranted(input)) {
+        return approvalDenied();
+      }
+
+      return executeDb(input.originalInput, context, { defaultMaxRows, defaultMaxBytes });
+    },
+  };
+}
+
+async function executeDb(
+  input: DbExecuteInput,
+  context: ToolHandlerContext,
+  defaults: { defaultMaxRows: number; defaultMaxBytes: number },
+): Promise<ToolExecution<DbExecuteResult>> {
+  const database = context.resources.database;
+  if (!database) {
+    return failed('DATABASE_RESOURCE_MISSING', '当前工具上下文缺少 database resource');
+  }
+  if (!isAllowedWriteSql(input.sql)) {
+    return failed('DB_EXECUTE_SQL_NOT_ALLOWED', 'db-execute 只允许单条数据变更 SQL，拒绝 DDL/DCL、维护命令、多语句和高危 PostgreSQL 能力');
+  }
+
+  try {
+    const maxRows = normalizeLimit(input.maxRows, defaults.defaultMaxRows, HARD_MAX_ROWS);
+    const queryResult = await database.query(input.sql, input.params, { maxRows: maxRows + 1 });
+    return {
+      status: 'completed',
+      modelResult: normalizeQueryResult(queryResult, input, defaults),
+    };
+  } catch (error) {
+    return failed('DB_EXECUTE_FAILED', error instanceof Error ? error.message : String(error));
+  }
+}
+
+function isAllowedWriteSql(sql: string): boolean {
+  const scan = scanSqlStructure(sql);
+  const normalized = scan.structureSql.trim();
+  if (!normalized || scan.hasStatementSeparator) {
+    return false;
+  }
+  if (containsDdlDclOrMaintenanceKeyword(normalized) || containsDangerousPostgresCapability(normalized)) {
+    return false;
+  }
+
+  const firstToken = normalized.match(/^[a-z]+/i)?.[0].toLowerCase();
+  if (firstToken === 'insert' || firstToken === 'update' || firstToken === 'delete' || firstToken === 'merge') {
+    return true;
+  }
+  if (firstToken !== 'with') {
+    return false;
+  }
+
+  return /\)\s*(insert|update|delete|merge)\b/i.test(normalized);
+}
+
+function normalizeQueryResult(
+  queryResult: unknown,
+  input: DbExecuteInput,
+  defaults: { defaultMaxRows: number; defaultMaxBytes: number },
+): DbExecuteResult {
+  const result = isRecord(queryResult) ? queryResult as QueryLikeResult : {};
+  const sourceRows = Array.isArray(result.rows) ? result.rows : [];
+  const rowCount = typeof result.rowCount === 'number' && Number.isFinite(result.rowCount)
+    ? Math.max(0, Math.trunc(result.rowCount))
+    : sourceRows.length;
+  const maxRows = normalizeLimit(input.maxRows, defaults.defaultMaxRows, HARD_MAX_ROWS);
+  const maxBytes = normalizeLimit(input.maxBytes, defaults.defaultMaxBytes, HARD_MAX_TEXT_BYTES);
+  const rows = truncateRows(sourceRows, maxRows);
+  const byteLimited = truncateResultBytes(rows.rows, maxBytes);
+  return {
+    rows: byteLimited.rows,
+    rowCount,
+    truncated: rows.truncated || byteLimited.truncated,
+    ...(rows.totalRows !== undefined ? { totalRows: rows.totalRows } : {}),
+    ...(byteLimited.totalBytes !== undefined ? { totalBytes: byteLimited.totalBytes } : {}),
+  };
+}
+
+function truncateResultBytes(rows: unknown[], maxBytes: number): { rows: unknown[]; truncated: boolean; totalBytes?: number } {
+  const encoded = new TextEncoder().encode(JSON.stringify(rows));
+  if (encoded.byteLength <= maxBytes) {
+    return { rows, truncated: false };
+  }
+
+  const limitedRows: unknown[] = [];
+  for (const row of rows) {
+    const candidate = [...limitedRows, row];
+    const candidateBytes = new TextEncoder().encode(JSON.stringify(candidate)).byteLength;
+    if (candidateBytes > maxBytes) {
+      break;
+    }
+    limitedRows.push(row);
+  }
+
+  return {
+    rows: limitedRows,
+    truncated: true,
+    totalBytes: encoded.byteLength,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}

package/src/sandbox-tools/db-query.ts

@@ -0,0 +1,211 @@
+import { z } from 'zod';
+import type {
+  Database,
+  ToolExecution,
+  ToolHandler,
+} from '@ct-agents/protocol';
+import {
+  HARD_MAX_ROWS,
+  HARD_MAX_TEXT_BYTES,
+  normalizeLimit,
+} from './shared.js';
+import {
+  containsDangerousPostgresCapability,
+  containsWriteOrDdlKeyword,
+  scanSqlStructure,
+} from './sql-guard.js';
+import { truncateRows } from './truncate.js';
+
+const DEFAULT_MAX_ROWS = 100;
+const DEFAULT_MAX_BYTES = 128_000;
+
+export type DbQueryToolOptions = {
+  defaultMaxRows?: number;
+  defaultMaxBytes?: number;
+};
+
+export const dbQueryInputSchema = z.object({
+  sql: z.string().trim().min(1, 'sql 为必填字段'),
+  params: z.array(z.unknown()).optional(),
+  maxRows: z.number().int().positive().optional(),
+  maxBytes: z.number().int().positive().optional(),
+}).strict();
+
+export type DbQueryInput = z.infer<typeof dbQueryInputSchema>;
+
+export type DbQueryResult = {
+  rows: unknown[];
+  rowCount: number;
+  truncated: boolean;
+  totalRows?: number;
+  totalBytes?: number;
+};
+
+export const dbQueryResultSchema = z.object({
+  rows: z.array(z.unknown()),
+  rowCount: z.number().int().nonnegative(),
+  truncated: z.boolean(),
+  totalRows: z.number().int().nonnegative().optional(),
+  totalBytes: z.number().int().nonnegative().optional(),
+}).strict() as z.ZodType<DbQueryResult>;
+
+type QueryLikeResult = {
+  rows?: unknown;
+  rowCount?: unknown;
+};
+
+export function createDbQueryToolHandler(options: DbQueryToolOptions = {}): ToolHandler<DbQueryInput, DbQueryResult> {
+  const defaultMaxRows = normalizeLimit(options.defaultMaxRows, DEFAULT_MAX_ROWS, HARD_MAX_ROWS);
+  const defaultMaxBytes = normalizeLimit(options.defaultMaxBytes, DEFAULT_MAX_BYTES, HARD_MAX_TEXT_BYTES);
+
+  return {
+    descriptor: {
+      name: 'db-query',
+      title: '查询数据库',
+      description: '执行只读 SQL 查询并返回截断后的结果集。database resource 必须使用最小权限只读账号。',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['sql'],
+        properties: {
+          sql: { type: 'string', minLength: 1, description: '只读 SQL；仅允许 SELECT 或 WITH ... SELECT。' },
+          params: { type: 'array', description: '查询参数。' },
+          maxRows: { type: 'integer', minimum: 1, description: '最多返回行数。' },
+          maxBytes: { type: 'integer', minimum: 1, description: '结果 JSON 的最大字节数。' },
+        },
+      },
+      resultSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['rows', 'rowCount', 'truncated'],
+        properties: {
+          rows: { type: 'array', items: {} },
+          rowCount: { type: 'integer', minimum: 0 },
+          truncated: { type: 'boolean' },
+          totalRows: { type: 'integer', minimum: 0 },
+          totalBytes: { type: 'integer', minimum: 0 },
+        },
+      },
+      requiredResources: ['database'],
+      annotations: {
+        readOnly: true,
+        idempotent: true,
+        openWorld: false,
+        destructive: false,
+      },
+    },
+    inputSchema: dbQueryInputSchema,
+    resultSchema: dbQueryResultSchema,
+    execute: async (input, context): Promise<ToolExecution<DbQueryResult>> => {
+      if (!isReadOnlySql(input.sql)) {
+        return failed('DB_QUERY_NOT_READ_ONLY', 'db-query 只允许执行 SELECT 或 WITH ... SELECT 查询');
+      }
+
+      const database = context.resources.database;
+      if (!database) {
+        return failed('DATABASE_RESOURCE_MISSING', '当前工具上下文缺少 database resource');
+      }
+
+      try {
+        const maxRows = normalizeLimit(input.maxRows, defaultMaxRows, HARD_MAX_ROWS);
+        const queryResult = await database.query(input.sql, input.params, { readOnly: true, maxRows: maxRows + 1 });
+        const modelResult = normalizeQueryResult(queryResult, input, {
+          defaultMaxRows,
+          defaultMaxBytes,
+        });
+        return {
+          status: 'completed',
+          modelResult,
+        };
+      } catch (error) {
+        return failed('DB_QUERY_FAILED', error instanceof Error ? error.message : String(error));
+      }
+    },
+  };
+}
+
+function normalizeQueryResult(
+  queryResult: unknown,
+  input: DbQueryInput,
+  defaults: { defaultMaxRows: number; defaultMaxBytes: number },
+): DbQueryResult {
+  const result = isRecord(queryResult) ? queryResult as QueryLikeResult : {};
+  const sourceRows = Array.isArray(result.rows) ? result.rows : [];
+  const rowCount = typeof result.rowCount === 'number' && Number.isFinite(result.rowCount)
+    ? Math.max(0, Math.trunc(result.rowCount))
+    : sourceRows.length;
+  const maxRows = normalizeLimit(input.maxRows, defaults.defaultMaxRows, HARD_MAX_ROWS);
+  const maxBytes = normalizeLimit(input.maxBytes, defaults.defaultMaxBytes, HARD_MAX_TEXT_BYTES);
+  const rows = truncateRows(sourceRows, maxRows);
+  const byteLimited = truncateResultBytes(rows.rows, maxBytes);
+  const truncated = rows.truncated || byteLimited.truncated;
+
+  return {
+    rows: byteLimited.rows,
+    rowCount,
+    truncated,
+    ...(rows.truncated ? { totalRows: sourceRows.length } : {}),
+    ...(byteLimited.truncated ? { totalBytes: byteLimited.totalBytes } : {}),
+  };
+}
+
+function truncateResultBytes(rows: unknown[], maxBytes: number): { rows: unknown[]; truncated: boolean; totalBytes?: number } {
+  const encoded = new TextEncoder().encode(JSON.stringify(rows));
+  if (encoded.byteLength <= maxBytes) {
+    return { rows, truncated: false };
+  }
+
+  const limitedRows: unknown[] = [];
+  for (const row of rows) {
+    const candidate = [...limitedRows, row];
+    const candidateBytes = new TextEncoder().encode(JSON.stringify(candidate)).byteLength;
+    if (candidateBytes > maxBytes) {
+      break;
+    }
+    limitedRows.push(row);
+  }
+
+  return {
+    rows: limitedRows,
+    truncated: true,
+    totalBytes: encoded.byteLength,
+  };
+}
+
+function isReadOnlySql(sql: string): boolean {
+  const scan = scanSqlStructure(sql);
+  const normalized = scan.structureSql.trim();
+  if (!normalized || scan.hasStatementSeparator) {
+    return false;
+  }
+
+  if (containsWriteOrDdlKeyword(normalized) || containsDangerousPostgresCapability(normalized)) {
+    return false;
+  }
+
+  const firstToken = normalized.match(/^[a-z]+/i)?.[0].toLowerCase();
+  if (firstToken === 'select') {
+    return true;
+  }
+
+  if (firstToken !== 'with') {
+    return false;
+  }
+
+  return /\)\s*select\b/i.test(normalized);
+}
+
+function failed(code: string, message: string): ToolExecution<DbQueryResult> {
+  return {
+    status: 'failed',
+    error: {
+      code,
+      message,
+      retryable: false,
+    },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}

package/src/sandbox-tools/fs-read.ts

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import type {
+  ToolExecution,
+  ToolHandler,
+} from '@ct-agents/protocol';
+import { truncateText } from './truncate.js';
+import {
+  DEFAULT_TEXT_MAX_BYTES,
+  HARD_MAX_TEXT_BYTES,
+  failed,
+  normalizeLimit,
+  normalizePathOrFailed,
+  requireSandbox,
+} from './shared.js';
+
+export type FsReadToolOptions = {
+  defaultMaxBytes?: number;
+};
+
+const UTF8_READ_AHEAD_BYTES = 4;
+
+export const fsReadInputSchema = z.object({
+  path: z.string().trim().min(1, 'path 为必填字段'),
+  offset: z.number().int().nonnegative().optional(),
+  limit: z.number().int().positive().optional(),
+  maxBytes: z.number().int().positive().optional(),
+}).strict();
+
+export type FsReadInput = z.infer<typeof fsReadInputSchema>;
+
+export type FsReadResult = {
+  path: string;
+  content: string;
+  truncated: boolean;
+  totalBytes?: number;
+};
+
+export const fsReadResultSchema = z.object({
+  path: z.string(),
+  content: z.string(),
+  truncated: z.boolean(),
+  totalBytes: z.number().int().nonnegative().optional(),
+}).strict() as z.ZodType<FsReadResult>;
+
+export function createFsReadToolHandler(options: FsReadToolOptions = {}): ToolHandler<FsReadInput, FsReadResult> {
+  const defaultMaxBytes = normalizeLimit(options.defaultMaxBytes, DEFAULT_TEXT_MAX_BYTES, HARD_MAX_TEXT_BYTES);
+
+  return {
+    descriptor: {
+      name: 'fs-read',
+      title: '读取沙箱文件',
+      description: '读取会话沙箱内的文本文件，并按字节上限返回内容。',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['path'],
+        properties: {
+          path: { type: 'string', minLength: 1, description: '沙箱内相对路径。' },
+          offset: { type: 'integer', minimum: 0, description: '读取内容的字节偏移。' },
+          limit: { type: 'integer', minimum: 1, description: '最多读取的字节数。' },
+          maxBytes: { type: 'integer', minimum: 1, description: '返回内容的最大字节数。' },
+        },
+      },
+      resultSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['path', 'content', 'truncated'],
+        properties: {
+          path: { type: 'string' },
+          content: { type: 'string' },
+          truncated: { type: 'boolean' },
+          totalBytes: { type: 'integer', minimum: 0 },
+        },
+      },
+      requiredResources: ['sandbox'],
+      annotations: {
+        readOnly: true,
+        idempotent: true,
+        openWorld: false,
+        destructive: false,
+      },
+    },
+    inputSchema: fsReadInputSchema,
+    resultSchema: fsReadResultSchema,
+    execute: async (input, context): Promise<ToolExecution<FsReadResult>> => {
+      const sandbox = requireSandbox(context);
+      if (isToolExecution(sandbox)) {
+        return sandbox;
+      }
+
+      const path = normalizePathOrFailed<FsReadResult>(input.path);
+      if (isToolExecution(path)) {
+        return path;
+      }
+
+      try {
+        const maxBytes = normalizeLimit(input.maxBytes, defaultMaxBytes, HARD_MAX_TEXT_BYTES);
+        const rawContent = await sandbox.readFile(path, {
+          ...(input.offset !== undefined ? { offset: normalizeOffset(input.offset) } : {}),
+          ...(input.limit !== undefined ? { limit: normalizeLimit(input.limit, 1, HARD_MAX_TEXT_BYTES) } : {}),
+          maxBytes: maxBytes + UTF8_READ_AHEAD_BYTES,
+        });
+        const truncated = truncateText(rawContent, maxBytes);
+        return {
+          status: 'completed',
+          modelResult: {
+            path,
+            content: truncated.text,
+            truncated: truncated.truncated,
+            ...(truncated.totalBytes !== undefined ? { totalBytes: truncated.totalBytes } : {}),
+          },
+        };
+      } catch (error) {
+        return failed('FS_READ_FAILED', error instanceof Error ? error.message : String(error));
+      }
+    },
+  };
+}
+
+function normalizeOffset(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.max(0, Math.trunc(value));
+}
+
+function isToolExecution<T>(value: unknown): value is ToolExecution<T> {
+  return value !== null && typeof value === 'object' && 'status' in value;
+}

package/src/sandbox-tools/fs-write.ts

@@ -0,0 +1,132 @@
+import { z } from 'zod';
+import type {
+  ToolExecution,
+  ToolHandler,
+  ToolHandlerContext,
+} from '@ct-agents/protocol';
+import {
+  approvalDenied,
+  isApprovalGranted,
+  pausedForApproval,
+} from './approval.js';
+import {
+  countUtf8Bytes,
+  failed,
+  normalizePathOrFailed,
+  requireSandbox,
+} from './shared.js';
+
+export type FsWriteToolOptions = {
+  requireApproval?: boolean;
+};
+
+export const fsWriteInputSchema = z.object({
+  path: z.string().trim().min(1, 'path 为必填字段'),
+  content: z.string(),
+}).strict();
+
+export type FsWriteInput = z.infer<typeof fsWriteInputSchema>;
+
+export type FsWriteResult = {
+  path: string;
+  bytesWritten: number;
+};
+
+export const fsWriteResultSchema = z.object({
+  path: z.string(),
+  bytesWritten: z.number().int().nonnegative(),
+}).strict() as z.ZodType<FsWriteResult>;
+
+export function createFsWriteToolHandler(options: FsWriteToolOptions = {}): ToolHandler<FsWriteInput, FsWriteResult> {
+  const requireApproval = options.requireApproval ?? true;
+
+  return {
+    descriptor: {
+      name: 'fs-write',
+      title: '写入沙箱文件',
+      description: '向会话沙箱内的文本文件写入内容。',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['path', 'content'],
+        properties: {
+          path: { type: 'string', minLength: 1, description: '沙箱内相对路径。' },
+          content: { type: 'string', description: '要写入的文本内容。' },
+        },
+      },
+      resultSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['path', 'bytesWritten'],
+        properties: {
+          path: { type: 'string' },
+          bytesWritten: { type: 'integer', minimum: 0 },
+        },
+      },
+      requiredResources: ['sandbox'],
+      annotations: {
+        readOnly: false,
+        idempotent: false,
+        openWorld: false,
+        destructive: true,
+      },
+    },
+    inputSchema: fsWriteInputSchema,
+    resultSchema: fsWriteResultSchema,
+    execute: async (input, context): Promise<ToolExecution<FsWriteResult>> => {
+      const path = normalizePathOrFailed<FsWriteResult>(input.path);
+      if (isToolExecution(path)) {
+        return path;
+      }
+
+      if (requireApproval) {
+        return pausedForApproval({
+          subject: 'fs-write',
+          summary: `写入文件：${path}`,
+        });
+      }
+
+      return executeFsWrite(input, context, path);
+    },
+    resume: async (input, context) => {
+      if (!isApprovalGranted(input)) {
+        return approvalDenied();
+      }
+
+      const path = normalizePathOrFailed<FsWriteResult>(input.originalInput.path);
+      if (isToolExecution(path)) {
+        return path;
+      }
+
+      return executeFsWrite(input.originalInput, context, path);
+    },
+  };
+}
+
+async function executeFsWrite(
+  input: FsWriteInput,
+  context: ToolHandlerContext,
+  path: string,
+): Promise<ToolExecution<FsWriteResult>> {
+  const sandbox = requireSandbox(context);
+  if (isToolExecution(sandbox)) {
+    return sandbox;
+  }
+
+  try {
+    await sandbox.writeFile(path, input.content);
+    return {
+      status: 'completed',
+      modelResult: {
+        path,
+        bytesWritten: countUtf8Bytes(input.content),
+      },
+    };
+  } catch (error) {
+    return failed('FS_WRITE_FAILED', error instanceof Error ? error.message : String(error));
+  }
+}
+
+function isToolExecution<T>(value: unknown): value is ToolExecution<T> {
+  return value !== null && typeof value === 'object' && 'status' in value;
+}