opencode-drive 0.1.2 → 0.1.4

package/src/cli/registry.ts

@@ -1,109 +1,265 @@
+import { mkdir, open, readdir, rename, rm } from "node:fs/promises"
 import { homedir } from "node:os"
 import { basename, join } from "node:path"
-import { mkdir, open, readdir, rename, rm } from "node:fs/promises"
-import type { InstanceManifest } from "./types.js"
+
+export interface InstanceManifest {
+  readonly version: 1
+  readonly name: string
+  readonly pid: number
+  readonly startedAt: string
+  readonly cwd: string
+  readonly artifacts: string
+  readonly visible: boolean
+  readonly status: "starting" | "ready"
+  readonly endpoints: { readonly ui: string; readonly backend: string }
+  readonly control: string
+}
 
 export function registryDirectory() {
-  if (process.env.DRIVE_REGISTRY_DIR) return process.env.DRIVE_REGISTRY_DIR
-  return join(process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state"), "opencode-drive", "instances")
+  return (
+    process.env.DRIVE_REGISTRY_DIR ??
+    join(
+      process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state"),
+      "opencode-drive",
+      "instances",
+    )
+  )
 }
 
 export function manifestPath(name: string) {
   return join(registryDirectory(), `${validateName(name)}.json`)
 }
 
-export async function registerInstance(manifest: InstanceManifest) {
-  await mkdir(registryDirectory(), { recursive: true })
-  const file = manifestPath(manifest.name)
-  const lock = `${file}.lock`
-  const existing = await readManifest(file)
-  if (existing && processAlive(existing.pid)) throw new Error(`drive instance "${manifest.name}" is already running`)
-  if (existing) await rm(file, { force: true })
-  const handle = await open(lock, "wx").catch(() => undefined)
-  if (!handle) throw new Error(`drive instance "${manifest.name}" is already starting`)
-  try {
-    const current = await readManifest(file)
-    if (current && processAlive(current.pid)) throw new Error(`drive instance "${manifest.name}" is already running`)
-    const temporary = `${file}.${process.pid}.tmp`
-    await Bun.write(temporary, `${JSON.stringify(manifest, undefined, 2)}\n`)
-    await rename(temporary, file)
-    return file
-  } finally {
-    await handle.close()
-    await rm(lock, { force: true })
-  }
+export function controlPath(name: string) {
+  return join(registryDirectory(), `${validateName(name)}.sock`)
 }
 
-export async function unregisterInstance(name: string, pid: number) {
-  const file = manifestPath(name)
-  const manifest = await readManifest(file)
-  if (manifest?.pid !== pid) return
-  await rm(file, { force: true })
+export async function register(manifest: InstanceManifest) {
+  await withLock(manifest.name, false, async () => {
+    const existing = await read(manifestPath(manifest.name))
+    if (existing && alive(existing.pid))
+      throw new Error(`drive instance "${manifest.name}" is already running`)
+    await Promise.all([
+      rm(manifestPath(manifest.name), { force: true }),
+      rm(controlPath(manifest.name), { force: true }),
+    ])
+    await write(manifest)
+  })
 }
 
-export async function transferInstance(manifest: InstanceManifest, pid: number) {
-  const file = manifestPath(manifest.name)
-  const current = await readManifest(file)
-  if (current?.pid !== manifest.pid) throw new Error(`drive instance "${manifest.name}" changed ownership`)
-  const temporary = `${file}.${process.pid}.tmp`
-  await Bun.write(temporary, `${JSON.stringify({ ...manifest, pid }, undefined, 2)}\n`)
-  await rename(temporary, file)
+export async function markReady(name: string, pid: number) {
+  await markStatus(name, pid, "ready")
 }
 
-export async function resolveInstance(name?: string) {
+export async function markStarting(name: string, pid: number) {
+  await markStatus(name, pid, "starting")
+}
+
+async function markStatus(
+  name: string,
+  pid: number,
+  status: InstanceManifest["status"],
+) {
+  await withLock(name, true, async () => {
+    const manifest = await read(manifestPath(name))
+    if (!manifest || manifest.pid !== pid)
+      throw new Error(`drive instance "${name}" changed ownership`)
+    await write({ ...manifest, status })
+  })
+}
+
+export async function resolveInstance(
+  name?: string,
+  options: { readonly ready?: boolean } = {},
+) {
   const instances = await listInstances()
-  if (name) {
-    const instance = instances.find((item) => item.name === name)
-    if (!instance) throw new Error(`drive instance "${name}" was not found`)
-    return instance
+  const manifest = name
+    ? instances.find((item) => item.name === name)
+    : instances.length === 1
+      ? instances[0]
+      : undefined
+  if (!manifest) {
+    if (!name && instances.length > 1)
+      throw new Error(
+        `multiple drive instances are running; pass --name (${instances.map((item) => item.name).join(", ")})`,
+      )
+    throw new Error(
+      name
+        ? `drive instance "${name}" was not found`
+        : "no drive instances are running",
+    )
   }
-  if (instances.length === 1) return instances[0]!
-  if (instances.length === 0) throw new Error("no drive instances are running")
-  throw new Error(`multiple drive instances are running; pass --name (${instances.map((item) => item.name).join(", ")})`)
+  if (options.ready !== false && manifest.status !== "ready")
+    throw new Error(`drive instance "${manifest.name}" is still starting`)
+  return manifest
 }
 
 export async function listInstances() {
   await mkdir(registryDirectory(), { recursive: true })
-  const directory = registryDirectory()
-  const files = (await readdir(directory)).filter((file) => file.endsWith(".json"))
-  const entries = await Promise.all(files.map((file) => readManifest(join(directory, file))))
-  const active = entries.filter((entry): entry is InstanceManifest => entry !== undefined && processAlive(entry.pid))
-  const activeNames = new Set(active.map((entry) => entry.name))
+  const files = await readdir(registryDirectory())
+  const manifests = await Promise.all(
+    files
+      .filter((file) => file.endsWith(".json"))
+      .map(async (file) => {
+        const name = basename(file, ".json")
+        if (!validName(name)) {
+          await rm(join(registryDirectory(), file), { force: true })
+          return undefined
+        }
+        const manifest = await read(join(registryDirectory(), file))
+        if (manifest?.name === name && alive(manifest.pid)) return manifest
+        await prune(name, manifest?.pid)
+        return undefined
+      }),
+  )
+  const active = manifests.filter(
+    (manifest): manifest is InstanceManifest => manifest !== undefined,
+  )
+  const names = new Set(active.map((manifest) => manifest.name))
   await Promise.all(
     files
-      .filter((file) => !activeNames.has(basename(file, ".json")))
-      .map((file) => rm(join(directory, file), { force: true })),
+      .filter((file) => file.endsWith(".sock"))
+      .flatMap((file) => {
+        const name = basename(file, ".sock")
+        if (!validName(name))
+          return [rm(join(registryDirectory(), file), { force: true })]
+        if (!names.has(name)) return [prune(name)]
+        return []
+      }),
   )
   return active.sort((a, b) => a.name.localeCompare(b.name))
 }
 
-async function readManifest(file: string): Promise<InstanceManifest | undefined> {
-  if (!(await Bun.file(file).exists())) return undefined
+export async function unregister(name: string, pid: number) {
+  await withLock(name, true, async () => {
+    const manifest = await read(manifestPath(name))
+    if (manifest?.pid !== pid) return
+    await Promise.all([
+      rm(manifestPath(name), { force: true }),
+      rm(controlPath(name), { force: true }),
+    ])
+  })
+}
+
+async function prune(name: string, pid?: number) {
+  await withLock(name, true, async () => {
+    const manifest = await read(manifestPath(name))
+    if (manifest && (manifest.pid !== pid || alive(manifest.pid))) return
+    await Promise.all([
+      rm(manifestPath(name), { force: true }),
+      rm(controlPath(name), { force: true }),
+    ])
+  })
+}
+
+async function write(manifest: InstanceManifest) {
+  const file = manifestPath(manifest.name)
+  const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`
   try {
-    const value = await Bun.file(file).json()
-    if (!isManifest(value)) return undefined
-    return value
-  } catch {
-    await rm(file, { force: true })
-    return undefined
+    await Bun.write(temporary, `${JSON.stringify(manifest, undefined, 2)}\n`)
+    await rename(temporary, file)
+  } finally {
+    await rm(temporary, { force: true })
+  }
+}
+
+async function read(file: string): Promise<InstanceManifest | undefined> {
+  const value: unknown = await Bun.file(file)
+    .json()
+    .catch(() => undefined)
+  if (isManifest(value)) return value
+  return undefined
+}
+
+async function withLock(
+  name: string,
+  wait: boolean,
+  task: () => Promise<void>,
+) {
+  await mkdir(registryDirectory(), { recursive: true })
+  const lock = `${manifestPath(name)}.lock`
+  const deadline = Date.now() + 10_000
+  while (true) {
+    const handle = await open(lock, "wx").catch((error: unknown) => {
+      if (isNodeError(error) && error.code === "EEXIST") return undefined
+      throw error
+    })
+    if (handle) {
+      try {
+        await handle.writeFile(`${process.pid}\n`)
+        await task()
+        return
+      } finally {
+        await handle.close()
+        await rm(lock, { force: true })
+      }
+    }
+    if (await staleLock(lock)) {
+      await rm(lock, { force: true })
+      continue
+    }
+    if (!wait)
+      throw new Error(`drive instance "${name}" is already starting`)
+    if (Date.now() >= deadline)
+      throw new Error(`timed out updating drive instance "${name}"`)
+    await Bun.sleep(10)
   }
 }
 
+async function staleLock(file: string) {
+  const pid = Number.parseInt(
+    await Bun.file(file)
+      .text()
+      .catch(() => ""),
+    10,
+  )
+  return Number.isInteger(pid) && !alive(pid)
+}
+
 function isManifest(value: unknown): value is InstanceManifest {
   if (typeof value !== "object" || value === null) return false
   if (!("version" in value) || value.version !== 1) return false
   if (!("name" in value) || typeof value.name !== "string") return false
   if (!("pid" in value) || typeof value.pid !== "number") return false
-  if (!("startedAt" in value) || typeof value.startedAt !== "string") return false
-  if (!("mode" in value) || (value.mode !== "simulated" && value.mode !== "real")) return false
-  if (!("headless" in value) || typeof value.headless !== "boolean") return false
+  if (!("startedAt" in value) || typeof value.startedAt !== "string")
+    return false
   if (!("cwd" in value) || typeof value.cwd !== "string") return false
-  if (!("artifacts" in value) || typeof value.artifacts !== "string") return false
-  if (!("endpoints" in value) || typeof value.endpoints !== "object" || value.endpoints === null) return false
-  return "ui" in value.endpoints && typeof value.endpoints.ui === "string" && "backend" in value.endpoints && typeof value.endpoints.backend === "string"
+  if (!("artifacts" in value) || typeof value.artifacts !== "string")
+    return false
+  if (!("visible" in value) || typeof value.visible !== "boolean") return false
+  if (
+    !("status" in value) ||
+    (value.status !== "starting" && value.status !== "ready")
+  )
+    return false
+  if (!("control" in value) || typeof value.control !== "string") return false
+  if (
+    !("endpoints" in value) ||
+    typeof value.endpoints !== "object" ||
+    value.endpoints === null
+  )
+    return false
+  return (
+    "ui" in value.endpoints &&
+    typeof value.endpoints.ui === "string" &&
+    "backend" in value.endpoints &&
+    typeof value.endpoints.backend === "string"
+  )
 }
 
-function processAlive(pid: number) {
+function validateName(name: string) {
+  if (!validName(name))
+    throw new Error(
+      "instance names must contain 1-64 letters, numbers, dots, underscores, or dashes",
+    )
+  return name
+}
+
+function validName(name: string) {
+  return /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(name)
+}
+
+function alive(pid: number) {
   try {
     process.kill(pid, 0)
     return true
@@ -112,9 +268,6 @@ function processAlive(pid: number) {
   }
 }
 
-function validateName(name: string) {
-  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(name)) {
-    throw new Error("instance names must contain 1-64 letters, numbers, dots, underscores, or dashes")
-  }
-  return name
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error
 }

package/src/cli/response-generator.ts

@@ -0,0 +1,334 @@
+import { Backend } from "../client/protocol.js"
+
+export const responseTypes = ["text", "reasoning", "tool", "diff"] as const
+export type ResponseType = (typeof responseTypes)[number]
+
+export interface ResponseConfiguration {
+  readonly types: ReadonlyArray<ResponseType>
+  readonly tools: ReadonlyArray<string>
+}
+
+export interface ResponseUpdate {
+  readonly types?: ReadonlyArray<string>
+  readonly tools?: ReadonlyArray<string>
+}
+
+type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | ReadonlyArray<JsonValue>
+  | { readonly [key: string]: JsonValue }
+
+const textResponses = [
+  "I took a careful look at the problem and followed it through the parts of the system that actually shape the behavior. The result is simpler than it first appeared: one clear boundary, one owner, and fewer opportunities for state to drift. There is a quiet satisfaction in watching the pieces settle into place.",
+  "The important path is working now, and the surrounding behavior remains intact. I kept the change focused, made the failure case visible, and checked the point where control passes from one process to another. It is a small adjustment, but it lets a little more daylight into the design.",
+  "I traced the request from its first input to its final effect and found the useful seam in between. The implementation now says what it means without asking the reader to remember hidden state. Nothing dramatic happened, which is often the nicest possible ending for this kind of work.",
+  "The pieces fit together cleanly after the change. Inputs are handled where they arrive, ownership stays explicit, and cleanup follows the same path every time. The code feels calmer now, like a room after someone has opened a window and put the books back in order.",
+  "I checked the current behavior, made the narrow change, and followed it through the edge cases that mattered. The result is direct enough to explain and ordinary enough to trust. Somewhere in the background, the event loop continues its patient little orbit.",
+]
+
+const reasoningResponses = [
+  "I should inspect the available context before choosing the smallest reliable path through this.",
+  "I need to preserve the working behavior while checking the boundary where ownership changes hands.",
+  "The request contains enough information to proceed, though the assumptions deserve one careful pass first.",
+  "I will separate the observed behavior from the implementation detail, then test the seam between them.",
+  "The safest approach is to validate the current state, make one deliberate change, and follow its effects.",
+]
+
+export function createResponseSettings() {
+  let configuration: ResponseConfiguration = {
+    types: ["text", "reasoning", "diff", "tool"],
+    tools: ["write", "apply_patch"],
+  }
+  return {
+    current: () => configuration,
+    update(input: ResponseUpdate) {
+      const updated = {
+        types: input.types ? parseTypes(input.types) : configuration.types,
+        tools: input.tools ? parseTools(input.tools) : configuration.tools,
+      }
+      if (
+        updated.types.includes("diff") &&
+        !updated.tools.includes("*") &&
+        !updated.tools.some((tool) => diffTools.has(tool))
+      )
+        throw new Error(
+          "diff responses require apply_patch, write, or edit in --tools",
+        )
+      configuration = updated
+      return configuration
+    },
+  }
+}
+
+export function generateResponse(
+  configuration: ResponseConfiguration,
+  request: Backend.OpenedExchange,
+): {
+  readonly items: ReadonlyArray<Backend.Item>
+  readonly finish: Backend.FinishReason
+} {
+  if (hasToolResult(request.body)) return textResponse()
+  const tools = offeredTools(request.body).filter(
+    (tool) => configuration.tools.includes("*") || configuration.tools.includes(tool.name),
+  )
+  const available = configuration.types.filter(
+    (type) =>
+      (type !== "tool" || tools.length > 0) &&
+      (type !== "diff" || tools.some((tool) => diffTools.has(tool.name))),
+  )
+  const type = pick(available)
+  if (type === "reasoning")
+    return {
+      items: [
+        { type: "reasoningDelta", text: pick(reasoningResponses) },
+        { type: "textDelta", text: pick(textResponses) },
+      ],
+      finish: "stop",
+    }
+  if (type === "tool") return toolResponse(tools.slice(0, 3), false)
+  if (type === "diff")
+    return toolResponse(
+      [
+        ["apply_patch", "write", "edit"]
+          .map((name) => tools.find((tool) => tool.name === name))
+          .find((tool) => tool !== undefined)!,
+      ],
+      true,
+    )
+  if (type === "text") return textResponse()
+  return {
+    items: [
+      {
+        type: "textDelta",
+        text: "No configured response type matched the tools offered by this request.",
+      },
+    ],
+    finish: "stop",
+  }
+}
+
+function textResponse() {
+  return {
+    items: [{ type: "textDelta" as const, text: pick(textResponses) }],
+    finish: "stop" as const,
+  }
+}
+
+interface ToolDefinition {
+  readonly name: string
+  readonly parameters: unknown
+}
+
+const diffTools = new Set(["apply_patch", "edit", "write"])
+let gardenExpanded = false
+
+function toolResponse(tools: ReadonlyArray<ToolDefinition>, diff: boolean) {
+  return {
+    items: tools.map((tool, index) => ({
+      type: "toolCall" as const,
+      index,
+      id: `call_${crypto.randomUUID().replaceAll("-", "").slice(0, 16)}`,
+      name: tool.name,
+      input: toolInput(tool, diff),
+    })),
+    finish: "tool-calls" as const,
+  }
+}
+
+function offeredTools(body: unknown) {
+  if (!isRecord(body) || !Array.isArray(body.tools)) return []
+  return body.tools.flatMap((value): ToolDefinition[] => {
+    if (!isRecord(value)) return []
+    const definition = isRecord(value.function) ? value.function : value
+    if (typeof definition.name !== "string") return []
+    return [
+      {
+        name: definition.name,
+        parameters: definition.parameters ?? definition.inputSchema,
+      },
+    ]
+  })
+}
+
+function toolInput(tool: ToolDefinition, diff: boolean) {
+  const generated = schemaValue(tool.parameters, "input")
+  const input = isJsonRecord(generated) ? generated : {}
+  const known = knownInput(tool.name, diff)
+  if (!isRecord(tool.parameters) || !isRecord(tool.parameters.properties))
+    return { ...input, ...known }
+  const properties = tool.parameters.properties
+  return {
+    ...input,
+    ...Object.fromEntries(
+      Object.entries(known).filter(
+        ([key, value]) =>
+          key in properties && acceptsValue(properties[key], value),
+      ),
+    ),
+  }
+}
+
+function knownInput(name: string, diff: boolean): Record<string, JsonValue> {
+  const suffix = crypto.randomUUID().slice(0, 8)
+  if (name === "apply_patch")
+    return {
+      patchText: gardenPatch(),
+    }
+  if (name === "write")
+    return {
+      path: "src/garden.js",
+      filePath: "src/garden.js",
+      content:
+        'export function greet(name, punctuation = "!") {\n  const visitor = name.trim() || "traveler"\n  return `Hello, ${visitor}${punctuation}`\n}\n',
+    }
+  if (name === "edit")
+    return {
+      path: ".opencode/opencode.jsonc",
+      filePath: ".opencode/opencode.jsonc",
+      oldString: '"name": "Simulation"',
+      newString: `"name": "Simulation ${suffix}"`,
+    }
+  if (name === "read")
+    return { path: ".opencode/opencode.jsonc", filePath: ".opencode/opencode.jsonc", offset: 1, limit: 120 }
+  if (name === "glob") return { pattern: "**/*", path: ".", limit: 20 }
+  if (name === "grep")
+    return { pattern: "simulation", path: ".opencode", include: "*.jsonc", limit: 20 }
+  if (name === "shell" || name === "bash")
+    return { command: diff ? "git diff --stat" : "pwd", description: "Inspect the workspace" }
+  return {}
+}
+
+function gardenPatch() {
+  const patch = gardenExpanded
+    ? '*** Begin Patch\n*** Update File: src/garden.js\n@@\n-export function greet(name, punctuation = "!") {\n-  const visitor = name.trim() || "traveler"\n-  return `Hello, ${visitor}${punctuation}`\n+export function greet(name) {\n+  return `Hello, ${name}.`\n }\n*** End Patch'
+    : '*** Begin Patch\n*** Update File: src/garden.js\n@@\n-export function greet(name) {\n-  return `Hello, ${name}.`\n+export function greet(name, punctuation = "!") {\n+  const visitor = name.trim() || "traveler"\n+  return `Hello, ${visitor}${punctuation}`\n }\n*** End Patch'
+  gardenExpanded = !gardenExpanded
+  return patch
+}
+
+function schemaValue(
+  schema: unknown,
+  key: string,
+  root: unknown = schema,
+): JsonValue {
+  if (!isRecord(schema)) return {}
+  if (typeof schema.$ref === "string" && schema.$ref.startsWith("#/$defs/")) {
+    const name = schema.$ref.slice("#/$defs/".length)
+    if (isRecord(root) && isRecord(root.$defs))
+      return schemaValue(root.$defs[name], key, root)
+  }
+  if ("const" in schema && isJson(schema.const)) return schema.const
+  if (Array.isArray(schema.enum) && schema.enum.length > 0 && isJson(schema.enum[0]))
+    return schema.enum[0]
+  const alternative = Array.isArray(schema.anyOf)
+    ? schema.anyOf[0]
+    : Array.isArray(schema.oneOf)
+      ? schema.oneOf[0]
+      : undefined
+  if (alternative !== undefined) return schemaValue(alternative, key, root)
+  if (Array.isArray(schema.allOf) && schema.allOf.length > 0 && schema.type === undefined)
+    return schemaValue(schema.allOf[0], key, root)
+  if (schema.type === "object" || isRecord(schema.properties)) {
+    const properties = isRecord(schema.properties) ? schema.properties : {}
+    const required = Array.isArray(schema.required)
+      ? schema.required.filter((value): value is string => typeof value === "string")
+      : []
+    return Object.fromEntries(
+      required.map((name) => [name, schemaValue(properties[name], name, root)]),
+    )
+  }
+  if (schema.type === "array") {
+    const count = typeof schema.minItems === "number" ? Math.max(1, schema.minItems) : 1
+    return Array.from({ length: count }, () => schemaValue(schema.items, key, root))
+  }
+  if (schema.type === "boolean") return false
+  if (schema.type === "integer" || schema.type === "number") {
+    if (typeof schema.minimum === "number") return schema.minimum
+    if (typeof schema.exclusiveMinimum === "number") return schema.exclusiveMinimum + 1
+    return 1
+  }
+  if (schema.type === "null") return null
+  if (key.toLowerCase().includes("path")) return "."
+  if (key.toLowerCase().includes("pattern")) return "TODO"
+  if (key.toLowerCase().includes("command")) return "pwd"
+  if (key.toLowerCase().includes("content")) return "Generated by the simulated model."
+  const value = "sample"
+  return typeof schema.minLength === "number"
+    ? value.padEnd(schema.minLength, "x")
+    : value
+}
+
+function hasToolResult(body: unknown) {
+  if (!isRecord(body) || !Array.isArray(body.messages)) return false
+  const message = body.messages.at(-1)
+  if (!isRecord(message)) return false
+  if (message.role === "tool") return true
+  if (!Array.isArray(message.content)) return false
+  return message.content.some(
+    (part) => isRecord(part) && (part.type === "tool-result" || part.type === "tool"),
+  )
+}
+
+function acceptsValue(schema: unknown, value: JsonValue) {
+  if (!isRecord(schema)) return true
+  if (Array.isArray(schema.enum) && !schema.enum.some((item) => item === value))
+    return false
+  if (schema.type === "string") return typeof value === "string"
+  if (schema.type === "number" || schema.type === "integer")
+    return typeof value === "number"
+  if (schema.type === "boolean") return typeof value === "boolean"
+  if (schema.type === "array") return Array.isArray(value)
+  if (schema.type === "object") return isJsonRecord(value)
+  return true
+}
+
+function parseTypes(values: ReadonlyArray<string>) {
+  const types = unique(values)
+  if (types.length === 0) throw new Error("responses requires at least one type")
+  const valid = types.filter(isResponseType)
+  const unknown = types.filter((value) => !isResponseType(value))
+  if (unknown.length > 0)
+    throw new Error(`unknown response types: ${unknown.join(", ")}`)
+  return valid
+}
+
+function parseTools(values: ReadonlyArray<string>) {
+  const tools = unique(values)
+  if (tools.length === 0) throw new Error("responses requires at least one tool or *")
+  if (tools.some((tool) => tool !== "*" && !/^[a-zA-Z0-9_.:-]+$/.test(tool)))
+    throw new Error("tool names may contain only letters, numbers, dots, underscores, colons, or dashes")
+  return tools
+}
+
+function unique(values: ReadonlyArray<string>) {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))]
+}
+
+function pick<T>(values: ReadonlyArray<T>) {
+  return values[Math.floor(Math.random() * values.length)]!
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function isJsonRecord(
+  value: JsonValue,
+): value is { readonly [key: string]: JsonValue } {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function isJson(value: unknown): value is JsonValue {
+  if (value === null) return true
+  if (["boolean", "number", "string"].includes(typeof value)) return true
+  if (Array.isArray(value)) return value.every(isJson)
+  if (!isRecord(value)) return false
+  return Object.values(value).every(isJson)
+}
+
+function isResponseType(value: string): value is ResponseType {
+  return responseTypes.some((type) => type === value)
+}