@llm4ts/runner 2.54.1 → 3.2.0

package/dist/Tools.js

@@ -0,0 +1,142 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { builtinTools } from "@llm4ts/flow/tools/Builtin";
+import { isToolName, renderUsage, specOf } from "@llm4ts/flow/tools/Tool";
+const tierRank = { project: 0, global: 1, builtin: 2 };
+export const catalogEntries = (kits) => {
+    const byName = new Map();
+    for (const tool of builtinTools) {
+        byName.set(tool.name, { _tag: "builtin", name: tool.name, tool });
+    }
+    const ordered = [...kits].sort((left, right) => tierRank[right.tier] - tierRank[left.tier]);
+    for (const kit of ordered) {
+        for (const name of kit.tools) {
+            if (!isToolName(name)) {
+                continue;
+            }
+            const file = ["ts", "js"]
+                .map((extension) => join(kit.root, "tools", `${name}.${extension}`))
+                .find((candidate) => existsSync(candidate));
+            if (file !== undefined) {
+                byName.set(name, { _tag: "kit", name, kit, file });
+            }
+        }
+    }
+    return [...byName.values()].sort((left, right) => left.name.localeCompare(right.name));
+};
+export const findEntry = (catalog, name) => catalog.find((entry) => entry.name === name);
+export class PresetError extends Schema.TaggedError()("PresetError", {
+    preset: Schema.String,
+    message: Schema.String
+}) {
+}
+export const resolvePreset = (catalog, name, extra) => {
+    const preset = catalog.presets.find((candidate) => candidate.name === name);
+    if (preset === undefined) {
+        return Effect.succeed(undefined);
+    }
+    const [toolName, ...rest] = preset.command;
+    if (toolName === undefined) {
+        return Effect.fail(new PresetError({ preset: name, message: "preset names no tool" }));
+    }
+    const entry = findEntry(catalog.entries, toolName);
+    if (entry === undefined) {
+        return Effect.fail(new PresetError({
+            preset: name,
+            message: `preset runs '${toolName}', which is not a catalog tool (run \`llm4ts tool list\`)`
+        }));
+    }
+    return Effect.succeed({ preset, entry, argv: [...rest, ...extra] });
+};
+/**
+ * The repository a worktree belongs to: `git rev-parse --git-common-dir`
+ * points back at the main checkout from any worktree, so the project tier
+ * (`<repo>/.llm4ts/kits`) is found without a file in the worktree or an
+ * environment variable the executor would strip (ADR 0048). Falls back to
+ * `cwd` outside a repository.
+ */
+export const projectRootOf = (cwd) => {
+    try {
+        const common = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"]
+        }).trim();
+        if (common.length === 0) {
+            return cwd;
+        }
+        const absolute = isAbsolute(common) ? common : resolve(cwd, common);
+        return dirname(absolute);
+    }
+    catch {
+        return cwd;
+    }
+};
+/** One line per catalog entry and preset, for `llm4ts tool list`. */
+export const renderCatalog = (catalog, specs) => {
+    const lines = [];
+    for (const entry of catalog.entries) {
+        const spec = specs.get(entry.name);
+        const origin = entry._tag === "builtin" ? "" : ` [${entry.kit.name} kit]`;
+        lines.push(spec === undefined
+            ? `${entry.name}${origin}`
+            : `${renderUsage(spec)}${origin}\n    ${spec.purpose}`);
+    }
+    if (catalog.presets.length > 0) {
+        lines.push("", "Presets (pack: command):");
+        for (const preset of catalog.presets) {
+            lines.push(`  ${preset.name} (${preset.pack}): ${preset.command.join(" ")}`);
+        }
+    }
+    return lines.join("\n");
+};
+export const catalogJson = (catalog, specs) => ({
+    tools: catalog.entries.map((entry) => {
+        const spec = specs.get(entry.name);
+        return {
+            name: entry.name,
+            origin: entry._tag === "builtin" ? "builtin" : `kit:${entry.kit.name}`,
+            ...(spec === undefined ? {} : { purpose: spec.purpose, usage: renderUsage(spec) })
+        };
+    }),
+    presets: catalog.presets.map((preset) => ({
+        name: preset.name,
+        pack: preset.pack,
+        command: preset.command.join(" ")
+    }))
+});
+/** Exit status for a report: 0 ok, 1 issues. Errors exit 2 (the CLI's own). */
+export const reportExitCode = (report) => (report.ok ? 0 : 1);
+/**
+ * The paragraph a coder's brief carries (ADR 0048): one rule, then each
+ * preset of the story's pack with the command to run. `LLM4TS_TOOL_BRIEF=off`
+ * drops it, for a run without the catalog to compare against.
+ */
+export const toolBrief = (presets, specs, environment = process.env) => {
+    if (environment.LLM4TS_TOOL_BRIEF?.trim().toLowerCase() === "off") {
+        return undefined;
+    }
+    const lines = [
+        "Tools: for validating a document, comparing two outputs, or checking a contract, run the",
+        "project's tool instead of writing a script — `llm4ts tool <name> [--flag value]` prints JSON",
+        "(ok, summary, issues). `llm4ts tool list` shows every tool; `llm4ts tool describe <name>`",
+        "its arguments. Never write a Python or Node one-liner for a job a tool covers."
+    ];
+    if (presets.length > 0) {
+        lines.push("", "This pack's presets (run them by name from the worktree root):");
+        for (const preset of presets) {
+            const [toolName, ...rest] = preset.command;
+            const spec = toolName === undefined ? undefined : specs.get(toolName);
+            const fixed = rest.length === 0 ? "" : ` (fixed: ${rest.join(" ")})`;
+            const purpose = spec === undefined ? "" : ` — ${spec.purpose}`;
+            lines.push(`- \`llm4ts tool ${preset.name}\`${fixed}${purpose}`);
+        }
+    }
+    return lines.join("\n");
+};
+/** Specs of the built-in tools, known without running anything. */
+export const builtinSpecs = () => new Map(builtinTools.map((tool) => [tool.name, specOf(tool)]));
+//# sourceMappingURL=Tools.js.map

package/dist/Tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tools.js","sourceRoot":"","sources":["../src/Tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/runner",
-  "version": "2.54.1",
+  "version": "3.2.0",
   "description": "Node runner, CLI, terminal, and MCP composition for llm4ts",
   "license": "MIT",
   "type": "module",
@@ -13,11 +13,12 @@
     "src"
   ],
   "exports": {
+    "./ToolMain": "./dist/ToolMain.js",
+    "./Tools": "./dist/Tools.js",
     ".": "./dist/index.js",
     "./Cli": "./dist/Cli.js",
     "./AgentTree": "./dist/AgentTree.js",
     "./AgentTreeSurface": "./dist/AgentTreeSurface.js",
-    "./CoderPolicy": "./dist/CoderPolicy.js",
     "./Connectors": "./dist/Connectors.js",
     "./Costs": "./dist/Costs.js",
     "./Doctor": "./dist/Doctor.js",
@@ -37,7 +38,6 @@
     "./NodeTemporaryFiles": "./dist/NodeTemporaryFiles.js",
     "./NodeWorkspace": "./dist/NodeWorkspace.js",
     "./Otel": "./dist/Otel.js",
-    "./NodeRuntime": "./dist/NodeRuntime.js",
     "./Packs": "./dist/Packs.js",
     "./Profile": "./dist/Profile.js",
     "./PiModels": "./dist/PiModels.js",
@@ -75,8 +75,8 @@
     "typescript"
   ],
   "dependencies": {
-    "@llm4ts/core": "2.54.1",
-    "@llm4ts/flow": "2.54.1"
+    "@llm4ts/core": "3.2.0",
+    "@llm4ts/flow": "3.2.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"

package/src/Kits.ts

@@ -29,6 +29,8 @@ export interface DiscoveredKit {
   readonly packs: ReadonlyArray<string>
   /** Flow names: every `flows/<name>.ts|js` (not `lib/` or `test/`). */
   readonly flows: ReadonlyArray<string>
+  /** Tool names: every `tools/<name>.ts|js` (ADR 0048), run by `llm4ts tool`. */
+  readonly tools: ReadonlyArray<string>
   readonly shadows: ReadonlyArray<KitTier>
 }
 
@@ -118,7 +120,14 @@ const readKit = (
         .map((entry) => entry.replace(/\.(ts|js)$/, ""))
         .sort()
     : []
-  if (packs.length === 0 && flows.length === 0) {
+  const toolsDir = join(root, "tools")
+  const tools = isDirectory(toolsDir)
+    ? readdirSync(toolsDir)
+        .filter((entry) => entry.endsWith(".ts") || entry.endsWith(".js"))
+        .map((entry) => entry.replace(/\.(ts|js)$/, ""))
+        .sort()
+    : []
+  if (packs.length === 0 && flows.length === 0 && tools.length === 0) {
     return undefined
   }
   const readme = join(root, "README.md")
@@ -131,7 +140,8 @@ const readKit = (
     tier,
     ...(description === undefined ? {} : { description }),
     packs,
-    flows
+    flows,
+    tools
   }
 }
 

package/src/Profile.ts

@@ -65,11 +65,16 @@ export const Gap = Schema.Struct({
 })
 export type Gap = typeof Gap.Type
 
-/** The coder's tool calls by kind of work (build, install and git count as other). */
+/**
+ * The coder's tool calls by kind of work (build, install and git count as
+ * other). `script` is the ad-hoc Python/Node one-liners, heredocs and scratch
+ * files it improvised; profiles saved before it existed decode it as 0.
+ */
 export const ToolCalls = Schema.Struct({
   explore: Schema.Int,
   edit: Schema.Int,
   test: Schema.Int,
+  script: Schema.Int.pipe(Schema.withDecodingDefaultKey(Effect.succeed(0))),
   other: Schema.Int
 })
 export type ToolCalls = typeof ToolCalls.Type
@@ -146,7 +151,7 @@ export const ProfileReport = Schema.Struct({
   models: Schema.Array(ModelRow),
   gates: Schema.Array(GateRow),
   tools: Schema.Array(CountRow),
-  /** Coder tool time by kind of work: explore, edit, test, build, install, git, other. */
+  /** Coder tool time by kind of work: explore, edit, test, script, build, install, git, other. */
   toolCategories: Schema.Array(CountRow),
   waits: Schema.Array(CountRow),
   /** Timed on the run's events, in no story: the run's own planning, or a seat no story owns. */
@@ -184,7 +189,7 @@ interface Lane {
   tasks: number
   /** When the coder's first task began: setup and task planning come before it. */
   firstTask: number | undefined
-  toolCalls: { explore: number; edit: number; test: number; other: number }
+  toolCalls: { explore: number; edit: number; test: number; script: number; other: number }
   firstEdit: number | undefined
   exploreBeforeEdit: number
   unverifiedClaims: number
@@ -363,7 +368,7 @@ export const profileOf = (inputs: ReadonlyArray<TreeInput>): ProfileReport => {
             openTools: 0,
             tasks: 0,
             firstTask: undefined,
-            toolCalls: { explore: 0, edit: 0, test: 0, other: 0 },
+            toolCalls: { explore: 0, edit: 0, test: 0, script: 0, other: 0 },
             firstEdit: undefined,
             exploreBeforeEdit: 0,
             unverifiedClaims: 0,
@@ -397,7 +402,10 @@ export const profileOf = (inputs: ReadonlyArray<TreeInput>): ProfileReport => {
         lane?.timed.push({ at, event })
         if (lane !== undefined && event.kind === "tool" && event.category !== undefined) {
           const kind =
-            event.category === "explore" || event.category === "edit" || event.category === "test"
+            event.category === "explore" ||
+            event.category === "edit" ||
+            event.category === "test" ||
+            event.category === "script"
               ? event.category
               : "other"
           lane.toolCalls[kind] += 1
@@ -808,6 +816,15 @@ const findingsOf = (facts: {
         ]
       : []
   )
+  const improvised = facts.stories.flatMap((story) =>
+    story.toolCalls.script >= 3
+      ? [
+          {
+            text: `${story.id}: ${story.toolCalls.script} ad-hoc scripts — a pack tool preset (llm4ts tool) would make this repeatable`
+          }
+        ]
+      : []
+  )
   const growth = facts.stories.flatMap((story) =>
     story.turns.promptGrowth &&
     story.turns.firstPrompt !== undefined &&
@@ -819,7 +836,7 @@ const findingsOf = (facts: {
         ]
       : []
   )
-  return [...ranked, ...fabricated, ...growth]
+  return [...ranked, ...fabricated, ...improvised, ...growth]
 }
 
 const table = (
@@ -908,6 +925,7 @@ export const renderProfile = (report: ProfileReport): string => {
         story.toolCalls.explore +
           story.toolCalls.edit +
           story.toolCalls.test +
+          story.toolCalls.script +
           story.toolCalls.other ===
         0
     )
@@ -922,6 +940,7 @@ export const renderProfile = (report: ProfileReport): string => {
               "explore",
               "edit",
               "test",
+              "script",
               "other",
               "before 1st edit",
               "1st edit at"
@@ -932,6 +951,7 @@ export const renderProfile = (report: ProfileReport): string => {
               String(story.toolCalls.explore),
               String(story.toolCalls.edit),
               String(story.toolCalls.test),
+              String(story.toolCalls.script),
               String(story.toolCalls.other),
               story.firstEditMs === undefined ? "" : `${story.exploreBeforeEdit} explore`,
               story.firstEditMs === undefined ? "never" : duration(story.firstEditMs)
@@ -1091,6 +1111,7 @@ export const profileDelta = (before: ProfileReport, after: ProfileReport): Profi
       count("coder turns", (r) => sum(r.stories.map((s) => s.turns.count))),
       count("coder edits", (r) => sum(r.stories.map((s) => s.toolCalls.edit)), "none"),
       count("coder test runs", (r) => sum(r.stories.map((s) => s.toolCalls.test)), "none"),
+      count("coder scripts", (r) => sum(r.stories.map((s) => s.toolCalls.script))),
       count("reviewer calls", (r) => roleCalls(r, "reviewer")),
       count("judge calls", (r) => roleCalls(r, "judge")),
       count("gate runs", (r) => sum(r.gates.map((g) => g.runs))),

package/src/ToolMain.ts

@@ -0,0 +1,76 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as Layer from "effect/Layer"
+import { SoapTransport, makeNodeSoapTransport } from "@llm4ts/flow/endpoint/Transport"
+import { ToolContext, ToolReport, ToolSpec, specOf, type ToolShape } from "@llm4ts/flow/tools/Tool"
+import { NodePlainFileStoreLive } from "./NodePlainFileStore.ts"
+
+/**
+ * The main of a kit tool file (`kits/<kit>/tools/<name>.ts`, ADR 0048):
+ * `llm4ts tool` runs the file as a Node child and speaks this protocol —
+ * `--describe` prints the `ToolSpec`; otherwise the parsed arguments arrive
+ * as one JSON object on stdin and the `ToolReport` goes out on stdout. Exit
+ * 0 when the report is ok, 1 when it carries issues, 2 when the tool could
+ * not run (the error is JSON on stdout too, `{"error": …}`). `--project
+ * <root>` names the project the tool runs for (default: the current
+ * directory); secrets resolve from this process's environment.
+ */
+export const runToolMain = (tool: ToolShape): void => {
+  if (process.argv.includes("--describe")) {
+    process.stdout.write(`${JSON.stringify(Schema.encodeSync(ToolSpec)(specOf(tool)))}\n`)
+    return
+  }
+  void readStdin().then((text) => {
+    let values: Record<string, unknown>
+    try {
+      const parsed: unknown = text.trim().length === 0 ? {} : JSON.parse(text)
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("stdin must hold one JSON object of arguments")
+      }
+      values = Object.fromEntries(Object.entries(parsed))
+    } catch (error) {
+      process.stdout.write(
+        `${JSON.stringify({ error: error instanceof Error ? error.message : String(error) })}\n`
+      )
+      process.exitCode = 2
+      return
+    }
+    const projectFlag = process.argv.indexOf("--project")
+    const projectRoot =
+      projectFlag >= 0 && process.argv[projectFlag + 1] !== undefined
+        ? process.argv[projectFlag + 1]
+        : process.cwd()
+    return Effect.runPromise(
+      tool.execute(values).pipe(
+        Effect.provide(
+          Layer.mergeAll(
+            NodePlainFileStoreLive,
+            Layer.succeed(ToolContext)({ projectRoot, environment: process.env }),
+            Layer.succeed(SoapTransport)(makeNodeSoapTransport())
+          )
+        ),
+        Effect.match({
+          onFailure: (error) => {
+            process.stdout.write(`${JSON.stringify({ error: error.message })}\n`)
+            process.exitCode = 2
+          },
+          onSuccess: (report) => {
+            process.stdout.write(`${JSON.stringify(Schema.encodeSync(ToolReport)(report))}\n`)
+            process.exitCode = report.ok ? 0 : 1
+          }
+        })
+      )
+    )
+  })
+}
+
+const readStdin = (): Promise<string> =>
+  new Promise((resolvePromise, rejectPromise) => {
+    const chunks: Array<Buffer> = []
+    process.stdin.on("data", (chunk: Buffer) => chunks.push(chunk))
+    process.stdin.on("end", () => resolvePromise(Buffer.concat(chunks).toString("utf8")))
+    process.stdin.on("error", rejectPromise)
+  })
+
+/** The child's stdout as the parent reads it: a report, or the error it printed. */
+export const ChildToolOutput = Schema.Union([Schema.Struct({ error: Schema.String }), ToolReport])

package/src/Tools.ts

@@ -0,0 +1,204 @@
+import { execFileSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import { dirname, isAbsolute, join, resolve } from "node:path"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { builtinTools } from "@llm4ts/flow/tools/Builtin"
+import type { ToolReport, ToolSpec } from "@llm4ts/flow/tools/Tool"
+import { isToolName, renderUsage, specOf, type ToolShape } from "@llm4ts/flow/tools/Tool"
+import type { ToolPreset } from "@llm4ts/flow/Pack"
+import type { DiscoveredKit } from "./Kits.ts"
+
+/**
+ * The tool catalog (ADR 0048): the built-in tools, every discovered kit's
+ * `tools/<name>.ts`, and the presets of the packs in reach. A kit tool with
+ * a built-in's name shadows it, project kits first, as flows do.
+ */
+export type CatalogEntry =
+  | { readonly _tag: "builtin"; readonly name: string; readonly tool: ToolShape }
+  | {
+      readonly _tag: "kit"
+      readonly name: string
+      readonly kit: DiscoveredKit
+      readonly file: string
+    }
+
+export interface ToolCatalog {
+  readonly entries: ReadonlyArray<CatalogEntry>
+  readonly presets: ReadonlyArray<ToolPreset & { readonly pack: string }>
+}
+
+const tierRank = { project: 0, global: 1, builtin: 2 } as const
+
+export const catalogEntries = (kits: ReadonlyArray<DiscoveredKit>): ReadonlyArray<CatalogEntry> => {
+  const byName = new Map<string, CatalogEntry>()
+  for (const tool of builtinTools) {
+    byName.set(tool.name, { _tag: "builtin", name: tool.name, tool })
+  }
+  const ordered = [...kits].sort((left, right) => tierRank[right.tier] - tierRank[left.tier])
+  for (const kit of ordered) {
+    for (const name of kit.tools) {
+      if (!isToolName(name)) {
+        continue
+      }
+      const file = ["ts", "js"]
+        .map((extension) => join(kit.root, "tools", `${name}.${extension}`))
+        .find((candidate) => existsSync(candidate))
+      if (file !== undefined) {
+        byName.set(name, { _tag: "kit", name, kit, file })
+      }
+    }
+  }
+  return [...byName.values()].sort((left, right) => left.name.localeCompare(right.name))
+}
+
+export const findEntry = (
+  catalog: ReadonlyArray<CatalogEntry>,
+  name: string
+): CatalogEntry | undefined => catalog.find((entry) => entry.name === name)
+
+/**
+ * A preset is `tool --flag value …`: the catalog tool, then its arguments,
+ * with whatever the caller appends. A preset never names another preset.
+ */
+export interface ResolvedPreset {
+  readonly preset: ToolPreset & { readonly pack: string }
+  readonly entry: CatalogEntry
+  readonly argv: ReadonlyArray<string>
+}
+
+export class PresetError extends Schema.TaggedError<PresetError>()("PresetError", {
+  preset: Schema.String,
+  message: Schema.String
+}) {}
+
+export const resolvePreset = (
+  catalog: ToolCatalog,
+  name: string,
+  extra: ReadonlyArray<string>
+): Effect.Effect<ResolvedPreset | undefined, PresetError> => {
+  const preset = catalog.presets.find((candidate) => candidate.name === name)
+  if (preset === undefined) {
+    return Effect.succeed(undefined)
+  }
+  const [toolName, ...rest] = preset.command
+  if (toolName === undefined) {
+    return Effect.fail(new PresetError({ preset: name, message: "preset names no tool" }))
+  }
+  const entry = findEntry(catalog.entries, toolName)
+  if (entry === undefined) {
+    return Effect.fail(
+      new PresetError({
+        preset: name,
+        message: `preset runs '${toolName}', which is not a catalog tool (run \`llm4ts tool list\`)`
+      })
+    )
+  }
+  return Effect.succeed({ preset, entry, argv: [...rest, ...extra] })
+}
+
+/**
+ * The repository a worktree belongs to: `git rev-parse --git-common-dir`
+ * points back at the main checkout from any worktree, so the project tier
+ * (`<repo>/.llm4ts/kits`) is found without a file in the worktree or an
+ * environment variable the executor would strip (ADR 0048). Falls back to
+ * `cwd` outside a repository.
+ */
+export const projectRootOf = (cwd: string): string => {
+  try {
+    const common = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim()
+    if (common.length === 0) {
+      return cwd
+    }
+    const absolute = isAbsolute(common) ? common : resolve(cwd, common)
+    return dirname(absolute)
+  } catch {
+    return cwd
+  }
+}
+
+/** One line per catalog entry and preset, for `llm4ts tool list`. */
+export const renderCatalog = (
+  catalog: ToolCatalog,
+  specs: ReadonlyMap<string, ToolSpec>
+): string => {
+  const lines: Array<string> = []
+  for (const entry of catalog.entries) {
+    const spec = specs.get(entry.name)
+    const origin = entry._tag === "builtin" ? "" : ` [${entry.kit.name} kit]`
+    lines.push(
+      spec === undefined
+        ? `${entry.name}${origin}`
+        : `${renderUsage(spec)}${origin}\n    ${spec.purpose}`
+    )
+  }
+  if (catalog.presets.length > 0) {
+    lines.push("", "Presets (pack: command):")
+    for (const preset of catalog.presets) {
+      lines.push(`  ${preset.name} (${preset.pack}): ${preset.command.join(" ")}`)
+    }
+  }
+  return lines.join("\n")
+}
+
+export const catalogJson = (
+  catalog: ToolCatalog,
+  specs: ReadonlyMap<string, ToolSpec>
+): typeof Schema.Json.Type => ({
+  tools: catalog.entries.map((entry) => {
+    const spec = specs.get(entry.name)
+    return {
+      name: entry.name,
+      origin: entry._tag === "builtin" ? "builtin" : `kit:${entry.kit.name}`,
+      ...(spec === undefined ? {} : { purpose: spec.purpose, usage: renderUsage(spec) })
+    }
+  }),
+  presets: catalog.presets.map((preset) => ({
+    name: preset.name,
+    pack: preset.pack,
+    command: preset.command.join(" ")
+  }))
+})
+
+/** Exit status for a report: 0 ok, 1 issues. Errors exit 2 (the CLI's own). */
+export const reportExitCode = (report: ToolReport): number => (report.ok ? 0 : 1)
+
+/**
+ * The paragraph a coder's brief carries (ADR 0048): one rule, then each
+ * preset of the story's pack with the command to run. `LLM4TS_TOOL_BRIEF=off`
+ * drops it, for a run without the catalog to compare against.
+ */
+export const toolBrief = (
+  presets: ReadonlyArray<ToolPreset>,
+  specs: ReadonlyMap<string, ToolSpec>,
+  environment: Readonly<Record<string, string | undefined>> = process.env
+): string | undefined => {
+  if (environment.LLM4TS_TOOL_BRIEF?.trim().toLowerCase() === "off") {
+    return undefined
+  }
+  const lines = [
+    "Tools: for validating a document, comparing two outputs, or checking a contract, run the",
+    "project's tool instead of writing a script — `llm4ts tool <name> [--flag value]` prints JSON",
+    "(ok, summary, issues). `llm4ts tool list` shows every tool; `llm4ts tool describe <name>`",
+    "its arguments. Never write a Python or Node one-liner for a job a tool covers."
+  ]
+  if (presets.length > 0) {
+    lines.push("", "This pack's presets (run them by name from the worktree root):")
+    for (const preset of presets) {
+      const [toolName, ...rest] = preset.command
+      const spec = toolName === undefined ? undefined : specs.get(toolName)
+      const fixed = rest.length === 0 ? "" : ` (fixed: ${rest.join(" ")})`
+      const purpose = spec === undefined ? "" : ` — ${spec.purpose}`
+      lines.push(`- \`llm4ts tool ${preset.name}\`${fixed}${purpose}`)
+    }
+  }
+  return lines.join("\n")
+}
+
+/** Specs of the built-in tools, known without running anything. */
+export const builtinSpecs = (): ReadonlyMap<string, ToolSpec> =>
+  new Map(builtinTools.map((tool) => [tool.name, specOf(tool)]))

package/dist/CoderPolicy.d.ts

@@ -1,12 +0,0 @@
-import * as Schema from "effect/Schema";
-import type { Grants } from "@llm4ts/core/Capability";
-import { CliConnectorConfig } from "@llm4ts/core/ConnectorConfig";
-declare const AppliedCoderPolicy_base: Schema.Class<AppliedCoderPolicy, Schema.Struct<{
-    readonly config: typeof CliConnectorConfig;
-    readonly unenforceable: Schema.$Array<Schema.String>;
-}>, {}>;
-export declare class AppliedCoderPolicy extends AppliedCoderPolicy_base {
-}
-export declare const applyCoderPolicy: (config: CliConnectorConfig, grants: Grants) => AppliedCoderPolicy;
-export {};
-//# sourceMappingURL=CoderPolicy.d.ts.map

package/dist/CoderPolicy.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"CoderPolicy.d.ts","sourceRoot":"","sources":["../src/CoderPolicy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAA;;;;;AAGjE,qBAAa,kBAAmB,SAAQ,uBAGtC;CAAG;AAgDL,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,kBAAkB,EAC1B,QAAQ,MAAM,KACb,kBAqBF,CAAA"}