@codeany/open-agent-sdk 0.1.0

package/src/tools/notebook-edit.ts

@@ -0,0 +1,93 @@
+/**
+ * NotebookEditTool - Edit Jupyter notebooks
+ */
+
+import { readFile, writeFile } from 'fs/promises'
+import { resolve } from 'path'
+import { defineTool } from './types.js'
+
+export const NotebookEditTool = defineTool({
+  name: 'NotebookEdit',
+  description: 'Edit Jupyter notebook (.ipynb) cells. Can insert, replace, or delete cells.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      file_path: {
+        type: 'string',
+        description: 'Path to the .ipynb file',
+      },
+      command: {
+        type: 'string',
+        enum: ['insert', 'replace', 'delete'],
+        description: 'The edit operation to perform',
+      },
+      cell_number: {
+        type: 'number',
+        description: 'Cell index (0-based) to operate on',
+      },
+      cell_type: {
+        type: 'string',
+        enum: ['code', 'markdown'],
+        description: 'Type of cell (for insert/replace)',
+      },
+      source: {
+        type: 'string',
+        description: 'Cell content (for insert/replace)',
+      },
+    },
+    required: ['file_path', 'command', 'cell_number'],
+  },
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  async call(input, context) {
+    const filePath = resolve(context.cwd, input.file_path)
+
+    try {
+      const content = await readFile(filePath, 'utf-8')
+      const notebook = JSON.parse(content)
+
+      if (!notebook.cells || !Array.isArray(notebook.cells)) {
+        return { data: 'Error: Invalid notebook format', is_error: true }
+      }
+
+      const { command, cell_number, cell_type, source } = input
+
+      switch (command) {
+        case 'insert': {
+          const newCell = {
+            cell_type: cell_type || 'code',
+            source: (source || '').split('\n').map((l: string, i: number, arr: string[]) =>
+              i < arr.length - 1 ? l + '\n' : l
+            ),
+            metadata: {},
+            ...(cell_type !== 'markdown' ? { outputs: [], execution_count: null } : {}),
+          }
+          notebook.cells.splice(cell_number, 0, newCell)
+          break
+        }
+        case 'replace': {
+          if (cell_number >= notebook.cells.length) {
+            return { data: `Error: Cell ${cell_number} does not exist`, is_error: true }
+          }
+          notebook.cells[cell_number].source = (source || '').split('\n').map(
+            (l: string, i: number, arr: string[]) => i < arr.length - 1 ? l + '\n' : l
+          )
+          if (cell_type) notebook.cells[cell_number].cell_type = cell_type
+          break
+        }
+        case 'delete': {
+          if (cell_number >= notebook.cells.length) {
+            return { data: `Error: Cell ${cell_number} does not exist`, is_error: true }
+          }
+          notebook.cells.splice(cell_number, 1)
+          break
+        }
+      }
+
+      await writeFile(filePath, JSON.stringify(notebook, null, 1), 'utf-8')
+      return `Notebook ${command}: cell ${cell_number} in ${filePath}`
+    } catch (err: any) {
+      return { data: `Error: ${err.message}`, is_error: true }
+    }
+  },
+})

package/src/tools/plan-tools.ts

@@ -0,0 +1,88 @@
+/**
+ * Plan Mode Tools
+ *
+ * EnterPlanMode / ExitPlanMode - Structured planning workflow.
+ * Allows the agent to enter a design/planning phase before execution.
+ */
+
+import type { ToolDefinition, ToolResult } from '../types.js'
+
+// Track plan mode state
+let planModeActive = false
+let currentPlan: string | null = null
+
+export function isPlanModeActive(): boolean {
+  return planModeActive
+}
+
+export function getCurrentPlan(): string | null {
+  return currentPlan
+}
+
+export const EnterPlanModeTool: ToolDefinition = {
+  name: 'EnterPlanMode',
+  description: 'Enter plan/design mode for complex tasks. In plan mode, the agent focuses on designing the approach before executing.',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+  },
+  isReadOnly: () => false,
+  isConcurrencySafe: () => false,
+  isEnabled: () => true,
+  async prompt() { return 'Enter plan mode for structured planning.' },
+  async call(): Promise<ToolResult> {
+    if (planModeActive) {
+      return {
+        type: 'tool_result',
+        tool_use_id: '',
+        content: 'Already in plan mode.',
+      }
+    }
+
+    planModeActive = true
+    currentPlan = null
+
+    return {
+      type: 'tool_result',
+      tool_use_id: '',
+      content: 'Entered plan mode. Design your approach before executing. Use ExitPlanMode when the plan is ready.',
+    }
+  },
+}
+
+export const ExitPlanModeTool: ToolDefinition = {
+  name: 'ExitPlanMode',
+  description: 'Exit plan mode with a completed plan. The plan will be recorded and execution can proceed.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      plan: { type: 'string', description: 'The completed plan' },
+      approved: { type: 'boolean', description: 'Whether the plan is approved for execution' },
+    },
+  },
+  isReadOnly: () => false,
+  isConcurrencySafe: () => false,
+  isEnabled: () => true,
+  async prompt() { return 'Exit plan mode with a completed plan.' },
+  async call(input: any): Promise<ToolResult> {
+    if (!planModeActive) {
+      return {
+        type: 'tool_result',
+        tool_use_id: '',
+        content: 'Not in plan mode.',
+        is_error: true,
+      }
+    }
+
+    planModeActive = false
+    currentPlan = input.plan || null
+
+    const status = input.approved !== false ? 'approved' : 'pending approval'
+
+    return {
+      type: 'tool_result',
+      tool_use_id: '',
+      content: `Plan mode exited. Plan status: ${status}.${currentPlan ? `\n\nPlan:\n${currentPlan}` : ''}`,
+    }
+  },
+}

package/src/tools/read.ts

@@ -0,0 +1,73 @@
+/**
+ * FileReadTool - Read file contents with line numbers
+ */
+
+import { readFile, stat } from 'fs/promises'
+import { resolve } from 'path'
+import { defineTool } from './types.js'
+
+export const FileReadTool = defineTool({
+  name: 'Read',
+  description: 'Read a file from the filesystem. Returns content with line numbers. Supports text files, images (returns visual content), and PDFs.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      file_path: {
+        type: 'string',
+        description: 'The absolute path to the file to read',
+      },
+      offset: {
+        type: 'number',
+        description: 'Line number to start reading from (0-based)',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of lines to read',
+      },
+    },
+    required: ['file_path'],
+  },
+  isReadOnly: true,
+  isConcurrencySafe: true,
+  async call(input, context) {
+    const filePath = resolve(context.cwd, input.file_path)
+
+    try {
+      const fileStat = await stat(filePath)
+      if (fileStat.isDirectory()) {
+        return { data: `Error: ${filePath} is a directory, not a file. Use Bash with 'ls' to list directory contents.`, is_error: true }
+      }
+
+      // Check for binary/image files
+      const ext = filePath.split('.').pop()?.toLowerCase()
+      if (['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'svg'].includes(ext || '')) {
+        return `[Image file: ${filePath} (${fileStat.size} bytes)]`
+      }
+
+      const content = await readFile(filePath, 'utf-8')
+      const lines = content.split('\n')
+
+      const offset = input.offset || 0
+      const limit = input.limit || 2000
+      const selectedLines = lines.slice(offset, offset + limit)
+
+      // Format with line numbers (cat -n style)
+      const numbered = selectedLines.map((line: string, i: number) => {
+        const lineNum = offset + i + 1
+        return `${lineNum}\t${line}`
+      }).join('\n')
+
+      let result = numbered
+      if (lines.length > offset + limit) {
+        result += `\n\n(${lines.length - offset - limit} more lines not shown)`
+      }
+
+      return result || '(empty file)'
+    } catch (err: any) {
+      if (err.code === 'ENOENT') {
+        return { data: `Error: File not found: ${filePath}`, is_error: true }
+      }
+      return { data: `Error reading file: ${err.message}`, is_error: true }
+    }
+  },
+})

package/src/tools/send-message.ts

@@ -0,0 +1,96 @@
+/**
+ * SendMessageTool - Inter-agent messaging
+ *
+ * Supports plain text and structured protocol messages
+ * between teammates in a multi-agent setup.
+ */
+
+import type { ToolDefinition, ToolResult } from '../types.js'
+
+/**
+ * Message inbox for inter-agent communication.
+ */
+export interface AgentMessage {
+  from: string
+  to: string
+  content: string
+  timestamp: string
+  type: 'text' | 'shutdown_request' | 'shutdown_response' | 'plan_approval_response'
+}
+
+const mailboxes = new Map<string, AgentMessage[]>()
+
+/**
+ * Read messages from a mailbox.
+ */
+export function readMailbox(agentName: string): AgentMessage[] {
+  const messages = mailboxes.get(agentName) || []
+  mailboxes.set(agentName, []) // Clear after reading
+  return messages
+}
+
+/**
+ * Write to a mailbox.
+ */
+export function writeToMailbox(agentName: string, message: AgentMessage): void {
+  const messages = mailboxes.get(agentName) || []
+  messages.push(message)
+  mailboxes.set(agentName, messages)
+}
+
+/**
+ * Clear all mailboxes.
+ */
+export function clearMailboxes(): void {
+  mailboxes.clear()
+}
+
+export const SendMessageTool: ToolDefinition = {
+  name: 'SendMessage',
+  description: 'Send a message to another agent or teammate. Supports plain text and structured protocol messages.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      to: { type: 'string', description: 'Recipient agent name or ID. Use "*" for broadcast.' },
+      content: { type: 'string', description: 'Message content' },
+      type: {
+        type: 'string',
+        enum: ['text', 'shutdown_request', 'shutdown_response', 'plan_approval_response'],
+        description: 'Message type (default: text)',
+      },
+    },
+    required: ['to', 'content'],
+  },
+  isReadOnly: () => false,
+  isConcurrencySafe: () => true,
+  isEnabled: () => true,
+  async prompt() { return 'Send a message to another agent.' },
+  async call(input: any): Promise<ToolResult> {
+    const message: AgentMessage = {
+      from: 'self',
+      to: input.to,
+      content: input.content,
+      timestamp: new Date().toISOString(),
+      type: input.type || 'text',
+    }
+
+    if (input.to === '*') {
+      // Broadcast to all known mailboxes
+      for (const [name] of mailboxes) {
+        writeToMailbox(name, { ...message, to: name })
+      }
+      return {
+        type: 'tool_result',
+        tool_use_id: '',
+        content: `Message broadcast to all agents`,
+      }
+    }
+
+    writeToMailbox(input.to, message)
+    return {
+      type: 'tool_result',
+      tool_use_id: '',
+      content: `Message sent to ${input.to}`,
+    }
+  },
+}

package/src/tools/task-tools.ts

@@ -0,0 +1,290 @@
+/**
+ * Task Management Tools
+ *
+ * TaskCreate, TaskList, TaskUpdate, TaskGet, TaskStop, TaskOutput
+ *
+ * Provides in-memory task tracking for agent coordination.
+ * Tasks persist across turns within a session.
+ */
+
+import type { ToolDefinition, ToolContext, ToolResult } from '../types.js'
+
+/**
+ * Task status.
+ */
+export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled'
+
+/**
+ * Task entry.
+ */
+export interface Task {
+  id: string
+  subject: string
+  description?: string
+  status: TaskStatus
+  owner?: string
+  createdAt: string
+  updatedAt: string
+  output?: string
+  blockedBy?: string[]
+  blocks?: string[]
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Global task store (shared across tools in a session).
+ */
+const taskStore = new Map<string, Task>()
+
+let taskCounter = 0
+
+/**
+ * Get all tasks.
+ */
+export function getAllTasks(): Task[] {
+  return Array.from(taskStore.values())
+}
+
+/**
+ * Get a task by ID.
+ */
+export function getTask(id: string): Task | undefined {
+  return taskStore.get(id)
+}
+
+/**
+ * Clear all tasks (for session reset).
+ */
+export function clearTasks(): void {
+  taskStore.clear()
+  taskCounter = 0
+}
+
+// ============================================================================
+// TaskCreateTool
+// ============================================================================
+
+export const TaskCreateTool: ToolDefinition = {
+  name: 'TaskCreate',
+  description: 'Create a new task for tracking work progress. Tasks help organize multi-step operations.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      subject: { type: 'string', description: 'Short task title' },
+      description: { type: 'string', description: 'Detailed task description' },
+      owner: { type: 'string', description: 'Task owner/assignee' },
+      status: { type: 'string', enum: ['pending', 'in_progress'], description: 'Initial status' },
+    },
+    required: ['subject'],
+  },
+  isReadOnly: () => false,
+  isConcurrencySafe: () => true,
+  isEnabled: () => true,
+  async prompt() { return 'Create a task for tracking progress.' },
+  async call(input: any): Promise<ToolResult> {
+    const id = `task_${++taskCounter}`
+    const task: Task = {
+      id,
+      subject: input.subject,
+      description: input.description,
+      status: input.status || 'pending',
+      owner: input.owner,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    }
+    taskStore.set(id, task)
+
+    return {
+      type: 'tool_result',
+      tool_use_id: '',
+      content: `Task created: ${id} - "${task.subject}" (${task.status})`,
+    }
+  },
+}
+
+// ============================================================================
+// TaskListTool
+// ============================================================================
+
+export const TaskListTool: ToolDefinition = {
+  name: 'TaskList',
+  description: 'List all tasks with their status, ownership, and dependencies.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      status: { type: 'string', description: 'Filter by status' },
+      owner: { type: 'string', description: 'Filter by owner' },
+    },
+  },
+  isReadOnly: () => true,
+  isConcurrencySafe: () => true,
+  isEnabled: () => true,
+  async prompt() { return 'List tasks.' },
+  async call(input: any): Promise<ToolResult> {
+    let tasks = getAllTasks()
+
+    if (input.status) {
+      tasks = tasks.filter(t => t.status === input.status)
+    }
+    if (input.owner) {
+      tasks = tasks.filter(t => t.owner === input.owner)
+    }
+
+    if (tasks.length === 0) {
+      return { type: 'tool_result', tool_use_id: '', content: 'No tasks found.' }
+    }
+
+    const lines = tasks.map(t =>
+      `[${t.id}] ${t.status.toUpperCase()} - ${t.subject}${t.owner ? ` (owner: ${t.owner})` : ''}`
+    )
+
+    return {
+      type: 'tool_result',
+      tool_use_id: '',
+      content: lines.join('\n'),
+    }
+  },
+}
+
+// ============================================================================
+// TaskUpdateTool
+// ============================================================================
+
+export const TaskUpdateTool: ToolDefinition = {
+  name: 'TaskUpdate',
+  description: 'Update a task\'s status, description, or other properties.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'Task ID' },
+      status: { type: 'string', enum: ['pending', 'in_progress', 'completed', 'failed', 'cancelled'] },
+      description: { type: 'string', description: 'Updated description' },
+      owner: { type: 'string', description: 'New owner' },
+      output: { type: 'string', description: 'Task output/result' },
+    },
+    required: ['id'],
+  },
+  isReadOnly: () => false,
+  isConcurrencySafe: () => true,
+  isEnabled: () => true,
+  async prompt() { return 'Update a task.' },
+  async call(input: any): Promise<ToolResult> {
+    const task = taskStore.get(input.id)
+    if (!task) {
+      return { type: 'tool_result', tool_use_id: '', content: `Task not found: ${input.id}`, is_error: true }
+    }
+
+    if (input.status) task.status = input.status
+    if (input.description) task.description = input.description
+    if (input.owner) task.owner = input.owner
+    if (input.output) task.output = input.output
+    task.updatedAt = new Date().toISOString()
+
+    return {
+      type: 'tool_result',
+      tool_use_id: '',
+      content: `Task updated: ${task.id} - ${task.status} - "${task.subject}"`,
+    }
+  },
+}
+
+// ============================================================================
+// TaskGetTool
+// ============================================================================
+
+export const TaskGetTool: ToolDefinition = {
+  name: 'TaskGet',
+  description: 'Get full details of a specific task.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'Task ID' },
+    },
+    required: ['id'],
+  },
+  isReadOnly: () => true,
+  isConcurrencySafe: () => true,
+  isEnabled: () => true,
+  async prompt() { return 'Get task details.' },
+  async call(input: any): Promise<ToolResult> {
+    const task = taskStore.get(input.id)
+    if (!task) {
+      return { type: 'tool_result', tool_use_id: '', content: `Task not found: ${input.id}`, is_error: true }
+    }
+
+    return {
+      type: 'tool_result',
+      tool_use_id: '',
+      content: JSON.stringify(task, null, 2),
+    }
+  },
+}
+
+// ============================================================================
+// TaskStopTool
+// ============================================================================
+
+export const TaskStopTool: ToolDefinition = {
+  name: 'TaskStop',
+  description: 'Stop/cancel a running task.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'Task ID to stop' },
+      reason: { type: 'string', description: 'Reason for stopping' },
+    },
+    required: ['id'],
+  },
+  isReadOnly: () => false,
+  isConcurrencySafe: () => true,
+  isEnabled: () => true,
+  async prompt() { return 'Stop a task.' },
+  async call(input: any): Promise<ToolResult> {
+    const task = taskStore.get(input.id)
+    if (!task) {
+      return { type: 'tool_result', tool_use_id: '', content: `Task not found: ${input.id}`, is_error: true }
+    }
+
+    task.status = 'cancelled'
+    task.updatedAt = new Date().toISOString()
+    if (input.reason) task.output = `Stopped: ${input.reason}`
+
+    return {
+      type: 'tool_result',
+      tool_use_id: '',
+      content: `Task stopped: ${task.id}`,
+    }
+  },
+}
+
+// ============================================================================
+// TaskOutputTool
+// ============================================================================
+
+export const TaskOutputTool: ToolDefinition = {
+  name: 'TaskOutput',
+  description: 'Get the output/result of a task.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'Task ID' },
+    },
+    required: ['id'],
+  },
+  isReadOnly: () => true,
+  isConcurrencySafe: () => true,
+  isEnabled: () => true,
+  async prompt() { return 'Get task output.' },
+  async call(input: any): Promise<ToolResult> {
+    const task = taskStore.get(input.id)
+    if (!task) {
+      return { type: 'tool_result', tool_use_id: '', content: `Task not found: ${input.id}`, is_error: true }
+    }
+
+    return {
+      type: 'tool_result',
+      tool_use_id: '',
+      content: task.output || '(no output yet)',
+    }
+  },
+}