hoomanjs 1.14.0 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hoomanjs",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Hackable Bun-powered AI agent toolkit for building local CLI, ACP, MCP, and channel-driven workflows.",
   "author": {
     "name": "Vaibhav Pandey",

package/src/acp/utils/tool-kind.ts

@@ -14,6 +14,7 @@ const KNOWN_TOOL_KINDS = new Map<string, ToolKind>([
   ["search_files", "search"],
   ["get_file_info", "read"],
   ["shell", "execute"],
+  ["sleep", "other"],
   ["fetch", "fetch"],
   ["wiki_list_files", "read"],
   ["wiki_read_file", "read"],
@@ -22,9 +23,23 @@ const KNOWN_TOOL_KINDS = new Map<string, ToolKind>([
   ["wiki_stats", "read"],
   ["wiki_search", "search"],
   ["think", "think"],
+  ["run_agents", "other"],
   ["update_todos", "other"],
   ["get_current_time", "other"],
   ["convert_time", "other"],
+  ["list_skills", "read"],
+  ["search_skills", "search"],
+  ["install_skill", "edit"],
+  ["delete_skill", "edit"],
+  ["store_memory", "edit"],
+  ["search_memory", "search"],
+  ["update_memory", "edit"],
+  ["archive_memory", "edit"],
+  ["list_mcp_servers", "read"],
+  ["get_mcp_server", "read"],
+  ["add_mcp_server", "edit"],
+  ["update_mcp_server", "edit"],
+  ["delete_mcp_server", "edit"],
 ]);
 
 export { INTERNAL_ALWAYS_ALLOWED };

package/src/configure/app.tsx

@@ -499,6 +499,23 @@ export function ConfigureApp({
           setScreen({ kind: "config" });
         },
       },
+      {
+        label: `Sleep tool • ${configData.tools.sleep.enabled ? "Enabled" : "Disabled"}`,
+        value: () => {
+          updateConfig(
+            {
+              tools: {
+                ...config.tools,
+                sleep: {
+                  enabled: !configData.tools.sleep.enabled,
+                },
+              },
+            },
+            `Sleep tool ${configData.tools.sleep.enabled ? "disabled" : "enabled"}.`,
+          );
+          setScreen({ kind: "config" });
+        },
+      },
       {
         label: `Long-term memory • ${configData.tools.ltm.enabled ? "Enabled" : "Disabled"} • ${configData.tools.ltm.chroma.collection.memory}`,
         value: () => setScreen({ kind: "config-ltm" }),

package/src/core/agent/index.ts

@@ -1,4 +1,5 @@
 import { Agent, BeforeInvocationEvent } from "@strands-agents/sdk";
+import type { Tool } from "@strands-agents/sdk";
 import type { Config } from "../config.ts";
 import { modelProviders } from "../models";
 import {
@@ -14,10 +15,15 @@ import {
   createLongTermMemoryTools,
 } from "../memory";
 import { createSkillsTools, type Registry } from "../skills";
+import {
+  createRunAgentsTools,
+  loadBuiltInAgentDefinitions,
+} from "../agents/index.ts";
 import {
   createTodoTools,
   createFetchTools,
   createFilesystemTools,
+  createSleepTools,
   createShellTools,
   createThinkingTools,
   createTimeTools,
@@ -49,7 +55,7 @@ export async function create(
   const skills = config.tools.skills.enabled
     ? (await createSkillsPrompt(registry)).content
     : "";
-  const tools = config.tools.mcp.enabled
+  const prefixed = config.tools.mcp.enabled
     ? await mcp.manager.listPrefixedTools()
     : [];
   const append = config.tools.mcp.enabled
@@ -58,27 +64,44 @@ export async function create(
   const prompt = [system.content, meta.systemPrompt, ...append, skills]
     .filter((x) => !!x)
     .join(SECTION_BREAK);
+  const model = llm.create(config.llm.model, config.llm.params);
+  const tools: Tool[] = [
+    ...createTimeTools(),
+    ...(config.tools.sleep.enabled ? createSleepTools() : []),
+    ...(config.tools.todo.enabled ? createTodoTools() : []),
+    ...(config.tools.fetch.enabled ? createFetchTools() : []),
+    ...(ltm ? createLongTermMemoryTools(ltm) : []),
+    ...(config.tools.filesystem.enabled ? createFilesystemTools() : []),
+    ...(config.tools.shell.enabled ? createShellTools() : []),
+    ...(config.tools.wiki.enabled ? createWikiTools(config) : []),
+    ...(config.tools.mcp.enabled ? createMcpTools(mcp.config) : []),
+    ...(config.tools.skills.enabled ? createSkillsTools(registry) : []),
+    ...createThinkingTools(),
+    ...prefixed,
+  ];
+  if (config.tools.agents.enabled) {
+    const definitions = loadBuiltInAgentDefinitions(config, {
+      knownTools: tools.map((entry) => entry.name),
+    });
+    tools.push(
+      ...createRunAgentsTools({
+        parent: config.name,
+        definitions,
+        tools,
+        createModel: () => llm.create(config.llm.model, config.llm.params),
+        defaultConcurrency: config.tools.agents.concurrency,
+      }),
+    );
+  }
   const agent = new Agent({
     name: config.name,
     systemPrompt: prompt,
-    model: llm.create(config.llm.model, config.llm.params),
+    model,
     appState: {
       ...(userId ? { userId } : {}),
       ...(sessionId ? { sessionId } : {}),
     },
-    tools: [
-      ...createTimeTools(),
-      ...(config.tools.todo.enabled ? createTodoTools() : []),
-      ...(config.tools.fetch.enabled ? createFetchTools() : []),
-      ...(ltm ? createLongTermMemoryTools(ltm) : []),
-      ...(config.tools.filesystem.enabled ? createFilesystemTools() : []),
-      ...(config.tools.shell.enabled ? createShellTools() : []),
-      ...(config.tools.wiki.enabled ? createWikiTools(config) : []),
-      ...(config.tools.mcp.enabled ? createMcpTools(mcp.config) : []),
-      ...(config.tools.skills.enabled ? createSkillsTools(registry) : []),
-      ...createThinkingTools(),
-      ...tools,
-    ],
+    tools,
     printer: print,
     ...stm,
   });

package/src/core/agents/definitions.ts

@@ -0,0 +1,47 @@
+export const BUILTIN_AGENT_KINDS = ["research", "plan"] as const;
+
+export type AgentKind = (typeof BUILTIN_AGENT_KINDS)[number];
+
+export type AgentConfig = {
+  id: AgentKind;
+  instructions: string;
+  description: string;
+  tools: readonly string[];
+};
+
+export type AgentDefinition = AgentConfig & {
+  instructionsText: string;
+};
+
+export const BUILTIN_AGENT_CONFIGS: readonly AgentConfig[] = [
+  {
+    id: "research",
+    instructions: "research.md",
+    description: "Investigates code, docs, and context before implementation.",
+    tools: [
+      "read_file",
+      "read_multiple_files",
+      "list_directory",
+      "directory_tree",
+      "search_files",
+      "get_file_info",
+      "fetch",
+      "think",
+    ],
+  },
+  {
+    id: "plan",
+    instructions: "plan.md",
+    description:
+      "Produces implementation plans, tradeoffs, risks, and validation steps.",
+    tools: [
+      "read_file",
+      "read_multiple_files",
+      "list_directory",
+      "directory_tree",
+      "search_files",
+      "get_file_info",
+      "think",
+    ],
+  },
+];

package/src/core/agents/index.ts

@@ -0,0 +1,15 @@
+export {
+  BUILTIN_AGENT_CONFIGS,
+  BUILTIN_AGENT_KINDS,
+  type AgentConfig,
+  type AgentDefinition,
+  type AgentKind,
+} from "./definitions.ts";
+export { loadBuiltInAgentDefinitions } from "./registry.ts";
+export {
+  runAgentJobs,
+  type AgentJob,
+  type AgentJobResult,
+  type RunAgentJobsResult,
+} from "./runner.ts";
+export { RUN_AGENTS_TOOL_NAME, createRunAgentsTools } from "./tools.ts";

package/src/core/agents/registry.ts

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { compile } from "handlebars";
+import type { Config } from "../config.ts";
+import { getEnvironmentPromptContext } from "../prompts/environment.ts";
+import {
+  BUILTIN_AGENT_CONFIGS,
+  type AgentConfig,
+  type AgentDefinition,
+} from "./definitions.ts";
+
+function promptsDir(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), "../prompts/agents");
+}
+
+function validateConfigs(configs: readonly AgentConfig[]): void {
+  const seen = new Set<string>();
+  for (const config of configs) {
+    if (!config.id.trim()) {
+      throw new Error("Agent config id cannot be empty.");
+    }
+    if (seen.has(config.id)) {
+      throw new Error(`Duplicate agent config id: '${config.id}'.`);
+    }
+    seen.add(config.id);
+    if (!config.instructions.trim()) {
+      throw new Error(
+        `Agent '${config.id}' instructions file cannot be empty.`,
+      );
+    }
+    if (!config.description.trim()) {
+      throw new Error(`Agent '${config.id}' description cannot be empty.`);
+    }
+    if (!Array.isArray(config.tools) || config.tools.length === 0) {
+      throw new Error(`Agent '${config.id}' must declare at least one tool.`);
+    }
+    for (const toolName of config.tools) {
+      if (!toolName.trim()) {
+        throw new Error(`Agent '${config.id}' has an empty tool name.`);
+      }
+    }
+  }
+}
+
+function assertKnownTools(
+  definitions: readonly AgentDefinition[],
+  knownTools: readonly string[],
+): void {
+  const known = new Set(knownTools);
+  for (const definition of definitions) {
+    for (const toolName of definition.tools) {
+      if (!known.has(toolName)) {
+        throw new Error(
+          `Agent '${definition.id}' references unknown tool '${toolName}'.`,
+        );
+      }
+    }
+  }
+}
+
+function context(config: Config): Record<string, unknown> {
+  return {
+    name: config.name,
+    llm: config.llm,
+    environment: getEnvironmentPromptContext(),
+    ltm: config.tools.ltm,
+    wiki: config.tools.wiki,
+    compaction: config.compaction,
+  };
+}
+
+export function loadBuiltInAgentDefinitions(
+  config: Config,
+  options?: { knownTools?: readonly string[] },
+): AgentDefinition[] {
+  validateConfigs(BUILTIN_AGENT_CONFIGS);
+  const dir = promptsDir();
+  const definitions = BUILTIN_AGENT_CONFIGS.map((entry) => {
+    const fullPath = join(dir, entry.instructions);
+    if (!existsSync(fullPath)) {
+      throw new Error(
+        `Agent '${entry.id}' instructions file not found: ${entry.instructions}`,
+      );
+    }
+    const raw = readFileSync(fullPath, "utf8").trim();
+    if (!raw) {
+      throw new Error(
+        `Agent '${entry.id}' instructions file is empty: ${entry.instructions}`,
+      );
+    }
+    const template = compile(raw);
+    const instructionsText = template(context(config)).trim();
+    if (!instructionsText) {
+      throw new Error(
+        `Agent '${entry.id}' instructions rendered to empty content.`,
+      );
+    }
+    return {
+      ...entry,
+      instructionsText,
+    };
+  });
+  if (options?.knownTools) {
+    assertKnownTools(definitions, options.knownTools);
+  }
+  return definitions;
+}

package/src/core/agents/runner.ts

@@ -0,0 +1,375 @@
+import { Agent, TextBlock } from "@strands-agents/sdk";
+import { Graph, Node, Status } from "@strands-agents/sdk/multiagent";
+import type {
+  BaseModelConfig,
+  Model,
+  Tool,
+  ContentBlock,
+} from "@strands-agents/sdk";
+import type {
+  MultiAgentInput,
+  MultiAgentState,
+  MultiAgentStreamEvent,
+  NodeInputOptions,
+  NodeResultUpdate,
+} from "@strands-agents/sdk/multiagent";
+import type { AgentDefinition, AgentKind } from "./definitions.ts";
+
+export type AgentJob = {
+  id: string;
+  kind: AgentKind;
+  description: string;
+  prompt: string;
+};
+
+export type AgentJobResult = {
+  id: string;
+  kind: AgentKind;
+  description: string;
+  status: "completed" | "failed";
+  content: string;
+  durationMs: number;
+  error: string | null;
+  stopReason: string | null;
+};
+
+export type RunAgentJobsResult = {
+  results: AgentJobResult[];
+};
+
+type RunAgentJobsOptions = {
+  jobs: readonly AgentJob[];
+  definitions: readonly AgentDefinition[];
+  tools: readonly Tool[];
+  createModel: () => Model<BaseModelConfig>;
+  concurrency: number;
+  parent: string;
+  appState: {
+    userId?: string;
+    sessionId?: string;
+  };
+  cancelSignal?: AbortSignal;
+};
+
+class JobNode extends Node {
+  override readonly type = "agentJobNode";
+  private readonly execute: () => Promise<AgentJobResult>;
+  private readonly cancelSignal?: AbortSignal;
+
+  constructor(
+    id: string,
+    execute: () => Promise<AgentJobResult>,
+    description: string,
+    cancelSignal?: AbortSignal,
+  ) {
+    super(id, { description });
+    this.execute = execute;
+    this.cancelSignal = cancelSignal;
+  }
+
+  override async *handle(
+    _input: MultiAgentInput,
+    _state: MultiAgentState,
+    _options?: NodeInputOptions,
+  ): AsyncGenerator<MultiAgentStreamEvent, NodeResultUpdate, undefined> {
+    if (this.cancelSignal?.aborted) {
+      return {
+        status: Status.CANCELLED,
+        content: [new TextBlock("Cancelled before job execution.")],
+        error: new Error("Cancelled before job execution."),
+      };
+    }
+    const result = await this.execute();
+    if (result.status === "completed") {
+      const content = result.content.trim()
+        ? [new TextBlock(result.content.trim())]
+        : [];
+      return {
+        status: Status.COMPLETED,
+        content,
+      };
+    }
+    return {
+      status:
+        result.stopReason === "cancelled" ? Status.CANCELLED : Status.FAILED,
+      content: result.error ? [new TextBlock(result.error)] : [],
+      error: result.error ? new Error(result.error) : undefined,
+    };
+  }
+}
+
+function buildJobPrompt(job: AgentJob): string {
+  return `Task: ${job.description}\n\nUser request:\n${job.prompt}`;
+}
+
+function selectTools(
+  definition: AgentDefinition,
+  tools: readonly Tool[],
+): Tool[] {
+  const byName = new Map<string, Tool>();
+  for (const tool of tools) {
+    byName.set(tool.name, tool);
+  }
+  const selected: Tool[] = [];
+  for (const name of definition.tools) {
+    const tool = byName.get(name);
+    if (!tool) {
+      throw new Error(
+        `Agent '${definition.id}' cannot access missing tool '${name}'.`,
+      );
+    }
+    selected.push(tool);
+  }
+  return selected;
+}
+
+async function runSingleJob(
+  job: AgentJob,
+  definition: AgentDefinition,
+  options: Omit<RunAgentJobsOptions, "jobs" | "definitions" | "concurrency">,
+): Promise<AgentJobResult> {
+  const started = Date.now();
+  if (options.cancelSignal?.aborted) {
+    return {
+      id: job.id,
+      kind: job.kind,
+      description: job.description,
+      status: "failed",
+      content: "",
+      durationMs: 0,
+      error: "Cancelled before execution.",
+      stopReason: "cancelled",
+    };
+  }
+  try {
+    const child = new Agent({
+      name: `${options.parent}-${definition.id}-${job.id}`,
+      systemPrompt: definition.instructionsText,
+      model: options.createModel(),
+      appState: {
+        ...(options.appState.userId ? { userId: options.appState.userId } : {}),
+        ...(options.appState.sessionId
+          ? { sessionId: options.appState.sessionId }
+          : {}),
+        agentKind: definition.id,
+      },
+      tools: selectTools(definition, options.tools),
+      printer: false,
+    });
+    const result = await child.invoke(buildJobPrompt(job), {
+      ...(options.cancelSignal ? { cancelSignal: options.cancelSignal } : {}),
+    });
+    return {
+      id: job.id,
+      kind: job.kind,
+      description: job.description,
+      status: result.stopReason === "cancelled" ? "failed" : "completed",
+      content: result.toString().trim(),
+      durationMs: Date.now() - started,
+      error: result.stopReason === "cancelled" ? "Cancelled." : null,
+      stopReason: result.stopReason,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const cancelled = options.cancelSignal?.aborted ?? false;
+    return {
+      id: job.id,
+      kind: job.kind,
+      description: job.description,
+      status: "failed",
+      content: "",
+      durationMs: Date.now() - started,
+      error: message,
+      stopReason: cancelled ? "cancelled" : null,
+    };
+  }
+}
+
+function contentToText(content: readonly ContentBlock[]): string {
+  return content
+    .map((block) => {
+      if ("text" in block && typeof block.text === "string") {
+        return block.text;
+      }
+      return "";
+    })
+    .filter(Boolean)
+    .join("\n")
+    .trim();
+}
+
+function cancelledResult(job: AgentJob, message: string): AgentJobResult {
+  return {
+    id: job.id,
+    kind: job.kind,
+    description: job.description,
+    status: "failed",
+    content: "",
+    durationMs: 0,
+    error: message,
+    stopReason: "cancelled",
+  };
+}
+
+export async function runAgentJobs(
+  options: RunAgentJobsOptions,
+): Promise<RunAgentJobsResult> {
+  if (options.jobs.length === 0) {
+    return { results: [] };
+  }
+  if (options.cancelSignal?.aborted) {
+    return {
+      results: options.jobs.map((job) => ({
+        id: job.id,
+        kind: job.kind,
+        description: job.description,
+        status: "failed",
+        content: "",
+        durationMs: 0,
+        error: "Cancelled before execution.",
+        stopReason: "cancelled",
+      })),
+    };
+  }
+  const defsByKind = new Map<AgentKind, AgentDefinition>(
+    options.definitions.map((entry) => [entry.id, entry]),
+  );
+  const ordered = [...options.jobs];
+  const results: Array<AgentJobResult | null> = ordered.map(() => null);
+  const graphNodes: JobNode[] = [];
+  const graphSources: string[] = [];
+  const nodeToIndex = new Map<string, number>();
+  const graphNodeResults = new Map<string, AgentJobResult>();
+
+  for (const [index, job] of ordered.entries()) {
+    const definition = defsByKind.get(job.kind);
+    if (!definition) {
+      results[index] = {
+        id: job.id,
+        kind: job.kind,
+        description: job.description,
+        status: "failed",
+        content: "",
+        durationMs: 0,
+        error: `Unknown agent kind '${job.kind}'.`,
+        stopReason: null,
+      };
+      continue;
+    }
+    const nodeId = `${job.id}__${index + 1}`;
+    nodeToIndex.set(nodeId, index);
+    graphSources.push(nodeId);
+    graphNodes.push(
+      new JobNode(
+        nodeId,
+        async () => {
+          const jobResult = await runSingleJob(job, definition, {
+            tools: options.tools,
+            createModel: options.createModel,
+            parent: options.parent,
+            appState: options.appState,
+            cancelSignal: options.cancelSignal,
+          });
+          graphNodeResults.set(nodeId, jobResult);
+          return jobResult;
+        },
+        `${job.kind} :: ${job.description}`,
+        options.cancelSignal,
+      ),
+    );
+  }
+
+  if (graphNodes.length > 0) {
+    try {
+      const graph = new Graph({
+        id: "run_agents_graph",
+        nodes: graphNodes,
+        edges: [],
+        sources: graphSources,
+        maxConcurrency: Math.max(
+          1,
+          Math.min(options.concurrency, graphNodes.length),
+        ),
+      });
+      const graphRun = graph.invoke("run jobs");
+      const graphResult = options.cancelSignal
+        ? await Promise.race([
+            graphRun,
+            new Promise<null>((resolve) => {
+              const onAbort = () => resolve(null);
+              options.cancelSignal?.addEventListener("abort", onAbort, {
+                once: true,
+              });
+            }),
+          ])
+        : await graphRun;
+      if (graphResult === null) {
+        for (const [nodeId, index] of nodeToIndex.entries()) {
+          if (results[index]) {
+            continue;
+          }
+          const recorded = graphNodeResults.get(nodeId);
+          results[index] =
+            recorded ?? cancelledResult(ordered[index]!, "Cancelled.");
+        }
+        return {
+          results: results.filter(
+            (entry): entry is AgentJobResult => entry !== null,
+          ),
+        };
+      }
+      const nodeResultsById = new Map(
+        graphResult.results.map((entry) => [entry.nodeId, entry] as const),
+      );
+      for (const [nodeId, index] of nodeToIndex.entries()) {
+        const recorded = graphNodeResults.get(nodeId);
+        if (recorded) {
+          results[index] = recorded;
+          continue;
+        }
+        const nodeResult = nodeResultsById.get(nodeId);
+        const job = ordered[index]!;
+        const cancelled = options.cancelSignal?.aborted ?? false;
+        results[index] = {
+          id: job.id,
+          kind: job.kind,
+          description: job.description,
+          status:
+            nodeResult?.status === Status.COMPLETED ? "completed" : "failed",
+          content: nodeResult ? contentToText(nodeResult.content) : "",
+          durationMs: nodeResult?.duration ?? 0,
+          error:
+            nodeResult?.error?.message ??
+            "Job did not produce a result from Graph execution.",
+          stopReason:
+            nodeResult?.status === Status.CANCELLED || cancelled
+              ? "cancelled"
+              : null,
+        };
+      }
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : "Graph execution failed.";
+      for (const [nodeId, index] of nodeToIndex.entries()) {
+        if (results[index]) {
+          continue;
+        }
+        const job = ordered[index]!;
+        results[index] = {
+          id: job.id,
+          kind: job.kind,
+          description: job.description,
+          status: "failed",
+          content: "",
+          durationMs: 0,
+          error: message,
+          stopReason: options.cancelSignal?.aborted ? "cancelled" : null,
+        };
+      }
+    }
+  }
+
+  return {
+    results: results.filter((entry): entry is AgentJobResult => entry !== null),
+  };
+}

package/src/core/agents/tools.ts

@@ -0,0 +1,100 @@
+import {
+  tool,
+  type JSONValue,
+  type Tool,
+  type ToolContext,
+} from "@strands-agents/sdk";
+import type { BaseModelConfig, Model } from "@strands-agents/sdk";
+import { z } from "zod";
+import { BUILTIN_AGENT_KINDS, type AgentDefinition } from "./definitions.ts";
+import { runAgentJobs } from "./runner.ts";
+
+export const RUN_AGENTS_TOOL_NAME = "run_agents";
+
+const JobSchema = z.object({
+  kind: z.enum(BUILTIN_AGENT_KINDS),
+  description: z.string().trim().min(1),
+  prompt: z.string().trim().min(1),
+});
+
+const RunAgentsInputSchema = z.object({
+  jobs: z.array(JobSchema).min(1),
+  maxConcurrency: z.coerce.number().int().min(1).optional(),
+});
+
+type RunAgentsToolOptions = {
+  parent: string;
+  definitions: readonly AgentDefinition[];
+  tools: readonly Tool[];
+  createModel: () => Model<BaseModelConfig>;
+  defaultConcurrency: number;
+};
+
+function toJsonValue(value: unknown): JSONValue {
+  return JSON.parse(JSON.stringify(value)) as JSONValue;
+}
+
+function readAppStateString(
+  context: ToolContext,
+  key: "userId" | "sessionId",
+): string | undefined {
+  const value = context.agent.appState.get(key);
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+export function createRunAgentsTools(options: RunAgentsToolOptions) {
+  const kinds = options.definitions.map(
+    (entry) => `- ${entry.id}: ${entry.description}`,
+  );
+  const baseTools = options.tools.filter(
+    (entry) => entry.name !== RUN_AGENTS_TOOL_NAME,
+  );
+  return [
+    tool({
+      name: RUN_AGENTS_TOOL_NAME,
+      description: `Run one or more specialized child agents in parallel and return their outputs.
+Use this for deeper research or planning work that can be split into independent jobs.
+Available agent kinds:
+${kinds.join("\n")}`,
+      inputSchema: RunAgentsInputSchema,
+      callback: async (input, context?: ToolContext) => {
+        if (!context) {
+          throw new Error(
+            `${RUN_AGENTS_TOOL_NAME} requires execution context.`,
+          );
+        }
+        const concurrency = Math.max(
+          1,
+          Math.min(
+            input.maxConcurrency ?? options.defaultConcurrency,
+            input.jobs.length,
+          ),
+        );
+        const jobs = input.jobs.map((job, index) => ({
+          id: `job-${index + 1}`,
+          kind: job.kind,
+          description: job.description,
+          prompt: job.prompt,
+        }));
+        const result = await runAgentJobs({
+          jobs,
+          definitions: options.definitions,
+          tools: baseTools,
+          createModel: options.createModel,
+          concurrency,
+          parent: options.parent,
+          appState: {
+            userId: readAppStateString(context, "userId"),
+            sessionId: readAppStateString(context, "sessionId"),
+          },
+          cancelSignal: context.agent.cancelSignal,
+        });
+        return toJsonValue({
+          requestedJobs: jobs.length,
+          concurrency,
+          ...result,
+        });
+      },
+    }),
+  ];
+}

package/src/core/approvals/allowed-tools.ts

@@ -10,17 +10,42 @@ type AgentLike = {
 const SESSION_ALLOWED_TOOLS_KEY = "allowedTools";
 
 export const INTERNAL_ALWAYS_ALLOWED = new Set([
+  // Strands / runtime
   "strands_structured_output",
+  // Todos
   "update_todos",
+  // Thinking
   "think",
-  "get_current_time",
+  // Agent orchestration
+  "run_agents",
+  // Sleep
+  "sleep",
+  // Time
   "convert_time",
+  "get_current_time",
+  // Wiki
+  "wiki_knowledge_graph",
   "wiki_list_files",
   "wiki_read_file",
-  "wiki_write_file",
-  "wiki_knowledge_graph",
-  "wiki_stats",
   "wiki_search",
+  "wiki_stats",
+  "wiki_write_file",
+  // Long-term memory
+  "archive_memory",
+  "search_memory",
+  "store_memory",
+  "update_memory",
+  // Skills
+  "list_skills",
+  "search_skills",
+  // MCP config
+  "get_mcp_server",
+  "list_mcp_servers",
+  // Filesystem (list / search / metadata)
+  "directory_tree",
+  "get_file_info",
+  "list_directory",
+  "search_files",
 ]);
 
 function normalizeAllowedTools(value: unknown): string[] {

package/src/core/config.ts

@@ -71,15 +71,22 @@ const ToolTogglePartialSchema = z.object({
   enabled: z.boolean().optional(),
 });
 
+const AgentsPartialSchema = z.object({
+  enabled: z.boolean().optional(),
+  concurrency: z.number().int().min(1).optional(),
+});
+
 const ToolsPartialSchema = z.object({
   todo: ToolTogglePartialSchema.optional(),
   fetch: ToolTogglePartialSchema.optional(),
   filesystem: ToolTogglePartialSchema.optional(),
   shell: ToolTogglePartialSchema.optional(),
+  sleep: ToolTogglePartialSchema.optional(),
   ltm: LtmPartialSchema.optional(),
   wiki: WikiPartialSchema.optional(),
   mcp: ToolTogglePartialSchema.optional(),
   skills: ToolTogglePartialSchema.optional(),
+  agents: AgentsPartialSchema.optional(),
 });
 
 const ConfigSchema = z
@@ -111,6 +118,9 @@ const ConfigSchema = z
         shell: {
           enabled: input.tools?.shell?.enabled ?? true,
         },
+        sleep: {
+          enabled: input.tools?.sleep?.enabled ?? true,
+        },
         ltm: {
           enabled: ltm?.enabled ?? false,
           chroma: {
@@ -139,6 +149,10 @@ const ConfigSchema = z
         skills: {
           enabled: input.tools?.skills?.enabled ?? false,
         },
+        agents: {
+          enabled: input.tools?.agents?.enabled ?? true,
+          concurrency: input.tools?.agents?.concurrency ?? 3,
+        },
       },
       compaction: input.compaction,
     };
@@ -171,6 +185,9 @@ const defaultConfigData = (): ConfigData => ({
     shell: {
       enabled: true,
     },
+    sleep: {
+      enabled: true,
+    },
     ltm: {
       enabled: false,
       chroma: {
@@ -191,6 +208,10 @@ const defaultConfigData = (): ConfigData => ({
     skills: {
       enabled: false,
     },
+    agents: {
+      enabled: true,
+      concurrency: 2,
+    },
   },
   compaction: {
     ratio: 0.75,
@@ -222,6 +243,7 @@ export class Config {
       fetch: { ...this.data.tools.fetch },
       filesystem: { ...this.data.tools.filesystem },
       shell: { ...this.data.tools.shell },
+      sleep: { ...this.data.tools.sleep },
       ltm: {
         ...this.data.tools.ltm,
         chroma: {
@@ -238,6 +260,7 @@ export class Config {
       },
       mcp: { ...this.data.tools.mcp },
       skills: { ...this.data.tools.skills },
+      agents: { ...this.data.tools.agents },
     };
   }
 

package/src/core/prompts/agents/plan.md

@@ -0,0 +1,35 @@
+## Plan Agent
+
+You are a specialized planning sub-agent for {{ name }}.
+
+Your job is to design a practical, low-risk implementation plan that the parent agent can execute.
+
+This is a strict read-only role:
+
+- Do not create, edit, move, or delete files.
+- Do not run commands that change system state.
+- Do not write final implementation code; focus on strategy.
+
+Planning process:
+
+1. Clarify the objective and constraints from the task.
+2. Inspect existing architecture and patterns before proposing changes.
+3. Choose an approach that fits current code conventions and minimizes regressions.
+4. Break work into ordered, reviewable steps.
+5. Identify dependencies, migration concerns, and rollback or fallback considerations.
+
+What good plans include:
+
+- Why this approach is preferred over obvious alternatives.
+- Exact files/modules likely to change.
+- Key data flow, API, or interface impacts.
+- Edge cases, failure modes, and compatibility concerns.
+- A concrete verification plan (tests, manual checks, and expected outcomes).
+
+Return format:
+
+1. **Proposed Approach** - concise rationale and trade-offs.
+2. **Implementation Steps** - numbered sequence, each step actionable.
+3. **Critical Files / Areas** - paths and why they matter.
+4. **Risks and Mitigations** - specific, not generic.
+5. **Validation Plan** - how the parent agent should confirm correctness.

package/src/core/prompts/agents/research.md

@@ -0,0 +1,32 @@
+## Research Agent
+
+You are a specialized research sub-agent for {{ name }}.
+
+Your job is to investigate the task, gather high-signal evidence, and return findings that help the parent agent decide what to do next.
+
+This is a strict read-only role:
+
+- Do not create, edit, move, or delete files.
+- Do not run commands that change system state.
+- Do not propose speculative conclusions as facts.
+
+How to work:
+
+1. Understand the exact question and identify what evidence is required.
+2. Explore efficiently: start broad, then narrow to the most relevant files/symbols.
+3. Prefer concrete code evidence over assumptions.
+4. Surface contradictions, unknowns, and risks early.
+5. Stop exploring once confidence is high enough to answer the question.
+
+Quality bar:
+
+- Be precise, not verbose.
+- Include file paths, symbol names, and behavior-level findings.
+- Differentiate between "confirmed", "likely", and "unknown".
+- If information is missing, state what additional check would resolve it.
+
+Return format:
+
+1. **Findings** - short bullets with evidence.
+2. **Open Questions / Uncertainties** - only if relevant.
+3. **Recommended Next Step for Parent Agent** - one concise action.

package/src/core/prompts/environment.ts

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+  release as osRelease,
+  type as osType,
+  version as osVersion,
+} from "node:os";
+
+type EnvironmentPromptContext = {
+  cwd: string;
+  platform: string;
+  osVersion: string;
+  shell: string;
+  isGitRepo: boolean;
+};
+
+function detectPlatform(): string {
+  return ["darwin", "linux", "win32"].includes(process.platform)
+    ? process.platform
+    : process.platform;
+}
+
+function detectOsVersion(): string {
+  if (process.platform === "win32") {
+    return `${osVersion()} ${osRelease()}`;
+  }
+  return `${osType()} ${osRelease()}`;
+}
+
+function detectShell(): string {
+  const shell =
+    process.env.SHELL ||
+    process.env.ComSpec ||
+    process.env.COMSPEC ||
+    "unknown";
+  return shell.trim() || "unknown";
+}
+
+function detectGitRepo(startDir: string): boolean {
+  let current = startDir;
+  while (true) {
+    if (existsSync(join(current, ".git"))) {
+      return true;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return false;
+    }
+    current = parent;
+  }
+}
+
+export function getEnvironmentPromptContext(): EnvironmentPromptContext {
+  const cwd = process.cwd();
+  return {
+    cwd,
+    platform: detectPlatform(),
+    osVersion: detectOsVersion(),
+    shell: detectShell(),
+    isGitRepo: detectGitRepo(cwd),
+  };
+}

package/src/core/prompts/static/environment.md

@@ -0,0 +1,15 @@
+## Environment
+
+You are running in the following runtime environment:
+
+- Primary working directory: `{{ environment.cwd }}`
+- Platform: `{{ environment.platform }}`
+- Shell: `{{ environment.shell }}`
+- OS version: `{{ environment.osVersion }}`
+- Is git repository: `{{ environment.isGitRepo }}`
+
+### How To Use This
+
+- Use this information to choose correct path handling, shell syntax, and platform-specific behavior
+- Treat this section as runtime context, not real-time clock data
+- If the task needs the current date or time, call `get_current_time` instead of inferring from this section

package/src/core/prompts/static/sleep.md

@@ -0,0 +1,20 @@
+## Sleep
+
+You have access to a `sleep` tool that waits for a specified duration.
+
+### When To Use It
+
+- Use `sleep` when the user explicitly asks you to wait, pause, rest, or retry later
+- Use `sleep` while waiting for external events where polling immediately would be wasteful
+- Prefer this over shell-based sleep commands to avoid holding a shell process
+
+### How To Use It
+
+- Pass `seconds` as a positive number
+- Choose the shortest useful delay for responsiveness and cost
+- Keep waits intentional; do not sleep if there is useful work to do now
+
+### Cancellation
+
+- Sleep can be interrupted by user cancellation
+- If cancellation happens, report that the wait was cancelled and continue with next best action

package/src/core/prompts/static/subagents.md

@@ -0,0 +1,28 @@
+## Sub Agents
+
+You can delegate specific work using the `run_agents` tool.
+
+Use this tool when delegation makes the response better:
+
+- The task has independent parts that can run in parallel.
+- You need deeper investigation before writing a final answer.
+- You want one agent focused on research and another on planning.
+
+Use delegation thoughtfully:
+
+- Split jobs by clear goals and scopes.
+- Write each job prompt with enough context to be actionable.
+- Prefer concise descriptions that state the expected output.
+- Run only as many jobs as needed for quality and speed.
+
+Do not use `run_agents` when:
+
+- The task is simple and can be handled directly.
+- The work is tightly coupled and cannot be split cleanly.
+- You already have enough evidence to answer confidently.
+
+Output expectations:
+
+- Child agents are read-only and return findings or plans.
+- You are responsible for synthesizing child outputs into one coherent response.
+- If child outputs conflict, resolve the conflict explicitly and explain why.

package/src/core/prompts/system.ts

@@ -3,18 +3,22 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { compile } from "handlebars";
 import type { Config } from "../config.ts";
+import { getEnvironmentPromptContext } from "./environment.ts";
 
 /** Bundled markdown next to this module (`prompts/static/`). */
 const STATIC_PROMPT_FILES = [
   "identity.md",
+  "environment.md",
   "ltm.md",
   "todo.md",
   "thinking.md",
   "filesystem.md",
   "fetch.md",
   "shell.md",
+  "sleep.md",
   "wiki.md",
   "skills.md",
+  "subagents.md",
 ] as const;
 
 const SECTION_BREAK = "\n\n---\n\n";
@@ -46,10 +50,14 @@ export class System {
           return this.config.tools.filesystem.enabled;
         case "shell.md":
           return this.config.tools.shell.enabled;
+        case "sleep.md":
+          return this.config.tools.sleep.enabled;
         case "wiki.md":
           return this.config.tools.wiki.enabled;
         case "skills.md":
           return this.config.tools.skills.enabled;
+        case "subagents.md":
+          return this.config.tools.agents.enabled;
         case "thinking.md":
         default:
           return true;
@@ -101,6 +109,7 @@ export class System {
     return {
       name: this.config.name,
       llm: this.config.llm,
+      environment: getEnvironmentPromptContext(),
       ltm: this.config.tools.ltm,
       wiki: this.config.tools.wiki,
       compaction: this.config.compaction,

package/src/core/tools/index.ts

@@ -1,5 +1,6 @@
 export { createFilesystemTools } from "./filesystem.ts";
 export { createFetchTools } from "./fetch.ts";
+export { createSleepTools } from "./sleep.ts";
 export { createShellTools } from "./shell.ts";
 export { createThinkingTools } from "./thinking.ts";
 export { createTimeTools } from "./time.ts";

package/src/core/tools/sleep.ts

@@ -0,0 +1,51 @@
+import { setTimeout as sleepTimer } from "node:timers/promises";
+import { tool } from "@strands-agents/sdk";
+import type { JSONValue, ToolContext } from "@strands-agents/sdk";
+import { z } from "zod";
+
+const MAX_SLEEP_SECONDS = 60 * 60;
+
+function toJsonValue(value: unknown): JSONValue {
+  return JSON.parse(JSON.stringify(value)) as JSONValue;
+}
+
+export function createSleepTools() {
+  return [
+    tool({
+      name: "sleep",
+      description:
+        "Wait for a specified number of seconds without using shell processes. Use when the user asks you to pause or retry after a delay.",
+      inputSchema: z.object({
+        seconds: z.coerce
+          .number()
+          .positive()
+          .max(MAX_SLEEP_SECONDS)
+          .describe(
+            `How long to wait, in seconds. Must be greater than 0 and at most ${MAX_SLEEP_SECONDS}.`,
+          ),
+      }),
+      callback: async (input, context?: ToolContext) => {
+        const startedAt = Date.now();
+        try {
+          await sleepTimer(input.seconds * 1000, undefined, {
+            signal: context?.agent.cancelSignal,
+          });
+          return toJsonValue({
+            status: "completed",
+            requested_seconds: input.seconds,
+            slept_seconds: (Date.now() - startedAt) / 1000,
+          });
+        } catch (error) {
+          if (error instanceof Error && error.name === "AbortError") {
+            return toJsonValue({
+              status: "cancelled",
+              requested_seconds: input.seconds,
+              slept_seconds: (Date.now() - startedAt) / 1000,
+            });
+          }
+          throw error;
+        }
+      },
+    }),
+  ];
+}