SEAJellySEAJelly

Tools & Toolkits Architecture

This is the control plane for builtin agent tools and toolkits.

Goals

  • Keep LLM-facing tools atomic and explicit.
  • Let the UI grant a grouped capability through a single toolkit switch.
  • Centralize policy injection and tool-focus behavior.
  • Keep runtime code as the source of truth.

Mental Model

  • A tool is an atomic capability the model can call directly.
  • A toolkit is a code-owned bundle of multiple tools plus policy and UI metadata.
  • tools_config stores agent permissions.

Config Semantics

  • If tools_config.self_evolution_toolkit === true, member tools are enabled by default.
  • If tools_config.self_evolution_toolkit === false, all member tools are disabled.
  • If the toolkit key is absent, legacy per-tool booleans still work.
  • Individual member tool booleans are treated as overrides.

Zero-schema-migration compatibility while supporting the new one-switch UX.

Adding a New Toolkit

  1. Implement the atomic tool functions in tooling/tools/<your-toolkit>.ts.
  2. Add the toolkit key and member tool names to catalog.ts.
  3. Add client-safe toolkit metadata to BUILTIN_TOOLKIT_CATALOG.
  4. Add runtime behavior in toolkits/<your-toolkit>.ts:
    • buildPolicySection for system prompt instructions
    • getGenerateTextDirective for activeTools / toolChoice behavior
  5. Register the toolkit in registry.ts.
  6. Mount the atomic tools from createAgentTools().

Adding a New Builtin Tool

  1. Add the tool implementation in createAgentTools() or extract it into tooling/tools/<domain>.ts.
  2. Register the tool in BUILTIN_TOOL_CATALOG.
  3. If the tool needs prompt policy, add it in runtime.ts.
  4. If more tools arrive later, promote them into a toolkit.

Adding a Sub-App Tool

  • Implement in createSubAppTools() in tools.ts.
  • Bind through sub_apps.tool_names.
  • If it needs prompt policy, add it in runtime.ts.
  • Do not hardcode policy text in loop.ts.

Rules of Thumb

  • Prefer a toolkit when the UI should expose one high-level permission switch.
  • Prefer atomic tools for the model.
  • Keep audit, allowlist, and write-guard logic close to the tool implementation.
  • Keep prompt policy text close to the toolkit runtime definition.
  • Treat SKILL.md as examples, not the canonical authority.