@botbotgo/runtime 1.0.0

package/src/runtime/middleware/toolArgsNormalizer.ts

@@ -0,0 +1,277 @@
+import { existsSync } from "node:fs";
+import { basename, dirname, relative, resolve } from "node:path";
+import { TOOL_PATH_ARG_KEYS, type ToolArgs } from "./types.js";
+
+export class ToolArgsNormalizer {
+  public static normalizeToolArgs(
+    rootDir: string,
+    skillRoots: string[],
+    name: string,
+    args: ToolArgs,
+    skillPathMap?: Record<string, string>,
+  ): ToolArgs {
+    let nextArgs: ToolArgs = this.expandPlaceholders(rootDir, skillRoots, args, skillPathMap);
+    nextArgs = this.normalizePathArgs(rootDir, nextArgs);
+
+    if (name === "execute" && typeof nextArgs.command === "string") {
+      nextArgs = {
+        ...nextArgs,
+        command: this.normalizeExecuteCommand(rootDir, skillRoots, nextArgs.command, skillPathMap),
+      };
+    }
+    if (this.usesFilePathAlias(name, args)) {
+      nextArgs = { ...nextArgs, file_path: args.path };
+    }
+    if (name === "write_todos") {
+      nextArgs = this.normalizeWriteTodosArgs(args, nextArgs);
+    }
+
+    return nextArgs;
+  }
+
+  private static usesFilePathAlias(name: string, args: ToolArgs): boolean {
+    return (name === "read_file" || name === "write_file" || name === "edit_file") &&
+      typeof args.path === "string" &&
+      !("file_path" in args);
+  }
+
+  private static normalizeExecuteCommand(
+    rootDir: string,
+    skillRoots: string[],
+    command: string,
+    skillPathMap?: Record<string, string>,
+  ): string {
+    const trimmed = this.expandStringPlaceholders(rootDir, skillRoots, command, skillPathMap).trim();
+    const normalized = /^\.\/(Users|home|usr|opt)\//.test(trimmed)
+      ? `/${trimmed.slice(2)}`
+      : trimmed;
+    if (skillRoots.length === 0) {
+      return normalized;
+    }
+
+    const parts = this.tokenizeCommand(normalized);
+    if (parts.length < 2) {
+      return normalized;
+    }
+
+    let changed = false;
+    const rewritten = parts.map((part, index) => {
+      if (index === 0) return part;
+      const nextPart = this.resolveSkillRelativeCommandArg(rootDir, skillRoots, part);
+      if (nextPart !== part) {
+        changed = true;
+      }
+      return nextPart;
+    });
+
+    return changed ? rewritten.map((part) => this.quoteCommandPart(part)).join(" ") : normalized;
+  }
+
+  private static normalizePathArgs(rootDir: string, args: ToolArgs): ToolArgs {
+    let nextArgs: ToolArgs = { ...args };
+    for (const key of TOOL_PATH_ARG_KEYS) {
+      const value = nextArgs[key];
+      if (!this.shouldNormalizePath(value)) {
+        continue;
+      }
+      if (this.isResolvableAbsolutePath(rootDir, value)) {
+        continue;
+      }
+      const stripped = value.replace(/^\/+/, "");
+      if (!stripped.startsWith("usr/") && !stripped.startsWith("etc/") && !stripped.startsWith("var/")) {
+        nextArgs = { ...nextArgs, [key]: stripped };
+      }
+    }
+    return nextArgs;
+  }
+
+  private static expandPlaceholders(
+    rootDir: string,
+    skillRoots: string[],
+    args: ToolArgs,
+    skillPathMap?: Record<string, string>,
+  ): ToolArgs {
+    let nextArgs: ToolArgs = { ...args };
+    for (const [key, value] of Object.entries(nextArgs)) {
+      if (typeof value === "string") {
+        nextArgs = {
+          ...nextArgs,
+          [key]: this.expandStringPlaceholders(rootDir, skillRoots, value, skillPathMap),
+        };
+      }
+    }
+    return nextArgs;
+  }
+
+  private static expandStringPlaceholders(
+    rootDir: string,
+    skillRoots: string[],
+    value: string,
+    skillPathMap?: Record<string, string>,
+  ): string {
+    let nextValue = value.replaceAll("${WORKSPACE}", rootDir.replace(/\\/g, "/"));
+    nextValue = nextValue.replace(/\$\{SKILL_PATH(?::([^}]+))?\}/g, (_match, skillName: string | undefined) => {
+      const resolved = this.resolveSkillPathPlaceholder(skillRoots, skillName, skillPathMap);
+      return resolved ?? _match;
+    });
+    return nextValue;
+  }
+
+  private static resolveSkillPathPlaceholder(
+    skillRoots: string[],
+    skillName: string | undefined,
+    skillPathMap?: Record<string, string>,
+  ): string | null {
+    if (skillName && skillPathMap?.[skillName]) {
+      return skillPathMap[skillName]!;
+    }
+    const normalizedRoots = skillRoots.map((root) => root.replace(/\\/g, "/"));
+    if (skillName) {
+      const matches = normalizedRoots.filter((root) => basename(root) === skillName);
+      return matches.length === 1 ? matches[0]! : null;
+    }
+    return normalizedRoots.length === 1 ? normalizedRoots[0]! : null;
+  }
+
+  private static shouldNormalizePath(value: unknown): value is string {
+    return typeof value === "string" && value.startsWith("/") && !value.startsWith("//");
+  }
+
+  private static isResolvableAbsolutePath(rootDir: string, value: string): boolean {
+    return value === rootDir ||
+      value.startsWith(`${rootDir}/`) ||
+      existsSync(value) ||
+      existsSync(dirname(value));
+  }
+
+  private static tokenizeCommand(command: string): string[] {
+    const parts: string[] = [];
+    let current = "";
+    let quote: "'" | "\"" | null = null;
+    let escaped = false;
+
+    for (const char of command) {
+      if (escaped) {
+        current += char;
+        escaped = false;
+        continue;
+      }
+      if (char === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (quote) {
+        if (char === quote) {
+          quote = null;
+        } else {
+          current += char;
+        }
+        continue;
+      }
+      if (char === "'" || char === "\"") {
+        quote = char;
+        continue;
+      }
+      if (/\s/.test(char)) {
+        if (current) {
+          parts.push(current);
+          current = "";
+        }
+        continue;
+      }
+      current += char;
+    }
+
+    if (current) {
+      parts.push(current);
+    }
+    return parts;
+  }
+
+  private static resolveSkillRelativeCommandArg(rootDir: string, skillRoots: string[], value: string): string {
+    if (!this.looksLikeRelativePath(value) || value.startsWith("./") || value.startsWith("../")) {
+      return value;
+    }
+    if (existsSync(resolve(rootDir, value))) {
+      return value;
+    }
+
+    const matches = skillRoots
+      .map((skillRoot) => resolve(skillRoot, value))
+      .filter((candidate) => existsSync(candidate));
+    if (matches.length !== 1) {
+      return value;
+    }
+
+    const rel = relative(rootDir, matches[0]!).replace(/\\/g, "/");
+    return rel && !rel.startsWith("..") ? rel : matches[0]!.replace(/\\/g, "/");
+  }
+
+  private static looksLikeRelativePath(value: string): boolean {
+    return value.includes("/") && !value.startsWith("/") && !value.startsWith("~") && !value.startsWith("-");
+  }
+
+  private static quoteCommandPart(value: string): string {
+    return /^[A-Za-z0-9_./:@=-]+$/.test(value)
+      ? value
+      : `'${value.replace(/'/g, `'\\''`)}'`;
+  }
+
+  private static normalizeWriteTodosArgs(args: ToolArgs, nextArgs: ToolArgs): ToolArgs {
+    if (!Array.isArray(args.todos)) {
+      const text = this.extractTodoText(args);
+      if (!text) {
+        return nextArgs;
+      }
+      return {
+        ...nextArgs,
+        todos: [{
+          content: text,
+          status: args.status === "in_progress" || args.status === "completed" ? args.status : "pending",
+        }],
+      };
+    }
+
+    return {
+      ...nextArgs,
+      todos: args.todos.map((todo) => this.normalizeTodo(todo)),
+    };
+  }
+
+  private static extractTodoText(args: ToolArgs): string | null {
+    if (typeof args.description === "string") {
+      return args.description;
+    }
+    if (typeof args.content === "string") {
+      return args.content;
+    }
+    return null;
+  }
+
+  private static normalizeTodo(todo: unknown): { content: string; status: "pending" | "in_progress" | "completed" } {
+    if (typeof todo === "string") {
+      return { content: todo, status: "pending" };
+    }
+    if (!todo || typeof todo !== "object") {
+      return { content: JSON.stringify(todo), status: "pending" };
+    }
+
+    const candidate = todo as { content?: unknown; description?: unknown; status?: unknown };
+    const content = typeof candidate.content === "string"
+      ? candidate.content
+      : typeof candidate.description === "string"
+        ? candidate.description
+        : JSON.stringify(todo);
+    const status = candidate.status === "in_progress" || candidate.status === "completed"
+      ? candidate.status
+      : "pending";
+    return { content, status };
+  }
+
+  public static resolveScriptSourcePath(rootDir: string, value: string): string {
+    const normalized = value.replace(/\\/g, "/");
+    return normalized.startsWith("/")
+      ? normalized
+      : resolve(rootDir, normalized).replace(/\\/g, "/");
+  }
+}

package/src/runtime/middleware/toolCallGuard.ts

@@ -0,0 +1,73 @@
+import { CommandPolicy } from "./commandPolicy.js";
+import { ToolArgsNormalizer } from "./toolArgsNormalizer.js";
+import { TOOL_PATH_ARG_KEYS, type ToolArgs, type ToolMessageConstructorLike, type ToolMessageLike } from "./types.js";
+
+export class ToolCallGuard {
+  public static maybeBlock(
+    name: string,
+    args: ToolArgs,
+    toolCallId: string | undefined,
+    ToolMessage: ToolMessageConstructorLike,
+    rootDir: string,
+    allowedToolNames?: string[],
+    allowedPathPrefixes: string[] = [],
+  ): ToolMessageLike | null {
+    if (allowedToolNames?.length && !this.isToolAllowed(name, allowedToolNames)) {
+      return new ToolMessage({
+        content: `Error: Tool "${name}" is not allowed by tool config allowlist.`,
+        tool_call_id: toolCallId ?? name,
+      });
+    }
+    if ((name === "read_file" || name === "edit_file") && this.isScriptSourcePath(args, rootDir)) {
+      return new ToolMessage({
+        content: "Error: Do not inspect script source files unless the user explicitly asks for script code.",
+        tool_call_id: toolCallId ?? name,
+      });
+    }
+    if (this.hasAbsolutePathArgOutsideWorkspace(args, rootDir, allowedPathPrefixes)) {
+      return new ToolMessage({
+        content: "Error: Do not use absolute filesystem paths outside workspace root. Use workspace-relative paths only.",
+        tool_call_id: toolCallId ?? name,
+      });
+    }
+    if (name === "execute" && typeof args.command === "string") {
+      return CommandPolicy.maybeBlockExecuteCommand(args.command, toolCallId, ToolMessage, rootDir, allowedPathPrefixes);
+    }
+    return null;
+  }
+
+  private static isToolAllowed(name: string, allowedToolNames: string[]): boolean {
+    if (allowedToolNames.includes(name)) return true;
+    return allowedToolNames.some((allowed) => {
+      const normalized = allowed.trim();
+      return Boolean(normalized && !normalized.includes(".") && name.endsWith(`.${normalized}`));
+    });
+  }
+
+  private static hasAbsolutePathArgOutsideWorkspace(
+    args: ToolArgs,
+    rootDir: string,
+    allowedPathPrefixes: string[],
+  ): boolean {
+    const normalizedRoot = rootDir.replace(/\\/g, "/");
+    const normalizedAllowed = allowedPathPrefixes.map((entry) => entry.replace(/\\/g, "/"));
+    return TOOL_PATH_ARG_KEYS.some((key) => {
+      const value = args[key];
+      if (typeof value !== "string") return false;
+      const path = value.replace(/\\/g, "/");
+      return path.startsWith("/") &&
+        !path.startsWith("//") &&
+        path !== normalizedRoot &&
+        !path.startsWith(`${normalizedRoot}/`) &&
+        !normalizedAllowed.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+    });
+  }
+
+  private static isScriptSourcePath(args: ToolArgs, rootDir: string): boolean {
+    return TOOL_PATH_ARG_KEYS.some((key) => {
+      const value = args[key];
+      return typeof value === "string" &&
+        ToolArgsNormalizer.resolveScriptSourcePath(rootDir, value).includes("/scripts/");
+    });
+  }
+}

package/src/runtime/middleware/toolFsHandlers.ts

@@ -0,0 +1,94 @@
+import { lstat, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { MAX_LS_ENTRIES, type ToolArgs } from "./types.js";
+
+export class ToolFsHandlers {
+  public static async expandEditFileContent(rootDir: string, args: ToolArgs): Promise<ToolArgs> {
+    if (
+      typeof args.content !== "string" ||
+      !(args.file_path ?? args.path) ||
+      "old_string" in args
+    ) {
+      return args;
+    }
+
+    const relPath = String(args.file_path ?? args.path);
+    const absPath = resolve(rootDir, relPath);
+    const oldContent = await readFile(absPath, "utf8").catch(() => "");
+    return { ...args, file_path: relPath, old_string: oldContent, new_string: args.content };
+  }
+
+  public static async handleWriteFile(
+    rootDir: string,
+    args: ToolArgs,
+    logger: (message: string) => void,
+  ): Promise<{ content: string } | null> {
+    const targetPath = args.file_path ?? args.path;
+    if (typeof targetPath !== "string") {
+      return null;
+    }
+
+    const absPath = targetPath.startsWith("/") ? targetPath : resolve(rootDir, targetPath);
+    if (absPath !== rootDir && !absPath.startsWith(`${rootDir}/`)) {
+      return null;
+    }
+
+    const content = String(args.content);
+    if (/\.json$/i.test(absPath)) {
+      try {
+        JSON.parse(content);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: `Error: invalid JSON for '${targetPath}': ${message}` };
+      }
+    }
+
+    await mkdir(dirname(absPath), { recursive: true });
+    await writeFile(absPath, content, "utf8");
+    logger(`[tool] write_file: ${targetPath} (${content.length} chars)`);
+    logger("[tool] write_file done in 0ms");
+    return { content: `Successfully wrote to '${targetPath}'` };
+  }
+
+  public static async handleListFiles(rootDir: string, args: ToolArgs): Promise<{ content: string } | null> {
+    const requestedPath = typeof args.path === "string" && args.path.trim() ? args.path.trim() : ".";
+    const absPath = requestedPath.startsWith("/") ? requestedPath : resolve(rootDir, requestedPath);
+    if (absPath !== rootDir && !absPath.startsWith(`${rootDir}/`)) {
+      return { content: `Error: path '${requestedPath}' is outside workspace root` };
+    }
+
+    const info = await lstat(absPath).catch(() => null);
+    if (!info) {
+      return { content: `Error: path '${requestedPath}' does not exist` };
+    }
+    if (!info.isDirectory()) {
+      const size = typeof info.size === "number" ? `${info.size} bytes` : "unknown size";
+      return { content: `${requestedPath === "." ? "." : requestedPath}\n[file] ${size}` };
+    }
+
+    const entries = await readdir(absPath, { withFileTypes: true }).catch(() => null);
+    if (!entries) {
+      return { content: `Error: unable to list '${requestedPath}'` };
+    }
+
+    const lines = entries
+      .sort((a, b) => this.compareEntries(a.isDirectory(), b.isDirectory(), a.name, b.name))
+      .slice(0, MAX_LS_ENTRIES)
+      .map((entry) => `${entry.name}${entry.isDirectory() ? "/" : entry.isSymbolicLink() ? "@" : ""}`);
+    const truncated = entries.length > MAX_LS_ENTRIES
+      ? `\n... truncated ${entries.length - MAX_LS_ENTRIES} more entries`
+      : "";
+    return {
+      content: `${requestedPath === "." ? "." : requestedPath}\n${lines.join("\n")}${truncated}`,
+    };
+  }
+
+  private static compareEntries(aIsDirectory: boolean, bIsDirectory: boolean, aName: string, bName: string): number {
+    const aRank = aIsDirectory ? 0 : 1;
+    const bRank = bIsDirectory ? 0 : 1;
+    if (aRank !== bRank) {
+      return aRank - bRank;
+    }
+    return aName.localeCompare(bName);
+  }
+}

package/src/runtime/middleware/toolRequestParser.ts

@@ -0,0 +1,84 @@
+import type {
+  MiddlewareRequest,
+  ToolArgs,
+  ToolCallAfterHookContext,
+  ToolCallHookContext,
+} from "./types.js";
+
+export class ToolRequestParser {
+  public static toMiddlewareRequest(request: unknown): MiddlewareRequest {
+    if (!request || typeof request !== "object") {
+      throw new Error("Invalid tool call request");
+    }
+    const candidate = request as Partial<MiddlewareRequest>;
+    if (!candidate.toolCall || typeof candidate.toolCall.name !== "string") {
+      throw new Error("Invalid tool call request");
+    }
+
+    return {
+      ...candidate,
+      threadId: this.extractThreadId(candidate),
+      toolCall: {
+        id: candidate.toolCall.id,
+        name: candidate.toolCall.name,
+        args: candidate.toolCall.args,
+      },
+    };
+  }
+
+  public static toToolArgs(args: unknown): ToolArgs {
+    if (!args || typeof args !== "object") {
+      return {};
+    }
+    return args as ToolArgs;
+  }
+
+  public static toHookRequest(request: MiddlewareRequest): ToolCallHookContext["request"] {
+    return {
+      toolCall: {
+        id: request.toolCall.id,
+        name: request.toolCall.name,
+        args: request.toolCall.args,
+      },
+    };
+  }
+
+  public static toAfterHookRequest(request: MiddlewareRequest): ToolCallAfterHookContext["request"] {
+    return {
+      toolCall: {
+        id: request.toolCall.id,
+        name: request.toolCall.name,
+        args: request.toolCall.args,
+      },
+    };
+  }
+
+  public static toModelRequest(request: unknown): Record<string, unknown> & { systemPrompt?: string; threadId?: string } {
+    if (!request || typeof request !== "object") {
+      throw new Error("Invalid model request");
+    }
+
+    const candidate = request as Record<string, unknown>;
+    return {
+      ...candidate,
+      systemPrompt: typeof candidate.systemPrompt === "string" ? candidate.systemPrompt : undefined,
+      threadId: this.extractThreadId(candidate),
+    };
+  }
+
+  private static extractThreadId(candidate: Record<string, unknown>): string | undefined {
+    const direct = this.readThreadId(candidate.configurable);
+    if (direct) return direct;
+    const config = candidate.config;
+    if (config && typeof config === "object") {
+      return this.readThreadId((config as { configurable?: unknown }).configurable);
+    }
+    return undefined;
+  }
+
+  private static readThreadId(value: unknown): string | undefined {
+    if (!value || typeof value !== "object") return undefined;
+    const threadId = (value as { thread_id?: unknown }).thread_id;
+    return typeof threadId === "string" && threadId.trim().length > 0 ? threadId : undefined;
+  }
+}

package/src/runtime/middleware/types.ts

@@ -0,0 +1,91 @@
+import type {
+  HumanLoopService,
+  HumanLoopToolPolicy,
+} from "../human-loop/humanLoop.js";
+
+export const TOOL_PATH_ARG_KEYS = ["file_path", "path"] as const;
+export const MAX_LS_ENTRIES = 200;
+
+export type ToolArgs = Record<string, unknown>;
+export type AgentMiddlewareLike = unknown;
+export type ToolMessageLike = unknown;
+
+export interface RequestToolCall {
+  id?: string;
+  name: string;
+  args?: unknown;
+}
+
+export interface MiddlewareRequest extends Record<string, unknown> {
+  toolCall: RequestToolCall;
+  threadId?: string;
+}
+
+export interface CreateMiddlewareLike {
+  (definition: {
+    name: string;
+    wrapToolCall: (request: unknown, handler: (request: unknown) => unknown) => unknown;
+    wrapModelCall?: (request: unknown, handler: (request: unknown) => unknown) => unknown;
+  }): AgentMiddlewareLike;
+}
+
+export interface ToolMessageConstructorLike {
+  new (fields: { content: string; tool_call_id: string }): ToolMessageLike;
+}
+
+export interface ToolCallHookContext {
+  threadId?: string;
+  name: string;
+  args: ToolArgs;
+  nextArgs: ToolArgs;
+  request: {
+    toolCall: {
+      id?: string;
+      name: string;
+      args: unknown;
+    };
+  };
+  rootDir: string;
+}
+
+export interface ToolCallAfterHookContext {
+  threadId?: string;
+  name: string;
+  args: ToolArgs;
+  result: unknown;
+  request: {
+    toolCall: {
+      id?: string;
+      name: string;
+      args: unknown;
+    };
+  };
+  rootDir: string;
+}
+
+export interface CreateAgentToolMiddlewareOptions {
+  rootDir: string;
+  skillRoots?: string[];
+  skillPathMap?: Record<string, string>;
+  createMiddleware: CreateMiddlewareLike;
+  ToolMessage: ToolMessageConstructorLike;
+  events?: {
+    emit(event: {
+      name: string;
+      from: string;
+      to: string;
+      payload?: Record<string, unknown>;
+    }): void;
+  };
+  executeTimeoutMs?: number;
+  blockTaskTool?: boolean;
+  allowedToolNames?: string[];
+  logger?: (message: string) => void;
+  persistTodos?: (todos: unknown[]) => Promise<void> | void;
+  humanLoop?: HumanLoopService;
+  humanLoopToolPolicy?: HumanLoopToolPolicy;
+  beforeToolCall?: (
+    context: ToolCallHookContext
+  ) => Promise<{ args?: ToolArgs; result?: ToolMessageLike } | void> | { args?: ToolArgs; result?: ToolMessageLike } | void;
+  afterToolCall?: (context: ToolCallAfterHookContext) => Promise<void> | void;
+}