@twinklerg/coden 0.1.0

package/src/observability/terminal.ts

@@ -0,0 +1,201 @@
+import * as readline from "node:readline";
+import pc from "picocolors";
+import type { EventBus, RuntimeEvent } from "../core/events.js";
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+
+export interface TerminalOptions {
+  stdout?: NodeJS.WritableStream;
+  stderr?: NodeJS.WritableStream;
+  tty?: boolean;
+  verbose?: boolean;
+  printMode?: boolean;
+}
+export class TerminalRenderer {
+  private readonly stdout: NodeJS.WritableStream;
+  private readonly stderr: NodeJS.WritableStream;
+  private readonly tty: boolean;
+  private spinner: NodeJS.Timeout | undefined;
+  private frame = 0;
+  private providerStartedAt: number | undefined;
+  private reasoningText = "";
+  private contentStarted = false;
+  // Non-TTY output is buffered until the provider attempt succeeds so that a
+  // failed stream attempt followed by a retry cannot corrupt pipeline output.
+  private pendingText = "";
+  constructor(
+    events: EventBus,
+    private readonly options: TerminalOptions = {},
+  ) {
+    this.stdout = options.stdout ?? process.stdout;
+    this.stderr = options.stderr ?? process.stderr;
+    this.tty =
+      options.tty ?? Boolean(process.stderr.isTTY && !process.env.NO_COLOR && !process.env.CI);
+    events.on((event) => this.render(event));
+  }
+  private render(event: RuntimeEvent): void {
+    if (event.type === "provider.started") this.startProviderAttempt();
+    if (event.type === "provider.reasoning_delta") {
+      const text = String(event.data?.text ?? "");
+      if (this.tty && this.providerStartedAt !== undefined && !this.contentStarted && text) {
+        this.reasoningText += text;
+        this.renderThinkingLine();
+      }
+    }
+    if (event.type === "provider.delta") {
+      const text = String(event.data?.text ?? "");
+      if (text && !this.contentStarted) this.finishThinking();
+      if (this.tty) this.stdout.write(text);
+      else this.pendingText += text;
+    }
+    if (event.type === "provider.completed") {
+      if (!this.tty && this.pendingText) {
+        this.stdout.write(this.pendingText);
+        this.pendingText = "";
+      }
+      this.endProviderAttempt();
+    }
+    if (event.type === "provider.retry" || event.type === "turn.failed") {
+      this.endProviderAttempt();
+      this.pendingText = "";
+    }
+    if (event.type === "tool.started") {
+      this.endProviderAttempt();
+      this.status(`tool ${String(event.data?.name)} started`);
+    }
+    if (event.type === "tool.completed")
+      this.status(
+        `tool ${String(event.data?.name)} ${event.data?.isError ? "failed" : "completed"} (${String(event.data?.durationMs)}ms)`,
+      );
+    if (event.type === "provider.retry" && this.options.verbose)
+      this.status(`provider retry ${String(event.data?.attempt)}`);
+    if (event.type === "turn.completed") {
+      this.endProviderAttempt();
+      this.stdout.write("\n");
+      this.status(
+        `done: ${String(event.data?.tools)} tools, ${String(event.data?.durationMs)}ms, ${String(event.data?.inputTokens)}/${String(event.data?.outputTokens)} tokens`,
+      );
+    }
+    if (event.type === "turn.failed") {
+      this.status(pc.red(`failed: ${String(event.data?.message)}`));
+    }
+    if (event.type === "plugin.loaded" && this.options.verbose) {
+      this.status(`plugin loaded: ${pluginLabel(event)}`);
+    }
+    if (event.type === "plugin.failed") {
+      this.status(pc.red(`plugin failed: ${pluginLabel(event)}${eventMessage(event)}`));
+    }
+    if (event.type === "plugin.unavailable") {
+      this.status(pc.yellow(`plugin unavailable: ${pluginLabel(event)}${eventMessage(event)}`));
+    }
+    if (event.type === "plugin.restart_required") {
+      this.status(
+        pc.yellow(`plugin restart required: ${pluginLabel(event)}${eventMessage(event)}`),
+      );
+    }
+  }
+  private status(message: string): void {
+    this.stderr.write(this.tty ? `${pc.dim(message)}\n` : `[coden] ${message}\n`);
+  }
+  private startProviderAttempt(): void {
+    this.endProviderAttempt();
+    this.providerStartedAt = Date.now();
+    this.startSpinner();
+  }
+  private endProviderAttempt(): void {
+    this.stopSpinner();
+    this.providerStartedAt = undefined;
+    this.reasoningText = "";
+    this.contentStarted = false;
+  }
+  private finishThinking(): void {
+    const startedAt = this.providerStartedAt;
+    const hadReasoning = Boolean(this.normalizedReasoning());
+    this.stopSpinner();
+    this.contentStarted = true;
+    if (this.tty && startedAt !== undefined && hadReasoning) {
+      const seconds = ((Date.now() - startedAt) / 1000).toFixed(1);
+      this.stderr.write(`${pc.dim(`thought for ${seconds}s`)}\n`);
+    }
+  }
+  private normalizedReasoning(): string {
+    return this.reasoningText.replace(/\s+/g, " ").trim();
+  }
+  private renderThinkingLine(): void {
+    const normalized = this.normalizedReasoning();
+    if (!normalized) return;
+    const columns = (this.stderr as NodeJS.WritableStream & { columns?: number }).columns ?? 80;
+    const frame = SPINNER_FRAMES[this.frame++ % SPINNER_FRAMES.length] ?? "";
+    const visible = this.truncateTail(normalized, Math.max(0, columns - 2));
+    readline.clearLine(this.stderr, 0);
+    readline.cursorTo(this.stderr, 0);
+    this.stderr.write(pc.dim(`${frame} ${visible}`));
+  }
+  private truncateTail(text: string, maxColumns: number): string {
+    if (maxColumns <= 0) return "";
+    const characters = Array.from(text);
+    const width = (character: string) => ((character.codePointAt(0) ?? 0) <= 0xff ? 1 : 2);
+    const total = characters.reduce((sum, character) => sum + width(character), 0);
+    if (total <= maxColumns) return text;
+    const kept: string[] = [];
+    let used = 1;
+    for (let index = characters.length - 1; index >= 0; index--) {
+      const character = characters[index];
+      if (character === undefined || used + width(character) > maxColumns) break;
+      kept.unshift(character);
+      used += width(character);
+    }
+    return `…${kept.join("")}`;
+  }
+  private startSpinner(): void {
+    if (!this.tty || this.spinner) {
+      if (!this.tty && this.options.verbose) this.status("requesting model");
+      return;
+    }
+    this.spinner = setInterval(() => {
+      if (this.normalizedReasoning()) {
+        this.renderThinkingLine();
+        return;
+      }
+      readline.clearLine(this.stderr, 0);
+      readline.cursorTo(this.stderr, 0);
+      const frame = SPINNER_FRAMES[this.frame++ % SPINNER_FRAMES.length] ?? "";
+      this.stderr.write(`${frame} thinking`);
+    }, 80);
+  }
+  private stopSpinner(): void {
+    if (!this.spinner) return;
+    clearInterval(this.spinner);
+    this.spinner = undefined;
+    readline.clearLine(this.stderr, 0);
+    readline.cursorTo(this.stderr, 0);
+  }
+  dispose(): void {
+    this.endProviderAttempt();
+  }
+}
+
+function pluginLabel(event: RuntimeEvent): string {
+  const data = event.data ?? {};
+  const scope = stringValue(data.scope);
+  const packageName = stringValue(data.packageName);
+  const version = stringValue(data.version ?? data.diskVersion);
+  const name = stringValue(data.name);
+  const path = stringValue(data.path);
+  const source = stringValue(data.source);
+  if (packageName)
+    return `${scope ? `${scope} ` : ""}${packageName}${version ? `@${version}` : ""}`;
+  if (name) return name;
+  if (path) return `${scope ? `${scope} ` : ""}${path}`;
+  if (source) return source;
+  return "plugin";
+}
+
+function eventMessage(event: RuntimeEvent): string {
+  const message = stringValue(event.data?.message ?? event.data?.reason);
+  return message ? ` — ${message}` : "";
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/src/observability/trace.ts

@@ -0,0 +1,30 @@
+import { appendFile, chmod, mkdir } from "node:fs/promises";
+import path from "node:path";
+import type { EventBus, RuntimeEvent } from "../core/events.js";
+
+export class JSONLTraceWriter {
+  #queue = Promise.resolve();
+  constructor(
+    private readonly file: string,
+    events: EventBus,
+  ) {
+    events.on((event) => this.write(event));
+  }
+  write(event: RuntimeEvent): Promise<void> {
+    const operation = this.#queue.then(async () => {
+      const directory = path.dirname(this.file);
+      await mkdir(directory, { recursive: true, mode: 0o700 });
+      await chmod(directory, 0o700);
+      await appendFile(this.file, `${JSON.stringify(event)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+      });
+      await chmod(this.file, 0o600);
+    });
+    this.#queue = operation.catch(() => {});
+    return operation;
+  }
+  async flush(): Promise<void> {
+    await this.#queue;
+  }
+}

package/src/permissions/policy.ts

@@ -0,0 +1,56 @@
+import type { ToolCall, ToolDefinition, ToolRisk } from "../core/types.js";
+
+export type PermissionDecision = "allow_once" | "allow_session" | "deny";
+export type PermissionPrompt = (
+  tool: ToolDefinition,
+  call: ToolCall,
+  risk: ToolRisk,
+  signal?: AbortSignal,
+) => Promise<PermissionDecision>;
+
+const DANGEROUS = [
+  /\brm\s+(?:-[^\s]*r[^\s]*\s+|--recursive\b)/i,
+  /\bsudo\b/i,
+  /\bgit\b[^;&|\n]*\breset\s+--hard\b/i,
+  /\bgit\b[^;&|\n]*\bclean\s+(?:-[^\s]*f[^\s]*|--force)\b/i,
+  /\bgit\b[^;&|\n]*\bpush\b[^;&|\n]*(?:--force(?:-with-lease)?|-f)\b/i,
+  /\bgit\b[^;&|\n]*\bcheckout\s+--\s/i,
+  /\bgit\b[^;&|\n]*\brestore\b/i,
+  /\b(?:mkfs|fdisk|dd)\b/i,
+  /\b(?:killall|pkill)\b/i,
+  /(?:curl|wget)[^|;&]*(?:\||&&)\s*(?:sh|bash)\b/i,
+  /(?:^|\s)(?:\/etc|\/usr|\/bin|\/sbin)\//,
+];
+
+export function classifyBashRisk(command: string): ToolRisk {
+  return DANGEROUS.some((pattern) => pattern.test(command)) ? "dangerous" : "modify";
+}
+
+export class PermissionPolicy {
+  readonly #sessionAllowed = new Set<string>();
+  constructor(
+    private readonly auto: boolean,
+    private readonly prompt?: PermissionPrompt,
+  ) {}
+
+  async authorize(
+    tool: ToolDefinition,
+    call: ToolCall,
+    signal?: AbortSignal,
+  ): Promise<{ allowed: boolean; risk: ToolRisk }> {
+    let risk = tool.risk;
+    if (
+      tool.name === "bash" &&
+      typeof (call.input as { command?: unknown })?.command === "string"
+    ) {
+      const classified = classifyBashRisk((call.input as { command: string }).command);
+      if (classified === "dangerous") risk = "dangerous";
+    }
+    if (this.auto || risk === "read" || (risk === "modify" && this.#sessionAllowed.has(tool.name)))
+      return { allowed: true, risk };
+    if (!this.prompt) return { allowed: false, risk };
+    const decision = await this.prompt(tool, call, risk, signal);
+    if (decision === "allow_session" && risk !== "dangerous") this.#sessionAllowed.add(tool.name);
+    return { allowed: decision !== "deny", risk };
+  }
+}

package/src/permissions/workspace.ts

@@ -0,0 +1,139 @@
+import { constants } from "node:fs";
+import { lstat, open, readlink, realpath } from "node:fs/promises";
+import path from "node:path";
+import { CodeNError } from "../core/types.js";
+
+function isInside(child: string, parent: string): boolean {
+  const relative = path.relative(parent, child);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export async function readWorkspaceTextFile(
+  workspace: string,
+  requested: string,
+  maxBytes = 1_000_000,
+): Promise<string> {
+  const target = await resolveWorkspacePath(workspace, requested);
+  const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const fileStat = await handle.stat();
+    if (fileStat.size > maxBytes)
+      throw new CodeNError(
+        "context",
+        "workspace.instructions_too_large",
+        `${requested} exceeds the ${maxBytes}-byte instruction limit`,
+      );
+    return await handle.readFile("utf8");
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function resolveWorkspacePath(workspace: string, requested: string): Promise<string> {
+  const workspaceReal = await realpath(workspace);
+  const absolute = path.resolve(workspaceReal, requested);
+  if (!isInside(absolute, workspaceReal))
+    throw new CodeNError(
+      "permission",
+      "workspace.outside",
+      `Path is outside workspace: ${requested}`,
+    );
+  try {
+    const targetReal = await realpath(absolute);
+    if (!isInside(targetReal, workspaceReal))
+      throw new CodeNError(
+        "permission",
+        "workspace.symlink_escape",
+        `Path escapes workspace through a symlink: ${requested}`,
+      );
+    return targetReal;
+  } catch (error) {
+    if (error instanceof CodeNError) throw error;
+    // The target does not exist or is a dangling symlink. Validate every
+    // existing component (including symlink target chains) before returning.
+    try {
+      const targetStat = await lstat(absolute);
+      if (targetStat.isSymbolicLink()) {
+        const linkTarget = path.resolve(path.dirname(absolute), await readlink(absolute));
+        await assertResolvedInside(linkTarget, workspaceReal, requested, "dangling symlink");
+      }
+    } catch (linkError) {
+      if (linkError instanceof CodeNError) throw linkError;
+    }
+    await assertAncestorsInside(absolute, workspaceReal, requested);
+    return absolute;
+  }
+}
+
+async function assertResolvedInside(
+  target: string,
+  workspaceReal: string,
+  requested: string,
+  kind: string,
+): Promise<void> {
+  const resolved = await nearestExistingRealpath(target);
+  if (!resolved || !isInside(resolved, workspaceReal))
+    throw new CodeNError(
+      "permission",
+      "workspace.symlink_escape",
+      `Path escapes workspace through a ${kind}: ${requested}`,
+    );
+}
+
+async function assertAncestorsInside(
+  absolute: string,
+  workspaceReal: string,
+  requested: string,
+): Promise<void> {
+  let parent = path.dirname(absolute);
+  while (parent !== path.dirname(parent)) {
+    let statResult: Awaited<ReturnType<typeof lstat>> | undefined;
+    try {
+      statResult = await lstat(parent);
+    } catch {
+      parent = path.dirname(parent);
+      continue;
+    }
+    if (!statResult) {
+      parent = path.dirname(parent);
+      continue;
+    }
+    if (statResult.isSymbolicLink()) {
+      // An intermediate symlink (possibly dangling) must resolve inside the
+      // workspace even when the final component does not exist yet.
+      const linkTarget = path.resolve(path.dirname(parent), await readlink(parent));
+      await assertResolvedInside(linkTarget, workspaceReal, requested, "symlink");
+    } else {
+      let parentReal: string | undefined;
+      try {
+        parentReal = await realpath(parent);
+      } catch {
+        parent = path.dirname(parent);
+        continue;
+      }
+      if (!parentReal) continue;
+      // The deepest existing ancestor is a real directory. If it is inside the
+      // workspace we are done; upper levels are the workspace's own ancestors.
+      if (isInside(parentReal, workspaceReal)) return;
+      throw new CodeNError(
+        "permission",
+        "workspace.symlink_escape",
+        `Parent escapes workspace: ${requested}`,
+      );
+    }
+    parent = path.dirname(parent);
+  }
+}
+
+async function nearestExistingRealpath(target: string): Promise<string | undefined> {
+  let current = target;
+  while (true) {
+    try {
+      return await realpath(current);
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) return undefined;
+      current = parent;
+    }
+  }
+}

package/src/plugins/api.ts

@@ -0,0 +1,68 @@
+import { CodeNError, type ToolDefinition } from "../core/types.js";
+
+export type {
+  JsonSchema,
+  ToolContext,
+  ToolDefinition,
+  ToolResult,
+  ToolRisk,
+} from "../core/types.js";
+
+export const CODEN_PLUGIN_API_VERSION = 1 as const;
+
+export interface CodeNPlugin {
+  apiVersion: typeof CODEN_PLUGIN_API_VERSION;
+  name: string;
+  tools: ToolDefinition[];
+}
+
+export type PluginModuleExport = ToolDefinition | CodeNPlugin;
+
+export function normalizePluginExport(value: unknown, packageName: string): ToolDefinition[] {
+  if (isToolDefinitionShape(value)) return [value];
+  if (!value || typeof value !== "object")
+    throw new CodeNError(
+      "plugin",
+      "plugin.export_invalid",
+      "plugin.export_invalid: default export must be a tool or CodeNPlugin",
+    );
+
+  const plugin = value as Partial<CodeNPlugin> & { apiVersion?: unknown; tools?: unknown };
+  if (plugin.apiVersion !== CODEN_PLUGIN_API_VERSION)
+    throw new CodeNError(
+      "plugin",
+      "plugin.api_unsupported",
+      `plugin.api_unsupported: ${String(plugin.apiVersion)}`,
+    );
+  if (plugin.name !== packageName)
+    throw new CodeNError(
+      "plugin",
+      "plugin.name_mismatch",
+      `plugin.name_mismatch: expected ${packageName}, received ${String(plugin.name)}`,
+    );
+  if (!Array.isArray(plugin.tools) || plugin.tools.length === 0)
+    throw new CodeNError(
+      "plugin",
+      "plugin.export_invalid",
+      "plugin.export_invalid: tools must be a non-empty array",
+    );
+  if (!plugin.tools.every(isToolDefinitionShape))
+    throw new CodeNError(
+      "plugin",
+      "plugin.export_invalid",
+      "plugin.export_invalid: every tool must match ToolDefinition",
+    );
+  return plugin.tools;
+}
+
+function isToolDefinitionShape(value: unknown): value is ToolDefinition {
+  if (!value || typeof value !== "object") return false;
+  const tool = value as Partial<ToolDefinition>;
+  return (
+    typeof tool.name === "string" &&
+    typeof tool.description === "string" &&
+    (tool.risk === "read" || tool.risk === "modify" || tool.risk === "dangerous") &&
+    !!tool.inputSchema &&
+    typeof tool.execute === "function"
+  );
+}

package/src/plugins/bun-package-manager.ts

@@ -0,0 +1,35 @@
+import { truncateOutput } from "../context/truncate.js";
+import { CodeNError } from "../core/types.js";
+import { type ProcessRunner, type ProcessRunResult, runProcess } from "../process/runner.js";
+import type { PackageInstallRequest, PackageManager } from "./package-manager.js";
+
+function boundedInstallMessage(result: ProcessRunResult): string {
+  const status = result.timedOut
+    ? "bun install timed out"
+    : result.cancelled
+      ? "bun install cancelled"
+      : `bun install exited with code ${result.exitCode ?? "null"}${result.signal ? ` (signal ${result.signal})` : ""}`;
+  return truncateOutput(
+    [status, result.stderr ? `stderr:\n${result.stderr}` : "stderr:\n<empty>"].join("\n"),
+    4_000,
+  );
+}
+
+export class BunPackageManager implements PackageManager {
+  constructor(private readonly runner: ProcessRunner = runProcess) {}
+
+  async install(request: PackageInstallRequest): Promise<void> {
+    const args = ["install", "--registry", "https://registry.npmjs.org"];
+    if (request.frozenLockfile) args.push("--frozen-lockfile");
+    if (!request.allowScripts) args.push("--ignore-scripts");
+    const result = await this.runner("bun", args, {
+      cwd: request.cwd,
+      env: process.env,
+      ...(request.signal ? { signal: request.signal } : {}),
+      timeoutMs: 120_000,
+      maxOutputChars: 30_000,
+    });
+    if (!result.ok)
+      throw new CodeNError("plugin", "plugin.install_failed", boundedInstallMessage(result));
+  }
+}

package/src/plugins/installed-loader.ts

@@ -0,0 +1,144 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { CodeNError, type ToolDefinition } from "../core/types.js";
+import { ToolRegistry, type ToolSource } from "../tools/registry.js";
+import { normalizePluginExport } from "./api.js";
+import { readPluginManifest } from "./manifest.js";
+import { readInstalledPackageMetadata } from "./package-metadata.js";
+import type { PluginPaths } from "./paths.js";
+
+export interface LoadedPackagePlugin {
+  packageName: string;
+  version: string;
+  entryPath: string;
+  tools: ToolDefinition[];
+}
+
+export interface PackagePluginFailure {
+  packageName: string;
+  path: string;
+  message: string;
+}
+
+export interface PackagePluginLoadResult {
+  loaded: LoadedPackagePlugin[];
+  failed: PackagePluginFailure[];
+}
+
+export type PackageImporter = (specifier: string) => Promise<{ default?: unknown }>;
+
+export interface ShadowedPackage {
+  packageName: string;
+  globalVersion: string;
+  projectVersion: string;
+}
+
+export class InstalledPluginLoader {
+  constructor(private readonly importer: PackageImporter = (specifier) => import(specifier)) {}
+
+  async loadScope(paths: PluginPaths): Promise<PackagePluginLoadResult> {
+    const manifest = await readPluginManifest(paths.manifestPath);
+    const loaded: LoadedPackagePlugin[] = [];
+    const failed: PackagePluginFailure[] = [];
+
+    for (const packageName of Object.keys(manifest.plugins).sort()) {
+      const packageDirectory = packageDirectoryFor(paths.runtimeDir, packageName);
+      try {
+        const metadata = await readInstalledPackageMetadata(paths.runtimeDir, packageName);
+        try {
+          const module = await this.importer(pathToFileURL(metadata.entryPath).href);
+          const tools = normalizePluginExport(module.default, packageName);
+          loaded.push({
+            packageName,
+            version: metadata.version,
+            entryPath: metadata.entryPath,
+            tools,
+          });
+        } catch (error) {
+          failed.push({
+            packageName,
+            path: metadata.entryPath,
+            message: errorMessage(error),
+          });
+        }
+      } catch (error) {
+        failed.push({
+          packageName,
+          path: packageDirectory,
+          message: errorMessage(error),
+        });
+      }
+    }
+
+    return { loaded, failed };
+  }
+}
+
+export function composePackageRegistry(
+  builtins: ToolDefinition[],
+  globalPlugins: LoadedPackagePlugin[],
+  projectPlugins: LoadedPackagePlugin[],
+): { registry: ToolRegistry; effective: LoadedPackagePlugin[]; shadowed: ShadowedPackage[] } {
+  const registry = new ToolRegistry(builtins);
+  const projectByName = new Map(projectPlugins.map((plugin) => [plugin.packageName, plugin]));
+  const shadowed: ShadowedPackage[] = [];
+  const effectiveGlobals: LoadedPackagePlugin[] = [];
+
+  for (const plugin of globalPlugins) {
+    const projectPlugin = projectByName.get(plugin.packageName);
+    if (projectPlugin) {
+      shadowed.push({
+        packageName: plugin.packageName,
+        globalVersion: plugin.version,
+        projectVersion: projectPlugin.version,
+      });
+      continue;
+    }
+    effectiveGlobals.push(plugin);
+  }
+
+  const effective = [...effectiveGlobals, ...projectPlugins];
+  for (const plugin of effective) registerPackageTools(registry, plugin);
+  return { registry, effective, shadowed };
+}
+
+function registerPackageTools(registry: ToolRegistry, plugin: LoadedPackagePlugin): void {
+  const source: ToolSource = {
+    kind: "npm",
+    pluginName: plugin.packageName,
+    pluginVersion: plugin.version,
+    path: plugin.entryPath,
+  };
+  for (const tool of plugin.tools) {
+    const existingSource = registry.source(tool.name);
+    if (existingSource) {
+      throw new CodeNError(
+        "plugin",
+        "plugin.tool_conflict",
+        `plugin.tool_conflict: ${tool.name} from ${formatSource(existingSource)} conflicts with ${formatSource(source)}`,
+      );
+    }
+    registry.register(tool, source);
+  }
+}
+
+function packageDirectoryFor(runtimeDir: string, packageName: string): string {
+  return path.join(runtimeDir, "node_modules", ...packageName.split("/"));
+}
+
+function formatSource(source: ToolSource): string {
+  switch (source.kind) {
+    case "builtin":
+      return "builtin";
+    case "local":
+      return source.path ? `local:${source.path}` : "local";
+    case "npm":
+      return source.path
+        ? `${source.pluginName}@${source.pluginVersion}:${source.path}`
+        : `${source.pluginName}@${source.pluginVersion}`;
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}