@botbotgo/runtime 1.0.0

package/src/runtime/middleware/agentToolMiddleware.ts

@@ -0,0 +1,329 @@
+import type { AgentRuntimeEventPublisher } from "../events/eventPublisher.js";
+import type { HumanLoopDecision, HumanLoopRequest } from "../human-loop/humanLoop.js";
+import { FrameworkPrompt } from "./frameworkPrompt.js";
+import { ToolArgsNormalizer } from "./toolArgsNormalizer.js";
+import { ToolCallGuard } from "./toolCallGuard.js";
+import { ToolFsHandlers } from "./toolFsHandlers.js";
+import { ToolRequestParser } from "./toolRequestParser.js";
+import { buildSkillPathMap, expandSkillRoots } from "./skillPathMap.js";
+import type {
+  AgentMiddlewareLike,
+  CreateAgentToolMiddlewareOptions,
+  ToolArgs,
+} from "./types.js";
+
+export class AgentToolMiddlewareFactory {
+  private readonly rootDir: string;
+  private readonly skillRoots: string[];
+  private readonly skillPathMap: Record<string, string>;
+  private readonly createMiddleware: CreateAgentToolMiddlewareOptions["createMiddleware"];
+  private readonly ToolMessage: CreateAgentToolMiddlewareOptions["ToolMessage"];
+  private readonly events?: AgentRuntimeEventPublisher;
+  private readonly executeTimeoutMs: number;
+  private readonly blockTaskTool: boolean;
+  private readonly allowedToolNames?: string[];
+  private readonly logger: (message: string) => void;
+  private readonly persistTodos?: (todos: unknown[]) => Promise<void> | void;
+  private readonly humanLoop?: CreateAgentToolMiddlewareOptions["humanLoop"];
+  private readonly humanLoopToolPolicy?: CreateAgentToolMiddlewareOptions["humanLoopToolPolicy"];
+  private readonly beforeToolCall?: CreateAgentToolMiddlewareOptions["beforeToolCall"];
+  private readonly afterToolCall?: CreateAgentToolMiddlewareOptions["afterToolCall"];
+
+  public constructor(options: CreateAgentToolMiddlewareOptions) {
+    this.rootDir = options.rootDir;
+    this.skillRoots = expandSkillRoots(options.skillRoots ?? []);
+    this.skillPathMap = options.skillPathMap ?? buildSkillPathMap(this.skillRoots);
+    this.createMiddleware = options.createMiddleware;
+    this.ToolMessage = options.ToolMessage;
+    this.events = options.events as AgentRuntimeEventPublisher | undefined;
+    this.executeTimeoutMs = options.executeTimeoutMs ?? 60_000;
+    this.blockTaskTool = options.blockTaskTool ?? false;
+    this.allowedToolNames = options.allowedToolNames?.filter((name) => typeof name === "string" && name.trim().length > 0);
+    this.logger = options.logger ?? (() => {});
+    this.persistTodos = options.persistTodos;
+    this.humanLoop = options.humanLoop;
+    this.humanLoopToolPolicy = options.humanLoopToolPolicy;
+    this.beforeToolCall = options.beforeToolCall;
+    this.afterToolCall = options.afterToolCall;
+  }
+
+  public create(): AgentMiddlewareLike {
+    return this.createMiddleware({
+      name: "AgentToolMiddleware",
+      wrapModelCall: async (request, handler) => this.wrapModelCall(request, handler),
+      wrapToolCall: async (request, handler) => this.wrapToolCall(request, handler),
+    });
+  }
+
+  private async wrapModelCall(request: unknown, handler: (request: unknown) => unknown): Promise<unknown> {
+    const modelRequest = ToolRequestParser.toModelRequest(request);
+    return handler({
+      ...modelRequest,
+      systemPrompt: FrameworkPrompt.build(
+        modelRequest.systemPrompt,
+        this.blockTaskTool,
+        this.allowedToolNames,
+        this.skillPathMap,
+      ),
+    });
+  }
+
+  private async wrapToolCall(request: unknown, handler: (request: unknown) => unknown): Promise<unknown> {
+    const toolRequest = ToolRequestParser.toMiddlewareRequest(request);
+    const name = toolRequest.toolCall.name;
+    const toolCallId = toolRequest.toolCall.id;
+
+    if (this.blockTaskTool && name === "task") {
+      this.events?.emit({
+        name: "agent.runtime2.tool.call.blocked",
+        from: "agent-runtime2.middleware",
+        to: name,
+        payload: { toolCallId, reason: "task_tool_disabled" },
+      });
+      return new this.ToolMessage({
+        content: "Error: Do not use the task tool. Use execute(), write_file(), and read_file() directly.",
+        tool_call_id: toolCallId ?? "blocked",
+      });
+    }
+
+    const args = ToolRequestParser.toToolArgs(toolRequest.toolCall.args);
+    const blocked = ToolCallGuard.maybeBlock(
+      name,
+      args,
+      toolCallId,
+      this.ToolMessage,
+      this.rootDir,
+      this.allowedToolNames,
+      Object.values(this.skillPathMap),
+    );
+    if (blocked) {
+      this.events?.emit({
+        name: "agent.runtime2.tool.call.blocked",
+        from: "agent-runtime2.middleware",
+        to: name,
+        payload: { toolCallId, args, reason: "policy_violation" },
+      });
+      return blocked;
+    }
+
+    let nextArgs = ToolArgsNormalizer.normalizeToolArgs(
+      this.rootDir,
+      this.skillRoots,
+      name,
+      args,
+      this.skillPathMap,
+    );
+    nextArgs = await this.expandSyntheticFileEdits(name, nextArgs);
+
+    const syntheticResult = await this.handleSyntheticToolResponse(name, toolRequest.toolCall.id, nextArgs);
+    if (syntheticResult) {
+      return syntheticResult;
+    }
+
+    const humanLoopResult = await this.requestHumanApprovalIfNeeded(toolRequest, name, nextArgs);
+    if (humanLoopResult?.result) {
+      return humanLoopResult.result;
+    }
+    if (humanLoopResult?.args) {
+      nextArgs = humanLoopResult.args;
+    }
+
+    const override = await this.beforeToolCall?.({
+      threadId: toolRequest.threadId,
+      name,
+      args,
+      nextArgs,
+      request: ToolRequestParser.toHookRequest(toolRequest),
+      rootDir: this.rootDir,
+    });
+    if (override?.result) {
+      return override.result;
+    }
+    if (override?.args) {
+      nextArgs = override.args;
+    }
+
+    return this.invokeToolHandler(toolRequest, name, nextArgs, handler);
+  }
+
+  private async expandSyntheticFileEdits(name: string, args: ToolArgs): Promise<ToolArgs> {
+    if (name !== "edit_file") {
+      return args;
+    }
+    return ToolFsHandlers.expandEditFileContent(this.rootDir, args);
+  }
+
+  private async handleSyntheticToolResponse(
+    name: string,
+    toolCallId: string | undefined,
+    args: ToolArgs,
+  ): Promise<unknown | null> {
+    if (name === "write_file" && typeof args.content === "string") {
+      const result = await ToolFsHandlers.handleWriteFile(this.rootDir, args, this.logger);
+      if (result) {
+        return new this.ToolMessage({ content: result.content, tool_call_id: toolCallId ?? "write_file" });
+      }
+    }
+    if (name === "ls" || name === "inspect_files") {
+      const result = await ToolFsHandlers.handleListFiles(this.rootDir, args);
+      if (result) {
+        this.logger(`[tool] ${name}: ${String(args.path ?? ".")}`);
+        this.logger(`[tool] ${name} done in 0ms`);
+        return new this.ToolMessage({ content: result.content, tool_call_id: toolCallId ?? name });
+      }
+    }
+    return null;
+  }
+
+  private async invokeToolHandler(
+    toolRequest: ReturnType<typeof ToolRequestParser.toMiddlewareRequest>,
+    name: string,
+    nextArgs: ToolArgs,
+    handler: (request: unknown) => unknown,
+  ): Promise<unknown> {
+    this.events?.emit({
+      name: "agent.runtime2.tool.call.start",
+      from: "agent-runtime2.middleware",
+      to: name,
+      payload: { toolCallId: toolRequest.toolCall.id, args: nextArgs },
+    });
+    this.logToolStart(name, nextArgs);
+
+    const startedAt = Date.now();
+    try {
+      const result = await this.runTool(name, nextArgs, toolRequest, handler);
+      const durationMs = Date.now() - startedAt;
+      this.logger(`[tool] ${name} done in ${durationMs}ms`);
+      if (name === "write_todos" && Array.isArray(nextArgs.todos)) {
+        await this.persistTodos?.(nextArgs.todos);
+      }
+      await this.afterToolCall?.({
+        threadId: toolRequest.threadId,
+        name,
+        args: nextArgs,
+        result,
+        request: ToolRequestParser.toAfterHookRequest(toolRequest),
+        rootDir: this.rootDir,
+      });
+      this.events?.emit({
+        name: "agent.runtime2.tool.call.done",
+        from: name,
+        to: "agent-runtime2.middleware",
+        payload: { toolCallId: toolRequest.toolCall.id, args: nextArgs, durationMs, result },
+      });
+      return result;
+    } catch (error) {
+      this.events?.emit({
+        name: "agent.runtime2.tool.call.error",
+        from: name,
+        to: "agent-runtime2.middleware",
+        payload: {
+          toolCallId: toolRequest.toolCall.id,
+          args: nextArgs,
+          durationMs: Date.now() - startedAt,
+          error: error instanceof Error ? error.message : String(error),
+        },
+      });
+      throw error;
+    }
+  }
+
+  private async requestHumanApprovalIfNeeded(
+    toolRequest: ReturnType<typeof ToolRequestParser.toMiddlewareRequest>,
+    name: string,
+    args: ToolArgs,
+  ): Promise<{ args?: ToolArgs; result?: unknown } | void> {
+    const request = this.humanLoopToolPolicy?.buildRequest({
+      threadId: toolRequest.threadId,
+      toolCallId: toolRequest.toolCall.id,
+      toolName: name,
+      args,
+      rootDir: this.rootDir,
+    });
+    if (!request || !this.humanLoop) {
+      return;
+    }
+
+    this.events?.emit({
+      name: "agent.runtime2.human_loop.requested",
+      from: "agent-runtime2.middleware",
+      to: "human",
+      payload: request,
+    });
+    const decision = await this.humanLoop.request(request);
+    this.events?.emit({
+      name: "agent.runtime2.human_loop.resolved",
+      from: "human",
+      to: "agent-runtime2.middleware",
+      payload: {
+        request,
+        decision,
+      },
+    });
+
+    return this.resolveHumanLoopDecision(toolRequest.toolCall.id, request, decision);
+  }
+
+  private resolveHumanLoopDecision(
+    toolCallId: string | undefined,
+    request: HumanLoopRequest,
+    decision: HumanLoopDecision,
+  ): { args?: ToolArgs; result?: unknown } {
+    if (decision.action === "approve") {
+      return decision.revisedArgs ? { args: decision.revisedArgs } : {};
+    }
+    if (decision.action === "revise") {
+      if (decision.revisedArgs) {
+        return { args: decision.revisedArgs };
+      }
+      return {
+        result: new this.ToolMessage({
+          content: decision.message ?? "Error: human review requested revised args but none were provided.",
+          tool_call_id: toolCallId ?? request.id,
+        }),
+      };
+    }
+    return {
+      result: new this.ToolMessage({
+        content: decision.message ?? `Rejected by human reviewer for tool ${request.toolName}.`,
+        tool_call_id: toolCallId ?? request.id,
+      }),
+    };
+  }
+
+  private async runTool(
+    name: string,
+    nextArgs: ToolArgs,
+    toolRequest: ReturnType<typeof ToolRequestParser.toMiddlewareRequest>,
+    handler: (request: unknown) => unknown,
+  ): Promise<unknown> {
+    const runPromise = Promise.resolve(handler({
+      ...toolRequest,
+      toolCall: { ...toolRequest.toolCall, args: nextArgs },
+    }));
+    if (name !== "execute") {
+      return runPromise;
+    }
+    return Promise.race([
+      runPromise,
+      new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error(`execute timeout after ${this.executeTimeoutMs / 1000}s`)), this.executeTimeoutMs)
+      ),
+    ]);
+  }
+
+  private logToolStart(name: string, args: ToolArgs): void {
+    if (name === "execute" && typeof args.command === "string") {
+      const command = args.command.length > 120 ? `${args.command.slice(0, 117)}…` : args.command;
+      this.logger(`[tool] execute: ${command}`);
+      return;
+    }
+    if (name === "write_file") {
+      const filePath = String(args.file_path ?? args.path ?? "");
+      const length = typeof args.content === "string" ? args.content.length : 0;
+      this.logger(`[tool] write_file: ${filePath} (${length} chars)`);
+      return;
+    }
+    this.logger(`[tool] ${name}`);
+  }
+}

package/src/runtime/middleware/commandPolicy.ts

@@ -0,0 +1,65 @@
+import type { ToolMessageConstructorLike, ToolMessageLike } from "./types.js";
+
+export class CommandPolicy {
+  public static maybeBlockExecuteCommand(
+    command: string,
+    toolCallId: string | undefined,
+    ToolMessage: ToolMessageConstructorLike,
+    rootDir: string,
+    allowedPathPrefixes: string[] = [],
+  ): ToolMessageLike | null {
+    const message = this.getViolationMessage(command, rootDir, allowedPathPrefixes);
+    return message ? new ToolMessage({ content: message, tool_call_id: toolCallId ?? "execute" }) : null;
+  }
+
+  private static getViolationMessage(command: string, rootDir: string, allowedPathPrefixes: string[]): string | null {
+    if (/\bls\b/.test(command) && command.includes("?")) {
+      return "Error: Do not run fuzzy ls probes with unknown paths. Continue with known workflow commands.";
+    }
+    if ((/\bbash\b/i.test(command) || /\/bin\/bash\b/i.test(command) || /\bzsh\b/i.test(command)) && command.includes("/scripts/")) {
+      return "Error: Do not wrap skill scripts with `bash`. Execute the script path directly.";
+    }
+    if (/\bchmod\s+\+x\b/i.test(command)) {
+      return "Error: Do not run chmod +x. Use direct execution of the target command or script.";
+    }
+    if (/\b(?:ba)?sh\s+-lc\b/i.test(command)) {
+      return "Error: Do not wrap command execution with shell -lc. Execute the target command directly.";
+    }
+    if (/\b(curl|wget)\b/i.test(command)) {
+      return "Error: Do not execute direct network fetch commands. Use provided scripts/tools and then write results with write_file/edit_file.";
+    }
+    if (/\|\s*reportgen\b/i.test(command)) {
+      return "Error: Do not pipe output to ad-hoc generators. Use write_file/edit_file for artifact generation.";
+    }
+    if (/(^|[\s;|&])(?:echo|cat|printf)[^|&;]*>\s*[^\s]+/i.test(command)) {
+      return "Error: Do not write files via shell redirection in execute. Use write_file/edit_file tools.";
+    }
+    return this.containsAbsolutePathOutsideWorkspace(command, rootDir, allowedPathPrefixes)
+      ? "Error: Do not execute commands with absolute paths outside workspace root. Use workspace-relative paths only."
+      : null;
+  }
+
+  private static containsAbsolutePathOutsideWorkspace(
+    command: string,
+    rootDir: string,
+    allowedPathPrefixes: string[],
+  ): boolean {
+    const normalizedRoot = rootDir.replace(/\\/g, "/");
+    const normalizedAllowed = allowedPathPrefixes.map((entry) => entry.replace(/\\/g, "/"));
+    const pathLikeMatches = [...command.matchAll(/(?:^|[\s=>(;|&])(["']?)(\/[^\s"'`<>|&;]+)\1/g)];
+    for (const match of pathLikeMatches) {
+      const pathToken = match[2];
+      if (!pathToken || pathToken.startsWith("//")) continue;
+      if (this.isSystemPath(pathToken)) continue;
+      if (pathToken === normalizedRoot || pathToken.startsWith(`${normalizedRoot}/`)) continue;
+      if (normalizedAllowed.some((prefix) => pathToken === prefix || pathToken.startsWith(`${prefix}/`))) continue;
+      return true;
+    }
+    return false;
+  }
+
+  private static isSystemPath(pathToken: string): boolean {
+    return ["/usr/", "/bin/", "/etc/", "/var/", "/dev/", "/proc/", "/System/", "/opt/"]
+      .some((prefix) => pathToken.startsWith(prefix));
+  }
+}

package/src/runtime/middleware/frameworkPrompt.ts

@@ -0,0 +1,51 @@
+export class FrameworkPrompt {
+  public static build(
+    currentPrompt: string | undefined,
+    blockTaskTool: boolean,
+    allowedToolNames?: string[],
+    skillPathMap?: Record<string, string>,
+  ): string {
+    const baseRules = [
+      "Framework execution rules:",
+      "- Follow SKILL instructions exactly as the source of truth.",
+      "- Execute required workflow steps in order; do not skip required steps.",
+      "- Do not add extra exploratory or redundant operations outside the SKILL workflow.",
+      "- Support both tool calls and script commands: use whichever the SKILL explicitly allows for each step.",
+      "- If a SKILL allows both tool and script for the same step, prefer the safer/more structured tool path.",
+      "- For independent operations with no data dependency, prefer parallel tool calls to reduce latency.",
+      "- Do not stop after intermediate reads/planning. Continue autonomously until required outputs are produced.",
+      '- Return strict JSON for tool arguments (example: {"offset":0}, never "offset=0").',
+      "- Use workspace-relative paths only; do not invent absolute filesystem paths unless provided by runtime placeholders.",
+      "- Do not inspect script source files unless explicitly requested.",
+      "- Runtime path variable `${WORKSPACE}` expands to the workspace root.",
+    ];
+
+    if (blockTaskTool) {
+      baseRules.push("- The task tool is disabled. Never call task; complete work using available file and execute tools.");
+    }
+    if (allowedToolNames?.length) {
+      baseRules.push(`- Tool allowlist is enforced by config. Only call these tools: ${allowedToolNames.join(", ")}.`);
+    }
+
+    const skillEntries = Object.entries(skillPathMap ?? {});
+    if (skillEntries.length > 0) {
+      baseRules.push("- Active skills for this run:");
+      for (const [skillId, skillPath] of skillEntries) {
+        baseRules.push(`  - ${skillId} => ${skillPath}`);
+      }
+      baseRules.push("- Use `${SKILL_PATH:<skill-id>}` to reference a specific skill directory from the active skill mapping above.");
+      if (skillEntries.length === 1) {
+        baseRules.push("- Because only one skill is active, `${SKILL_PATH}` also resolves to that skill directory.");
+      }
+      baseRules.push("- `${SKILL_PATH...}` is only for skill-owned assets such as scripts/, references/, templates, and static inputs explicitly required by the SKILL.");
+      baseRules.push("- Do not use `${SKILL_PATH...}` for exploration, listing, globbing, discovery, or inspection. Do not call ls/glob/read_file on a skill path unless the user explicitly asks for skill source or contents.");
+      baseRules.push("- If a SKILL provides an explicit script command using `${SKILL_PATH...}` and `${WORKSPACE}`, execute that command directly instead of exploring the skill directory first.");
+    }
+
+    const frameworkPrompt = baseRules.join("\n");
+    if (!currentPrompt?.trim() || currentPrompt.includes("Framework execution rules:")) {
+      return currentPrompt?.trim() ? currentPrompt : frameworkPrompt;
+    }
+    return `${currentPrompt}\n\n${frameworkPrompt}`;
+  }
+}

package/src/runtime/middleware/index.ts

@@ -0,0 +1,7 @@
+export { AgentToolMiddlewareFactory } from "./agentToolMiddleware.js";
+export { buildSkillPathMap } from "./skillPathMap.js";
+export type {
+  CreateAgentToolMiddlewareOptions,
+  ToolCallAfterHookContext,
+  ToolCallHookContext,
+} from "./types.js";

package/src/runtime/middleware/skillPathMap.ts

@@ -0,0 +1,49 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+
+export function buildSkillPathMap(skillRoots: string[]): Record<string, string> {
+  const counts = new Map<string, number>();
+  const result: Record<string, string> = {};
+
+  for (const skillRoot of expandSkillRoots(skillRoots)) {
+    const normalizedRoot = skillRoot.replace(/\\/g, "/");
+    const baseName = sanitizeSkillId(basename(normalizedRoot) || "skill");
+    const seen = counts.get(baseName) ?? 0;
+    counts.set(baseName, seen + 1);
+    const id = seen === 0 ? baseName : `${baseName}_${seen + 1}`;
+    result[id] = normalizedRoot;
+  }
+
+  return result;
+}
+
+function sanitizeSkillId(value: string): string {
+  return value
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase() || "skill";
+}
+
+export function expandSkillRoots(skillRoots: string[]): string[] {
+  const expanded = skillRoots.flatMap((skillRoot) => {
+    const directSkill = join(skillRoot, "SKILL.md");
+    if (existsSync(directSkill)) {
+      return [skillRoot];
+    }
+
+    try {
+      return readdirSync(skillRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(skillRoot, entry.name))
+        .filter((entryPath) => {
+          const skillFile = join(entryPath, "SKILL.md");
+          return existsSync(skillFile) && statSync(entryPath).isDirectory();
+        });
+    } catch {
+      return [skillRoot];
+    }
+  });
+
+  return expanded.length > 0 ? expanded : skillRoots;
+}