@arnilo/prism-tools 0.0.0-stage → 0.13.0

package/coding/src/targets.ts

@@ -0,0 +1,110 @@
+/**
+ * The `coding.targets` service: for one of this package's tools, the absolute paths a call
+ * touches and the roots that contain them. Approval (plan 154 Task 6) and the hard-deny hook
+ * read it, so neither has to parse tool names or arguments.
+ *
+ * A call from a session bound to a worktree (plan 165 Task 7) reports that worktree as its root, so
+ * approval and the hard-deny hook follow the session: inside the worktree for the bound session,
+ * outside it for every other.
+ *
+ * Read-effect tools also get one read-only root per effective skill directory (plan 190 Task 6), so
+ * a skill's `references/` files can be read without granting any write access outside the workspace.
+ */
+import { dirname, isAbsolute, resolve } from "node:path";
+import type { JsonObject, Skill } from "@arnilo/prism";
+
+import type { WorkspaceService } from "./workspace/service.js";
+
+export interface CodingTargets {
+  /** Absolute paths the call touches. Empty for `shell`. */
+  readonly paths: readonly string[];
+  /** `root` plus every extra root, resolved; read-effect tools also get each skill's directory. */
+  readonly roots: readonly string[];
+}
+
+/** Argument keys holding paths, per registered tool. `shell` and `shell_output` have none. */
+const PATH_ARG_KEYS: Readonly<Record<string, readonly string[]>> = {
+  read: ["path"],
+  write: ["path"],
+  edit: ["path"],
+  delete: ["path"],
+  glob: ["path"],
+  grep: ["path"],
+  diagnostics: ["path"],
+  move: ["from", "to"],
+  shell: [],
+  shell_output: [],
+};
+
+/** Every tool this package registers. */
+export const CODING_TOOL_NAMES: ReadonlySet<string> = new Set(Object.keys(PATH_ARG_KEYS));
+
+export type CodingTargetsFn = (name: string, args: JsonObject, context?: CodingTargetsContext) => CodingTargets | undefined;
+
+/** The caller's identity, when it has one. Only `sessionId` can select a worktree. */
+export interface CodingTargetsContext {
+  readonly sessionId?: string;
+}
+
+/** Read-effect tools that may read a skill's directory; a write to one stays outside the roots. */
+const SKILL_READ_TOOL_NAMES: ReadonlySet<string> = new Set(["read", "glob", "grep", "diagnostics"]);
+const NO_SKILL_ROOTS: readonly string[] = Object.freeze([]);
+
+/**
+ * Build the service for `root` and `roots`. Unknown names return `undefined` (the tool is not
+ * ours). A relative argument resolves against `root`, matching the tools' own cwd — or against the
+ * calling session's worktree when `workspace` reports one, matching the routed tool's cwd.
+ *
+ * `skills` is read lazily, after setup, and only for read-effect tools. The derived directories are
+ * cached until the effective list's paths change; a skill without an absolute path contributes
+ * nothing. Reads fail soft, so a host that cannot list skills keeps the coding roots.
+ */
+export function createCodingTargets(
+  root: string,
+  roots: readonly string[],
+  workspace?: WorkspaceService,
+  skills?: () => readonly Skill[],
+): CodingTargetsFn {
+  const resolvedRoot = resolve(root);
+  const extraRoots = Object.freeze(roots.map((extra) => resolve(extra)));
+  const rootTargets = Object.freeze([resolvedRoot, ...extraRoots]);
+  let cachedSignature: string | undefined;
+  let cachedSkillRoots: readonly string[] = NO_SKILL_ROOTS;
+  const skillRoots = (): readonly string[] => {
+    if (skills === undefined) return NO_SKILL_ROOTS;
+    let list: readonly Skill[];
+    try {
+      list = skills();
+    } catch {
+      return cachedSkillRoots;
+    }
+    // The public skills API has no change signal, so reading the list is the only way to notice a
+    // registration; only its path signature and the derived directories are cached.
+    const signature = JSON.stringify(list.map((skill) => skill.path ?? null));
+    if (signature === cachedSignature) return cachedSkillRoots;
+    const dirs = new Set<string>();
+    for (const skill of list) {
+      if (skill.path !== undefined && isAbsolute(skill.path)) dirs.add(dirname(skill.path));
+    }
+    cachedSignature = signature;
+    cachedSkillRoots = Object.freeze([...dirs]);
+    return cachedSkillRoots;
+  };
+  return (name, args, context) => {
+    const keys = PATH_ARG_KEYS[name];
+    if (!keys) return undefined;
+    const worktree = context?.sessionId === undefined ? undefined : workspace?.worktree.bound(context.sessionId);
+    const cwd = worktree === undefined ? resolvedRoot : resolve(worktree.path);
+    const baseRoots = worktree === undefined ? rootTargets : Object.freeze([cwd, ...extraRoots]);
+    const extraSkillRoots = SKILL_READ_TOOL_NAMES.has(name) ? skillRoots() : NO_SKILL_ROOTS;
+    const allRoots = extraSkillRoots.length === 0 ? baseRoots : Object.freeze([...baseRoots, ...extraSkillRoots]);
+    const paths: string[] = [];
+    for (const key of keys) {
+      const value = args[key];
+      if (typeof value === "string" && value.length > 0) {
+        paths.push(isAbsolute(value) ? value : resolve(cwd, value));
+      }
+    }
+    return { paths, roots: allRoots };
+  };
+}

package/coding/src/workspace/diff.ts

@@ -0,0 +1,78 @@
+/**
+ * Bounded worktree diff: tracked changes against the worktree's base, plus untracked files.
+ *
+ * `FileActivity` is the driver kit's file-activity type, so a workspace diff and a vendor diff
+ * normalize to the same shape. Overlay files never appear: they are listed in the common
+ * `.git/info/exclude`, so `ls-files --others --exclude-standard` skips them.
+ */
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { type FileActivity, mapDiff } from "@arnilo/prism/driver-kit";
+
+import type { GitOperations } from "../agent/git.js";
+
+/** One changed file, in the driver kit's file-activity shape. */
+export type FileChange = FileActivity;
+
+export interface WorkspaceDiffBounds {
+  /** Maximum files listed. Default 200. */
+  readonly maxFiles: number;
+  /** Maximum bytes of one file's `diff` text. A larger file is listed with no `diff`. Default 1 MiB. */
+  readonly maxBytes: number;
+}
+
+export interface WorkspaceDiff {
+  readonly changes: readonly FileChange[];
+  /** True when a file's `diff` was withheld (over `maxBytes`) or the list was cut at `maxFiles`. */
+  readonly truncated: boolean;
+}
+
+/**
+ * `git diff <base>` for tracked files (committed and uncommitted), then one `created` entry per
+ * untracked, non-ignored file. Paths are worktree-relative. A file whose diff exceeds `maxBytes`
+ * is listed without `diff` and marks the result truncated.
+ */
+export async function workspaceDiff(
+  git: GitOperations,
+  worktree: string,
+  base: string,
+  bounds: WorkspaceDiffBounds,
+  signal?: AbortSignal,
+): Promise<WorkspaceDiff> {
+  const tracked = await git.diff({ base, signal });
+  const untracked = await git.untrackedFiles({ signal });
+
+  let truncated = tracked.truncated;
+  const changes: FileChange[] = [];
+  for (const change of mapDiff(tracked.text)) {
+    if (Buffer.byteLength(change.diff ?? "", "utf8") > bounds.maxBytes) {
+      truncated = true;
+      const { diff: _dropped, ...rest } = change;
+      changes.push(rest);
+    } else {
+      changes.push(change);
+    }
+  }
+
+  const listed = new Set(changes.map((change) => change.path));
+  for (const path of untracked) {
+    if (listed.has(path)) continue;
+    const size = await fileSize(join(worktree, path));
+    if (size !== undefined && size > bounds.maxBytes) truncated = true;
+    changes.push({ kind: "file", path, change: "created", source: "diff" });
+  }
+
+  if (changes.length > bounds.maxFiles) {
+    return { changes: changes.slice(0, bounds.maxFiles), truncated: true };
+  }
+  return { changes, truncated };
+}
+
+async function fileSize(path: string): Promise<number | undefined> {
+  try {
+    const stats = await lstat(path);
+    return stats.isFile() ? stats.size : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/coding/src/workspace/errors.ts

@@ -0,0 +1,28 @@
+/**
+ * The `workspace` service's error type.
+ *
+ * Codes are plain `workspace_*` strings, deliberately outside the 0.12 error namespace this plan
+ * retires, and messages name the rule, never a config value.
+ */
+export type WorkspaceServiceErrorCode =
+  | "workspace_not_git"
+  | "workspace_path_escape"
+  | "workspace_limit"
+  | "workspace_unknown"
+  | "workspace_main_immutable"
+  | "workspace_dirty"
+  | "workspace_dirty_target"
+  | "workspace_identity_missing"
+  | "workspace_git_unsupported"
+  | "workspace_merge_failed"
+  | "workspace_sandbox_unsupported";
+
+export class WorkspaceServiceError extends Error {
+  readonly code: WorkspaceServiceErrorCode;
+
+  constructor(code: WorkspaceServiceErrorCode, message: string) {
+    super(message);
+    this.name = "WorkspaceServiceError";
+    this.code = code;
+  }
+}

package/coding/src/workspace/index.ts

@@ -0,0 +1,5 @@
+export * from "./diff.js";
+export * from "./errors.js";
+export * from "./merge.js";
+export * from "./routing.js";
+export * from "./service.js";

package/coding/src/workspace/merge.ts

@@ -0,0 +1,151 @@
+/**
+ * Merge one worktree's branch into another branch, reporting conflicts instead of resolving them.
+ *
+ * Everything is decided before anything moves. A dirty worktree is folded into a *dangling* commit
+ * of its current state (the index is snapshotted first and restored if the merge turns out to
+ * conflict), so a conflict leaves both trees, the index, and every ref byte-for-byte unchanged. A
+ * clean probe is turned into a merge commit (`commit-tree`) and the target ref is advanced with a
+ * compare-and-swap (`update-ref`); when the target is checked out somewhere, that worktree is
+ * fast-forwarded instead so its index and files stay consistent with its HEAD.
+ *
+ * The service never pushes, never resolves a conflict, and never invents an identity.
+ */
+import { GitError, type GitOperations, type GitWorktreeEntry } from "../agent/git.js";
+import { WorkspaceServiceError } from "./errors.js";
+
+export interface WorkspaceMergeRequest {
+  /** The branch the worktree's branch is merged into. */
+  readonly into: string;
+  /** Required when the worktree has uncommitted changes: it records them, and names the merge. */
+  readonly commit?: { readonly message: string };
+}
+
+export type WorkspaceMergeResult =
+  | { readonly status: "merged"; readonly commit: string }
+  | { readonly status: "conflict"; readonly files: readonly string[] };
+
+export interface MergeContext {
+  /** The worktree being merged (its `cwd`). */
+  readonly worktree: string;
+  /** The branch checked out in that worktree. */
+  readonly branch: string;
+  /** Git operations for a path; the worktree's own instance is created on demand. */
+  readonly gitFor: (path: string) => Promise<GitOperations>;
+  /** `git worktree list` entries, used to find where `into` is checked out. */
+  readonly worktrees: readonly GitWorktreeEntry[];
+  /** The repository's configured commit identity, or undefined when it has none. */
+  readonly identity: { readonly name: string; readonly email: string } | undefined;
+  readonly signal?: AbortSignal;
+}
+
+export async function mergeWorktree(context: MergeContext, request: WorkspaceMergeRequest): Promise<WorkspaceMergeResult> {
+  const { branch, signal } = context;
+  if (request.into === branch) {
+    throw new WorkspaceServiceError("workspace_merge_failed", "a worktree cannot be merged into its own branch");
+  }
+
+  const git = await context.gitFor(context.worktree);
+  const dirty = await dirtyPaths(git, signal);
+  if (dirty.length > 0 && request.commit === undefined) {
+    throw new WorkspaceServiceError(
+      "workspace_dirty",
+      `the worktree has ${dirty.length} uncommitted change(s); pass commit to record them before merging`,
+    );
+  }
+
+  // The tree being merged: the worktree's live state when it is dirty, else its branch tip.
+  const message = request.commit?.message ?? `Merge ${branch} into ${request.into}`;
+  let restore: string | undefined;
+  let source = branch;
+  if (dirty.length > 0) {
+    requireIdentity(context.identity);
+    restore = await git.writeTree({ signal });
+    await git.stageAll({ signal });
+    const staged = await git.writeTree({ signal });
+    source = await git.commitTree({ tree: staged, parents: [branch], message, signal });
+  }
+
+  const abort = async (): Promise<void> => {
+    // The index is the only thing the fold touched; put it back exactly as it was.
+    if (restore !== undefined) await git.readTree({ tree: restore, signal }).catch(() => undefined);
+  };
+
+  const holder = context.worktrees.find((entry) => entry.branch === `refs/heads/${request.into}`);
+  if (holder !== undefined) {
+    const holderDirty = await dirtyPaths(await context.gitFor(holder.path), signal);
+    if (holderDirty.length > 0) {
+      await abort();
+      throw new WorkspaceServiceError(
+        "workspace_dirty_target",
+        `${request.into} is checked out in ${holder.path}, which has uncommitted changes`,
+      );
+    }
+  }
+
+  let tree: string;
+  let conflicts: readonly string[];
+  try {
+    ({ tree, conflicts } = await git.mergeTree({ into: request.into, from: source, signal }));
+  } catch (error) {
+    await abort();
+    throw mapMergeError(error);
+  }
+  if (conflicts.length > 0) {
+    await abort();
+    return { status: "conflict", files: conflicts };
+  }
+
+  requireIdentity(context.identity);
+  let commit: string;
+  try {
+    commit = await git.commitTree({ tree, parents: [request.into, source], message, signal });
+  } catch (error) {
+    await abort();
+    throw mapMergeError(error);
+  }
+
+  try {
+    if (holder === undefined) {
+      await git.updateRef({ ref: `refs/heads/${request.into}`, to: commit, expected: request.into, signal });
+    } else {
+      await (await context.gitFor(holder.path)).fastForward({ to: commit, signal });
+    }
+    // Record the worktree's own state on its branch so its index and HEAD agree again.
+    if (restore !== undefined) {
+      await git.updateRef({ ref: `refs/heads/${branch}`, to: source, expected: branch, signal });
+    }
+  } catch (error) {
+    throw new WorkspaceServiceError(
+      "workspace_merge_failed",
+      `could not advance ${request.into}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  return { status: "merged", commit };
+}
+
+/** A merge and a commit both need the repository's configured identity; neither invents one. */
+export function requireIdentity(identity: MergeContext["identity"]): asserts identity is { name: string; email: string } {
+  if (identity === undefined) {
+    throw new WorkspaceServiceError("workspace_identity_missing", "no commit identity is configured for this repository");
+  }
+}
+
+async function dirtyPaths(git: GitOperations, signal?: AbortSignal): Promise<string[]> {
+  const status = await git.status({ signal });
+  return status.entries.filter((entry) => entry.kind !== "ignored").map((entry) => entry.path);
+}
+
+function mapMergeError(error: unknown): WorkspaceServiceError {
+  if (error instanceof WorkspaceServiceError) return error;
+  if (error instanceof GitError) {
+    const unsupported = error.exitCode === 129 || /unknown option|is not a git command/i.test(error.message);
+    if (unsupported) {
+      return new WorkspaceServiceError("workspace_git_unsupported", `git merge-tree is not supported here: ${error.message}`);
+    }
+    if (/auto-detect email|empty ident name/i.test(error.message)) {
+      return new WorkspaceServiceError("workspace_identity_missing", "no commit identity is configured for this repository");
+    }
+    return new WorkspaceServiceError("workspace_merge_failed", error.message);
+  }
+  return new WorkspaceServiceError("workspace_merge_failed", error instanceof Error ? error.message : String(error));
+}

package/coding/src/workspace/routing.ts

@@ -0,0 +1,76 @@
+/**
+ * Per-session worktree routing (plan 165 Task 7).
+ *
+ * A session bound by `worktree.create({ sessionId })` runs every cwd-taking tool of this package
+ * inside that session's worktree. The registered set wraps each base tool with one `execute` that
+ * looks the calling session's worktree up and dispatches to the instance built for that worktree,
+ * so no tool needs to know about sessions and no schema changes.
+ *
+ * The binding is the service's memory, keyed by session id: it is never read from tool arguments or
+ * model output. An unbound session (or an unknown session id) falls through to the base tool.
+ *
+ * ```ts
+ * const routing = createWorktreeRouting({ base, create: cwdTools, workspace });
+ * prism.hooks.on("session.closed", (event) => routing.forget(event.sessionId), { id: "workspace-routing" });
+ * for (const tool of routing.tools) prism.tools.register(tool);
+ * ```
+ */
+import type { JsonObject, ToolDefinition, ToolExecutionContext, ToolResult } from "@arnilo/prism";
+
+import type { WorkspaceService } from "./service.js";
+
+export interface WorktreeRoutingOptions {
+  /** The tool set built for the package root; registered as-is for a session without a worktree. */
+  readonly base: readonly ToolDefinition[];
+  /** Builds the cwd-taking tools for one directory. Called once per bound worktree. */
+  readonly create: (cwd: string) => readonly ToolDefinition[];
+  readonly workspace: WorkspaceService;
+}
+
+export interface WorktreeRouting {
+  /** `base`, with every tool `create` also returns dispatched per session. */
+  readonly tools: readonly ToolDefinition[];
+  /** Drops one session's cached instances. Wire to `session.closed`. */
+  forget(sessionId: string): void;
+}
+
+interface CachedTools {
+  readonly path: string;
+  readonly byName: ReadonlyMap<string, ToolDefinition>;
+}
+
+export function createWorktreeRouting(options: WorktreeRoutingOptions): WorktreeRouting {
+  const cache = new Map<string, CachedTools>();
+
+  /**
+   * The tool instances for `sessionId`'s worktree, built on first use. A disposed worktree unbinds,
+   * so the entry is dropped on the next call; a session rebound to another worktree rebuilds.
+   */
+  function instancesFor(sessionId: string): ReadonlyMap<string, ToolDefinition> | undefined {
+    const worktree = options.workspace.worktree.bound(sessionId);
+    if (worktree === undefined) {
+      cache.delete(sessionId);
+      return undefined;
+    }
+    const cached = cache.get(sessionId);
+    if (cached !== undefined && cached.path === worktree.path) return cached.byName;
+    const byName = new Map(options.create(worktree.path).map((tool) => [tool.name, tool]));
+    cache.set(sessionId, { path: worktree.path, byName });
+    return byName;
+  }
+
+  const tools = options.base.map((tool) => ({
+    ...tool,
+    async execute(args: JsonObject, context: ToolExecutionContext): Promise<ToolResult> {
+      const instance = instancesFor(context.sessionId)?.get(tool.name);
+      return await (instance ?? tool).execute(args, context);
+    },
+  }));
+
+  return {
+    tools,
+    forget(sessionId) {
+      cache.delete(sessionId);
+    },
+  };
+}