deepagentsdk 0.9.2

package/src/prompts.ts

@@ -0,0 +1,196 @@
+/**
+ * System prompts for Deep Agent.
+ */
+
+export const BASE_PROMPT = `In order to complete the objective that the user asks of you, you have access to a number of standard tools.`;
+
+export const TODO_SYSTEM_PROMPT = `## \`write_todos\` (task planning)
+
+You have access to a \`write_todos\` tool to help you manage and plan tasks. Use this tool whenever you are working on a complex task.
+
+### When to Use This Tool
+
+Use proactively for:
+1. Complex multi-step tasks (3+ distinct steps)
+2. Non-trivial tasks requiring careful planning
+3. After receiving new instructions - capture requirements as todos
+4. After completing tasks - mark complete and add follow-ups
+5. When starting new tasks - mark as in_progress (ideally only one at a time)
+
+### When NOT to Use
+
+Skip for:
+1. Single, straightforward tasks
+2. Trivial tasks with no organizational benefit
+3. Tasks completable in < 3 trivial steps
+4. Purely conversational/informational requests
+
+### Task States and Management
+
+1. **Task States:**
+  - pending: Not yet started
+  - in_progress: Currently working on
+  - completed: Finished successfully
+  - cancelled: No longer needed
+
+2. **Task Management:**
+  - Update status in real-time
+  - Mark complete IMMEDIATELY after finishing
+  - Only ONE task in_progress at a time
+  - Complete current tasks before starting new ones`;
+
+export const FILESYSTEM_SYSTEM_PROMPT = `## Virtual Filesystem
+
+You have access to a virtual filesystem. All file paths must start with a /.
+
+- ls: list files in a directory (requires absolute path)
+- read_file: read a file from the filesystem
+- write_file: write to a file in the filesystem
+- edit_file: edit a file in the filesystem
+- glob: find files matching a pattern (e.g., "**/*.py")
+- grep: search for text within files`;
+
+export const TASK_SYSTEM_PROMPT = `## \`task\` (subagent spawner)
+
+You have access to a \`task\` tool to launch short-lived subagents that handle isolated tasks. These agents are ephemeral — they live only for the duration of the task and return a single result.
+
+When to use the task tool:
+- When a task is complex and multi-step, and can be fully delegated in isolation
+- When a task is independent of other tasks and can run in parallel
+- When a task requires focused reasoning or heavy token/context usage that would bloat the orchestrator thread
+- When sandboxing improves reliability (e.g. code execution, structured searches, data formatting)
+- When you only care about the output of the subagent, and not the intermediate steps
+
+Subagent lifecycle:
+1. **Spawn** → Provide clear role, instructions, and expected output
+2. **Run** → The subagent completes the task autonomously
+3. **Return** → The subagent provides a single structured result
+4. **Reconcile** → Incorporate or synthesize the result into the main thread
+
+When NOT to use the task tool:
+- If you need to see the intermediate reasoning or steps after the subagent has completed (the task tool hides them)
+- If the task is trivial (a few tool calls or simple lookup)
+- If delegating does not reduce token usage, complexity, or context switching
+- If splitting would add latency without benefit
+
+## Important Task Tool Usage Notes
+- Whenever possible, parallelize the work that you do. Whenever you have independent steps to complete - kick off tasks (subagents) in parallel to accomplish them faster.
+- Remember to use the \`task\` tool to silo independent tasks within a multi-part objective.
+- You should use the \`task\` tool whenever you have a complex task that will take multiple steps, and is independent from other tasks that the agent needs to complete.`;
+
+/**
+ * Get the task tool description with available subagent types.
+ */
+export function getTaskToolDescription(subagentDescriptions: string[]): string {
+  return `
+Launch an ephemeral subagent to handle complex, multi-step independent tasks with isolated context windows.
+
+Available agent types and the tools they have access to:
+${subagentDescriptions.join("\n")}
+
+When using the Task tool, you must specify a subagent_type parameter to select which agent type to use.
+
+## Usage notes:
+1. Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
+2. When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
+3. Each agent invocation is stateless. You will not be able to send additional messages to the agent, nor will the agent be able to communicate with you outside of its final report. Therefore, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
+4. The agent's outputs should generally be trusted
+5. Clearly tell the agent whether you expect it to create content, perform analysis, or just do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent
+6. If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
+7. When only the general-purpose agent is provided, you should use it for all tasks. It is great for isolating context and token usage, and completing specific, complex tasks, as it has all the same capabilities as the main agent.
+
+### Example usage of the general-purpose agent:
+
+<example_agent_descriptions>
+"general-purpose": use this agent for general purpose tasks, it has access to all tools as the main agent.
+</example_agent_descriptions>
+
+<example>
+User: "I want to conduct research on the accomplishments of Lebron James, Michael Jordan, and Kobe Bryant, and then compare them."
+Assistant: *Uses the task tool in parallel to conduct isolated research on each of the three players*
+Assistant: *Synthesizes the results of the three isolated research tasks and responds to the User*
+<commentary>
+Research is a complex, multi-step task in it of itself.
+The research of each individual player is not dependent on the research of the other players.
+The assistant uses the task tool to break down the complex objective into three isolated tasks.
+Each research task only needs to worry about context and tokens about one player, then returns synthesized information about each player as the Tool Result.
+This means each research task can dive deep and spend tokens and context deeply researching each player, but the final result is synthesized information, and saves us tokens in the long run when comparing the players to each other.
+</commentary>
+</example>
+
+<example>
+User: "Analyze a single large code repository for security vulnerabilities and generate a report."
+Assistant: *Launches a single \`task\` subagent for the repository analysis*
+Assistant: *Receives report and integrates results into final summary*
+<commentary>
+Subagent is used to isolate a large, context-heavy task, even though there is only one. This prevents the main thread from being overloaded with details.
+If the user then asks followup questions, we have a concise report to reference instead of the entire history of analysis and tool calls, which is good and saves us time and money.
+</commentary>
+</example>
+  `.trim();
+}
+
+export const DEFAULT_GENERAL_PURPOSE_DESCRIPTION =
+  "General-purpose agent for researching complex questions, searching for files and content, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you. This agent has access to all tools as the main agent.";
+
+export const DEFAULT_SUBAGENT_PROMPT =
+  "In order to complete the objective that the user asks of you, you have access to a number of standard tools.";
+
+export const EXECUTE_SYSTEM_PROMPT = `## \`execute\` (shell command execution)
+
+You have access to an \`execute\` tool to run shell commands in the sandbox environment.
+
+### When to Use This Tool
+
+Use for:
+- Running build commands (npm install, npm run build, bun install)
+- Running tests (npm test, bun test, pytest)
+- Executing scripts (node script.js, python script.py)
+- Installing dependencies
+- Checking system state (ls, cat, pwd, which)
+- Any shell command that helps accomplish the task
+
+### Important Notes
+
+1. **Exit Codes**: Always check the exit code to determine success
+   - 0 = success
+   - non-zero = failure
+   - null = possibly timed out
+
+2. **Command Chaining**:
+   - Use \`&&\` to chain commands that depend on each other
+   - Use \`;\` to run commands sequentially regardless of success
+
+3. **Timeouts**: Long-running commands may timeout
+
+4. **Working Directory**: Commands run in the sandbox's working directory`;
+
+/**
+ * Build skills section for system prompt with progressive disclosure.
+ */
+export function buildSkillsPrompt(skills: Array<{ name: string; description: string; path: string }>): string {
+  if (skills.length === 0) {
+    return '';
+  }
+
+  const skillsList = skills
+    .map(skill => `- **${skill.name}**: ${skill.description}\n  → Read \`${skill.path}\` for full instructions`)
+    .join('\n');
+
+  return `## Skills System
+
+You have access to a skills library providing specialized domain knowledge and workflows.
+
+**Available Skills:**
+
+${skillsList}
+
+**How to Use Skills (Progressive Disclosure):**
+
+1. **Recognize when a skill applies**: Check if the user's task matches any skill's domain
+2. **Read the skill's full instructions**: Use read_file to load the SKILL.md content
+3. **Follow the skill's workflow**: Skills contain step-by-step instructions and examples
+4. **Access supporting files**: Skills may include helper scripts or configuration files in their directory
+
+Skills provide expert knowledge for specialized tasks. Always read the full skill before using it.`;
+}

package/src/skills/index.ts

@@ -0,0 +1,2 @@
+export { listSkills, parseSkillMetadata } from "./load";
+export type { SkillMetadata, SkillLoadOptions } from "./types";

package/src/skills/load.ts

@@ -0,0 +1,191 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import os from "node:os";
+import type { SkillMetadata, SkillLoadOptions } from "./types";
+import { findGitRoot } from "../utils/project-detection.js";
+
+/**
+ * Parse YAML frontmatter from a SKILL.md file.
+ *
+ * Expected format:
+ * ---
+ * name: skill-name
+ * description: What this skill does
+ * ---
+ *
+ * # Skill Content
+ * ...
+ */
+export async function parseSkillMetadata(
+  skillMdPath: string,
+  source: 'user' | 'project'
+): Promise<SkillMetadata | null> {
+  try {
+    const content = await fs.readFile(skillMdPath, 'utf-8');
+
+    // Match YAML frontmatter between --- delimiters
+    const frontmatterPattern = /^---\s*\n(.*?)\n---\s*\n/s;
+    const match = content.match(frontmatterPattern);
+
+    if (!match) {
+      console.warn(`[Skills] No frontmatter found in ${skillMdPath}`);
+      return null;
+    }
+
+    const frontmatter = match[1];
+    if (!frontmatter) {
+      console.warn(`[Skills] Empty frontmatter in ${skillMdPath}`);
+      return null;
+    }
+
+    // Parse key-value pairs from YAML (simple parsing, no full YAML parser needed)
+    const metadata: Record<string, string> = {};
+    for (const line of frontmatter.split('\n')) {
+      const kvMatch = line.match(/^(\w+):\s*(.+)$/);
+      if (kvMatch) {
+        const [, key, value] = kvMatch;
+        if (key && value) {
+          metadata[key] = value.trim();
+        }
+      }
+    }
+
+    // Validate required fields
+    if (!metadata.name || !metadata.description) {
+      console.warn(
+        `[Skills] Missing required fields (name, description) in ${skillMdPath}`
+      );
+      return null;
+    }
+
+    return {
+      name: metadata.name,
+      description: metadata.description,
+      path: skillMdPath,
+      source,
+    };
+  } catch (error) {
+    console.warn(`[Skills] Failed to parse ${skillMdPath}:`, error);
+    return null;
+  }
+}
+
+/**
+ * List all skills in a directory.
+ * Scans for subdirectories containing SKILL.md files.
+ */
+async function listSkillsInDirectory(
+  skillsDir: string,
+  source: 'user' | 'project'
+): Promise<SkillMetadata[]> {
+  try {
+    // Security: Resolve to prevent path traversal
+    const resolvedDir = path.resolve(skillsDir);
+
+    // Check if directory exists
+    try {
+      const stat = await fs.stat(resolvedDir);
+      if (!stat.isDirectory()) {
+        return [];
+      }
+    } catch {
+      return []; // Directory doesn't exist
+    }
+
+    const entries = await fs.readdir(resolvedDir, { withFileTypes: true });
+    const skills: SkillMetadata[] = [];
+
+    for (const entry of entries) {
+      // Skip non-directories and hidden directories
+      if (!entry.isDirectory() || entry.name.startsWith('.')) {
+        continue;
+      }
+
+      // Security: Skip symlinks to prevent traversal attacks
+      if (entry.isSymbolicLink()) {
+        console.warn(
+          `[Skills] Skipping symlink: ${path.join(resolvedDir, entry.name)}`
+        );
+        continue;
+      }
+
+      // Look for SKILL.md in subdirectory
+      const skillMdPath = path.join(resolvedDir, entry.name, 'SKILL.md');
+
+      try {
+        await fs.access(skillMdPath);
+        const metadata = await parseSkillMetadata(skillMdPath, source);
+        if (metadata) {
+          skills.push(metadata);
+        }
+      } catch {
+        // SKILL.md doesn't exist in this directory, skip
+        continue;
+      }
+    }
+
+    return skills;
+  } catch (error) {
+    console.warn(`[Skills] Failed to list skills in ${skillsDir}:`, error);
+    return [];
+  }
+}
+
+/**
+ * List all skills from user and project directories.
+ * Project skills override user skills with the same name.
+ *
+ * Supports two modes:
+ * 1. Legacy mode: Use userSkillsDir and projectSkillsDir directly (deprecated)
+ * 2. Agent mode: Use agentId to load from ~/.deepagents/{agentId}/skills/ and .deepagents/skills/
+ */
+export async function listSkills(
+  options: SkillLoadOptions
+): Promise<SkillMetadata[]> {
+  const { userSkillsDir, projectSkillsDir, agentId, workingDirectory } = options;
+  const skillsMap = new Map<string, SkillMetadata>();
+
+  // Determine directories based on mode
+  let resolvedUserSkillsDir = userSkillsDir;
+  let resolvedProjectSkillsDir = projectSkillsDir;
+
+  if (agentId) {
+    // Agent mode: Load from .deepagents/{agentId}/skills/
+    resolvedUserSkillsDir = path.join(os.homedir(), '.deepagents', agentId, 'skills');
+
+    // Detect project root and use .deepagents/skills/ (shared across agents)
+    const gitRoot = await findGitRoot(workingDirectory || process.cwd());
+    if (gitRoot) {
+      resolvedProjectSkillsDir = path.join(gitRoot, '.deepagents', 'skills');
+    }
+
+    // Show deprecation warning if old params are used alongside agentId
+    if (userSkillsDir || projectSkillsDir) {
+      console.warn(
+        '[Skills] agentId parameter takes precedence over userSkillsDir/projectSkillsDir. ' +
+        'The latter parameters are deprecated and will be ignored.'
+      );
+    }
+  } else if (!userSkillsDir && !projectSkillsDir) {
+    // No skills directories provided at all
+    return [];
+  }
+
+  // Load user skills first
+  if (resolvedUserSkillsDir) {
+    const userSkills = await listSkillsInDirectory(resolvedUserSkillsDir, 'user');
+    for (const skill of userSkills) {
+      skillsMap.set(skill.name, skill);
+    }
+  }
+
+  // Load project skills second (override user skills)
+  if (resolvedProjectSkillsDir) {
+    const projectSkills = await listSkillsInDirectory(resolvedProjectSkillsDir, 'project');
+    for (const skill of projectSkills) {
+      skillsMap.set(skill.name, skill); // Override user skill if exists
+    }
+  }
+
+  return Array.from(skillsMap.values());
+}

package/src/skills/types.ts

@@ -0,0 +1,53 @@
+/**
+ * Metadata extracted from SKILL.md frontmatter.
+ */
+export interface SkillMetadata {
+  /**
+   * Unique skill name (kebab-case, e.g., 'web-research')
+   */
+  name: string;
+
+  /**
+   * Short description of what the skill does
+   */
+  description: string;
+
+  /**
+   * Absolute path to the SKILL.md file
+   */
+  path: string;
+
+  /**
+   * Source of the skill ('user' or 'project')
+   * Project skills override user skills with same name
+   */
+  source: 'user' | 'project';
+}
+
+/**
+ * Options for skill loading
+ */
+export interface SkillLoadOptions {
+  /**
+   * User-level skills directory (e.g., ~/.deepagents/skills/)
+   */
+  userSkillsDir?: string;
+
+  /**
+   * Project-level skills directory (e.g., ./.deepagents/skills/)
+   */
+  projectSkillsDir?: string;
+
+  /**
+   * Optional agent ID for loading agent-specific skills.
+   * When provided, looks for skills in ~/.deepagents/{agentId}/skills/
+   * and .deepagents/skills/ (project-level, shared across agents).
+   */
+  agentId?: string;
+
+  /**
+   * Optional working directory for detecting project root.
+   * Only used when agentId is provided.
+   */
+  workingDirectory?: string;
+}

package/src/tools/execute.ts

@@ -0,0 +1,167 @@
+/**
+ * Execute tool for running shell commands in sandbox backends.
+ *
+ * This tool is only available when the backend implements SandboxBackendProtocol.
+ */
+
+import { tool } from "ai";
+import { z } from "zod";
+import type { SandboxBackendProtocol, EventCallback } from "../types";
+
+/**
+ * Tool description for the execute tool.
+ */
+const EXECUTE_TOOL_DESCRIPTION = `Execute a shell command in the sandbox environment.
+
+Use this tool to:
+- Run build commands (npm install, npm run build, bun install)
+- Run tests (npm test, bun test, pytest)
+- Execute scripts (node script.js, python script.py)
+- Check system state (ls, cat, pwd, which)
+- Install dependencies
+- Run any shell command
+
+The command runs in the sandbox's working directory. Commands have a timeout limit.
+
+IMPORTANT:
+- Always check the exit code to determine success (0 = success)
+- Long-running commands may timeout
+- Use && to chain commands that depend on each other
+- Use ; to run commands sequentially regardless of success`;
+
+/**
+ * Options for creating the execute tool.
+ */
+export interface CreateExecuteToolOptions {
+  /** The sandbox backend to execute commands in */
+  backend: SandboxBackendProtocol;
+  /** Optional callback for emitting events */
+  onEvent?: EventCallback;
+  /** Optional custom description for the tool */
+  description?: string;
+}
+
+/**
+ * Create an execute tool for running shell commands.
+ *
+ * @param options - Options including the sandbox backend and optional event callback
+ * @returns An AI SDK tool that executes shell commands
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { LocalSandbox, createExecuteTool } from 'deepagentsdk';
+ *
+ * const sandbox = new LocalSandbox({ cwd: './workspace' });
+ * const executeTool = createExecuteTool({ backend: sandbox });
+ *
+ * // Use with agent
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   backend: sandbox,
+ *   tools: { execute: executeTool },
+ * });
+ * ```
+ *
+ * @example With event streaming
+ * ```typescript
+ * const executeTool = createExecuteTool({
+ *   backend: sandbox,
+ *   onEvent: (event) => {
+ *     if (event.type === 'execute-start') {
+ *       console.log(`Running: ${event.command}`);
+ *     } else if (event.type === 'execute-finish') {
+ *       console.log(`Exit code: ${event.exitCode}`);
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export function createExecuteTool(options: CreateExecuteToolOptions) {
+  const { backend, onEvent, description } = options;
+
+  return tool({
+    description: description || EXECUTE_TOOL_DESCRIPTION,
+    inputSchema: z.object({
+      command: z
+        .string()
+        .describe("The shell command to execute (e.g., 'npm install', 'ls -la', 'cat file.txt')"),
+    }),
+    execute: async ({ command }) => {
+      // Emit execute-start event
+      if (onEvent) {
+        onEvent({
+          type: "execute-start",
+          command,
+          sandboxId: backend.id,
+        });
+      }
+
+      // Execute the command
+      const result = await backend.execute(command);
+
+      // Emit execute-finish event
+      if (onEvent) {
+        onEvent({
+          type: "execute-finish",
+          command,
+          exitCode: result.exitCode,
+          truncated: result.truncated,
+          sandboxId: backend.id,
+        });
+      }
+
+      // Format the response
+      const parts: string[] = [];
+
+      if (result.output) {
+        parts.push(result.output);
+      }
+
+      // Add exit code information
+      if (result.exitCode === 0) {
+        parts.push(`\n[Exit code: 0 (success)]`);
+      } else if (result.exitCode !== null) {
+        parts.push(`\n[Exit code: ${result.exitCode} (failure)]`);
+      } else {
+        parts.push(`\n[Exit code: unknown (possibly timed out)]`);
+      }
+
+      // Note if output was truncated
+      if (result.truncated) {
+        parts.push(`[Output truncated due to size limit]`);
+      }
+
+      return parts.join("");
+    },
+  });
+}
+
+/**
+ * Convenience function to create execute tool from just a backend.
+ * Useful for simple cases without event handling.
+ *
+ * @param backend - The sandbox backend
+ * @returns An AI SDK tool that executes shell commands
+ *
+ * @example
+ * ```typescript
+ * const sandbox = new LocalSandbox({ cwd: './workspace' });
+ * const tools = {
+ *   execute: createExecuteToolFromBackend(sandbox),
+ * };
+ * ```
+ */
+export function createExecuteToolFromBackend(backend: SandboxBackendProtocol) {
+  return createExecuteTool({ backend });
+}
+
+// ============================================================================
+// Individual Tool Reference
+// ============================================================================
+
+/**
+ * Individual builtin tool reference for selective subagent configuration.
+ * This is a reference to the creator function, not an instance.
+ */
+export const execute = createExecuteTool;
+