@easynet/agent-runtime 1.0.3 → 1.0.4

package/agent-runtime/src/agents/react-agent.ts

@@ -0,0 +1,584 @@
+import { createAgent as createLangChainAgent } from "langchain";
+import type { BaseMessageLike } from "@langchain/core/messages";
+import { DynamicStructuredTool } from "@langchain/core/tools";
+import type { LanguageModelLike } from "@langchain/core/language_models/base";
+import { z } from "zod";
+import { extractLastMessageText, stripNullishObjectFields, summarizeForLog } from "@easynet/agent-common";
+import type { Skill } from "@easynet/agent-skill";
+import type { BaseAgentConfig, BotContext } from "../core/context.js";
+import {
+  buildPtcHint,
+  deriveFallbackTextFromMessages,
+  extractSchemaKeys,
+  hasToolMessages,
+  inferMemoryTypeByStructure,
+  inferMemoryTypeWithModel,
+  pickAgentConfig,
+  pickFirstAgentName,
+  printReactSteps,
+  readAppBoolean,
+  readAppString,
+  type ToolRunStats,
+} from "./react-agent.helpers.js";
+
+export interface ReactAgentRuntime {
+  agent: unknown;
+  run: (userMessage: string) => Promise<{ text: string; messages?: unknown }>;
+  remember: (content: string, type?: "thread" | "cross_thread" | "knowledge" | "auto") => Promise<void>;
+}
+
+export interface ReactAgentOptions {
+  agentName?: string;
+  systemPrompt?: string;
+  namespace?: string;
+  topK?: number;
+  budgetTokens?: number;
+  maxSteps?: number;
+  printSteps?: boolean;
+  fallbackText?: string;
+  commandWindowLabel?: string;
+  middleware?: unknown[];
+  autoWriteMemory?: boolean;
+  ptc?: {
+    enabled?: boolean;
+    maxRetries?: number;
+  };
+}
+
+type RuntimeTool = {
+  name: string;
+  description?: string;
+  schema: Record<string, unknown>;
+  invoke: (args: unknown) => Promise<unknown>;
+};
+
+type PublishEvent = (name: string, from: string, to: string, payload?: unknown) => void;
+
+function applyDefaultToolChoice(model: unknown): void {
+  const m = model as {
+    bindTools?: (tools: unknown, opts?: Record<string, unknown>) => unknown;
+  };
+  const orig = m.bindTools?.bind(model);
+  if (!orig) return;
+  m.bindTools = function (tools: unknown, opts?: Record<string, unknown>) {
+    return orig(tools, { ...opts, tool_choice: "auto" });
+  };
+}
+
+type ReactRuntimeConfig = {
+  agentName?: string;
+  configReact?: Record<string, unknown> & {
+    systemPrompt?: string;
+    maxSteps?: number;
+    printSteps?: boolean;
+    fallbackText?: string;
+    commandWindowLabel?: string;
+    skills?: {
+      mode?: string;
+      embedding_threshold?: number;
+      keyword_threshold?: number;
+    };
+    memory?: {
+      namespace?: string;
+      top_k?: number;
+      budget_tokens?: number;
+      auto_write?: boolean;
+      auto_write_scope?: "thread" | "cross_thread" | "knowledge" | "auto";
+      auto_write_max_chars?: number;
+      auto_write_user?: boolean;
+      auto_write_assistant?: boolean;
+    };
+  };
+  namespace?: string;
+  topK?: number;
+  budgetTokens?: number;
+  systemPrompt?: string;
+  maxSteps?: number;
+  printSteps?: boolean;
+  fallbackText?: string;
+  commandWindowLabel?: string;
+  autoWriteMemory: boolean;
+  autoWriteScope: "thread" | "cross_thread" | "knowledge" | "auto";
+  autoWriteMaxChars: number;
+  autoWriteUser: boolean;
+  autoWriteAssistant: boolean;
+  ptcEnabled: boolean;
+  ptcMaxRetries: number;
+  invokeTimeoutMs: number;
+};
+
+function resolveRuntimeConfig<TConfig extends BaseAgentConfig>(ctx: BotContext<TConfig>, options: ReactAgentOptions): ReactRuntimeConfig {
+  const agentName = options.agentName ?? pickFirstAgentName(ctx.config);
+  const configReact = pickAgentConfig(ctx.config, agentName);
+  const appConfig = ctx.config.app;
+  return {
+    agentName,
+    configReact,
+    namespace: options.namespace ?? configReact?.memory?.namespace,
+    topK: options.topK ?? configReact?.memory?.top_k,
+    budgetTokens: options.budgetTokens ?? configReact?.memory?.budget_tokens,
+    systemPrompt: options.systemPrompt ?? configReact?.systemPrompt,
+    maxSteps: options.maxSteps ?? configReact?.maxSteps,
+    printSteps: options.printSteps ?? configReact?.printSteps ?? readAppBoolean(appConfig, "printSteps"),
+    fallbackText: options.fallbackText ?? configReact?.fallbackText ?? readAppString(appConfig, "fallbackText"),
+    commandWindowLabel: options.commandWindowLabel ?? configReact?.commandWindowLabel ?? readAppString(appConfig, "commandWindowLabel"),
+    autoWriteMemory: options.autoWriteMemory ?? (configReact?.memory?.auto_write ?? true),
+    autoWriteScope: configReact?.memory?.auto_write_scope ?? "thread",
+    autoWriteMaxChars: configReact?.memory?.auto_write_max_chars ?? 2400,
+    autoWriteUser: configReact?.memory?.auto_write_user ?? true,
+    autoWriteAssistant: configReact?.memory?.auto_write_assistant ?? true,
+    ptcEnabled: options.ptc?.enabled ?? true,
+    ptcMaxRetries: Math.max(0, options.ptc?.maxRetries ?? 1),
+    invokeTimeoutMs: Math.max(
+      5000,
+      Number(
+        (configReact as { invokeTimeoutMs?: unknown } | undefined)?.invokeTimeoutMs
+          ?? (appConfig as { invokeTimeoutMs?: unknown } | undefined)?.invokeTimeoutMs
+          ?? 90000,
+      ) || 90000,
+    ),
+  };
+}
+
+function createAliasGenerator() {
+  const usedNames = new Set<string>();
+  return (raw: string, index: number): string => {
+    const segments = raw.split(".");
+    const base = segments[0] === "file" && segments.length > 2
+      ? segments.slice(2).join("-")
+      : segments.pop() || `tool_${index + 1}`;
+    const normalized = base.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 48) || `tool_${index + 1}`;
+    let name = normalized;
+    let suffix = 2;
+    while (usedNames.has(name)) {
+      name = `${normalized}_${suffix}`;
+      suffix += 1;
+    }
+    usedNames.add(name);
+    return name;
+  };
+}
+
+function buildAliasedTools(args: {
+  runtimeTools: RuntimeTool[];
+  publish: PublishEvent;
+  currentToolStatsRef: { current: ToolRunStats | null };
+}): DynamicStructuredTool[] {
+  const toAlias = createAliasGenerator();
+  return args.runtimeTools.map((tool, idx) => {
+    const alias = toAlias(tool.name, idx);
+    return new DynamicStructuredTool({
+      name: alias,
+      description: tool.description ?? `Tool ${alias}`,
+      schema: tool.schema,
+      func: async (inputArgs: unknown) => {
+        const sanitizedArgs = stripNullishObjectFields((inputArgs ?? {}) as Record<string, unknown>);
+        if (args.currentToolStatsRef.current) args.currentToolStatsRef.current.invoked += 1;
+        args.publish("agent.react.tool.invoke.start", "react-agent", alias, { args: sanitizedArgs });
+        try {
+          const raw = await tool.invoke(sanitizedArgs);
+          if (args.currentToolStatsRef.current) args.currentToolStatsRef.current.succeeded += 1;
+          args.publish("agent.react.tool.invoke.done", alias, "react-agent", { result: raw, resultPreview: summarizeForLog(raw) });
+          return typeof raw === "string" ? raw : raw == null ? "" : JSON.stringify(raw);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          if (args.currentToolStatsRef.current) {
+            args.currentToolStatsRef.current.failed += 1;
+            args.currentToolStatsRef.current.lastError = message;
+          }
+          args.publish("agent.react.tool.invoke.error", alias, "react-agent", { error: message });
+          throw err;
+        }
+      },
+    });
+  });
+}
+
+function maybeAddActivateSkillTool<TConfig extends BaseAgentConfig>(
+  allTools: DynamicStructuredTool[],
+  ctx: BotContext<TConfig>,
+  config: ReactRuntimeConfig,
+): void {
+  const skillsConfig = pickAgentConfig(ctx.config, config.agentName)?.skills;
+  if (!ctx.skillSet || skillsConfig?.mode !== "subagent" || ctx.skillSet.list().length === 0) return;
+
+  const skillNames = ctx.skillSet.list().map((skill: Skill) => skill.name);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- zod enum tuple constraints
+  allTools.push(new DynamicStructuredTool({
+    name: "activateSkill",
+    description: `Activate a skill by name to get its detailed instructions. Available skills: ${skillNames.join(", ")}`,
+    schema: z.object({
+      skillName: z.enum(skillNames as [string, ...string[]]).describe("Name of the skill to activate"),
+    }),
+    func: async (args: { skillName: string }) => {
+      try {
+        return await ctx.skillSet!.read(args.skillName);
+      } catch (err) {
+        return JSON.stringify({ error: err instanceof Error ? err.message : String(err) });
+      }
+    },
+  }) as any);
+}
+
+async function recallInjectedText<TConfig extends BaseAgentConfig>(
+  ctx: BotContext<TConfig>,
+  config: ReactRuntimeConfig,
+  userMessage: string,
+): Promise<string> {
+  if (!config.namespace) return "";
+  const recalled = await ctx.memory.recall({
+    namespace: config.namespace,
+    query: userMessage,
+    ...(typeof config.topK === "number" ? { topK: config.topK } : {}),
+    ...(typeof config.budgetTokens === "number" ? { budgetTokens: config.budgetTokens } : {}),
+  });
+  return recalled.injectedText;
+}
+
+async function buildEffectiveMessage<TConfig extends BaseAgentConfig>(
+  ctx: BotContext<TConfig>,
+  config: ReactRuntimeConfig,
+  userMessage: string,
+  injectedText: string,
+  publish: PublishEvent,
+): Promise<string> {
+  let skillBlock = "";
+  if (ctx.skillSet) {
+    const skillMatchOptions = {
+      ...(typeof config.configReact?.skills?.embedding_threshold === "number"
+        ? { embeddingThreshold: config.configReact.skills.embedding_threshold }
+        : {}),
+      ...(typeof config.configReact?.skills?.keyword_threshold === "number"
+        ? { keywordThreshold: config.configReact.skills.keyword_threshold }
+        : {}),
+    };
+    const match = await ctx.skillSet.match(userMessage, skillMatchOptions);
+    if (match) {
+      publish("agent.react.skill.matched", "react-agent", "skill", { skill: match.skill.name, score: match.score });
+      skillBlock = `[Matched skill: ${match.skill.name}]\nFollow these instructions step by step:\n\n${match.instructions}\n\n`;
+    }
+  }
+
+  const contextBlock = injectedText.trim().length > 0 ? `[Relevant memory]\n${injectedText}\n\n` : "";
+  return skillBlock + contextBlock + userMessage;
+}
+
+async function invokeWithOptionalRecursion(
+  agent: { invoke: (input: unknown, config?: { recursionLimit?: number }) => Promise<unknown> },
+  messageContent: string,
+  conversationHistory: BaseMessageLike[],
+  maxSteps: number | undefined,
+  invokeTimeoutMs: number,
+  currentToolStatsRef: { current: ToolRunStats | null },
+): Promise<{ out: unknown; stats: ToolRunStats | null }> {
+  const invokeInput = { messages: [...conversationHistory, { role: "user" as const, content: messageContent }] };
+  currentToolStatsRef.current = { invoked: 0, succeeded: 0, failed: 0 };
+  try {
+    const invokePromise = typeof maxSteps === "number"
+      ? agent.invoke(invokeInput, { recursionLimit: maxSteps })
+      : agent.invoke(invokeInput);
+    const out = await Promise.race([
+      invokePromise,
+      new Promise<never>((_, reject) => {
+        setTimeout(() => reject(new Error(`Agent invoke timed out after ${invokeTimeoutMs}ms`)), invokeTimeoutMs);
+      }),
+    ]);
+    return { out, stats: currentToolStatsRef.current };
+  } finally {
+    currentToolStatsRef.current = null;
+  }
+}
+
+async function runWithPtcIfNeeded(args: {
+  agent: { invoke: (input: unknown, config?: { recursionLimit?: number }) => Promise<unknown> };
+  effectiveMessage: string;
+  userMessage: string;
+  ptcEnabled: boolean;
+  ptcMaxRetries: number;
+  toolSignatures: string[];
+  publish: PublishEvent;
+  maxSteps?: number;
+  invokeTimeoutMs: number;
+  conversationHistory: BaseMessageLike[];
+  currentToolStatsRef: { current: ToolRunStats | null };
+}): Promise<{ result: unknown; messages: unknown; extractedText: string; stats: ToolRunStats | null }> {
+  let { out: result, stats } = await invokeWithOptionalRecursion(
+    args.agent,
+    args.effectiveMessage,
+    args.conversationHistory,
+    args.maxSteps,
+    args.invokeTimeoutMs,
+    args.currentToolStatsRef,
+  );
+  let messages = (result as { messages?: unknown } | null | undefined)?.messages ?? result;
+  let extractedText = extractLastMessageText(result).trim();
+
+  if (!args.ptcEnabled || args.ptcMaxRetries <= 0) {
+    return { result, messages, extractedText, stats };
+  }
+
+  let retries = 0;
+  while (retries < args.ptcMaxRetries) {
+    const noToolActivity = (stats?.invoked ?? 0) === 0 && !hasToolMessages(messages);
+    const onlyToolFailure = (stats?.invoked ?? 0) > 0 && (stats?.succeeded ?? 0) === 0;
+    if (!noToolActivity && !onlyToolFailure) break;
+
+    args.publish("agent.react.ptc.retry", "react-agent", "react-agent", {
+      retry: retries + 1,
+      reason: noToolActivity ? "no_tool_activity" : "tool_failed",
+      stats,
+    });
+
+    const ptcHint = buildPtcHint({
+      taskIntent: args.userMessage,
+      stats: stats ?? { invoked: 0, succeeded: 0, failed: 0 },
+      toolSignatures: args.toolSignatures,
+    });
+    const retried = await invokeWithOptionalRecursion(
+      args.agent,
+      `${args.effectiveMessage}\n\n${ptcHint}`,
+      args.conversationHistory,
+      args.maxSteps,
+      args.invokeTimeoutMs,
+      args.currentToolStatsRef,
+    );
+    result = retried.out;
+    stats = retried.stats;
+    messages = (result as { messages?: unknown } | null | undefined)?.messages ?? result;
+    extractedText = extractLastMessageText(result).trim();
+    retries += 1;
+  }
+
+  return { result, messages, extractedText, stats };
+}
+
+function updateConversationHistory(history: BaseMessageLike[], userMessage: string, text: string): void {
+  history.push({ role: "user", content: userMessage });
+  if (text.trim().length > 0) history.push({ role: "assistant", content: text });
+  if (history.length > 24) {
+    history.splice(0, history.length - 24);
+  }
+}
+
+function findItermCommandTool(tools: RuntimeTool[]): RuntimeTool | null {
+  return tools.find((tool) => tool.name.includes("itermRunCommandInSession")) ?? null;
+}
+
+function extractItermOutput(raw: unknown): {
+  output: string;
+  command: string;
+  isOutputTruncated: boolean;
+  readError: string;
+  sessionId: string;
+  totalBufferLines: number;
+  returnedLineCount: number;
+} {
+  if (!raw || typeof raw !== "object") {
+    return {
+      output: "",
+      command: "pwd && ls -la",
+      isOutputTruncated: false,
+      readError: "",
+      sessionId: "",
+      totalBufferLines: 0,
+      returnedLineCount: 0,
+    };
+  }
+  const result = (raw as { result?: unknown }).result;
+  if (!result || typeof result !== "object") {
+    return {
+      output: "",
+      command: "pwd && ls -la",
+      isOutputTruncated: false,
+      readError: "",
+      sessionId: "",
+      totalBufferLines: 0,
+      returnedLineCount: 0,
+    };
+  }
+  const rec = result as Record<string, unknown>;
+  return {
+    output: typeof rec.output === "string" ? rec.output : "",
+    command: typeof rec.command === "string" && rec.command.trim() ? rec.command : "pwd && ls -la",
+    isOutputTruncated: rec.isOutputTruncated === true,
+    readError: typeof rec.readError === "string" ? rec.readError.trim() : "",
+    sessionId: typeof rec.sessionId === "string" ? rec.sessionId : "",
+    totalBufferLines:
+      typeof rec.totalBufferLines === "number" && Number.isFinite(rec.totalBufferLines)
+        ? rec.totalBufferLines
+        : 0,
+    returnedLineCount:
+      typeof rec.returnedLineCount === "number" && Number.isFinite(rec.returnedLineCount)
+        ? rec.returnedLineCount
+        : 0,
+  };
+}
+
+async function fallbackWithTargetPanelContext(args: {
+  runtimeTools: RuntimeTool[];
+  userMessage: string;
+  publish: PublishEvent;
+}): Promise<string | null> {
+  const itermTool = findItermCommandTool(args.runtimeTools);
+  if (!itermTool) return null;
+  const fallbackCommand = "pwd && ls -la";
+  args.publish("agent.react.tool.invoke.start", "react-agent", itermTool.name, {
+    args: { command: fallbackCommand, maxOutputLines: 200, outputOffsetLines: 0 },
+    forced: true,
+    reason: "no_tool_activity",
+  });
+  try {
+    const raw = await itermTool.invoke({
+      command: fallbackCommand,
+      maxOutputLines: 200,
+      outputOffsetLines: 0,
+    });
+    args.publish("agent.react.tool.invoke.done", itermTool.name, "react-agent", {
+      forced: true,
+      reason: "no_tool_activity",
+      resultPreview: summarizeForLog(raw),
+    });
+    const parsed = extractItermOutput(raw);
+    if (!parsed.output.trim()) {
+      if (parsed.readError) {
+        return `Executed \`${parsed.command}\` in target panel, but reading terminal output failed: ${parsed.readError}`;
+      }
+      const diagnostics = [
+        parsed.sessionId ? `sessionId=${parsed.sessionId}` : "",
+        `bufferLines=${parsed.totalBufferLines}`,
+        `returnedLines=${parsed.returnedLineCount}`,
+      ].filter(Boolean).join(", ");
+      return `Executed \`${parsed.command}\` in target panel, but no output was returned (${diagnostics}).`;
+    }
+    return [
+      "I collected context from target panel and used it as the source of truth.",
+      "",
+      `Command: \`${parsed.command}\``,
+      "",
+      "```",
+      parsed.output,
+      "```",
+      parsed.isOutputTruncated ? "\nNote: output is truncated; run paginated reads for full coverage." : "",
+    ].join("\n");
+  } catch (err) {
+    args.publish("agent.react.tool.invoke.error", itermTool.name, "react-agent", {
+      forced: true,
+      reason: "no_tool_activity",
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return null;
+  }
+}
+
+async function autoWriteMemoryIfNeeded<TConfig extends BaseAgentConfig>(
+  ctx: BotContext<TConfig>,
+  config: ReactRuntimeConfig,
+  userMessage: string,
+  text: string,
+  publish: PublishEvent,
+): Promise<void> {
+  if (!config.namespace || !config.autoWriteMemory) return;
+
+  const scope = config.autoWriteScope === "auto"
+    ? inferMemoryTypeByStructure(`${userMessage}\n${text}`)
+    : config.autoWriteScope;
+  const writeItems: string[] = [];
+  if (config.autoWriteUser && userMessage.trim().length > 0) writeItems.push(`[user]\n${userMessage.trim()}`);
+  if (config.autoWriteAssistant && text.trim().length > 0) writeItems.push(`[assistant]\n${text.trim()}`);
+
+  const content = writeItems.join("\n\n").slice(0, Math.max(0, config.autoWriteMaxChars));
+  if (!content.length) return;
+
+  try {
+    publish("agent.react.memory.write.start", "react-agent", "memory", { type: scope, auto: true });
+    await ctx.memory.memorize(config.namespace, scope, content);
+    publish("agent.react.memory.write.done", "memory", "react-agent", { type: scope, auto: true });
+  } catch (err) {
+    publish("agent.react.memory.write.error", "memory", "react-agent", {
+      auto: true,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
+export { printReactSteps } from "./react-agent.helpers.js";
+
+export function createReactAgent<TConfig extends BaseAgentConfig>(ctx: BotContext<TConfig>, options: ReactAgentOptions = {}) {
+  const publish: PublishEvent = (name, from, to, payload) => {
+    ctx.events.publish({ name, from, to, payload });
+  };
+
+  const runtimeTools = ctx.tools as unknown as RuntimeTool[];
+  const config = resolveRuntimeConfig(ctx, options);
+  const currentToolStatsRef = { current: null as ToolRunStats | null };
+
+  const aliasedTools = buildAliasedTools({ runtimeTools, publish, currentToolStatsRef });
+  const allTools = [...aliasedTools];
+  maybeAddActivateSkillTool(allTools, ctx, config);
+  const toolSignatures = aliasedTools.map((tool) => {
+    const keys = extractSchemaKeys((tool as unknown as { schema?: unknown }).schema);
+    return keys.length > 0 ? `${tool.name}(${keys.join(",")})` : `${tool.name}(...)`;
+  });
+
+  applyDefaultToolChoice(ctx.llm);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- heavily overloaded createAgent
+  const agent = createLangChainAgent({
+    model: ctx.llm as LanguageModelLike,
+    tools: allTools,
+    systemPrompt: config.systemPrompt,
+    ...(options.middleware?.length ? { middleware: options.middleware } : {}),
+  } as any) as unknown as { invoke: (input: unknown, cfg?: { recursionLimit?: number }) => Promise<unknown> };
+
+  const conversationHistory: BaseMessageLike[] = [];
+
+  return {
+    agent,
+    async run(userMessage: string): Promise<{ text: string; messages?: unknown }> {
+      publish("agent.react.run.start", "user", "react-agent", { userMessage });
+      const injectedText = await recallInjectedText(ctx, config, userMessage);
+      const effectiveMessage = await buildEffectiveMessage(ctx, config, userMessage, injectedText, publish);
+      const runResult = await runWithPtcIfNeeded({
+        agent,
+        effectiveMessage,
+        userMessage,
+        ptcEnabled: config.ptcEnabled,
+        ptcMaxRetries: config.ptcMaxRetries,
+        toolSignatures,
+        publish,
+        maxSteps: typeof config.maxSteps === "number" ? config.maxSteps : 8,
+        invokeTimeoutMs: config.invokeTimeoutMs,
+        conversationHistory,
+        currentToolStatsRef,
+      });
+
+      if (config.printSteps === true) printReactSteps(runResult.messages);
+      const noToolActivity = (runResult.stats?.invoked ?? 0) === 0 && !hasToolMessages(runResult.messages);
+      const forcedText = noToolActivity
+        ? await fallbackWithTargetPanelContext({ runtimeTools, userMessage, publish })
+        : null;
+      const text = forcedText ?? (runResult.extractedText || (config.fallbackText
+        ? deriveFallbackTextFromMessages((Array.isArray(runResult.messages) ? runResult.messages : []) as BaseMessageLike[], {
+          fallbackText: config.fallbackText,
+          commandWindowLabel: config.commandWindowLabel,
+        })
+        : runResult.extractedText));
+
+      updateConversationHistory(conversationHistory, userMessage, text);
+      await autoWriteMemoryIfNeeded(ctx, config, userMessage, text, publish);
+      publish("agent.react.run.done", "react-agent", "user", { text });
+      return { text, messages: runResult.messages };
+    },
+    async remember(content: string, type: "thread" | "cross_thread" | "knowledge" | "auto" = "auto") {
+      const resolvedType = type === "auto"
+        ? (await inferMemoryTypeWithModel(ctx.llm as LanguageModelLike, content)) ?? inferMemoryTypeByStructure(content)
+        : type;
+      publish("agent.react.memory.write.start", "react-agent", "memory", { type: resolvedType });
+      if (!config.namespace) {
+        publish("agent.react.memory.write.skipped", "react-agent", "memory", { reason: "namespace_not_configured" });
+        return;
+      }
+      await ctx.memory.memorize(config.namespace, resolvedType, content);
+      publish("agent.react.memory.write.done", "memory", "react-agent", { type: resolvedType });
+    },
+  };
+}

package/{src → agent-runtime/src/agents}/sub-agent.ts

@@ -7,8 +7,8 @@
  */
 import { createReactAgent } from "./react-agent.js";
 import { createDeepAgent } from "./deep-agent.js";
-import { malformedToolCallMiddleware } from "./malformed-tool-call-middleware.js";
-import type { BotContext } from "./context.js";
+import { malformedToolCallMiddleware } from "../middleware/malformed-tool-call-middleware.js";
+import type { BotContext } from "../core/context.js";
 
 export interface SubAgentOptions {
   /** Agent kind: react or deep. */

package/agent-runtime/src/cli/args.ts

@@ -0,0 +1,15 @@
+import { DEEP, REACT, type AgentKind } from "./types.js";
+
+export interface ParsedArgs {
+  kind: AgentKind;
+  query?: string;
+  explicitKind: boolean;
+}
+
+export function parseArgs(argv: string[] = process.argv.slice(2)): ParsedArgs {
+  const first = argv[0]?.toLowerCase();
+  const explicitKind = first === REACT || first === DEEP;
+  const kind: AgentKind = first === DEEP ? DEEP : REACT;
+  const query = explicitKind ? (argv[1] ?? undefined) : (first ?? undefined);
+  return { kind, query, explicitKind };
+}