@ct-agents/tools 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ct-agents/tools",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "files": [
     "src"
@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "zod": "4.4.3",
-    "@ct-agents/protocol": "0.1.4"
+    "@ct-agents/protocol": "0.1.5"
   },
   "publishConfig": {
     "access": "public"

package/src/builtin-tools/index.ts

@@ -1,2 +1,3 @@
 export * from './ask-user.js';
+export * from './todo-write.js';
 export * from './web-search.js';

package/src/builtin-tools/todo-write.ts

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+import type { ToolExecution, ToolHandler } from '@ct-agents/protocol';
+
+export const todoWriteStepStatusSchema = z.enum([
+  'pending',
+  'in_progress',
+  'completed',
+]);
+
+const todoWriteStepSchema = z.object({
+  step: z.string().trim().min(1).max(160),
+  status: todoWriteStepStatusSchema,
+}).strict();
+
+type TodoWriteStep = z.infer<typeof todoWriteStepSchema>;
+
+export function validateLinearTodoSteps(
+  steps: TodoWriteStep[],
+  context: z.RefinementCtx,
+): void {
+  if (steps.length === 0 || steps.every((step) => step.status === 'completed')) {
+    return;
+  }
+
+  const activeIndexes = steps
+    .map((step, index) => step.status === 'in_progress' ? index : -1)
+    .filter((index) => index >= 0);
+  if (activeIndexes.length !== 1) {
+    context.addIssue({
+      code: 'custom',
+      path: ['steps'],
+      message: '非空未完成计划必须且只能包含一个 in_progress 步骤',
+    });
+    return;
+  }
+
+  const activeIndex = activeIndexes[0];
+  if (activeIndex === undefined) {
+    return;
+  }
+  for (const [index, step] of steps.entries()) {
+    const expectedStatus = index < activeIndex
+      ? 'completed'
+      : index === activeIndex
+        ? 'in_progress'
+        : 'pending';
+    if (step.status !== expectedStatus) {
+      context.addIssue({
+        code: 'custom',
+        path: ['steps', index, 'status'],
+        message: '计划状态必须符合 completed* -> in_progress -> pending*',
+      });
+    }
+  }
+}
+
+export const todoWriteSnapshotSchema = z.object({
+  steps: z.array(todoWriteStepSchema).max(20),
+}).strict().superRefine((snapshot, context) => {
+  validateLinearTodoSteps(snapshot.steps, context);
+});
+
+export type TodoWriteSnapshot = z.infer<typeof todoWriteSnapshotSchema>;
+
+const todoWriteStepJsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['step', 'status'],
+  properties: {
+    step: { type: 'string', minLength: 1, maxLength: 160, description: '任务步骤文本。' },
+    status: {
+      type: 'string',
+      enum: ['pending', 'in_progress', 'completed'],
+      description: '步骤在线性计划中的当前状态。',
+    },
+  },
+} as const;
+
+/**
+ * 写入线性任务计划的完整快照。
+ *
+ * handler 不读取历史快照或 Resource；事件持久化和模型上下文恢复继续由 Environment/Harness 负责。
+ */
+export function createTodoWriteToolHandler(): ToolHandler<TodoWriteSnapshot, TodoWriteSnapshot> {
+  return {
+    descriptor: {
+      name: 'todo-write',
+      title: '更新任务计划',
+      description: [
+        '在长任务中创建、推进、完成或清空线性任务计划。',
+        '每次调用必须提交完整 steps 快照：未完成计划只能有一个 in_progress，之前只能是 completed，之后只能是 pending；全部完成时保留所有 completed 步骤。',
+        '使用 { steps: [] } 显式清空计划。',
+      ].join('\n'),
+      inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['steps'],
+        properties: {
+          steps: {
+            type: 'array',
+            maxItems: 20,
+            description: '完整计划快照。空数组表示清空；非空未完成快照必须符合 completed* -> in_progress -> pending*，全部完成快照只能包含 completed。',
+            items: todoWriteStepJsonSchema,
+          },
+        },
+      },
+      resultSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['steps'],
+        properties: {
+          steps: {
+            type: 'array',
+            maxItems: 20,
+            description: '规范化后的完整计划快照。',
+            items: todoWriteStepJsonSchema,
+          },
+        },
+      },
+      annotations: {
+        readOnly: true,
+        idempotent: true,
+        openWorld: false,
+        destructive: false,
+      },
+    },
+    inputSchema: todoWriteSnapshotSchema,
+    resultSchema: todoWriteSnapshotSchema,
+    execute: async (input): Promise<ToolExecution<TodoWriteSnapshot>> => {
+      const normalizedSnapshot = todoWriteSnapshotSchema.parse(input);
+      return {
+        status: 'completed',
+        modelResult: {
+          steps: normalizedSnapshot.steps.map((step) => ({ ...step })),
+        },
+        effects: [],
+      };
+    },
+  };
+}