@kevin5251984/guild 0.2.12

package/src/harness.ts

@@ -0,0 +1,326 @@
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { ToolContext, ToolOutcome, ToolTrace } from "./tools.ts";
+
+/**
+ * Codex-shaped sandbox names. Default is full_access (today's unsandboxed tools).
+ * This is the first Harness cut: a gate around executeTool, not Codex app-server.
+ */
+export const SANDBOX_MODES = [
+  "read_only",
+  "workspace_write",
+  "full_access",
+] as const;
+
+export type Sandbox = (typeof SANDBOX_MODES)[number];
+
+export type HarnessPolicy = {
+  sandbox: Sandbox;
+  workspace: string;
+};
+
+export type SandboxRefusal = { text: string; isError: true };
+
+const HOME = homedir();
+/** `packages/daemon` (this file lives in `src/`). */
+const DAEMON_DIR = fileURLToPath(new URL("..", import.meta.url));
+
+/** Guild checkout (parent of `packages/`). */
+export function defaultWorkspace(): string {
+  return resolve(DAEMON_DIR, "..", "..");
+}
+
+export function parseSandbox(raw: unknown): Sandbox {
+  if (raw === "read_only" || raw === "workspace_write" || raw === "full_access") {
+    return raw;
+  }
+  return "full_access";
+}
+
+/** Set `GUILD_SANDBOX` wins. Unset is undefined, not full_access. */
+export function envSandbox(env: NodeJS.ProcessEnv = process.env): Sandbox | undefined {
+  const raw = env.GUILD_SANDBOX;
+  if (raw === "read_only" || raw === "workspace_write" || raw === "full_access") {
+    return raw;
+  }
+  return undefined;
+}
+
+export function sandboxFromEnv(env: NodeJS.ProcessEnv = process.env): Sandbox {
+  return envSandbox(env) ?? "full_access";
+}
+
+/**
+ * Optional `sandbox: read_only|workspace_write|full_access` line in POSITION.md.
+ * Env still wins over this.
+ */
+export function sandboxFromPosition(body: string): Sandbox | undefined {
+  const match = body.match(
+    /(?:^|\n)\s*(?:[-*]\s*)?sandbox:\s*(read_only|workspace_write|full_access)\b/i,
+  );
+  if (!match) return undefined;
+  const value = match[1].toLowerCase();
+  if (value === "read_only" || value === "workspace_write" || value === "full_access") {
+    return value;
+  }
+  return undefined;
+}
+
+export function resolveToolPath(input: string, base = HOME): string {
+  const trimmed = input.trim();
+  if (trimmed === "~") return HOME;
+  if (trimmed.startsWith("~/")) return resolve(HOME, trimmed.slice(2));
+  if (trimmed.startsWith("/")) return resolve(trimmed);
+  return resolve(base, trimmed);
+}
+
+export function workspaceFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+  fallback?: string,
+): string {
+  const raw = env.GUILD_WORKSPACE?.trim();
+  if (raw) return resolveToolPath(raw);
+  if (fallback?.trim()) return resolveToolPath(fallback);
+  return defaultWorkspace();
+}
+
+export function policyFor(
+  env: NodeJS.ProcessEnv = process.env,
+  input: {
+    sandbox?: Sandbox;
+    workspace?: string;
+    position?: string;
+  } = {},
+): HarnessPolicy {
+  const sandbox =
+    envSandbox(env) ??
+    input.sandbox ??
+    sandboxFromPosition(input.position ?? "") ??
+    "full_access";
+  return {
+    sandbox,
+    workspace: workspaceFromEnv(env, input.workspace),
+  };
+}
+
+export function policyFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+  fallbackWorkspace?: string,
+): HarnessPolicy {
+  return policyFor(env, { workspace: fallbackWorkspace });
+}
+
+function canonicalize(path: string): string {
+  let abs = resolve(path);
+  const tail: string[] = [];
+  for (;;) {
+    try {
+      const real = realpathSync(abs);
+      return tail.length ? resolve(real, ...tail) : real;
+    } catch {
+      const parent = dirname(abs);
+      if (parent === abs) return tail.length ? resolve(abs, ...tail) : abs;
+      tail.unshift(basename(abs));
+      abs = parent;
+    }
+  }
+}
+
+export function pathInsideWorkspace(target: string, workspace: string): boolean {
+  const rel = relative(canonicalize(workspace), canonicalize(target));
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+export function mutatingTool(name: string): boolean {
+  return (
+    name === "run" ||
+    name === "write" ||
+    name === "spawn" ||
+    name === "image_gen" ||
+    name === "browser" ||
+    name.startsWith("mcp__")
+  );
+}
+
+export function gateTool(
+  name: string,
+  args: Record<string, unknown>,
+  input: {
+    sandbox?: Sandbox;
+    workspace?: string;
+  } = {},
+): SandboxRefusal | null {
+  const sandbox = parseSandbox(input.sandbox);
+  if (sandbox === "full_access") return null;
+
+  if (sandbox === "read_only") {
+    if (
+      name === "read" ||
+      name === "list" ||
+      name === "skill" ||
+      name === "spawn" ||
+      name === "read_spawn"
+    ) {
+      return null;
+    }
+    return {
+      text: `sandbox=read_only refused ${name}`,
+      isError: true,
+    };
+  }
+
+  const workspace = input.workspace?.trim()
+    ? resolveToolPath(input.workspace)
+    : HOME;
+
+  if (name.startsWith("mcp__")) {
+    return {
+      text: "sandbox=workspace_write refused mcp (unsandboxed child process); use full_access",
+      isError: true,
+    };
+  }
+
+  if (
+    name === "read" ||
+    name === "list" ||
+    name === "skill" ||
+    name === "spawn" ||
+    name === "read_spawn"
+  ) {
+    return null;
+  }
+
+  if (name === "write") {
+    const raw = typeof args.path === "string" ? args.path : "";
+    if (!raw.trim()) return null;
+    const target = resolveToolPath(raw, workspace);
+    if (!pathInsideWorkspace(target, workspace)) {
+      return {
+        text: `sandbox=workspace_write refused write outside workspace: ${target}`,
+        isError: true,
+      };
+    }
+    return null;
+  }
+
+  if (name === "run") {
+    const workdir = typeof args.workdir === "string" ? args.workdir.trim() : "";
+    const cwd = workdir ? resolveToolPath(workdir, workspace) : workspace;
+    if (!pathInsideWorkspace(cwd, workspace)) {
+      return {
+        text: `sandbox=workspace_write refused run cwd outside workspace: ${cwd}`,
+        isError: true,
+      };
+    }
+    return null;
+  }
+
+  if (name === "image_gen") {
+    return {
+      text: "sandbox=workspace_write refused image_gen (writes under GUILD_HOME); use full_access",
+      isError: true,
+    };
+  }
+
+  return null;
+}
+
+export type LoopCall = {
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+};
+
+export type LoopAsk = {
+  calls: LoopCall[];
+  text: string;
+  thinking?: string;
+};
+
+export type AgentLoopResult = {
+  text: string;
+  traces: ToolTrace[];
+  thinking: string;
+};
+
+const EMPTY_AFTER_TOOLS = "（工具跑完了，但模型沒寫最終回覆）";
+
+/**
+ * Shared tool loop (DSH-style). Providers only implement `ask`.
+ * Tool execution always goes through executeToolTraced → ctx.tools when dispatched.
+ */
+export async function runAgentLoop(input: {
+  toolCtx: ToolContext;
+  traces?: ToolTrace[];
+  thinkingChunks?: string[];
+  ask: (state: {
+    round: number;
+    wrap: boolean;
+    steer: string | null;
+  }) => Promise<LoopAsk | null>;
+  onRetry?: (lateSteer: string) => void;
+  onTools?: (calls: LoopCall[], outcomes: ToolOutcome[]) => void;
+  exhausted?: string;
+  emptyAfterTools?: string;
+  nullIfNoTraces?: boolean;
+}): Promise<AgentLoopResult | null> {
+  const {
+    executeToolTraced,
+    nextToolRound,
+    takeSteers,
+    throwIfAborted,
+    emitProgress,
+    TOOL_LOOP_EXHAUSTED,
+  } = await import("./tools.ts");
+  const traces = input.traces ?? [];
+  const thinkingChunks = input.thinkingChunks ?? [];
+  const exhausted = input.exhausted ?? TOOL_LOOP_EXHAUSTED;
+  const emptyAfterTools = input.emptyAfterTools ?? EMPTY_AFTER_TOOLS;
+  const thinkingOf = () => thinkingChunks.join("\n\n");
+
+  for (let round = 0; ; round++) {
+    throwIfAborted(input.toolCtx);
+    const phase = nextToolRound(round);
+    if (phase === "stop") {
+      if (!traces.length && input.nullIfNoTraces) return null;
+      return { text: exhausted, traces, thinking: thinkingOf() };
+    }
+    emitProgress(input.toolCtx, traces, thinkingOf());
+    const asked = await input.ask({
+      round,
+      wrap: phase === "wrap",
+      steer: takeSteers(input.toolCtx),
+    });
+    if (!asked) return null;
+    if (asked.thinking?.trim()) {
+      thinkingChunks.push(asked.thinking.trim());
+      emitProgress(input.toolCtx, traces, thinkingOf());
+    }
+    const thinking = thinkingOf();
+    if (!asked.calls.length) {
+      const late = takeSteers(input.toolCtx);
+      if (late) {
+        input.onRetry?.(late);
+        continue;
+      }
+      const text = asked.text.trim();
+      if (text) return { text, traces, thinking };
+      if (traces.length) return { text: emptyAfterTools, traces, thinking };
+      return input.nullIfNoTraces ? null : { text: emptyAfterTools, traces, thinking };
+    }
+    const outcomes = await Promise.all(
+      asked.calls.map((call) =>
+        executeToolTraced(
+          call.name,
+          call.args,
+          input.toolCtx,
+          traces,
+          thinking,
+        ),
+      ),
+    );
+    input.onTools?.(asked.calls, outcomes);
+  }
+}

package/src/host-agents.ts

@@ -0,0 +1,137 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { parseAgentFile } from "./agent-file.ts";
+
+export type HostAgent = {
+  id: string;
+  slug: string;
+  name: string;
+  description: string;
+  body: string;
+  instructions: string;
+  readOnly: boolean;
+  model?: string;
+  reasoning?: string;
+  source: "host";
+  host: string;
+  hostName: string;
+  path: string;
+  tags: string[];
+  createdAt: string;
+};
+
+type HostTool = {
+  id: string;
+  name: string;
+  dirs: string[];
+};
+
+const HOST_TOOLS: HostTool[] = [
+  { id: "codex", name: "Codex", dirs: [".codex/agents"] },
+  { id: "grok", name: "Grok", dirs: [".grok/agents", ".grok/bundled/agents"] },
+  { id: "claude", name: "Claude", dirs: [".claude/agents"] },
+  { id: "cursor", name: "Cursor", dirs: [".cursor/agents"] },
+];
+
+const BODY_CAP = 80_000;
+const LIST_CAP = 400;
+const AGENT_FILE = /\.(toml|md)$/i;
+
+function agentFilesIn(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  try {
+    if (!statSync(dir).isDirectory()) return [];
+  } catch {
+    return [];
+  }
+  let entries: { name: string; isFile: () => boolean; isDirectory: () => boolean }[] =
+    [];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const found: string[] = [];
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    if (entry.isDirectory()) continue;
+    if (entry.isFile() && AGENT_FILE.test(entry.name)) {
+      found.push(join(dir, entry.name));
+    }
+  }
+  return found;
+}
+
+function readAgent(file: string, tool: HostTool, home: string): HostAgent | null {
+  try {
+    const raw = readFileSync(file, "utf8");
+    const slug = basename(file).replace(/\.(toml|md)$/i, "");
+    const parsed = parseAgentFile(raw, slug);
+    if (!parsed.instructions.trim()) return null;
+    const st = statSync(file);
+    const rel = file.startsWith(home) ? `~${file.slice(home.length)}` : file;
+    const body = raw.length > BODY_CAP ? raw.slice(0, BODY_CAP) : raw;
+    return {
+      id: `host:${tool.id}:${slug}`,
+      slug,
+      name: parsed.name || slug,
+      description: parsed.description || "",
+      body,
+      instructions: parsed.instructions,
+      readOnly: parsed.readOnly,
+      model: parsed.model,
+      reasoning: parsed.reasoning,
+      source: "host",
+      host: tool.id,
+      hostName: tool.name,
+      path: rel,
+      tags: [tool.id, ...(parsed.readOnly ? ["read-only"] : [])],
+      createdAt: st.mtime.toISOString(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function listHostAgents(opts?: {
+  home?: string;
+  cwd?: string;
+  includeBody?: boolean;
+}): HostAgent[] {
+  const home = opts?.home || homedir();
+  const cwd = opts?.cwd || process.cwd();
+  const includeBody = opts?.includeBody !== false;
+  const seen = new Set<string>();
+  const out: HostAgent[] = [];
+  for (const tool of HOST_TOOLS) {
+    const dirs = tool.dirs.flatMap((rel) => [join(home, rel), join(cwd, rel)]);
+    for (const dir of dirs) {
+      for (const file of agentFilesIn(dir)) {
+        let key = file;
+        try {
+          key = realpathSync(file);
+        } catch {
+          /* keep file */
+        }
+        if (seen.has(key)) continue;
+        const item = readAgent(file, tool, home);
+        if (!item) continue;
+        if (!includeBody) item.body = "";
+        seen.add(key);
+        const clash = out.some((row) => row.id === item.id);
+        if (clash) item.id = `${item.id}:${out.length}`;
+        out.push(item);
+        if (out.length >= LIST_CAP) return out;
+      }
+    }
+  }
+  return out.sort(
+    (a, b) =>
+      a.hostName.localeCompare(b.hostName) || a.name.localeCompare(b.name),
+  );
+}
+
+export function hostAgentTools(): { id: string; name: string }[] {
+  return HOST_TOOLS.map((tool) => ({ id: tool.id, name: tool.name }));
+}

package/src/host-browse.ts

@@ -0,0 +1,199 @@
+import { execFile } from "node:child_process";
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { StoreError } from "./store.ts";
+
+const execFileAsync = promisify(execFile);
+const HOME = homedir();
+const LS_CAP = 200;
+const READ_CAP = 48_000;
+const GIT_CAP = 12_000;
+const TREE_CAP = 8_000;
+
+export type HostEntry = {
+  name: string;
+  kind: "file" | "dir" | "link";
+  size?: number;
+};
+
+function resolveUserPath(input: string): string {
+  const trimmed = String(input || "~").trim() || "~";
+  if (trimmed === "~") return HOME;
+  if (trimmed.startsWith("~/")) return resolve(HOME, trimmed.slice(2));
+  if (trimmed.startsWith("/")) return resolve(trimmed);
+  return resolve(HOME, trimmed);
+}
+
+function parentOf(path: string): string | null {
+  const parent = dirname(path);
+  if (parent === path) return null;
+  return parent;
+}
+
+function asHostError(error: unknown, fallback: string): never {
+  if (error instanceof StoreError) throw error;
+  const err = error as { code?: string; message?: string };
+  if (err.code === "ENOENT") throw new StoreError(404, "path not found");
+  if (err.code === "EACCES") throw new StoreError(403, "permission denied");
+  throw new StoreError(400, err.message || fallback);
+}
+
+export function hostList(rawPath: string): {
+  path: string;
+  parent: string | null;
+  entries: HostEntry[];
+} {
+  try {
+    const target = resolveUserPath(rawPath);
+    const st = statSync(target);
+    if (!st.isDirectory()) throw new StoreError(400, "not a directory");
+    const entries = readdirSync(target, { withFileTypes: true })
+      .slice(0, LS_CAP)
+      .map((entry) => {
+        const item: HostEntry = {
+          name: entry.name,
+          kind: entry.isDirectory()
+            ? "dir"
+            : entry.isSymbolicLink()
+              ? "link"
+              : "file",
+        };
+        try {
+          if (entry.isFile()) {
+            item.size = statSync(join(target, entry.name)).size;
+          }
+        } catch {
+          /* ignore */
+        }
+        return item;
+      })
+      .sort((a, b) => {
+        if (a.kind === "dir" && b.kind !== "dir") return -1;
+        if (a.kind !== "dir" && b.kind === "dir") return 1;
+        return a.name.localeCompare(b.name);
+      });
+    return { path: target, parent: parentOf(target), entries };
+  } catch (error) {
+    asHostError(error, "list failed");
+  }
+}
+
+export function hostRead(rawPath: string): {
+  path: string;
+  name: string;
+  text: string;
+  truncated: boolean;
+  bytes: number;
+} {
+  try {
+    const target = resolveUserPath(rawPath);
+    const st = statSync(target);
+    if (!st.isFile()) throw new StoreError(400, "not a file");
+    const raw = readFileSync(target);
+    if (raw.includes(0)) throw new StoreError(400, "binary file");
+    const truncated = raw.length > READ_CAP;
+    const text = raw.subarray(0, READ_CAP).toString("utf8");
+    return {
+      path: target,
+      name: target.split("/").pop() || target,
+      text,
+      truncated,
+      bytes: raw.length,
+    };
+  } catch (error) {
+    asHostError(error, "read failed");
+  }
+}
+
+function walkTree(
+  root: string,
+  depth: number,
+  prefix: string,
+  lines: string[],
+  budget: { left: number },
+): void {
+  if (budget.left <= 0 || depth < 0) return;
+  let entries: ReturnType<typeof readdirSync>;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const visible = entries
+    .filter((entry) => entry.name !== "node_modules" && entry.name !== ".git")
+    .slice(0, 80);
+  for (const entry of visible) {
+    if (budget.left <= 0) {
+      lines.push(`${prefix}…`);
+      return;
+    }
+    budget.left -= 1;
+    const mark = entry.isDirectory() ? "/" : "";
+    lines.push(`${prefix}${entry.name}${mark}`);
+    if (entry.isDirectory() && depth > 0) {
+      walkTree(join(root, entry.name), depth - 1, `${prefix}  `, lines, budget);
+    }
+  }
+}
+
+export function hostTree(rawPath: string): { path: string; text: string } {
+  try {
+    const target = resolveUserPath(rawPath);
+    const st = statSync(target);
+    if (!st.isDirectory()) throw new StoreError(400, "not a directory");
+    const lines = [target];
+    walkTree(target, 2, "", lines, { left: 120 });
+    let text = lines.join("\n");
+    if (text.length > TREE_CAP) text = `${text.slice(0, TREE_CAP)}\n…`;
+    return { path: target, text };
+  } catch (error) {
+    asHostError(error, "tree failed");
+  }
+}
+
+function findGitRoot(start: string): string | null {
+  let dir = start;
+  for (let i = 0; i < 12; i += 1) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+export async function hostGit(rawPath: string): Promise<{
+  path: string;
+  root: string;
+  text: string;
+}> {
+  try {
+    const start = resolveUserPath(rawPath);
+    const base = statSync(start).isDirectory() ? start : dirname(start);
+    const root = findGitRoot(base);
+    if (!root) throw new StoreError(404, "not a git repository");
+    const opts = { cwd: root, timeout: 8_000, maxBuffer: GIT_CAP * 2 };
+    const status = await execFileAsync("git", ["status", "-sb"], opts);
+    let diff = "";
+    try {
+      const out = await execFileAsync("git", ["diff", "--stat", "HEAD"], opts);
+      diff = String(out.stdout || "");
+    } catch {
+      diff = "";
+    }
+    const text = [`repo: ${root}`, status.stdout.trim(), diff.trim()]
+      .filter(Boolean)
+      .join("\n")
+      .slice(0, GIT_CAP);
+    return { path: start, root, text: text || "(clean)" };
+  } catch (error) {
+    asHostError(error, "git failed");
+  }
+}