Project: A Local Coding Agent with Safe Permissions

// A local coding agent: read-only tools, a workspace sandbox, and a human
// confirmation gate before anything on disk actually changes.
import { readFile, readdir } from "node:fs/promises";
import path from "node:path";

const CHAT_URL = "http://localhost:11434/api/chat";
const CHAT_MODEL = "qwen2.5-coder:7b";
const WORKSPACE_ROOT = path.resolve("./workspace");

// Reject any path that resolves outside the workspace, however it's phrased.
function resolveInWorkspace(relativePath: string): string {
  const resolved = path.resolve(WORKSPACE_ROOT, relativePath);
  if (!resolved.startsWith(WORKSPACE_ROOT + path.sep)) {
    throw new Error(`Path escapes workspace sandbox: ${relativePath}`);
  }
  return resolved;
}

// --- the allowlisted tool set: read-only / low-risk only ---
const tools = {
  async readFile(relativePath: string) {
    return readFile(resolveInWorkspace(relativePath), "utf-8");
  },
  async listDirectory(relativePath: string) {
    return readdir(resolveInWorkspace(relativePath));
  },
  async runTests() {
    // Runs the project's existing test command in a subprocess with a
    // timeout; output is returned as text, never executed as new code.
    return runShellWithTimeout("npm test", WORKSPACE_ROOT, 30_000);
  },
};

const toolSchema = [
  { name: "readFile", description: "Read a file's contents.", parameters: { path: "string" } },
  { name: "listDirectory", description: "List files in a directory.", parameters: { path: "string" } },
  { name: "runTests", description: "Run the project's test suite.", parameters: {} },
];

type ToolCall = { name: keyof typeof tools; arguments: Record<string, string> };
type AgentMessage = { role: "system" | "user" | "assistant" | "tool"; content: string };

// --- the tool-calling loop ---
export async function runAgent(userRequest: string): Promise<string> {
  const messages: AgentMessage[] = [
    {
      role: "system",
      content:
        "You are a coding assistant restricted to the current workspace. " +
        "Use the provided tools to gather real evidence before answering. " +
        "You may explain code, point at a likely bug, or propose a fix as " +
        "a diff -- but you must never claim a file was changed. Only a " +
        "human-approved confirmation step actually writes or deletes files.",
    },
    { role: "user", content: userRequest },
  ];

  for (let step = 0; step < 8; step++) {
    const res = await fetch(CHAT_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        model: CHAT_MODEL,
        stream: false,
        messages,
        tools: toolSchema,
      }),
    });
    if (!res.ok) throw new Error(`Agent request failed: ${res.status}`);

    const data = (await res.json()) as {
      message: { content: string; tool_calls?: ToolCall[] };
    };

    if (!data.message.tool_calls?.length) {
      return data.message.content; // plain answer -- loop ends here
    }

    for (const call of data.message.tool_calls) {
      const result = await tools[call.name](
        ...(Object.values(call.arguments) as [string]),
      );
      messages.push({ role: "tool", content: JSON.stringify(result) });
    }
  }

  return "Agent stopped after too many tool-call steps without an answer.";
}

// --- confirmation gate: called only after a human clicks "Approve" ---
// writeFile/deleteFile are never in `tools`, so the model cannot call them.
export async function applyApprovedChange(
  relativePath: string,
  newContents: string,
): Promise<void> {
  const { writeFile } = await import("node:fs/promises");
  await writeFile(resolveInWorkspace(relativePath), newContents, "utf-8");
}

async function runShellWithTimeout(
  command: string,
  cwd: string,
  timeoutMs: number,
): Promise<string> {
  const { execFile } = await import("node:child_process");
  return new Promise((resolve) => {
    const child = execFile(command, { cwd, timeout: timeoutMs, shell: true });
    let output = "";
    child.stdout?.on("data", (d) => (output += d));
    child.stderr?.on("data", (d) => (output += d));
    child.on("close", () => resolve(output));
  });
}