@easynet/agent-runtime 1.0.2 → 1.0.4

package/apps/itermbot/src/context.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared runtime context: LLM, memory, tools.
+ * Built once and passed to both ReAct and Deep agents.
+ */
+import {
+  createContextBuilders,
+  type AppContextBuilders,
+  type BotContext,
+  type BotTool,
+  type CreateContextOptions,
+} from "@easynet/agent-runtime";
+import {
+  loadAppConfig,
+  getModelsConfigPath,
+  getMemoryConfigPath,
+  getToolConfigPath,
+  type AppConfig,
+} from "./config.js";
+
+export type { BotContext, BotTool, CreateContextOptions };
+
+const builders: AppContextBuilders = createContextBuilders<AppConfig>({
+  configApi: {
+    loadAgentConfig: loadAppConfig,
+    getModelsConfigPath: (config: AppConfig, agentName?: string) => getModelsConfigPath(config, agentName),
+    getMemoryConfigPath: (config: AppConfig, agentName?: string) => getMemoryConfigPath(config, agentName),
+    getToolConfigPath: (config: AppConfig, agentName?: string) => getToolConfigPath(config, agentName),
+  },
+});
+
+export const createAgentLlm: AppContextBuilders["createAgentLlm"] = builders.createAgentLlm;
+export const createAgentMemory: AppContextBuilders["createAgentMemory"] = builders.createAgentMemory;
+export const createAgentTools: AppContextBuilders["createAgentTools"] = builders.createAgentTools;
+export const createAgent: AppContextBuilders["createAgent"] = builders.createAgent;
+export const createBotContext: AppContextBuilders["createBotContext"] = builders.createBotContext;

package/apps/itermbot/src/index.ts

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * iTermBot: ReAct agent (LangChain) + Deep agent (DeepAgents).
+ * Usage:
+ *   npm start              # interactive: choose agent then chat
+ *   npm run react          # use ReAct agent
+ *   npm run deep           # use Deep agent
+ *   node dist/index.js react "Your question"
+ *   node dist/index.js deep "Your question"
+ */
+import {
+  runAppCli,
+  createStructuredRunEventListener,
+  resolveDefaultAgentName as resolveRuntimeDefaultAgentName,
+} from "@easynet/agent-runtime";
+import { createAgentEventBus } from "@easynet/agent-common";
+import type { TargetRoutingState } from "./iterm/target-routing.js";
+import { applyStartupPanelColors, restoreSessionColorsSync } from "./startup/colors.js";
+import { injectTargetSessionHint } from "./iterm/session-hint.js";
+import { enableDynamicTargetRouting } from "./iterm/target-routing.js";
+import {
+  clearStartupNoise,
+  formatLogPath,
+  getAppVersion,
+  printStartupBanner,
+  printStartupSummary,
+  resolveConfigPath,
+  runStartupStep,
+  StartupProgressRenderer,
+} from "./startup/ui.js";
+import {
+  getLlmSelectionLabel,
+  getSkillsPathLabel,
+  runLlmHealthCheck,
+} from "./startup/diagnostics.js";
+import {
+  loadAppConfig,
+  getModelsConfigPath,
+  getMemoryConfigPath,
+  getToolConfigPath,
+} from "./config.js";
+import { createAgent, createAgentLlm, createAgentMemory, createAgentTools } from "./context.js";
+let startupColorSnapshots: Parameters<typeof restoreSessionColorsSync>[0] = [];
+let stopDynamicTargetRouting: (() => void) | null = null;
+
+function sanitizeSessionId(input: string): string {
+  return input.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64);
+}
+
+function configureThreadMemoryNamespace(ctx: Parameters<NonNullable<Parameters<typeof runAppCli>[0]["onReady"]>>[0], args: {
+  chatSessionId: string | null;
+}): string {
+  const appConfig = ctx.config.app as
+    | {
+        agent?: Record<string, { memory?: { namespace_mode?: "thread" | "fixed"; namespace?: string } }>;
+      }
+    | undefined;
+  const agents = appConfig?.agent;
+  const agentList = agents ? Object.values(agents) : [];
+  const firstAgent = agentList[0];
+  const defaultBaseNamespace = "user:itermbot";
+  const baseNamespace =
+    firstAgent?.memory?.namespace ??
+    defaultBaseNamespace;
+  const mode = firstAgent?.memory?.namespace_mode ?? "thread";
+  const seed = args.chatSessionId ? sanitizeSessionId(args.chatSessionId) : `local_${Date.now().toString(36)}`;
+  const threadNamespace = mode === "fixed" ? baseNamespace : `${baseNamespace}:thread:${seed}`;
+
+  if (!ctx.config.app) ctx.config.app = {};
+  if (!ctx.config.app.agent) ctx.config.app.agent = {};
+
+  for (const agentName of Object.keys(ctx.config.app.agent)) {
+    const current = ctx.config.app.agent[agentName] ?? {};
+    const currentMemory = current.memory ?? {};
+    ctx.config.app.agent[agentName] = {
+      ...current,
+      memory: {
+        ...currentMemory,
+        namespace: threadNamespace,
+      },
+    };
+  }
+
+  return threadNamespace;
+}
+
+function ensureItermEnvironmentOrExit(): void {
+  const termProgram = process.env.TERM_PROGRAM?.trim();
+  const itermSessionId = process.env.ITERM_SESSION_ID?.trim();
+  const isIterm = termProgram === "iTerm.app" || Boolean(itermSessionId);
+  if (isIterm) return;
+
+  console.error("iTermBot startup blocked: iTerm2 environment is required.");
+  console.error("Please run iTermBot inside iTerm2 and try again.");
+  process.exit(1);
+}
+
+async function createBotContextWithStartupSteps() {
+  const appConfigPath = resolveConfigPath("config/app.yaml");
+  const config = await loadAppConfig(appConfigPath);
+  const agentName = resolveRuntimeDefaultAgentName(
+    config,
+    (config.app as { defaultAgent?: string } | undefined)?.defaultAgent,
+  );
+  const events = createAgentEventBus();
+  const progress = new StartupProgressRenderer();
+  await runStartupStep(
+    progress,
+    "init app config",
+    async () => config,
+    () => `${formatLogPath(appConfigPath)} (agent=${agentName})`,
+  );
+  const modelsPath = getModelsConfigPath(config, agentName);
+  const memoryPath = getMemoryConfigPath(config, agentName);
+  const toolPath = getToolConfigPath(config, agentName);
+  const llmSelectionLabel = await getLlmSelectionLabel(modelsPath);
+  const skillsPathLabel = await getSkillsPathLabel(config, agentName);
+  const llmTask = runStartupStep(
+    progress,
+    "init llm",
+    () => createAgentLlm(config, events, agentName),
+    () => `${formatLogPath(modelsPath)} (${llmSelectionLabel})`,
+  ).then(async (llm) => {
+    await runStartupStep(
+      progress,
+      "check llm health",
+      () => runLlmHealthCheck(llm),
+      () => `${formatLogPath(modelsPath)} (${llmSelectionLabel})`,
+    );
+    return llm;
+  });
+  const memoryTask = runStartupStep(
+    progress,
+    "init memory",
+    () => createAgentMemory(config, events, agentName),
+    () => formatLogPath(memoryPath),
+  );
+  const toolsTask = runStartupStep(
+    progress,
+    "init tools",
+    () => createAgentTools(config, events, agentName),
+    (result) => `${formatLogPath(toolPath)} (count=${result.length})`,
+  );
+  const [llm, memory, tools] = await Promise.all([llmTask, memoryTask, toolsTask]);
+  return runStartupStep(
+    progress,
+    "init skills and context",
+    () => createAgent({ events, agentName, llm, memory, tools }),
+    (result) => `count=${result.skillSet?.list().length ?? 0} (${skillsPathLabel})`,
+  );
+}
+
+ensureItermEnvironmentOrExit();
+clearStartupNoise();
+printStartupBanner();
+
+runAppCli({
+  appName: "iTermBot",
+  createBotContext: createBotContextWithStartupSteps,
+  ui: {
+    assistantLabel: "iTermBot",
+    useColor: true,
+    echoUserQuestion: false,
+    processingSpinner: true,
+    processingText: false,
+    loadingText: false,
+    loadingSpinner: false,
+    readyText: false,
+    interactiveIntro: false,
+  },
+  eventListener: createStructuredRunEventListener((line) => console.log(line)),
+  onShutdown: () => {
+    if (stopDynamicTargetRouting) {
+      stopDynamicTargetRouting();
+      stopDynamicTargetRouting = null;
+    }
+    if (startupColorSnapshots.length > 0) {
+      restoreSessionColorsSync(startupColorSnapshots);
+    }
+  },
+  onReady: async (ctx) => {
+    const progress = new StartupProgressRenderer();
+    const startup = await runStartupStep(
+      progress,
+      "init iTerm panels",
+      () => applyStartupPanelColors(),
+    );
+    const routingState: TargetRoutingState = {
+      chatSessionId: startup.chatSessionId,
+      chatWindowId: startup.windowId,
+      chatTabIndex: startup.tabIndex,
+      targetSessionId: startup.targetSessionId,
+      windowId: startup.windowId,
+      tabIndex: startup.tabIndex,
+    };
+    stopDynamicTargetRouting = await runStartupStep(
+      progress,
+      "init target routing",
+      () => enableDynamicTargetRouting(ctx, routingState),
+    );
+    await runStartupStep(
+      progress,
+      "init memory namespace",
+      () =>
+        configureThreadMemoryNamespace(ctx, {
+          chatSessionId: startup.chatSessionId,
+        }),
+      (result) => result,
+    );
+
+    startupColorSnapshots = startup.colorSnapshots;
+
+    printStartupSummary({
+      version: getAppVersion(),
+    });
+    injectTargetSessionHint(ctx, {
+      ...startup,
+      targetSessionId: routingState.targetSessionId,
+      windowId: routingState.windowId,
+      tabIndex: routingState.tabIndex,
+    });
+  },
+});

package/apps/itermbot/src/iterm/session-hint.ts

@@ -0,0 +1,40 @@
+import type { BotContext } from "@easynet/agent-runtime";
+import type { StartupResult } from "../startup/colors.js";
+
+type PromptTemplates = {
+  itermPolicy?: string;
+  targetSession?: string;
+};
+
+function formatTargetSessionHint(template: string, startup: StartupResult): string {
+  return template
+    .replaceAll("{{sessionId}}", startup.targetSessionId ?? "")
+    .replaceAll("{{windowId}}", String(startup.windowId))
+    .replaceAll("{{tabIndex}}", String(startup.tabIndex));
+}
+
+function getPromptTemplates(ctx: BotContext): PromptTemplates | undefined {
+  const appConfig = ctx.config.app as { promptTemplates?: PromptTemplates } | undefined;
+  return appConfig?.promptTemplates;
+}
+
+export function injectTargetSessionHint(ctx: BotContext, startup: StartupResult): void {
+  const templates = getPromptTemplates(ctx);
+  const policyTemplate = templates?.itermPolicy?.trim() ?? "";
+  const targetTemplate = templates?.targetSession?.trim() ?? "";
+  const sessionRendered = startup.targetSessionId && targetTemplate
+    ? formatTargetSessionHint(targetTemplate, startup)
+    : "";
+
+  const agents = ctx.config.app?.agent as Record<string, { systemPrompt?: string } | undefined> | undefined;
+  if (!agents) return;
+  for (const agentCfg of Object.values(agents)) {
+    if (!agentCfg) continue;
+    const base = (agentCfg.systemPrompt ?? "").trim();
+    const parts: string[] = [];
+    if (policyTemplate && !base.includes(policyTemplate)) parts.push(policyTemplate);
+    if (sessionRendered && !base.includes(sessionRendered)) parts.push(sessionRendered);
+    if (base) parts.push(base);
+    agentCfg.systemPrompt = parts.join("\n\n");
+  }
+}