@easynet/agent-runtime 1.0.3 → 1.0.5

package/apps/itermbot/src/iterm/target-panel-policy.ts

@@ -0,0 +1,220 @@
+import type { BotContext } from "@easynet/agent-runtime";
+
+type ToolLike = {
+  name?: unknown;
+  invoke?: (args: unknown) => Promise<unknown>;
+};
+
+const BLOCKED_SHORT_NAMES = new Set([
+  "listDir",
+  "readText",
+  "writeText",
+  "runCommand",
+  "gitRead",
+  "gitAdd",
+  "gitCommit",
+  "gitDiff",
+  "gitPull",
+  "gitPush",
+  "gitSwitchBranch",
+  "gitLogHistory",
+]);
+
+type RedirectableShortName =
+  | "listDir"
+  | "readText"
+  | "runCommand"
+  | "itermListWindows"
+  | "itermListCurrentWindowSessions"
+  | "itermGetSessionInfo";
+
+type ItermCommandArgs = {
+  command: string;
+  waitMs?: number;
+  maxOutputLines?: number;
+  outputOffsetLines?: number;
+};
+
+function shortName(name: string): string {
+  const parts = name.split(".");
+  return parts[parts.length - 1] ?? name;
+}
+
+function shouldBlockTool(name: string): boolean {
+  if (name.includes("itermRunCommandInSession")) return false;
+  if (name.includes("iterm")) return true;
+  return BLOCKED_SHORT_NAMES.has(shortName(name));
+}
+
+function policyError(toolName: string): Error {
+  return new Error(
+    `Tool "${toolName}" is blocked in iTermBot policy. ` +
+    `Use itermRunCommandInSession on target panel, then analyze returned output.`,
+  );
+}
+
+function asRecord(input: unknown): Record<string, unknown> {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return {};
+  return input as Record<string, unknown>;
+}
+
+function quoteForBash(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+function asBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function asBoundedInt(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  const normalized = Math.floor(value);
+  return Math.max(min, Math.min(max, normalized));
+}
+
+function buildListDirCommand(args: Record<string, unknown>): ItermCommandArgs {
+  const path = typeof args.path === "string" && args.path.trim() ? args.path.trim() : ".";
+  const recursive = asBoolean(args.recursive, false);
+  const includeHidden = asBoolean(args.includeHidden, false);
+  const maxDepth = asBoundedInt(args.maxDepth, 3, 1, 20);
+  const maxEntries = asBoundedInt(args.maxEntries, 200, 1, 2000);
+  const quotedPath = quoteForBash(path);
+  if (!recursive) {
+    const lsFlags = includeHidden ? "-la" : "-l";
+    return { command: `ls ${lsFlags} ${quotedPath} | head -n ${maxEntries}` };
+  }
+  const hiddenFilter = includeHidden ? "" : ` | grep -Ev '/\\.[^/]+($|/)'`;
+  return {
+    command: `find ${quotedPath} -maxdepth ${maxDepth} -print${hiddenFilter} | head -n ${maxEntries}`,
+    maxOutputLines: Math.min(maxEntries + 50, 3000),
+  };
+}
+
+function buildReadTextCommand(args: Record<string, unknown>): ItermCommandArgs | null {
+  const path = typeof args.path === "string" ? args.path.trim() : "";
+  if (!path) return null;
+  const maxBytes = asBoundedInt(args.maxBytes, 24_000, 256, 200_000);
+  const maxLines = asBoundedInt(Math.floor(maxBytes / 120), 200, 20, 2000);
+  return {
+    command: `sed -n '1,${maxLines}p' ${quoteForBash(path)}`,
+    maxOutputLines: Math.min(maxLines + 40, 2500),
+  };
+}
+
+function buildRunCommandCommand(args: Record<string, unknown>): ItermCommandArgs | null {
+  if (typeof args.command === "string" && args.command.trim()) {
+    return { command: args.command.trim() };
+  }
+  if (typeof args.cmd === "string" && args.cmd.trim()) {
+    return { command: args.cmd.trim() };
+  }
+  if (Array.isArray(args.cmdArray) && args.cmdArray.length > 0) {
+    const joined = args.cmdArray.map((part) => String(part)).join(" ").trim();
+    if (joined) return { command: joined };
+  }
+  return null;
+}
+
+function toItermCommandArgs(toolName: string, args: unknown): ItermCommandArgs | null {
+  const tool = shortName(toolName);
+  const record = asRecord(args);
+  if (tool === "listDir") return buildListDirCommand(record);
+  if (tool === "readText") return buildReadTextCommand(record);
+  if (tool === "runCommand") return buildRunCommandCommand(record);
+  if (tool === "itermListWindows") return { command: "pwd && ls -la" };
+  if (tool === "itermListCurrentWindowSessions") return { command: "pwd && ls -la" };
+  if (tool === "itermGetSessionInfo") return { command: "pwd && ls -la" };
+  return null;
+}
+
+function isRedirectableTool(toolName: string): toolName is RedirectableShortName {
+  return (
+    toolName === "listDir" ||
+    toolName === "readText" ||
+    toolName === "runCommand" ||
+    toolName === "itermListWindows" ||
+    toolName === "itermListCurrentWindowSessions" ||
+    toolName === "itermGetSessionInfo"
+  );
+}
+
+function findItermCommandTool(tools: ToolLike[]): ToolLike | null {
+  return tools.find((tool) => typeof tool.name === "string" && typeof tool.invoke === "function" && tool.name.includes("itermRunCommandInSession")) ?? null;
+}
+
+async function invokeRedirect(
+  blockedName: string,
+  blockedArgs: unknown,
+  commandTool: ToolLike | null,
+): Promise<unknown> {
+  const mapped = toItermCommandArgs(blockedName, blockedArgs);
+  if (!mapped || !commandTool || typeof commandTool.invoke !== "function") {
+    throw policyError(blockedName);
+  }
+  const output = await commandTool.invoke(mapped);
+  return {
+    result: {
+      blockedTool: blockedName,
+      redirectedTool: commandTool.name,
+      redirected: true,
+      originalArgs: asRecord(blockedArgs),
+      mappedCommand: mapped.command,
+      output,
+    },
+    evidence: [
+      {
+        type: "policy",
+        ref: "target-panel-policy",
+        summary: `Redirected ${blockedName} to ${String(commandTool.name)} with target-panel command execution`,
+        createdAt: new Date().toISOString(),
+      },
+    ],
+  };
+}
+
+function blockedResult(toolName: string): unknown {
+  return {
+    result: {
+      blocked: true,
+      blockedTool: toolName,
+      requiredTool: "itermRunCommandInSession",
+      message:
+        `Tool "${toolName}" is blocked in iTermBot policy. ` +
+        `Use itermRunCommandInSession on target panel, then analyze returned output.`,
+      suggestedCommand: "pwd && ls -la",
+    },
+    evidence: [
+      {
+        type: "policy",
+        ref: "target-panel-policy",
+        summary: `Blocked ${toolName}; returned policy guidance for target-panel command execution`,
+        createdAt: new Date().toISOString(),
+      },
+    ],
+  };
+}
+
+export function enforceTargetPanelExecutionPolicy(ctx: BotContext): () => void {
+  const unpatchFns: Array<() => void> = [];
+  const allTools = ctx.tools as unknown as ToolLike[];
+  const itermCommandTool = findItermCommandTool(allTools);
+
+  for (const tool of allTools) {
+    if (!tool || typeof tool.name !== "string" || typeof tool.invoke !== "function") continue;
+    if (!shouldBlockTool(tool.name)) continue;
+    const originalInvoke = tool.invoke.bind(tool);
+    tool.invoke = async (args: unknown): Promise<unknown> => {
+      const toolShortName = shortName(tool.name as string);
+      if (isRedirectableTool(toolShortName)) {
+        return invokeRedirect(tool.name as string, args, itermCommandTool);
+      }
+      return blockedResult(tool.name as string);
+    };
+    unpatchFns.push(() => {
+      tool.invoke = originalInvoke;
+    });
+  }
+  return () => {
+    for (const unpatch of unpatchFns) unpatch();
+  };
+}

package/apps/itermbot/src/iterm/target-routing.ts

@@ -0,0 +1,419 @@
+import type { BotContext } from "@easynet/agent-runtime";
+import {
+  itermListCurrentWindowSessions,
+  itermRename,
+  itermSetSessionColors,
+  itermSplitPane,
+} from "@easynet/agent-tool-buildin/iterm";
+import {
+  CHAT_BG,
+  CHAT_FG,
+  TARGET_BG,
+  TARGET_FG,
+  captureSessionColorsByIdSync,
+  restoreSessionColorsSync,
+  type SessionColorSnapshot,
+} from "../startup/colors.js";
+
+interface SessionInfo {
+  windowId?: number;
+  tabIndex?: number;
+  sessionId?: string;
+  isCurrentSession?: boolean;
+  isCurrentTab?: boolean;
+}
+
+export interface TargetRoutingState {
+  chatSessionId: string | null;
+  chatWindowId: number | null;
+  chatTabIndex: number | null;
+  targetSessionId: string | null;
+  windowId: number | null;
+  tabIndex: number | null;
+}
+
+type ToolLike = {
+  name?: unknown;
+  invoke?: (args: unknown) => Promise<unknown>;
+};
+
+export function enableDynamicTargetRouting(
+  ctx: BotContext,
+  state: TargetRoutingState,
+  options: {
+    intervalMs?: number;
+    chatTitle?: string;
+    targetTitle?: string;
+  } = {},
+): () => void {
+  const intervalMs = options.intervalMs ?? 2000;
+  const chatTitle = options.chatTitle ?? "iTermBot Chat";
+  const targetTitle = options.targetTitle ?? "iTermBot Target";
+  const unpatchFns: Array<() => void> = [];
+  let announcedTarget = state.targetSessionId;
+  const originalColors = new Map<string, SessionColorSnapshot>();
+  const verboseRoutingLog = process.env.ITERMBOT_ROUTING_LOG === "1";
+
+  const announceRoutingChange = (message: string): void => {
+    // Avoid breaking readline prompt in interactive TTY mode.
+    if (!verboseRoutingLog) return;
+    console.error(message);
+  };
+
+  const isLikelyRoutingError = (error: unknown): boolean => {
+    const message =
+      error instanceof Error
+        ? error.message
+        : typeof error === "string"
+          ? error
+          : "";
+    if (!message) return false;
+    const lower = message.toLowerCase();
+    return (
+      lower.includes("session") ||
+      lower.includes("window") ||
+      lower.includes("tab") ||
+      lower.includes("not found") ||
+      lower.includes("missing value") ||
+      lower.includes("iterm")
+    );
+  };
+
+  const setSessionTitle = async (
+    sessionId: string,
+    windowId: number | null,
+    tabIndex: number | null,
+    sessionName: string,
+  ): Promise<void> => {
+    if (!sessionId) return;
+    if (typeof windowId !== "number" || typeof tabIndex !== "number") return;
+    try {
+      await itermRename({
+        windowId,
+        tabIndex,
+        sessionId,
+        sessionName,
+      });
+    } catch {
+      // non-fatal
+    }
+  };
+
+  const setSessionColors = async (
+    sessionId: string,
+    windowId: number | null,
+    tabIndex: number | null,
+    colors: { backgroundHex: string; foregroundHex: string },
+  ): Promise<void> => {
+    if (!sessionId) return;
+    if (typeof windowId !== "number" || typeof tabIndex !== "number") return;
+    try {
+      await itermSetSessionColors({
+        windowId,
+        tabIndex,
+        sessionId,
+        backgroundHex: colors.backgroundHex,
+        foregroundHex: colors.foregroundHex,
+      });
+    } catch {
+      // non-fatal
+    }
+  };
+
+  const rememberOriginalColors = (
+    sessionId: string,
+    windowId: number | null,
+    tabIndex: number | null,
+  ): void => {
+    if (!sessionId) return;
+    if (originalColors.has(sessionId)) return;
+    if (typeof windowId !== "number" || typeof tabIndex !== "number") return;
+    const snapshot = captureSessionColorsByIdSync({
+      windowId,
+      tabIndex,
+      sessionId,
+    });
+    if (!snapshot) return;
+    originalColors.set(sessionId, snapshot);
+  };
+
+  const restoreOriginalColors = (sessionId: string | null): void => {
+    if (!sessionId) return;
+    const snapshot = originalColors.get(sessionId);
+    if (!snapshot) return;
+    try {
+      restoreSessionColorsSync([snapshot]);
+    } catch {
+      // non-fatal
+    }
+  };
+
+  const enforceTitles = async (): Promise<void> => {
+    if (state.chatSessionId) {
+      await setSessionTitle(state.chatSessionId, state.chatWindowId, state.chatTabIndex, chatTitle);
+      await setSessionColors(state.chatSessionId, state.chatWindowId, state.chatTabIndex, {
+        backgroundHex: CHAT_BG,
+        foregroundHex: CHAT_FG,
+      });
+    }
+    if (state.targetSessionId) {
+      rememberOriginalColors(state.targetSessionId, state.windowId, state.tabIndex);
+      await setSessionTitle(state.targetSessionId, state.windowId, state.tabIndex, targetTitle);
+      await setSessionColors(state.targetSessionId, state.windowId, state.tabIndex, {
+        backgroundHex: TARGET_BG,
+        foregroundHex: TARGET_FG,
+      });
+    }
+  };
+
+  const chooseFallbackTarget = (sessions: SessionInfo[], chatSessionId: string | null): SessionInfo | null => {
+    const bySameTab = sessions.find((s) =>
+      Boolean(s.sessionId) &&
+      s.sessionId !== chatSessionId &&
+      typeof state.chatTabIndex === "number" &&
+      s.tabIndex === state.chatTabIndex,
+    );
+    if (bySameTab) return bySameTab;
+
+    const byCurrentTab = sessions.find((s) =>
+      Boolean(s.sessionId) &&
+      s.sessionId !== chatSessionId &&
+      s.isCurrentTab,
+    );
+    if (byCurrentTab) return byCurrentTab;
+
+    const byAny = sessions.find((s) =>
+      Boolean(s.sessionId) &&
+      s.sessionId !== chatSessionId,
+    );
+    return byAny ?? null;
+  };
+
+  const refreshTargetForCommand = async (opts: {
+    allowSplit: boolean;
+    adoptFocusedNonChat: boolean;
+  }): Promise<{
+    changed: boolean;
+    autoCreated: boolean;
+  }> => {
+    const { result } = await itermListCurrentWindowSessions();
+    const sessions = (result.sessions ?? []) as SessionInfo[];
+    if (sessions.length === 0) {
+      return { changed: false, autoCreated: false };
+    }
+
+    const current = sessions.find((s) => s.isCurrentSession && s.sessionId) ?? null;
+    const chatSession =
+      sessions.find((s) => s.sessionId && state.chatSessionId && s.sessionId === state.chatSessionId) ??
+      current ??
+      sessions.find((s) => Boolean(s.sessionId)) ??
+      null;
+
+    if (chatSession?.sessionId) {
+      const prevChatSessionId = state.chatSessionId;
+      state.chatSessionId = chatSession.sessionId;
+      if (typeof chatSession.windowId === "number") state.chatWindowId = chatSession.windowId;
+      if (typeof chatSession.tabIndex === "number") state.chatTabIndex = chatSession.tabIndex;
+      if (prevChatSessionId !== state.chatSessionId) {
+        state.targetSessionId = null;
+      }
+    }
+
+    if (opts.adoptFocusedNonChat && current?.sessionId && current.sessionId !== state.chatSessionId) {
+      const changed = state.targetSessionId !== current.sessionId;
+      state.targetSessionId = current.sessionId;
+      if (typeof current.windowId === "number") state.windowId = current.windowId;
+      if (typeof current.tabIndex === "number") state.tabIndex = current.tabIndex;
+      return { changed, autoCreated: false };
+    }
+
+    const currentTarget = sessions.find((s) => s.sessionId && s.sessionId === state.targetSessionId) ?? null;
+    const targetIsValid = Boolean(
+      currentTarget?.sessionId &&
+      (!state.chatSessionId || currentTarget.sessionId !== state.chatSessionId),
+    );
+    if (targetIsValid) {
+      if (currentTarget && typeof currentTarget.windowId === "number") state.windowId = currentTarget.windowId;
+      if (currentTarget && typeof currentTarget.tabIndex === "number") state.tabIndex = currentTarget.tabIndex;
+      return { changed: false, autoCreated: false };
+    }
+
+    const fallback = chooseFallbackTarget(sessions, state.chatSessionId);
+    if (fallback?.sessionId) {
+      const changed = state.targetSessionId !== fallback.sessionId;
+      state.targetSessionId = fallback.sessionId;
+      if (typeof fallback.windowId === "number") state.windowId = fallback.windowId;
+      if (typeof fallback.tabIndex === "number") state.tabIndex = fallback.tabIndex;
+      return { changed, autoCreated: false };
+    }
+
+    if (!opts.allowSplit || !chatSession?.sessionId) {
+      return { changed: false, autoCreated: false };
+    }
+
+    const split = await itermSplitPane({
+      windowId: typeof chatSession.windowId === "number" ? chatSession.windowId : undefined,
+      tabIndex: typeof chatSession.tabIndex === "number" ? chatSession.tabIndex : undefined,
+      sessionId: chatSession.sessionId,
+      direction: "vertical",
+      activate: false,
+    });
+
+    const splitSessionId = typeof split?.result?.sessionId === "string" ? split.result.sessionId : "";
+    if (splitSessionId && splitSessionId !== chatSession.sessionId) {
+      const changed = state.targetSessionId !== splitSessionId;
+      state.targetSessionId = splitSessionId;
+      if (typeof split.result.windowId === "number") state.windowId = split.result.windowId;
+      if (typeof split.result.tabIndex === "number") state.tabIndex = split.result.tabIndex;
+      return { changed, autoCreated: true };
+    }
+
+    const refreshed = await itermListCurrentWindowSessions();
+    const refreshedSessions = (refreshed.result.sessions ?? []) as SessionInfo[];
+    const refreshedFallback = chooseFallbackTarget(refreshedSessions, state.chatSessionId);
+    if (refreshedFallback?.sessionId) {
+      const changed = state.targetSessionId !== refreshedFallback.sessionId;
+      state.targetSessionId = refreshedFallback.sessionId;
+      if (typeof refreshedFallback.windowId === "number") state.windowId = refreshedFallback.windowId;
+      if (typeof refreshedFallback.tabIndex === "number") state.tabIndex = refreshedFallback.tabIndex;
+      return { changed, autoCreated: true };
+    }
+
+    return { changed: false, autoCreated: false };
+  };
+
+  // Initial titles
+  void enforceTitles();
+
+  for (const t of ctx.tools as unknown as ToolLike[]) {
+    if (!t || typeof t.name !== "string" || typeof t.invoke !== "function") continue;
+    if (!t.name.includes("itermRunCommandInSession")) continue;
+
+    const originalInvoke = t.invoke.bind(t);
+    t.invoke = async (args: unknown): Promise<unknown> => {
+      const baseArgs =
+        args && typeof args === "object"
+          ? { ...(args as Record<string, unknown>) }
+          : ({} as Record<string, unknown>);
+
+      const applyRoutingArgs = (target: Record<string, unknown>): void => {
+        if (state.targetSessionId) target.sessionId = state.targetSessionId;
+        if (typeof state.windowId === "number") target.windowId = state.windowId;
+        if (typeof state.tabIndex === "number") target.tabIndex = state.tabIndex;
+      };
+
+      try {
+        // Fast path: avoid iTerm preflight on every command.
+        // Only preflight when routing state is empty.
+        if (!state.targetSessionId) {
+          const previousTarget = state.targetSessionId;
+          const ensureResult = await refreshTargetForCommand({
+            allowSplit: true,
+            adoptFocusedNonChat: true,
+          });
+          if (ensureResult.changed) {
+            await enforceTitles();
+            if (previousTarget && previousTarget !== state.targetSessionId) {
+              restoreOriginalColors(previousTarget);
+            }
+            if (state.targetSessionId !== announcedTarget) {
+              announcedTarget = state.targetSessionId;
+              if (ensureResult.autoCreated) {
+                announceRoutingChange("Session routing updated: target panel auto-created and linked.");
+              } else {
+                announceRoutingChange("Session routing updated: target panel linked.");
+              }
+            }
+          }
+        }
+      } catch {
+        // keep previous target when preflight fails
+      }
+      applyRoutingArgs(baseArgs);
+
+      try {
+        return await originalInvoke(baseArgs);
+      } catch (error) {
+        if (!isLikelyRoutingError(error)) {
+          throw error;
+        }
+        // Slow path fallback: routing may be stale (target pane closed/moved).
+        const previousTarget = state.targetSessionId;
+        try {
+          const ensureResult = await refreshTargetForCommand({
+            allowSplit: true,
+            adoptFocusedNonChat: true,
+          });
+          if (ensureResult.changed) {
+            await enforceTitles();
+            if (previousTarget && previousTarget !== state.targetSessionId) {
+              restoreOriginalColors(previousTarget);
+            }
+            if (state.targetSessionId !== announcedTarget) {
+              announcedTarget = state.targetSessionId;
+              if (ensureResult.autoCreated) {
+                announceRoutingChange("Session routing updated: target panel auto-created and linked.");
+              } else {
+                announceRoutingChange("Session routing updated: target panel linked.");
+              }
+            }
+          }
+        } catch {
+          // If reroute fails, fall through and surface original error.
+        }
+
+        const retryArgs = { ...baseArgs };
+        applyRoutingArgs(retryArgs);
+        return originalInvoke(retryArgs);
+      }
+    };
+
+    unpatchFns.push(() => {
+      t.invoke = originalInvoke;
+    });
+  }
+
+  let stopped = false;
+  let polling = false;
+  const timer = setInterval(() => {
+    if (stopped || polling) return;
+    polling = true;
+    void (async () => {
+      try {
+        const previousTarget = state.targetSessionId;
+        const ensured = await refreshTargetForCommand({
+          allowSplit: false,
+          adoptFocusedNonChat: true,
+        });
+        if (ensured.changed) {
+          await enforceTitles();
+          if (previousTarget && previousTarget !== state.targetSessionId) {
+            restoreOriginalColors(previousTarget);
+          }
+        }
+        if (state.targetSessionId === announcedTarget) return;
+        announcedTarget = state.targetSessionId;
+        announceRoutingChange("Session routing updated: target panel linked.");
+      } catch {
+        // keep previous target when polling fails
+      } finally {
+        polling = false;
+      }
+    })();
+  }, intervalMs);
+
+  return () => {
+    stopped = true;
+    clearInterval(timer);
+    if (originalColors.size > 0) {
+      try {
+        restoreSessionColorsSync(Array.from(originalColors.values()));
+      } catch {
+        // non-fatal
+      }
+    }
+    for (const unpatch of unpatchFns) {
+      unpatch();
+    }
+  };
+}