@namzu/sdk 0.1.1

package/src/tools/builtins/bash.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod'
+import { defineTool } from '../defineTool.js'
+import type { ToolContext } from '../../types/tool/index.js'
+import { exec } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execAsync = promisify(exec)
+
+const inputSchema = z.object({
+  command: z.string().describe('The bash command to execute'),
+  timeout: z.preprocess(
+    (v) => (typeof v === 'string' ? Number(v) : v),
+    z.number().default(30_000),
+  ).describe('Command timeout in milliseconds. Default: 30000'),
+})
+
+type BashInput = z.infer<typeof inputSchema>
+
+const DANGEROUS_PATTERNS = [
+  /rm\s+-rf\s+\//,
+  /mkfs/,
+  /dd\s+if=/,
+  /:(){ :\|:& };:/,
+]
+
+function isDangerousCommand(command: string): boolean {
+  return DANGEROUS_PATTERNS.some((pattern) => pattern.test(command))
+}
+
+export const BashTool = defineTool({
+  name: 'bash',
+  description:
+    'Executes a bash command and returns stdout/stderr output. Command timeout is configurable.',
+  inputSchema,
+  category: 'shell',
+  permissions: ['shell_execute'],
+  readOnly: false,
+  destructive: (input: BashInput) => isDangerousCommand(input.command),
+  concurrencySafe: false,
+
+  async execute(input, context) {
+    if (isDangerousCommand(input.command)) {
+      return {
+        success: false,
+        output: '',
+        error: `Dangerous command blocked: "${input.command}"`,
+      }
+    }
+
+    const { stdout, stderr } = await execAsync(input.command, {
+      cwd: context.workingDirectory,
+      timeout: input.timeout,
+      env: { ...process.env, ...context.env },
+      maxBuffer: 1024 * 1024 * 10,
+    })
+
+    const output = [
+      stdout ? `STDOUT:\n${stdout}` : '',
+      stderr ? `STDERR:\n${stderr}` : '',
+    ]
+      .filter(Boolean)
+      .join('\n\n')
+
+    return {
+      success: true,
+      output: output || '(no output)',
+      data: { exitCode: 0 },
+    }
+  },
+})

package/src/tools/builtins/glob.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod'
+import { defineTool } from '../defineTool.js'
+import { basename, dirname, resolve, relative, sep } from 'node:path'
+import { glob } from 'node:fs/promises'
+
+const inputSchema = z.object({
+  pattern: z.string().describe('Glob pattern (e.g. "**/*.ts", "src/**/*.js")'),
+  path: z
+    .string()
+    .optional()
+    .describe('Directory to search in. Defaults to the working directory if not specified.'),
+})
+
+function extractGlobBaseDirectory(pattern: string): {
+  baseDir: string
+  relativePattern: string
+} {
+  const globChars = /[*?[{]/
+  const match = pattern.match(globChars)
+
+  if (!match || match.index === undefined) {
+    return { baseDir: dirname(pattern), relativePattern: basename(pattern) }
+  }
+
+  const staticPrefix = pattern.slice(0, match.index)
+  const lastSepIndex = Math.max(
+    staticPrefix.lastIndexOf('/'),
+    staticPrefix.lastIndexOf(sep),
+  )
+
+  if (lastSepIndex === -1) {
+    return { baseDir: '', relativePattern: pattern }
+  }
+
+  const baseDir = staticPrefix.slice(0, lastSepIndex)
+  const relativePattern = pattern.slice(lastSepIndex + 1)
+
+  return { baseDir, relativePattern }
+}
+
+export const GlobTool = defineTool({
+  name: 'glob',
+  description:
+    'Searches for files using a glob pattern. Returns matching file paths.',
+  inputSchema,
+  category: 'filesystem',
+  permissions: ['file_read'],
+  readOnly: true,
+  destructive: false,
+  concurrencySafe: true,
+
+  async execute(input, context) {
+    const basePath = input.path
+      ? resolve(context.workingDirectory, input.path)
+      : context.workingDirectory
+
+    let searchPath = basePath
+    let pattern = input.pattern
+
+    const { baseDir, relativePattern } = extractGlobBaseDirectory(pattern)
+    if (baseDir) {
+      const resolvedPatternBase = resolve(context.workingDirectory, baseDir)
+      if (resolvedPatternBase === basePath || resolvedPatternBase.startsWith(basePath + '/')) {
+        searchPath = resolvedPatternBase
+        pattern = relativePattern
+      }
+    }
+
+    if (!pattern.includes('/') && !pattern.startsWith('**/')) {
+      pattern = `**/${pattern}`
+    }
+
+    const matches: string[] = []
+    const MAX_RESULTS = 500
+
+    for await (const entry of glob(pattern, { cwd: searchPath })) {
+      const absolutePath = resolve(searchPath, entry)
+      matches.push(`./${relative(context.workingDirectory, absolutePath)}`)
+      if (matches.length >= MAX_RESULTS) break
+    }
+
+    if (matches.length === 0) {
+      return {
+        success: true,
+        output: `No files found matching pattern "${input.pattern}" in ${searchPath}`,
+        data: { count: 0, files: [] },
+      }
+    }
+
+    return {
+      success: true,
+      output: matches.join('\n'),
+      data: { count: matches.length, files: matches },
+    }
+  },
+})

package/src/tools/builtins/index.ts

@@ -0,0 +1,16 @@
+export { ReadFileTool } from "./read-file.js";
+export { WriteFileTool } from "./write-file.js";
+export { BashTool } from "./bash.js";
+export { GlobTool } from "./glob.js";
+export { SearchToolsTool } from "./search-tools.js";
+
+import type { ToolDefinition } from "../../types/tool/index.js";
+import { BashTool } from "./bash.js";
+import { GlobTool } from "./glob.js";
+import { ReadFileTool } from "./read-file.js";
+import { SearchToolsTool } from "./search-tools.js";
+import { WriteFileTool } from "./write-file.js";
+
+export function getBuiltinTools(): ToolDefinition[] {
+	return [ReadFileTool, WriteFileTool, BashTool, GlobTool, SearchToolsTool];
+}

package/src/tools/builtins/read-file.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod'
+import { defineTool } from '../defineTool.js'
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+const inputSchema = z.object({
+  path: z.string().describe('Path to the file to read (absolute or relative)'),
+  offset: z
+    .coerce.number()
+    .int()
+    .min(0)
+    .optional()
+    .describe('Starting line number (0-indexed). Defaults to 0 (beginning of file).'),
+  limit: z
+    .coerce.number()
+    .optional()
+    .describe('Maximum number of lines to read'),
+})
+
+export const ReadFileTool = defineTool({
+  name: 'read_file',
+  description:
+    'Reads a file and returns its contents with line numbers. Supports offset and limit parameters for large files.',
+  inputSchema,
+  category: 'filesystem',
+  permissions: ['file_read'],
+  readOnly: true,
+  destructive: false,
+  concurrencySafe: true,
+
+  async execute(input, context) {
+    const filePath = resolve(context.workingDirectory, input.path)
+    const content = await readFile(filePath, 'utf-8')
+    const lines = content.split('\n')
+
+    const start = Math.max(0, input.offset ?? 0)
+    const end = input.limit ? start + input.limit : lines.length
+    const selectedLines = lines.slice(start, end)
+
+    const numberedLines = selectedLines
+      .map((line, i) => `${start + i}\t${line}`)
+      .join('\n')
+
+    return {
+      success: true,
+      output: numberedLines,
+      data: {
+        totalLines: lines.length,
+        returnedLines: selectedLines.length,
+        path: filePath,
+      },
+    }
+  },
+})

package/src/tools/builtins/search-tools.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { defineTool } from "../defineTool.js";
+
+const inputSchema = z.object({
+	query: z.string().describe("Tool name or capability keyword to search for"),
+});
+
+export const SearchToolsTool = defineTool({
+	name: "search_tools",
+	description:
+		"Search and load available tools by name or capability. " +
+		"Deferred tools listed in the system prompt must be loaded via this tool before use.",
+	inputSchema,
+	category: "analysis",
+	permissions: [],
+	readOnly: true,
+	destructive: false,
+	concurrencySafe: true,
+
+	async execute(input, context) {
+		if (!context.toolRegistry) {
+			return {
+				success: false,
+				output: "",
+				error: "Tool registry not available in this context.",
+			};
+		}
+
+		const matches = context.toolRegistry.searchDeferred(input.query);
+
+		if (matches.length === 0) {
+			return {
+				success: true,
+				output: `No deferred tools matching "${input.query}". All matching tools are already active.`,
+			};
+		}
+
+		context.toolRegistry.activate(matches.map((t) => t.name));
+
+		const descriptions = matches
+			.map((t) => `- ${t.name}: ${t.description}`)
+			.join("\n");
+
+		return {
+			success: true,
+			output: `Activated ${matches.length} tool(s):\n${descriptions}`,
+			data: {
+				activated: matches.map((t) => t.name),
+				count: matches.length,
+			},
+		};
+	},
+});

package/src/tools/builtins/write-file.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod'
+import { defineTool } from '../defineTool.js'
+import { writeFile, mkdir } from 'node:fs/promises'
+import { resolve, dirname } from 'node:path'
+
+const inputSchema = z.object({
+  path: z.string().describe('Path to the file to write'),
+  content: z.string().describe('Content to write to the file'),
+})
+
+export const WriteFileTool = defineTool({
+  name: 'write_file',
+  description:
+    'Writes content to a file. Creates the file if it does not exist, overwrites if it does. Creates intermediate directories as needed.',
+  inputSchema,
+  category: 'filesystem',
+  permissions: ['file_write'],
+  readOnly: false,
+  destructive: true,
+  concurrencySafe: false,
+
+  async execute(input, context) {
+    const filePath = resolve(context.workingDirectory, input.path)
+
+    await mkdir(dirname(filePath), { recursive: true })
+    await writeFile(filePath, input.content, 'utf-8')
+
+    return {
+      success: true,
+      output: `File written successfully: ${filePath} (${input.content.length} chars)`,
+      data: { path: filePath, size: input.content.length },
+    }
+  },
+})

package/src/tools/coordinator/index.ts

@@ -0,0 +1,205 @@
+import { z } from 'zod'
+import type { TaskGateway } from '../../types/agent/gateway.js'
+import type { RunId, TaskId } from '../../types/ids/index.js'
+import type { PlanManager } from '../../manager/plan/lifecycle.js'
+import type { TaskStore } from '../../types/task/index.js'
+import type { ToolDefinition } from '../../types/tool/index.js'
+import { defineTool } from '../defineTool.js'
+
+export type TaskLaunchedCallback = (agentTaskId: TaskId, meta: {
+  agentId: string
+  description: string
+  planTaskId?: string
+}) => void
+
+export interface CoordinatorToolsOptions {
+  gateway: TaskGateway
+  workingDirectory: string
+  allowedAgentIds: string[]
+
+  taskStore?: TaskStore
+
+  runId?: RunId
+
+  getPlanManager?: () => PlanManager | undefined
+
+  onTaskLaunched?: TaskLaunchedCallback
+}
+
+export function buildCoordinatorTools(
+  opts: CoordinatorToolsOptions,
+): ToolDefinition[] {
+  const { gateway, allowedAgentIds: agentIds, taskStore, runId, getPlanManager, onTaskLaunched } = opts
+  const cwd = opts.workingDirectory
+
+  const agentIdEnum = agentIds.length > 0
+    ? z.enum(agentIds as [string, ...string[]])
+    : z.string()
+
+  const createTask = defineTool({
+    name: 'create_task',
+    description: `Launch a task on a specialized agent. NON-BLOCKING: returns immediately. You will receive a <task-notification> message when the agent finishes. Available agents: ${agentIds.join(', ')}. The agent cannot see your conversation — include ALL necessary context in the prompt. To launch multiple tasks in parallel, call this tool multiple times in a single response. After launching, briefly tell the user what you launched and end your turn — do NOT predict or fabricate results.`,
+    inputSchema: z.object({
+      agent_id: agentIdEnum.describe('Which agent to run'),
+      prompt: z.string().describe('Self-contained task description with all context the agent needs'),
+      description: z.string().describe('Short summary for tracking (shown to user)'),
+      plan_task_id: z.string().optional().describe('Existing planning task ID to link. If omitted, a planning task is auto-created.'),
+    }),
+    category: 'custom',
+    permissions: [],
+    readOnly: false,
+    destructive: false,
+    concurrencySafe: true,
+    async execute({ agent_id, prompt, description, plan_task_id }) {
+      let resolvedPlanTaskId = plan_task_id
+
+      if (taskStore) {
+        if (resolvedPlanTaskId) {
+          await taskStore.update(resolvedPlanTaskId as `task_${string}`, {
+            status: 'in_progress',
+            owner: agent_id,
+          })
+        } else if (runId) {
+          const planTask = await taskStore.create({
+            runId,
+            subject: description,
+            activeForm: description,
+            owner: agent_id,
+          })
+          await taskStore.update(planTask.id, { status: 'in_progress' })
+          resolvedPlanTaskId = planTask.id
+        }
+      }
+
+      const handle = await gateway.createTask({
+        agentId: agent_id,
+        prompt,
+        workingDirectory: cwd,
+      })
+
+      if (onTaskLaunched) {
+        onTaskLaunched(handle.taskId, {
+          agentId: agent_id,
+          description,
+          planTaskId: resolvedPlanTaskId,
+        })
+      }
+
+      return {
+        success: true,
+        output: `Task launched: ${handle.taskId} → ${agent_id} ("${description}"). You will receive a task-notification when it completes.`,
+        data: { task_id: handle.taskId, agent_id, description, state: 'running', plan_task_id: resolvedPlanTaskId },
+      }
+    },
+  })
+
+  const continueTask = defineTool({
+    name: 'continue_task',
+    description: 'Send a follow-up message to a previously completed task. NON-BLOCKING: the agent resumes in the background with full prior context. You will receive a task-notification when it finishes. Only use this with a task_id from a previous create_task or task-notification.',
+    inputSchema: z.object({
+      task_id: z.string().describe('Agent task ID from a previous create_task or task-notification'),
+      message: z.string().describe('Follow-up instruction for the agent'),
+    }),
+    category: 'custom',
+    permissions: [],
+    readOnly: false,
+    destructive: false,
+    concurrencySafe: true,
+    async execute({ task_id, message }) {
+      await gateway.continueTask(task_id as TaskId, message)
+
+      return {
+        success: true,
+        output: `Follow-up sent to ${task_id}. You will receive a task-notification when it finishes.`,
+        data: { task_id, state: 'running' },
+      }
+    },
+  })
+
+  const cancelTask = defineTool({
+    name: 'cancel_task',
+    description: 'Cancel a running agent task. Only use this with a task_id from a previous create_task.',
+    inputSchema: z.object({
+      task_id: z.string().describe('Agent task ID from a previous create_task'),
+    }),
+    category: 'custom',
+    permissions: [],
+    readOnly: false,
+    destructive: false,
+    concurrencySafe: true,
+    async execute({ task_id }) {
+      gateway.cancelTask(task_id as TaskId)
+      return {
+        success: true,
+        output: `Task ${task_id} cancelled`,
+        data: { task_id },
+      }
+    },
+  })
+
+  const tools: ToolDefinition[] = [createTask, continueTask, cancelTask]
+
+  if (getPlanManager) {
+    const approvePlan = defineTool({
+      name: 'approve_plan',
+      description: 'Present your execution plan to the user for approval before launching workers. Call this after you have analyzed the request and determined what tasks to run. The user can approve, reject with feedback, or modify the plan. Only proceed with create_task after approval.',
+      inputSchema: z.object({
+        title: z.string().describe('Short title for the plan (e.g. "TypeScript Security & Performance Review")'),
+        summary: z.string().describe('1-3 sentence summary of what you plan to do'),
+        steps: z.array(z.object({
+          description: z.string().describe('What this step does'),
+          agent_id: z.string().optional().describe('Which agent handles this (omit for orchestrator-owned steps)'),
+          depends_on: z.array(z.string()).optional().describe('Step descriptions this depends on'),
+        })).describe('Ordered list of planned steps'),
+      }),
+      category: 'custom',
+      permissions: [],
+      readOnly: true,
+      destructive: false,
+      concurrencySafe: true,
+      async execute({ title, summary, steps }) {
+        const pm = getPlanManager()
+        if (!pm) {
+          return {
+            success: false,
+            output: 'Plan approval is not available — proceed directly with create_task.',
+            data: { approved: true },
+          }
+        }
+
+        pm.startGenerating(title)
+        for (let i = 0; i < steps.length; i++) {
+          const step = steps[i]
+          pm.addStep({
+            id: `step_${i + 1}`,
+            description: step.description,
+            toolName: step.agent_id ? 'create_task' : undefined,
+            dependsOn: [],
+            order: i + 1,
+          })
+        }
+        pm.markReady(summary)
+
+        const response = await pm.requestApproval()
+
+        if (response.approved) {
+          pm.startExecution()
+          return {
+            success: true,
+            output: 'Plan approved by user. Proceed with execution — launch workers via create_task.',
+            data: { approved: true, feedback: response.feedback },
+          }
+        }
+
+        return {
+          success: false,
+          output: `Plan rejected. User feedback: ${response.feedback ?? 'No feedback provided'}. Revise your plan based on this feedback and call approve_plan again, or ask the user for clarification.`,
+          data: { approved: false, feedback: response.feedback },
+        }
+      },
+    })
+    tools.push(approvePlan)
+  }
+
+  return tools
+}

package/src/tools/defineTool.ts

@@ -0,0 +1,47 @@
+import type { z } from 'zod'
+import type { ToolDefinition, ToolContext, ToolResult, ToolPermission } from '../types/tool/index.js'
+import { toErrorMessage } from '../utils/error.js'
+
+export interface DefineToolOptions<S extends z.ZodType> {
+  name: string
+  description: string
+  inputSchema: S
+  category: ToolDefinition['category']
+  permissions: ToolPermission[]
+  readOnly: boolean
+  destructive: boolean | ((input: z.infer<S>) => boolean)
+  concurrencySafe: boolean
+  execute(input: z.infer<S>, context: ToolContext): Promise<ToolResult>
+}
+
+export function defineTool<S extends z.ZodType>(
+  options: DefineToolOptions<S>,
+): ToolDefinition<z.infer<S>> {
+  type TInput = z.infer<S>
+
+  return {
+    name: options.name,
+    description: options.description,
+    inputSchema: options.inputSchema,
+    category: options.category,
+    permissions: options.permissions,
+    isReadOnly: () => options.readOnly,
+    isDestructive: typeof options.destructive === 'function'
+      ? options.destructive
+      : () => options.destructive as boolean,
+    isConcurrencySafe: () => options.concurrencySafe,
+
+    async execute(input: TInput, context: ToolContext): Promise<ToolResult> {
+      try {
+        return await options.execute(input, context)
+      } catch (err) {
+        const message = toErrorMessage(err)
+        return {
+          success: false,
+          output: '',
+          error: `${options.name} failed: ${message}`,
+        }
+      }
+    },
+  }
+}

package/src/tools/task/create.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod'
+import type { TaskStore } from '../../types/task/index.js'
+import type { RunId } from '../../types/ids/index.js'
+import type { ToolDefinition } from '../../types/tool/index.js'
+import { defineTool } from '../defineTool.js'
+
+export function buildTaskCreateTool(
+  taskStore: TaskStore,
+  runId: RunId,
+): ToolDefinition {
+  return defineTool({
+    name: 'task_create',
+    description: 'Create a task to track a unit of planned work. Use this to break down complex work into trackable steps before starting. Each task has a subject (imperative: "Fix auth bug") and optionally an activeForm (present continuous: "Fixing auth bug") for progress display.',
+    inputSchema: z.object({
+      subject: z.string().describe('Brief title in imperative form ("Fix auth middleware")'),
+      description: z.string().optional().describe('Detailed description of the work'),
+      activeForm: z.string().optional().describe('Present continuous form for progress display ("Fixing auth middleware")'),
+      owner: z.string().optional().describe('Agent or role this task is assigned to (e.g. "code-review", "code-writer")'),
+      blockedBy: z.array(z.string()).optional().describe('Task IDs that must complete before this task can start'),
+      metadata: z.record(z.string(), z.unknown()).optional().describe('Free-form metadata'),
+    }),
+    category: 'custom',
+    permissions: [],
+    readOnly: false,
+    destructive: false,
+    concurrencySafe: true,
+    async execute({ subject, description, activeForm, owner, blockedBy, metadata }) {
+      const task = await taskStore.create({
+        runId,
+        subject,
+        description,
+        activeForm,
+        owner,
+        blockedBy: blockedBy as `task_${string}`[] | undefined,
+        metadata,
+      })
+
+      return {
+        success: true,
+        output: `Task created: ${task.id} — "${subject}"${owner ? ` [owner: ${owner}]` : ''}`,
+        data: { id: task.id, status: task.status, owner: task.owner },
+      }
+    },
+  })
+}

package/src/tools/task/index.ts

@@ -0,0 +1,21 @@
+import type { TaskStore } from '../../types/task/index.js'
+import type { RunId } from '../../types/ids/index.js'
+import type { ToolDefinition } from '../../types/tool/index.js'
+import { buildTaskCreateTool } from './create.js'
+import { buildTaskUpdateTool } from './update.js'
+import { buildTaskListTool } from './list.js'
+
+export function buildTaskTools(
+  taskStore: TaskStore,
+  runId: RunId,
+): ToolDefinition[] {
+  return [
+    buildTaskCreateTool(taskStore, runId),
+    buildTaskUpdateTool(taskStore),
+    buildTaskListTool(taskStore, runId),
+  ]
+}
+
+export { buildTaskCreateTool } from './create.js'
+export { buildTaskUpdateTool } from './update.js'
+export { buildTaskListTool } from './list.js'