refactor(backend): split chatTools.ts into per-tool registry (#2)

↗ view on GitHub · Archibald312 · 2026-05-14 · eb461a39

Move every tool the LLM can call into its own file under
backend/src/lib/tools/, dispatched through a typed registry. chatTools.ts
shrinks from 3,284 to 976 lines and contains only orchestration
(SYSTEM_PROMPT, runLLMStream, citation parsing, message-building, doc
context, workflow store).

Why: a single 3K-line monolith made every tool change risky, every new
tool an exercise in pattern-matching against existing branches, and the
schema/dispatch split (TOOLS/PROJECT_EXTRA_TOOLS/TABULAR_TOOLS/WORKFLOW_TOOLS
arrays composed by callers, mirrored by a giant if/else in runToolCalls)
left two places that had to stay in sync. Adding a tool now requires
one new file plus one line in the registry - no edits to the monolith.

Structure:
  tools/types.ts          ToolDefinition / ToolContext / ToolExecutionResult,
                          plus the tool-result types (EditAnnotation,
                          DocCreatedResult, DocReplicatedResult,
                          DocEditedResult, TurnEditState)
  tools/registry.ts       TOOL_REGISTRY (as const, typed-literal names),
                          buildAvailableToolSchemas, runToolCalls dispatcher
  tools/<toolName>.ts     One ToolDefinition per file (10 tools)
  tools/shared/           Helpers used by multiple tools
                          (documentReading, generateDocx, runEditDocument)

Per-tool availability is declared via `availableWhen(ctx)` predicates,
replacing the previous route-shaped tool composition. The registry
filters schemas per turn, so the model never sees tools that can't run.

The legacy arrays TOOLS, PROJECT_EXTRA_TOOLS, TABULAR_TOOLS,
WORKFLOW_TOOLS are deleted (callers in routes/tabular.ts and
routes/projectChat.ts lose the `extraTools:` pass-through accordingly).

Verified: tsc --noEmit clean, 57/57 unit tests pass. Behavior-preserving:
schemas reproduced verbatim, side-effect aggregation shape unchanged,
SSE events emitted identically.

TECHDEBT.md picks up two e2e findings surfaced (not caused) by this
work: the log-out test now times out, and the test Supabase project is
missing the user_profiles migration.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Repository Archibald312/GordonOSS
Author Archibald312 <129438073+Archibald312@users.noreply.github.com>
Authored
Parents 450632b9
Stats 19 files changed , +2576 , -2344
Part of chatTools.ts refactor into per-tool registry

Capture this commit into my fork

Download a Markdown prompt that tells Claude how to port this exact commit into your working tree. Run it via claude -p < capture-commit-eb461a39.md from inside the repo you want the change in.

⬇ Download capture-commit-eb461a39.md