hoomanjs 1.14.0 → 1.16.0

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

@@ -29,6 +29,14 @@ const CompactionPartialSchema = z.object({
 
 const DEFAULT_COMPACTION = { ratio: 0.75, keep: 5 } as const;
 
+const DEFAULT_PROMPTS = {
+  behaviour: true,
+  communication: true,
+  execution: true,
+  engineering: false,
+  guardrails: true,
+} as const;
+
 const DEFAULT_CHROMA = {
   url: "http://127.0.0.1:8000",
   collection: { memory: "memory" },
@@ -71,21 +79,37 @@ const ToolTogglePartialSchema = z.object({
   enabled: z.boolean().optional(),
 });
 
+const PromptsPartialSchema = z.object({
+  behaviour: z.boolean().optional(),
+  communication: z.boolean().optional(),
+  execution: z.boolean().optional(),
+  engineering: z.boolean().optional(),
+  guardrails: 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
   .object({
     name: z.string().min(1),
     llm: LlmSchema,
+    prompts: PromptsPartialSchema.nullish(),
     tools: ToolsPartialSchema.nullish(),
     compaction: CompactionPartialSchema.nullish().transform((c) => ({
       ratio: c?.ratio ?? DEFAULT_COMPACTION.ratio,
@@ -98,6 +122,14 @@ const ConfigSchema = z
     return {
       name: input.name,
       llm: input.llm,
+      prompts: {
+        behaviour: input.prompts?.behaviour ?? DEFAULT_PROMPTS.behaviour,
+        communication:
+          input.prompts?.communication ?? DEFAULT_PROMPTS.communication,
+        execution: input.prompts?.execution ?? DEFAULT_PROMPTS.execution,
+        engineering: input.prompts?.engineering ?? DEFAULT_PROMPTS.engineering,
+        guardrails: input.prompts?.guardrails ?? DEFAULT_PROMPTS.guardrails,
+      },
       tools: {
         todo: {
           enabled: input.tools?.todo?.enabled ?? true,
@@ -111,6 +143,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 +174,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,
     };
@@ -147,6 +186,7 @@ const ConfigSchema = z
 export type ConfigData = z.infer<typeof ConfigSchema>;
 export type LlmConfig = z.infer<typeof LlmSchema>;
 export type CompactionConfig = ConfigData["compaction"];
+export type PromptsConfig = ConfigData["prompts"];
 export type LtmConfig = ConfigData["tools"]["ltm"];
 export type WikiConfig = ConfigData["tools"]["wiki"];
 export type ToolsConfig = ConfigData["tools"];
@@ -158,6 +198,7 @@ const defaultConfigData = (): ConfigData => ({
     model: "gemma4:e4b",
     params: {},
   },
+  prompts: { ...DEFAULT_PROMPTS },
   tools: {
     todo: {
       enabled: true,
@@ -171,6 +212,9 @@ const defaultConfigData = (): ConfigData => ({
     shell: {
       enabled: true,
     },
+    sleep: {
+      enabled: true,
+    },
     ltm: {
       enabled: false,
       chroma: {
@@ -191,6 +235,10 @@ const defaultConfigData = (): ConfigData => ({
     skills: {
       enabled: false,
     },
+    agents: {
+      enabled: true,
+      concurrency: 2,
+    },
   },
   compaction: {
     ratio: 0.75,
@@ -215,6 +263,10 @@ export class Config {
     return this.data.llm;
   }
 
+  get prompts(): PromptsConfig {
+    return { ...this.data.prompts };
+  }
+
   get tools(): ToolsConfig {
     return {
       ...this.data.tools,
@@ -222,6 +274,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 +291,7 @@ export class Config {
       },
       mcp: { ...this.data.tools.mcp },
       skills: { ...this.data.tools.skills },
+      agents: { ...this.data.tools.agents },
     };
   }
 

package/src/core/index.ts

@@ -21,6 +21,7 @@ import {
 export type BootstrapMeta = {
   userId?: string;
   sessionId?: string;
+  mode?: "default" | "daemon";
   acp?: AcpMeta;
 };
 
@@ -47,7 +48,11 @@ export async function bootstrap(
   );
   const mcp = { config: mcpConfig, manager: mcpManager };
   const registry = createSkillsRegistry(basePath());
-  const system = await createSystemPrompt(instructionsMdPath(), config);
+  const system = await createSystemPrompt(
+    instructionsMdPath(),
+    config,
+    meta.mode ?? "default",
+  );
   const agent = await createAgent(config, system, registry, mcp, print, {
     userId: meta?.userId ?? meta?.sessionId,
     sessionId: meta?.sessionId,