@hraness/dawg 0.2.0 → 0.4.0

package/src/agent/tools.ts

@@ -1,12 +1,51 @@
 import {
-  AUTOMATION_LANES,
+  AUTOMATION_PARAMETERS,
+  automationPoints,
+  automationRange,
   SCORE_LIMITS,
   type AutomationParameter,
   type ScoreOperation,
   type TrackScore,
 } from "../../core/score.ts";
 import { AVAILABLE_INSTRUMENTS } from "../audio/wav.ts";
+import {
+  SYNTH_PRESETS,
+  SYNTH_SIMPLE,
+  isSynthPreset,
+  synthParamName,
+} from "../../core/synth.ts";
+import { applySynthCommand, type SynthCommand } from "../commands/synth.ts";
+import {
+  setSampleControls,
+  type SampleControlValue,
+} from "../commands/sample.ts";
+import {
+  EFFECT_NAMES,
+  FX_PRESETS,
+  effectSpec,
+  type EffectName,
+} from "../../core/fx.ts";
+import {
+  applyFxCommand,
+  effectPatch,
+  effectValues,
+  parseEffectName,
+  parseParamName,
+  type FxCommand,
+} from "../commands/fx.ts";
 import type { ChatTool } from "./gateway.ts";
+import { MEDIA_TOOLS } from "../media/tools.ts";
+import { PACK_TOOLS, PackToolError } from "./pack-tools.ts";
+import {
+  PreviewToolError,
+  previewSoundTool,
+  type PreviewHost,
+} from "./preview-tool.ts";
+import { PackError, type PackStore } from "../audio/packs.ts";
+import { RHYTHM_TOOLS } from "./rhythm-tools.ts";
+import { CHORD_TOOLS } from "./chord-tools.ts";
+import { DRUM_TOOLS } from "./drum-tools.ts";
+import type { MediaResult, MediaRunContext } from "../media/types.ts";
 import { pitchToMidi } from "./ops.ts";
 import {
   DRUM_VOICES,
@@ -15,8 +54,39 @@ import {
   parseDrumVoice,
   type DrumVoice,
 } from "../../core/drums.ts";
+import { trackSlug } from "../../core/slug.ts";
+import {
+  editFile,
+  listFiles,
+  readFile,
+  WORKSPACE_LIMITS,
+  WorkspaceError,
+  writeFile,
+  type WorkspaceScope,
+} from "./workspace.ts";
+import {
+  fetchUrl,
+  FETCH_LIMITS,
+  formatFetchedPage,
+  type Lookup,
+} from "../web/fetch.ts";
+import { WebError, type FetchLike } from "../web/http.ts";
+import {
+  describeSearchProvider,
+  formatSearchResults,
+  SEARCH_LIMITS,
+  webSearch,
+  type SearchSpend,
+} from "../web/search.ts";
 
 /** What a validated tool call asks the host to do. */
+export type ScorePlan = Readonly<{
+  kind: "score";
+  operations: readonly ScoreOperation[];
+  summary: string;
+  trackId?: string;
+}>;
+
 export type ToolPlan =
   | Readonly<{
       kind: "score";
@@ -29,7 +99,79 @@ export type ToolPlan =
       action: "play" | "pause" | "toggle";
       summary: string;
     }>
-  | Readonly<{ kind: "explain"; text: string; summary: string }>;
+  | Readonly<{ kind: "explain"; text: string; summary: string }>
+  | Readonly<{
+      kind: "action";
+      summary: string;
+      /** Side effects outside the score (files, network); bounded and async. */
+      run: (context: ActionContext) => Promise<ActionResult>;
+    }>
+  /**
+   * Score edits that need async work first (fetching a pack sound); `run`
+   * returns the score plan, committed like any other.
+   */
+  | Readonly<{
+      kind: "prepare";
+      summary: string;
+      run: (context: ActionContext) => Promise<ScorePlan>;
+    }>
+  /** A long-running local media job (download, stems, analysis, …). */
+  | Readonly<{
+      kind: "media";
+      summary: string;
+      run: (context: MediaRunContext) => Promise<MediaResult>;
+    }>;
+
+/** The project directory the workspace tools operate in. */
+export type WorkspaceHost = Readonly<{ root: string }>;
+
+/** Injection points for the web tools; defaults are the real network. */
+export type WebHost = Readonly<{
+  fetch?: FetchLike;
+  lookup?: Lookup;
+  /** Brave Web Search API key; defaults to `BRAVE_SEARCH_API_KEY` and overrides the chain. */
+  braveApiKey?: string;
+  /** AI Gateway key of the active provider; enables gateway search tools. */
+  gatewayApiKey?: string;
+  gatewayBaseUrl?: string;
+  /** Gateway search tool; defaults to `DAWG_WEB_SEARCH`, then `exa`. */
+  searchTool?: string;
+  /** OpenRouter key; defaults to `OPENROUTER_API_KEY`. */
+  openRouterApiKey?: string;
+  openRouterBaseUrl?: string;
+  /**
+   * Billed searches (gateway tools, OpenRouter web plugin) are reported here
+   * so the host can add them to its spend ledger (`webHostFor` in
+   * `src/agent/usage.ts`).
+   */
+  onSpend?: (spend: SearchSpend) => void;
+}>;
+
+/** What an `action` plan receives from the host when it runs. */
+export type ActionContext = Readonly<{
+  workspace?: WorkspaceHost;
+  /**
+   * Called after a successful `write_file`/`edit_file` with the
+   * project-relative path. Returned text (for example typecheck
+   * diagnostics) is appended to the tool result.
+   */
+  onWorkspaceWrite?: (path: string) => Promise<string | void> | string | void;
+  web?: WebHost;
+  signal?: AbortSignal;
+  /** Sample packs for list_packs/search_sounds/use_sound; default the user cache. */
+  packs?: PackStore;
+  /** Render and play hooks for preview_sound; absent renders in-thread, silent. */
+  preview?: PreviewHost;
+}>;
+
+export type ActionResult = Readonly<{
+  /** What the model reads; already bounded by the tool. */
+  content: string;
+  /** One line for the activity card. */
+  summary: string;
+  /** True when something outside the score changed (a file write). */
+  mutated?: boolean;
+}>;
 
 export type ToolContext = Readonly<{
   score: TrackScore;
@@ -54,10 +196,6 @@ export class ToolArgumentError extends Error {
   }
 }
 
-const AUTOMATION_PARAMETERS = Object.keys(
-  AUTOMATION_LANES,
-) as AutomationParameter[];
-
 const MAX_NOTES_PER_CALL = 128;
 const MAX_EXPLAIN_CHARS = 2_000;
 const ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
@@ -337,12 +475,16 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   },
   {
     name: "set_automation",
-    description: `Write an automation lane: volume (0..1), pan (-1..1), filter cutoff (${SCORE_LIMITS.minFilterCutoff}..${SCORE_LIMITS.maxFilterCutoff} Hz low-pass), resonance (0..${SCORE_LIMITS.maxFilterResonance}), delay-feedback (0..${SCORE_LIMITS.maxDelayFeedback}) or delay-mix (0..${SCORE_LIMITS.maxDelayMix}). Delay lanes need a delay on the track (set_effects) to be heard. mode=replace (default) rewrites the lane; merge keeps existing points at other beats. An empty replace clears it.`,
+    description: `Write an automation lane: volume 0..1, pan -1..1, filter (cutoff Hz), resonance 0..${SCORE_LIMITS.maxFilterResonance}, delay-feedback 0..${SCORE_LIMITS.maxDelayFeedback}, delay-mix, wt (wavetable position 0..1), or <effect>-<param> (the param's range). The effect must be on to be heard. mode=replace (default) rewrites the lane; merge keeps other beats. An empty replace clears it.`,
     parameters: {
       type: "object",
       properties: {
         trackId: trackIdSchema,
-        parameter: { type: "string", enum: AUTOMATION_PARAMETERS },
+        parameter: {
+          type: "string",
+          description:
+            "volume, pan, filter, resonance, delay-feedback, delay-mix, or <effect>-<param>",
+        },
         mode: { type: "string", enum: ["replace", "merge"] },
         points: {
           type: "array",
@@ -353,8 +495,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
               beat: beatSchema("Beat position"),
               value: {
                 type: "number",
-                description:
-                  "volume 0..1, pan -1..1, filter cutoff in Hz, resonance 0..1, delay-feedback 0..0.9, delay-mix 0..1",
+                description: "in the lane's range",
               },
             },
             required: ["beat", "value"],
@@ -376,7 +517,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
         args.mode === undefined
           ? "replace"
           : oneOf(args.mode, ["replace", "merge"], "mode");
-      const { min, max } = AUTOMATION_LANES[parameter];
+      const { min, max } = automationRange(parameter);
       const tpb = context.score.ticksPerBeat;
       const points = list(
         args,
@@ -391,7 +532,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
         };
       });
       const track = context.score.tracks.find((t) => t.id === trackId)!;
-      const existing = track[AUTOMATION_LANES[parameter].field] ?? [];
+      const existing = automationPoints(track, parameter);
       const merged = Array.from(
         new Map(
           [...(mode === "merge" ? existing : []), ...points].map((point) => [
@@ -413,9 +554,153 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
       };
     },
   },
+  {
+    name: "set_fx",
+    description:
+      "Turn an effect on/off, load a preset, or set params by dawg or Strudel name (lpq, delayfeedback…). on:true uses good defaults; effects and presets are in the brief.",
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: trackIdSchema,
+        effect: { type: "string", description: "see the brief's effects" },
+        on: { type: "boolean" },
+        preset: { type: "string" },
+        params: {
+          type: "object",
+          additionalProperties: { type: ["number", "string", "boolean"] },
+        },
+      },
+      required: ["effect"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = targetTrack(args, context);
+      const effect =
+        typeof args.effect === "string"
+          ? parseEffectName(args.effect)
+          : undefined;
+      if (!effect)
+        throw new ToolArgumentError(
+          `effect must be one of ${EFFECT_NAMES.join(", ")}`,
+        );
+      const command = fxToolCommand(effect, args);
+      const result = applyFxCommand(context.score, trackId, command);
+      if (!result.ok || !result.next)
+        throw new ToolArgumentError(result.message);
+      const track = context.score.tracks.find((t) => t.id === trackId)!;
+      const values = effectValues(
+        result.next.tracks.find((t) => t.id === trackId),
+        effect,
+      );
+      return {
+        kind: "score",
+        operations: [
+          {
+            type: "updateTrack",
+            trackId,
+            patch: effectPatch(track, effect, values ?? null),
+          },
+        ],
+        trackId,
+        summary: `${trackId} ${result.message}`,
+      };
+    },
+  },
+  {
+    name: "set_synth",
+    description:
+      "Shape a synth track's voice with Strudel synth params (attack decay sustain release, lpf lpq lpenv, fm fmh, unison detune spread, vib vibmod, penv, noise, pw…); null unsets one. preset loads a voice (instrument + params); reset clears all; zzfx takes a raw ZzFX array (empty slots null) and sets a z_* sound.",
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: trackIdSchema,
+        preset: { type: "string", enum: Object.keys(SYNTH_PRESETS) },
+        reset: { type: "boolean" },
+        zzfx: {
+          type: "array",
+          maxItems: 21,
+          items: { type: ["number", "null"] },
+        },
+        params: {
+          type: "object",
+          additionalProperties: {
+            type: ["number", "string", "boolean", "array", "null"],
+          },
+        },
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = targetTrack(args, context);
+      const command = synthToolCommand(args);
+      const result = applySynthCommand(context.score, trackId, command);
+      if (!result.ok || !result.next)
+        throw new ToolArgumentError(result.message);
+      const next = result.next.tracks.find((t) => t.id === trackId)!;
+      return {
+        kind: "score",
+        operations: [
+          {
+            type: "updateTrack",
+            trackId,
+            patch: { instrument: next.instrument, synth: next.synth ?? null },
+          },
+        ],
+        trackId,
+        summary: `${trackId} ${result.message}`,
+      };
+    },
+  },
+  {
+    name: "set_sample",
+    description:
+      "Set a sampler voice's Strudel sample controls: begin end gain speed unit(r|c|s) loop loopBegin loopEnd clip(legato) fit loopAt accelerate squiz cut; null unsets one.",
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: trackIdSchema,
+        voice: { type: "string" },
+        params: {
+          type: "object",
+          additionalProperties: {
+            type: ["number", "string", "boolean", "null"],
+          },
+        },
+      },
+      required: ["voice", "params"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = targetTrack(args, context);
+      const params = args.params;
+      if (
+        typeof args.voice !== "string" ||
+        typeof params !== "object" ||
+        params === null ||
+        Array.isArray(params)
+      )
+        throw new ToolArgumentError("set_sample needs voice and params");
+      const result = setSampleControls(
+        context.score,
+        trackId,
+        args.voice,
+        params as Record<string, SampleControlValue>,
+      );
+      if (!result.ok) throw new ToolArgumentError(result.message);
+      const next = result.next.tracks.find((t) => t.id === trackId)!;
+      return {
+        kind: "score",
+        operations: [
+          { type: "updateTrack", trackId, patch: { sampler: next.sampler } },
+        ],
+        trackId,
+        summary: `${trackId} ${result.message}`,
+      };
+    },
+  },
   {
     name: "set_effects",
-    description: `Set or remove a track's low-pass filter, tempo-synced stereo delay, and stereo reverb send. Pass null to remove an effect. filter: cutoff ${SCORE_LIMITS.minFilterCutoff}..${SCORE_LIMITS.maxFilterCutoff} Hz, resonance 0..${SCORE_LIMITS.maxFilterResonance}. delay: beats ${SCORE_LIMITS.minDelayBeats}..${SCORE_LIMITS.maxDelayBeats}, feedback 0..${SCORE_LIMITS.maxDelayFeedback}, mix 0..${SCORE_LIMITS.maxDelayMix}. reverb: mix 0..${SCORE_LIMITS.maxReverbMix} (0.15..0.35 is a natural room), size ${SCORE_LIMITS.minReverbSize}..${SCORE_LIMITS.maxReverbSize} (default 0.5; higher is a longer, darker tail).`,
+    description: `Shorthand: low-pass filter, delay (beats) and reverb (mix 0.15..0.35 is a room); null removes one. Prefer set_fx.`,
     parameters: {
       type: "object",
       properties: {
@@ -575,7 +860,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   },
   {
     name: "add_drums",
-    description: `Add drum hits to a kit track (create one with create_track instrument "kit"). Voices: ${DRUM_VOICES.map((info) => info.voice).join(", ")}. Give explicit hits, and/or patterns that repeat a voice every N beats across the loop.`,
+    description: `Add one-off drum hits to a kit track (create one with create_track instrument "kit"); prefer set_rhythm for repeating beats. Voices: ${DRUM_VOICES.map((info) => info.voice).join(", ")}. Give explicit hits, and/or patterns that repeat a voice every N beats across the loop.`,
     parameters: {
       type: "object",
       properties: {
@@ -827,8 +1112,329 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
       return { kind: "explain", text, summary: text.slice(0, 80) };
     },
   },
+  {
+    name: "list_files",
+    description:
+      "List a project directory (default: the project root): directories first, then files with size and mtime. At most 500 entries; .dawg/ is hidden.",
+    parameters: {
+      type: "object",
+      properties: { path: pathSchema("Project-relative directory") },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const path = optionalPath(args);
+      return {
+        kind: "action",
+        summary: `list ${path || "."}`,
+        run: async (action) => {
+          const scope = workspaceScope(action, context);
+          const result = await listFiles(scope, path);
+          return { content: result.text, summary: result.summary };
+        },
+      };
+    },
+  },
+  {
+    name: "read_file",
+    description: `Read a UTF-8 text file from the project by line range (offset is 1-based, limit is a line count). Output is capped at ${WORKSPACE_LIMITS.maxReadBytes / 1024} KiB; binary files report size and type.`,
+    parameters: {
+      type: "object",
+      properties: {
+        path: pathSchema("Project-relative file"),
+        offset: {
+          type: "integer",
+          minimum: 1,
+          description: "First line (1-based)",
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: WORKSPACE_LIMITS.maxReadLines,
+          description: "Number of lines",
+        },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const path = requiredPath(args);
+      const offset = optionalNumber(args, "offset", { min: 1, integer: true });
+      const limit = optionalNumber(args, "limit", {
+        min: 1,
+        max: WORKSPACE_LIMITS.maxReadLines,
+        integer: true,
+      });
+      return {
+        kind: "action",
+        summary: `read ${path}`,
+        run: async (action) => {
+          const scope = workspaceScope(action, context);
+          const result = await readFile(scope, path, {
+            ...(offset !== undefined ? { offset } : {}),
+            ...(limit !== undefined ? { limit } : {}),
+          });
+          return { content: result.text, summary: result.summary };
+        },
+      };
+    },
+  },
+  {
+    name: "write_file",
+    description: `Create or replace a file atomically with the full content (at most ${WORKSPACE_LIMITS.maxWriteBytes / 1024 / 1024} MiB). Writable: song.ts and the focused track's tracks/<slug>/ directory, where notes.md is your scratchpad. Parent directories are created.`,
+    parameters: {
+      type: "object",
+      properties: {
+        path: pathSchema("Project-relative file"),
+        content: { type: "string", description: "Entire new file content" },
+      },
+      required: ["path", "content"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const path = requiredPath(args);
+      if (typeof args.content !== "string")
+        throw new ToolArgumentError("content must be a string");
+      const content = args.content;
+      return {
+        kind: "action",
+        summary: `write ${path}`,
+        run: async (action) => {
+          const scope = workspaceScope(action, context);
+          const result = await writeFile(scope, path, content);
+          return {
+            content: await afterWrite(action, result.rel, result.text),
+            summary: result.summary,
+            mutated: true,
+          };
+        },
+      };
+    },
+  },
+  {
+    name: "edit_file",
+    description:
+      "Replace one exact occurrence of old with new in a writable file (same scope as write_file). old must match exactly once; otherwise the result tells you the count. Prefer this over many note tools for large edits or restructuring of tracks/<slug>/track.ts.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: pathSchema("Project-relative file"),
+        old: {
+          type: "string",
+          minLength: 1,
+          description: "Exact text to replace",
+        },
+        new: { type: "string", description: "Replacement text" },
+      },
+      required: ["path", "old", "new"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const path = requiredPath(args);
+      if (typeof args.old !== "string" || args.old.length === 0)
+        throw new ToolArgumentError("old must be a non-empty string");
+      if (typeof args.new !== "string")
+        throw new ToolArgumentError("new must be a string");
+      const { old: oldText, new: newText } = args;
+      return {
+        kind: "action",
+        summary: `edit ${path}`,
+        run: async (action) => {
+          const scope = workspaceScope(action, context);
+          const result = await editFile(scope, path, oldText, newText);
+          return {
+            content: await afterWrite(action, result.rel, result.text),
+            summary: result.summary,
+            mutated: true,
+          };
+        },
+      };
+    },
+  },
+  {
+    name: "web_search",
+    description: `Search the web; returns up to ${SEARCH_LIMITS.defaultCount} results as title, url and snippet. Follow up with fetch_url to read a page.`,
+    parameters: {
+      type: "object",
+      properties: {
+        query: { type: "string", maxLength: SEARCH_LIMITS.maxQueryChars },
+        count: { type: "integer", minimum: 1, maximum: SEARCH_LIMITS.maxCount },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+    plan(args) {
+      if (typeof args.query !== "string" || args.query.trim().length === 0)
+        throw new ToolArgumentError("query must be a non-empty string");
+      if (args.query.length > SEARCH_LIMITS.maxQueryChars)
+        throw new ToolArgumentError(
+          `query must be at most ${SEARCH_LIMITS.maxQueryChars} characters`,
+        );
+      const query = args.query.trim();
+      const count = optionalNumber(args, "count", {
+        min: 1,
+        max: SEARCH_LIMITS.maxCount,
+        integer: true,
+      });
+      return {
+        kind: "action",
+        summary: `search ${query.slice(0, 60)}`,
+        run: async (action) => {
+          const web = action.web ?? {};
+          const outcome = await webSearch(query, {
+            ...(count !== undefined ? { count } : {}),
+            braveApiKey: web.braveApiKey ?? process.env.BRAVE_SEARCH_API_KEY,
+            ...(web.gatewayApiKey ? { gatewayApiKey: web.gatewayApiKey } : {}),
+            ...(web.gatewayBaseUrl
+              ? { gatewayBaseUrl: web.gatewayBaseUrl }
+              : {}),
+            searchTool: web.searchTool ?? process.env.DAWG_WEB_SEARCH,
+            openRouterApiKey:
+              web.openRouterApiKey ?? process.env.OPENROUTER_API_KEY,
+            ...(web.openRouterBaseUrl
+              ? { openRouterBaseUrl: web.openRouterBaseUrl }
+              : {}),
+            ...(web.fetch ? { fetch: web.fetch } : {}),
+            ...(web.onSpend ? { onSpend: web.onSpend } : {}),
+            ...(action.signal ? { signal: action.signal } : {}),
+          });
+          const via = describeSearchProvider(outcome);
+          return {
+            content: formatSearchResults(outcome, query),
+            summary: `searched via ${via}${outcome.fallbackFrom ? " (fallback)" : ""} · ${outcome.results.length} result${outcome.results.length === 1 ? "" : "s"}`,
+          };
+        },
+      };
+    },
+  },
+  {
+    name: "fetch_url",
+    description: `Fetch a public http(s) page and return its readable text (HTML reduced to headings, text and links; at most ${FETCH_LIMITS.maxOutputChars / 1024} KiB). Private and local addresses are refused.`,
+    parameters: {
+      type: "object",
+      properties: {
+        url: { type: "string", maxLength: FETCH_LIMITS.maxUrlChars },
+      },
+      required: ["url"],
+      additionalProperties: false,
+    },
+    plan(args) {
+      if (typeof args.url !== "string" || args.url.trim().length === 0)
+        throw new ToolArgumentError("url must be a non-empty string");
+      if (args.url.length > FETCH_LIMITS.maxUrlChars)
+        throw new ToolArgumentError(
+          `url must be at most ${FETCH_LIMITS.maxUrlChars} characters`,
+        );
+      const url = args.url.trim();
+      let host = url;
+      try {
+        host = new URL(url).hostname;
+      } catch {
+        // admitUrl reports the diagnostic when the action runs.
+      }
+      return {
+        kind: "action",
+        summary: `fetch ${host.slice(0, 60)}`,
+        run: async (action) => {
+          const page = await fetchUrl(url, {
+            ...(action.web?.fetch ? { fetch: action.web.fetch } : {}),
+            ...(action.web?.lookup ? { lookup: action.web.lookup } : {}),
+            ...(action.signal ? { signal: action.signal } : {}),
+          });
+          return {
+            content: formatFetchedPage(page),
+            summary: `fetched ${new URL(page.url).hostname} (${page.bytes} bytes${page.truncated ? ", truncated" : ""})`,
+          };
+        },
+      };
+    },
+  },
+  ...RHYTHM_TOOLS,
+  ...CHORD_TOOLS,
+  ...DRUM_TOOLS,
+  ...MEDIA_TOOLS,
+  ...PACK_TOOLS,
+  // Looks tools up at call time, so it can plan any of the above.
+  previewSoundTool((name) => findAgentTool(name)),
 ] satisfies AgentTool[]);
 
+/** Errors an `action` plan may raise that are safe to show to the model. */
+export function isActionDiagnostic(error: unknown): boolean {
+  return (
+    error instanceof WorkspaceError ||
+    error instanceof WebError ||
+    error instanceof ToolArgumentError ||
+    error instanceof PackToolError ||
+    error instanceof PreviewToolError ||
+    error instanceof PackError
+  );
+}
+
+const MAX_HOOK_CHARS = 4_000;
+
+async function afterWrite(
+  action: ActionContext,
+  rel: string,
+  text: string,
+): Promise<string> {
+  if (!action.onWorkspaceWrite) return text;
+  try {
+    const note = await action.onWorkspaceWrite(rel);
+    return typeof note === "string" && note.trim()
+      ? `${text}\n${note.trim().slice(0, MAX_HOOK_CHARS)}`
+      : text;
+  } catch (error) {
+    const message = (
+      error instanceof Error ? error.message : String(error)
+    ).slice(0, MAX_HOOK_CHARS);
+    return `${text}\nafter write: ${message}`;
+  }
+}
+
+/** The slug of the focused track: its name, or its id for a draft track. */
+export function focusedTrackSlug(
+  context: Pick<ToolContext, "score" | "focusedTrackId">,
+): string {
+  const track = context.score.tracks.find(
+    (candidate) => candidate.id === context.focusedTrackId,
+  );
+  return trackSlug(track?.name ?? context.focusedTrackId);
+}
+
+function workspaceScope(
+  action: ActionContext,
+  context: ToolContext,
+): WorkspaceScope {
+  if (!action.workspace)
+    throw new WorkspaceError("file tools are unavailable in this session");
+  return { root: action.workspace.root, trackSlug: focusedTrackSlug(context) };
+}
+
+function pathSchema(description: string) {
+  return {
+    type: "string",
+    maxLength: WORKSPACE_LIMITS.maxPathChars,
+    description,
+  };
+}
+
+function requiredPath(args: Record<string, unknown>): string {
+  const path = optionalPath(args);
+  if (path === undefined || path.length === 0)
+    throw new ToolArgumentError("path is required");
+  return path;
+}
+
+function optionalPath(args: Record<string, unknown>): string | undefined {
+  if (args.path === undefined) return undefined;
+  if (typeof args.path !== "string")
+    throw new ToolArgumentError("path must be a string");
+  if (args.path.length > WORKSPACE_LIMITS.maxPathChars)
+    throw new ToolArgumentError(
+      `path must be at most ${WORKSPACE_LIMITS.maxPathChars} characters`,
+    );
+  return args.path;
+}
+
 const TOOLS_BY_NAME = new Map(AGENT_TOOLS.map((tool) => [tool.name, tool]));
 
 export function findAgentTool(
@@ -853,6 +1459,91 @@ export function chatTools(
   }));
 }
 
+function fxToolCommand(
+  effect: EffectName,
+  args: Record<string, unknown>,
+): FxCommand {
+  if (args.on === false) return { type: "fx-off", effect };
+  if (args.preset !== undefined) {
+    if (
+      typeof args.preset !== "string" ||
+      !Object.prototype.hasOwnProperty.call(
+        FX_PRESETS[effect] ?? {},
+        args.preset,
+      )
+    )
+      throw new ToolArgumentError(
+        `${effect} presets: ${Object.keys(FX_PRESETS[effect] ?? {}).join(", ") || "none"}`,
+      );
+    return { type: "fx-preset", effect, preset: args.preset };
+  }
+  if (args.params === undefined) {
+    if (args.on === true) return { type: "fx-on", effect };
+    throw new ToolArgumentError("set_fx needs on, preset, or params");
+  }
+  const params = record(args.params, "params");
+  const values: Record<string, number | string | boolean> = {};
+  for (const [name, value] of Object.entries(params)) {
+    const param = parseParamName(effect, name);
+    if (!param)
+      throw new ToolArgumentError(
+        `${effect} has no parameter ${name}; it takes ${Object.keys(effectSpec(effect).params).join(", ")}`,
+      );
+    if (
+      typeof value !== "number" &&
+      typeof value !== "string" &&
+      typeof value !== "boolean"
+    )
+      throw new ToolArgumentError(`${effect} ${name} must be a value`);
+    values[param] = value;
+  }
+  return { type: "fx-set", effect, values };
+}
+
+function synthToolCommand(args: Record<string, unknown>): SynthCommand {
+  if (args.reset === true) return { type: "synth-reset" };
+  if (args.zzfx !== undefined) {
+    if (
+      !Array.isArray(args.zzfx) ||
+      args.zzfx.length > 21 ||
+      !args.zzfx.every((n) => n === null || typeof n === "number")
+    )
+      throw new ToolArgumentError("zzfx must be up to 21 numbers or nulls");
+    return { type: "synth-zzfx", values: args.zzfx as (number | null)[] };
+  }
+  if (args.preset !== undefined) {
+    if (typeof args.preset !== "string" || !isSynthPreset(args.preset))
+      throw new ToolArgumentError(
+        `synth presets: ${Object.keys(SYNTH_PRESETS).join(", ")}`,
+      );
+    return { type: "synth-preset", preset: args.preset };
+  }
+  if (args.params === undefined)
+    throw new ToolArgumentError("set_synth needs preset, reset, or params");
+  const params = record(args.params, "params");
+  const values: Record<
+    string,
+    number | string | boolean | readonly number[] | null
+  > = {};
+  for (const [name, value] of Object.entries(params)) {
+    const param = synthParamName(name);
+    if (!param)
+      throw new ToolArgumentError(
+        `synth has no parameter ${name}; basics: ${SYNTH_SIMPLE.join(", ")} (DAWG.md lists all)`,
+      );
+    if (
+      value !== null &&
+      typeof value !== "number" &&
+      typeof value !== "string" &&
+      typeof value !== "boolean" &&
+      !(Array.isArray(value) && value.every((n) => typeof n === "number"))
+    )
+      throw new ToolArgumentError(`synth ${name} must be a value`);
+    values[param] = value as number;
+  }
+  return { type: "synth-set", values };
+}
+
 function targetTrack(args: Record<string, unknown>, context: ToolContext) {
   const trackId = args.trackId ?? context.focusedTrackId;
   if (typeof trackId !== "string" || trackId.length > SCORE_LIMITS.maxIdLength)