feat(tools): igniteTools core + ToolDialect port (ignite-element/tools) — PR 1/3

[0xjcf]

What

Adds igniteTools(component, dialect?) and the new ignite-element/tools entrypoint — the hexagonal, SDK-neutral bridge from the agent-runtime contract (getSchema() + execute()) to LLM tool-use. PR 1 of 3 (core + port + fake dialect; no provider SDK).

Design (docs/ignite-tools.md)

ignite's "no lock-in" philosophy applied one layer up — providers sit behind a single port.

• Functional core (pure, no I/O):
  • buildManifest(getSchema()) → NeutralManifest ({ name, description, inputSchema, gated }[], sorted; gated+unavailable commands omitted).
  • resolveCall(name, input) → Result<Route, ToolError> — validates the model-supplied input against the command schema + availability; errors as values, never throws.
• ToolDialect port: toToolDefs / parseToolCalls / toToolResult — the provider boundary; adapters are pure format translators on separate entrypoints (PR 2/3).
• Imperative shell: invoke(call) → Promise<Result<{ snapshot, events }, ToolError>> — the single execute() side effect; a failed command is data the agent maps to a provider tool_result.
• ToolError union: UnknownCommand · InvalidInput · Unavailable · ExecuteFailed.

Scope

• ✅ Neutral core + ToolDialect port + imperative shell + ignite-element/tools entrypoint.
• ✅ Composes with canExecute (duck-typed; all commands offered without it).
• ❌ No provider SDK — Anthropic (/tools/anthropic) and OpenAI/Codex/Ollama (/tools/openai) adapters land in PR 2 and PR 3.

Tests (TDD, zero LLM calls)

• src/tests/tools.test.ts — 35 behavior tests vs a fake component + fake dialect: manifest building + gating, input validation (type/enum/range/required/multipleOf float-safety/string/array), invoke routing + errors-as-values, and the dialect round-trip (parse → invoke → toToolResult).
• src/tests/types/tools.types.test.ts — typed observation flows from the component generics.

Verification

• verify.sh --full: format / lint / typecheck / test / architecture-drift / behavior-boundaries — all pass.
• npm run build + verify:exports — the new ./tools entrypoint builds (ESM+CJS+types) and resolves.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 68b82f7f-20f5-401f-8a1f-f6239455bd07

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/ignite-tools-core

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 94.89051% with 7 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (beta@36ebd26). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
packages/ignite-element/src/tools/core.ts	93.51%	7 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             beta      #64   +/-   ##
=======================================
  Coverage        ?   89.76%           
=======================================
  Files           ?       30           
  Lines           ?     1485           
  Branches        ?      426           
=======================================
  Hits            ?     1333           
  Misses          ?      142           
  Partials        ?       10           

Flag	Coverage Δ
unittests	89.76% <94.89%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/ignite-element/src/tools/igniteTools.ts	100.00% <100.00%> (ø)
packages/ignite-element/src/tools/result.ts	100.00% <100.00%> (ø)
packages/ignite-element/src/tools/core.ts	93.51% <93.51%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.