itermbot 1.0.2 → 1.0.4

package/src/runtime/text-tool-call-recovery.ts

@@ -0,0 +1,257 @@
+import {
+  asRecord,
+  normalizeToolList,
+  shortToolName,
+} from "@easynet/agent-common/utils";
+import { AgentContextTokens } from "@easynet/agent-common/context";
+
+function normalizeToolInvokeResult(raw: unknown): unknown {
+  return raw;
+}
+
+function stringifyToolResult(value: unknown): string {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+type RuntimeLike = {
+  context: {
+    get<T>(token: unknown): T;
+  };
+  run: (input: string) => Promise<{ text?: string; messages?: unknown }>;
+};
+
+export interface TextToolCallTargetHint {
+  windowId?: number;
+  tabIndex?: number;
+  sessionId?: string;
+}
+
+type ToolLike = {
+  name: string;
+  invoke: (args: unknown) => Promise<unknown>;
+};
+
+interface ToolCallPayload {
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+function collectToolObservationText(messages: unknown): string {
+  if (!Array.isArray(messages)) return "";
+  const chunks: string[] = [];
+  for (const message of messages) {
+    const rec = asRecord(message);
+    if (!rec) continue;
+    const type = typeof rec.type === "string" ? rec.type.toLowerCase() : "";
+    const role = typeof rec.role === "string" ? rec.role.toLowerCase() : "";
+    const isToolMessage = type.includes("tool") || role.includes("tool") || typeof rec.tool_call_id === "string";
+    if (!isToolMessage) continue;
+    const content = rec.content;
+    if (typeof content === "string" && content.trim().length > 0) {
+      chunks.push(content.trim());
+      continue;
+    }
+    if (Array.isArray(content)) {
+      const joined = content
+        .map((part) => {
+          if (typeof part === "string") return part;
+          const obj = asRecord(part);
+          return typeof obj?.text === "string" ? obj.text : "";
+        })
+        .join(" ")
+        .trim();
+      if (joined) chunks.push(joined);
+    }
+  }
+  return chunks.join("\n");
+}
+
+function isToolLike(tool: unknown): tool is ToolLike {
+  return Boolean(
+    tool
+    && typeof tool === "object"
+    && typeof (tool as { name?: unknown }).name === "string"
+    && typeof (tool as { invoke?: unknown }).invoke === "function",
+  );
+}
+
+function extractToolCallPayload(text: string): ToolCallPayload | null {
+  const match = text.match(/<tool-call>\s*([\s\S]*?)\s*<\/tool-call>/i);
+  if (match?.[1]) {
+    try {
+      const parsed = JSON.parse(match[1]) as { name?: unknown; arguments?: unknown };
+      const name = typeof parsed.name === "string" ? parsed.name.trim() : "";
+      const args = asRecord(parsed.arguments) ?? {};
+      if (!name) return null;
+      return { name, arguments: args };
+    } catch {
+      return null;
+    }
+  }
+
+  const fnMatch = text.match(/<function=([^\s>]+)>([\s\S]*)/i);
+  if (!fnMatch?.[1]) return null;
+  const name = fnMatch[1].trim();
+  if (!name) return null;
+  const tail = fnMatch[2] ?? "";
+  const args: Record<string, unknown> = {};
+  const paramRe = /<parameter=([^>]+)>\s*([\s\S]*?)(?=<parameter=[^>]+>|$)/gi;
+  for (const m of tail.matchAll(paramRe)) {
+    const key = (m[1] ?? "").trim();
+    const raw = (m[2] ?? "").trim();
+    if (!key || !raw) continue;
+    if (/^-?\d+$/.test(raw)) {
+      args[key] = Number(raw);
+      continue;
+    }
+    args[key] = raw;
+  }
+  return { name, arguments: args };
+}
+
+function findToolByName(runtime: RuntimeLike, requestedName: string): ToolLike | null {
+  const rawTools = runtime.context.get<unknown>(AgentContextTokens.Tools);
+  const tools = normalizeToolList<ToolLike>(rawTools, isToolLike);
+  if (tools.length === 0) return null;
+  const exact = tools.find((tool) => shortToolName(tool.name) === requestedName);
+  if (exact) return exact;
+  const contains = tools.find((tool) => tool.name.includes(requestedName));
+  return contains ?? null;
+}
+
+function buildRecoveredEvidence(raw: unknown): string {
+  const root = asRecord(raw);
+  const result = asRecord(root?.result);
+  if (!result) return "";
+
+  const blockedToolRaw = typeof result.blockedTool === "string" ? result.blockedTool : "";
+  const blockedTool = blockedToolRaw.split(".").pop() ?? blockedToolRaw;
+  const requestedPath = typeof result.requestedPath === "string" ? result.requestedPath : "";
+  const resolvedPath = typeof result.resolvedPath === "string" ? result.resolvedPath : "";
+  const pathFallbackUsed = typeof result.pathFallbackUsed === "boolean" ? result.pathFallbackUsed : false;
+
+  const outputRoot = asRecord(result.output);
+  const outputResult = asRecord(outputRoot?.result);
+  const outputText = typeof outputResult?.output === "string" ? outputResult.output : "";
+
+  if (blockedTool !== "listDir") return "";
+
+  const listingLines = outputText
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && (line.startsWith("./") || line.startsWith("../") || line.startsWith("/")))
+    .slice(0, 120);
+
+  const parts = [
+    "Structured execution facts:",
+    `- blockedTool: ${blockedTool}`,
+    `- requestedPath: ${requestedPath || "(unknown)"}`,
+    `- resolvedPath: ${resolvedPath || requestedPath || "(unknown)"}`,
+    `- pathFallbackUsed: ${String(pathFallbackUsed)}`,
+  ];
+  if (listingLines.length > 0) {
+    parts.push("- extractedListing:");
+    parts.push(listingLines.join("\n"));
+  }
+  return parts.join("\n");
+}
+
+function formatStepNumber(stepNumber: number): string {
+  return String(Math.max(0, stepNumber)).padStart(2, "0");
+}
+
+function writeStepRunStart(writer: (line: string) => void, label: string): number {
+  writer("");
+  writer(`=== Steps: ${label} ===`);
+  return Date.now();
+}
+
+function writeStepStart(writer: (line: string) => void, stepNumber: number, action: string): void {
+  writer(`[${formatStepNumber(stepNumber)}] ▶ ${action}`);
+}
+
+function writeStepDone(writer: (line: string) => void, stepNumber: number, action: string): void {
+  writer(`[${formatStepNumber(stepNumber)}] ✓ ${action}`);
+}
+
+function writeStepProgress(writer: (line: string) => void, completed: number, total: number): void {
+  writer(`    progress ${completed}/${total}`);
+}
+
+function writeStepRunDone(writer: (line: string) => void, startedAtMs: number, steps: number): void {
+  const elapsed = Math.max(0, Math.round(Date.now() - startedAtMs));
+  writer(`=== Steps complete: ${steps} step(s), ${elapsed}ms ===`);
+  writer("");
+}
+
+function formatRecoveredToolResult(payloadName: string, raw: unknown): string {
+  const recoveredEvidence = buildRecoveredEvidence(raw);
+  if (recoveredEvidence) {
+    return [
+      "### Recovered Tool Result",
+      `- Tool: \`${payloadName}\``,
+      "",
+      recoveredEvidence,
+    ].join("\n");
+  }
+  return stringifyToolResult(raw);
+}
+
+function mergeTargetHintForItermTool(
+  toolName: string,
+  args: Record<string, unknown>,
+  hint?: TextToolCallTargetHint,
+): Record<string, unknown> {
+  if (!toolName.includes("itermRunCommandInSession")) return args;
+  return {
+    ...args,
+    ...(args.windowId == null && hint?.windowId != null ? { windowId: hint.windowId } : {}),
+    ...(args.tabIndex == null && hint?.tabIndex != null ? { tabIndex: hint.tabIndex } : {}),
+    ...(args.sessionId == null && hint?.sessionId ? { sessionId: hint.sessionId } : {}),
+  };
+}
+
+export async function runWithTextToolCallRecovery(
+  runtime: RuntimeLike,
+  userInput: string,
+  writer: (line: string) => void = console.log,
+  targetHint?: TextToolCallTargetHint,
+): Promise<{ text: string; recovered: boolean; evidenceText?: string }> {
+  const first = await runtime.run(userInput);
+  const firstText = (first.text ?? "").trim();
+  const payload = extractToolCallPayload(firstText);
+  if (!payload) {
+    return { text: firstText, recovered: false, evidenceText: collectToolObservationText(first.messages) };
+  }
+
+  const tool = findToolByName(runtime, payload.name);
+  if (!tool) return { text: firstText, recovered: false, evidenceText: collectToolObservationText(first.messages) };
+
+  const recoveryStartedAtMs = writeStepRunStart(writer, "recover text tool-call");
+  writeStepStart(writer, 1, `execute recovered tool call: ${payload.name}`);
+  const mergedArgs = mergeTargetHintForItermTool(tool.name, payload.arguments, targetHint);
+  if (tool.name.includes("itermRunCommandInSession")) {
+    const cmd = typeof mergedArgs.command === "string" ? mergedArgs.command.trim() : "";
+    if (cmd) writer("    reason: Because the previous step produced a literal tool-call, execute it first to recover deterministic evidence.");
+  }
+  const raw = normalizeToolInvokeResult(await tool.invoke(mergedArgs));
+  writeStepDone(writer, 1, `execute recovered tool call: ${payload.name}`);
+  writeStepProgress(writer, 1, 2);
+
+  writeStepStart(writer, 2, "finalize response from recovered tool result");
+  const toolResult = stringifyToolResult(raw);
+  const secondText = formatRecoveredToolResult(payload.name, raw);
+  writeStepDone(writer, 2, "finalize response from recovered tool result");
+  writeStepProgress(writer, 2, 2);
+  writeStepRunDone(writer, recoveryStartedAtMs, 2);
+
+  return { text: secondText || toolResult, recovered: true, evidenceText: toolResult };
+}
+
+export type RecoveryTargetHint = TextToolCallTargetHint;
+export const runWithToolCallRecovery = runWithTextToolCallRecovery;

package/src/{startup-colors.ts → startup/colors.ts}

@@ -111,14 +111,6 @@ function captureSessionColorsSync(args: {
   }
 }
 
-export function captureSessionColorsByIdSync(args: {
-  windowId: number;
-  tabIndex: number;
-  sessionId: string;
-}): SessionColorSnapshot | null {
-  return captureSessionColorsSync(args);
-}
-
 export function restoreSessionColorsSync(snapshots: SessionColorSnapshot[]): void {
   for (const s of snapshots) {
     try {
@@ -180,7 +172,34 @@ export interface StartupResult {
   colorSnapshots: SessionColorSnapshot[];
 }
 
-export async function applyStartupPanelColors(): Promise<StartupResult> {
+type ListSessionsResult = Awaited<ReturnType<typeof itermListCurrentWindowSessions>>;
+
+export interface StartupPanelColorDeps {
+  getProcessTty: () => string | null;
+  listCurrentWindowSessions: () => Promise<ListSessionsResult>;
+  splitPane: typeof itermSplitPane;
+  setSessionColors: typeof itermSetSessionColors;
+  captureSessionColors: (args: { windowId: number; tabIndex: number; sessionId: string }) => SessionColorSnapshot | null;
+  onError: (message: string, error?: unknown) => void;
+}
+
+function createDefaultDeps(): StartupPanelColorDeps {
+  return {
+    getProcessTty: findProcessTty,
+    listCurrentWindowSessions: itermListCurrentWindowSessions,
+    splitPane: itermSplitPane,
+    setSessionColors: itermSetSessionColors,
+    captureSessionColors: captureSessionColorsSync,
+    onError: (message: string, error?: unknown) => {
+      if (error === undefined) console.error(message);
+      else console.error(message, error instanceof Error ? error.message : error);
+    },
+  };
+}
+
+export async function applyStartupPanelColorsWithDeps(
+  deps: StartupPanelColorDeps,
+): Promise<StartupResult> {
   const empty: StartupResult = {
     chatSessionId: null,
     targetSessionId: null,
@@ -189,8 +208,8 @@ export async function applyStartupPanelColors(): Promise<StartupResult> {
     colorSnapshots: [],
   };
 
-  const myTty = findProcessTty();
-  const { result } = await itermListCurrentWindowSessions();
+  const myTty = deps.getProcessTty();
+  const { result } = await deps.listCurrentWindowSessions();
 
   if (result.count === 0) return empty;
 
@@ -201,9 +220,7 @@ export async function applyStartupPanelColors(): Promise<StartupResult> {
     : sessions.find((s) => s.isCurrentSession);
 
   if (!chatSession) {
-    console.error(
-      `startup-colors: could not identify chat session (tty=${myTty}), skipping`,
-    );
+    deps.onError(`startup-colors: could not identify chat session (tty=${myTty}), skipping`);
     return empty;
   }
 
@@ -221,7 +238,7 @@ export async function applyStartupPanelColors(): Promise<StartupResult> {
   // If only chat panel exists, split once to create target panel on startup.
   if (sameTabSessions.length === 1 && chatSessionId) {
     try {
-      await itermSplitPane({
+      await deps.splitPane({
         windowId,
         tabIndex: currentTabIndex,
         sessionId: chatSessionId,
@@ -229,7 +246,7 @@ export async function applyStartupPanelColors(): Promise<StartupResult> {
         activate: false,
       });
 
-      const refreshed = await itermListCurrentWindowSessions();
+      const refreshed = await deps.listCurrentWindowSessions();
       sessions = refreshed.result.sessions as SessionInfo[];
       const preservedChat = sessions.find((s) => s.sessionId === chatSessionId);
       if (preservedChat) {
@@ -240,10 +257,7 @@ export async function applyStartupPanelColors(): Promise<StartupResult> {
       sameTabSessions = sessions.filter((s) => s.tabIndex === currentTabIndex);
       targetSessions = sameTabSessions.filter((s) => s.sessionId !== chatSessionId);
     } catch (err) {
-      console.error(
-        "startup-colors: failed to auto-split single panel:",
-        err instanceof Error ? err.message : err,
-      );
+      deps.onError("startup-colors: failed to auto-split single panel:", err);
     }
   }
 
@@ -266,7 +280,7 @@ export async function applyStartupPanelColors(): Promise<StartupResult> {
   for (const s of sessionsToSnapshot) {
     if (!s.sessionId || seen.has(s.sessionId)) continue;
     seen.add(s.sessionId);
-    const snapshot = captureSessionColorsSync({
+    const snapshot = deps.captureSessionColors({
       windowId,
       tabIndex: currentTabIndex,
       sessionId: s.sessionId,
@@ -280,7 +294,7 @@ export async function applyStartupPanelColors(): Promise<StartupResult> {
 
   if (chatSession.sessionId) {
     tasks.push(
-      itermSetSessionColors({
+      deps.setSessionColors({
         windowId,
         tabIndex: currentTabIndex,
         sessionId: chatSession.sessionId,
@@ -292,7 +306,7 @@ export async function applyStartupPanelColors(): Promise<StartupResult> {
 
   if (selectedTarget?.sessionId) {
     tasks.push(
-      itermSetSessionColors({
+      deps.setSessionColors({
         windowId,
         tabIndex: currentTabIndex,
         sessionId: selectedTarget.sessionId,
@@ -306,12 +320,13 @@ export async function applyStartupPanelColors(): Promise<StartupResult> {
 
   for (const r of results) {
     if (r.status === "rejected") {
-      console.error(
-        "startup-colors: failed to set color on a session:",
-        r.reason?.message ?? r.reason,
-      );
+      deps.onError("startup-colors: failed to set color on a session:", r.reason);
     }
   }
 
   return startupResult;
 }
+
+export async function applyStartupPanelColors(): Promise<StartupResult> {
+  return applyStartupPanelColorsWithDeps(createDefaultDeps());
+}

package/src/startup/diagnostics.ts

@@ -0,0 +1,25 @@
+import { AgentContextTokens } from "@easynet/agent-common/context";
+import { extractTextFromLlmOutput } from "@easynet/agent-common/utils";
+
+const LLM_HEALTHCHECK_PROMPT = "Health check: reply with OK only.";
+
+type AgentRuntimeLike = {
+  context: {
+    get<T>(token: unknown): T;
+  };
+};
+
+export async function runLlmHealthCheck(runtime: AgentRuntimeLike): Promise<string> {
+  const llm = runtime.context.get<{ invoke: (input: string) => Promise<unknown> }>(AgentContextTokens.ChatModel);
+  const timeoutMs = Number(process.env.ITERMBOT_LLM_HEALTHCHECK_TIMEOUT_MS ?? "12000");
+  const timeout = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 12000;
+
+  const invokePromise = llm.invoke(LLM_HEALTHCHECK_PROMPT);
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    setTimeout(() => reject(new Error(`LLM health check timeout (${timeout}ms)`)), timeout);
+  });
+  const output = await Promise.race([invokePromise, timeoutPromise]);
+  const text = extractTextFromLlmOutput(output);
+  if (!text) throw new Error("LLM health check returned empty response");
+  return text.length > 32 ? `${text.slice(0, 32)}...` : text;
+}

package/src/startup/os.ts

@@ -0,0 +1,63 @@
+import { itermRunCommandInSession } from "@easynet/agent-tool-buildin/iterm";
+
+export interface StartupOsInfo {
+  os: string;
+  source: "target-panel" | "local-fallback";
+}
+
+function normalizeOsName(raw: string): string {
+  const normalized = raw.trim();
+  if (!normalized) return "unknown";
+  if (/^darwin$/i.test(normalized)) return "darwin";
+  if (/^linux$/i.test(normalized)) return "linux";
+  if (/^(msys|mingw|cygwin|windows_nt)/i.test(normalized)) return "windows";
+  if (/^freebsd$/i.test(normalized)) return "freebsd";
+  if (/^openbsd$/i.test(normalized)) return "openbsd";
+  if (/^netbsd$/i.test(normalized)) return "netbsd";
+  if (/^sunos$/i.test(normalized)) return "sunos";
+  if (/^aix$/i.test(normalized)) return "aix";
+  return normalized.toLowerCase();
+}
+
+function inferFromLocalProcessPlatform(): string {
+  const p = process.platform;
+  if (p === "darwin") return "darwin";
+  if (p === "linux") return "linux";
+  if (p === "win32") return "windows";
+  return p;
+}
+
+function extractOsFromCommandOutput(output: unknown): string {
+  if (typeof output !== "string" || !output.trim()) return "unknown";
+  const lines = output
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  for (const line of lines) {
+    const match = line.match(/\b(Darwin|Linux|FreeBSD|OpenBSD|NetBSD|SunOS|AIX|MSYS|MINGW|CYGWIN|Windows_NT)\b/i);
+    if (match?.[1]) return normalizeOsName(match[1]);
+  }
+  return "unknown";
+}
+
+export async function detectStartupTargetOs(args: {
+  windowId?: number;
+  tabIndex?: number;
+  sessionId?: string;
+}): Promise<StartupOsInfo> {
+  try {
+    const out = await itermRunCommandInSession({
+      command: "uname -s",
+      waitMs: 400,
+      maxOutputLines: 120,
+      windowId: args.windowId,
+      tabIndex: args.tabIndex,
+      sessionId: args.sessionId,
+    });
+    const detected = extractOsFromCommandOutput(out?.result?.output);
+    if (detected !== "unknown") return { os: detected, source: "target-panel" };
+  } catch {
+    // fall back to local process platform
+  }
+  return { os: inferFromLocalProcessPlatform(), source: "local-fallback" };
+}

package/src/startup/ui.ts

@@ -0,0 +1,56 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  formatLogPath,
+  runStartupStep,
+  StartupProgressRenderer,
+  toErrorMessage,
+} from "@easynet/agent-common/cli";
+
+export { formatLogPath, runStartupStep, StartupProgressRenderer, toErrorMessage };
+
+export function clearStartupNoise(): void {
+  if (!process.stdout.isTTY) return;
+  process.stdout.write("\x1b[2J\x1b[H");
+}
+
+export function printStartupBanner(): void {
+  const lines = [
+    "  _ _____                   ____        _   ",
+    " (_)_   _|__ _ __ _ __ ___ | __ )  ___ | |_ ",
+    " | | | |/ _ \\ '__| '_ ` _ \\|  _ \\ / _ \\| __|",
+    " | | | |  __/ |  | | | | | | |_) | (_) | |_ ",
+    " |_| |_|\\___|_|  |_| |_| |_|____/ \\___/ \\__|",
+    "                   iTermBot                 ",
+  ];
+  console.log("--------------------------------------------------------------------------------------------------");
+  console.log(`\n${lines.join("\n")}`);
+  console.log("      Observe the terminal. Act with precision.\n");
+}
+
+export function getAppVersion(): string {
+  try {
+    const currentFile = fileURLToPath(import.meta.url);
+    const packageJsonPath = resolve(dirname(currentFile), "../package.json");
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { version?: unknown };
+    return typeof parsed.version === "string" ? parsed.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+export function printStartupSummary(args: { version: string; responseSafetyMode?: string; targetOs?: string }): void {
+  console.log("\n--------------------------------------------------------------------------------------------------");
+  console.log(`Version   : v${args.version}`);
+  console.log(`Workspace : ${process.cwd()}`);
+  if (args.targetOs) {
+    console.log(`Target OS : ${args.targetOs}`);
+  }
+  if (args.responseSafetyMode) {
+    console.log(`Safety    : response mode=${args.responseSafetyMode}`);
+  }
+  console.log("");
+  console.log("Commands  : list tools, list skills, exit");
+  console.log("--------------------------------------------------------------------------------------------------\n");
+}

package/src/types/marked-terminal.d.ts

@@ -0,0 +1,3 @@
+declare module "marked-terminal" {
+  export function markedTerminal(options?: Record<string, unknown>): unknown;
+}

package/test/builtin-commands.test.mjs

@@ -0,0 +1,50 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { AgentContextTokens } from "@easynet/agent-common/context";
+import { tryHandleBuiltinReadCommand } from "../dist/chat/builtin-commands.js";
+
+function makeRuntime({ tools = [], skills = [] } = {}) {
+  return {
+    context: {
+      get(token) {
+        if (token === AgentContextTokens.Tools) return tools;
+        if (token === AgentContextTokens.SkillSet) {
+          return { list: () => skills };
+        }
+        return undefined;
+      },
+    },
+  };
+}
+
+test("tryHandleBuiltinReadCommand: list tools returns local tool list", () => {
+  const runtime = makeRuntime({
+    tools: [
+      { name: "npm.easynet.agent.tool.buildin.0.0.70.listDir" },
+      { name: "npm.easynet.agent.tool.buildin.0.0.70.itermRunCommandInSession", description: "Run one command in target session." },
+    ],
+  });
+  const out = tryHandleBuiltinReadCommand("list tools", runtime);
+  assert.equal(out?.includes("Available tools (2):"), true);
+  assert.equal(out?.includes("- listDir"), true);
+  assert.equal(out?.includes("- itermRunCommandInSession: Run one command in target session."), true);
+});
+
+test("tryHandleBuiltinReadCommand: list skills returns local skill list", () => {
+  const runtime = makeRuntime({
+    skills: [
+      { name: "skill-a", description: "Do A" },
+      { name: "skill-b" },
+    ],
+  });
+  const out = tryHandleBuiltinReadCommand(" list   skills ", runtime);
+  assert.equal(out?.includes("Available skills (2):"), true);
+  assert.equal(out?.includes("- skill-a: Do A"), true);
+  assert.equal(out?.includes("- skill-b"), true);
+});
+
+test("tryHandleBuiltinReadCommand: unknown command returns null", () => {
+  const runtime = makeRuntime();
+  const out = tryHandleBuiltinReadCommand("check disk usage", runtime);
+  assert.equal(out, null);
+});