fix(subagent): lazy-register toolkit actions filtered out of fuzzy top-K

[senamakel]

Summary

• Stop wasting tokens when integrations_agent calls a Composio action slug that exists in the bound toolkit but was dropped by the up-front fuzzy top-K filter.
• Add LazyToolkitResolver: on an unknown call the inner loop builds the matching ComposioActionTool on the spot, admits it to the allowlist, and dispatches normally.
• Helpful error: genuine misses (typos, non-toolkit slugs) now include the available tool names so the model self-corrects in one turn instead of guessing.

Problem

integrations_agent narrows each Composio toolkit's per-action tools via a fuzzy top-K filter (12 for heavy toolkits like Gmail) so dense per-action JSON schemas don't blow Fireworks' grammar / context budget. The filter exists to keep schemas out of the system prompt — not to gate execution.

In practice the model frequently knows the correct slug (e.g. GMAIL_LIST_MESSAGES) even when it falls outside the top-K. The inner loop dead-ended with a bare Error: tool '...' is not available to the integrations_agent sub-agent, with no list of what is available, so the model retried / wandered, burning tokens.

Solution

In src/openhuman/agent/harness/subagent_runner/ops.rs:

• New LazyToolkitResolver struct holding the bound toolkit's full action catalogue + composio client. Built once in run_typed_mode for integrations_agent-with-toolkit alongside the existing top-K registration (re-uses the same fresh-actions / cached fallback).
• run_inner_loop now owns extra_tools / allowed_names (passed by value) so it can extend them mid-run, and takes an optional lazy_resolver: Option<LazyToolkitResolver>. Fork mode passes None.
• On unknown call: try the resolver first. Slug match → build ComposioActionTool, push into extra_tools, insert into allowed_names, dispatch on the same turn (and reuse on subsequent turns).
• For genuine misses, the error now lists the union of allowed names + toolkit slugs so the model can recover in one turn.

Tradeoff: a slightly looser invariant on allowed_names (it may grow during the loop), and one extra ComposioActionTool allocation per "miss". Both negligible vs. the token waste they replace.

Submission Checklist

• N/A: behaviour-only change to an internal sub-agent fallback path; existing 15 subagent_runner unit tests (including typed_mode_blocks_unallowed_tool_calls) still pass and exercise the gating logic.
• N/A: changed lines are inside the integrations_agent harness path which is exercised by existing rust tests; a dedicated unit test for the resolver would require stubbing ComposioClient, which has no mock harness today.
• N/A: behaviour-only change, no new feature rows in the coverage matrix.
• N/A: no feature-matrix IDs touched by this change.
• No new external network dependencies introduced.
• N/A: no release-cut surface changes.
• N/A: no linked issue.

Impact

• Runtime: integrations_agent (desktop core sidecar). No frontend impact, no Tauri shell changes, no schema/migration changes.
• Performance: removes an entire class of failed tool-call retry loops; one extra ComposioActionTool allocation per "miss" turn is negligible compared to the token spend it avoids.
• Security: no change in tool surface — only actions that the toolkit's own catalogue (from Composio) advertises can be lazily admitted; the connected + allowlist pre-flight in spawn_subagent is unchanged.

Related

• Closes:
• Follow-up PR(s)/TODOs:

Summary by CodeRabbit

• Refactor

  • Improved tool resolution flow and error messaging: unavailable tool errors now list resolvable tools and newly admitted tools are allowed for subsequent steps.

• Performance

  • Deferred tool construction until actually needed, reducing startup overhead and memory usage by loading tools on demand.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bd4c0e8e-900a-4b6b-825a-441300bcf9c6

📥 Commits

Reviewing files that changed from the base of the PR and between 389e43a and 8193d90.

📒 Files selected for processing (1)

• src/openhuman/agent/harness/subagent_runner/ops.rs

✅ Files skipped from review due to trivial changes (1)

• src/openhuman/agent/harness/subagent_runner/ops.rs

---

📝 Walkthrough

Walkthrough

A LazyToolkitResolver was added to defer construction of ComposioActionTool instances from a toolkit's full action catalogue. In typed mode the runner registers only fuzzy top-K tools up front, stores the full catalogue in the resolver, and lazily builds/admits tools on-demand during the inner loop; error messaging now includes resolver-known slugs.

Changes

Lazy Toolkit Resolution

Layer / File(s)	Summary
Data Shape src/openhuman/agent/harness/subagent_runner/ops.rs (lines 40–69)	Introduces LazyToolkitResolver with methods to resolve an action slug into a Box<dyn ComposioActionTool> and to list known slugs.
State Management src/openhuman/agent/harness/subagent_runner/ops.rs (lines 241–389)	Adds lazy_resolver: Option<LazyToolkitResolver> to the typed-mode runner state; when toolkit is provided, stores full integration.tools in the resolver while pushing only fuzzy top-K tools into dynamic_tools.
Function Signatures / Wiring src/openhuman/agent/harness/subagent_runner/ops.rs (lines 655–667, 763–767, 812–818)	Updates run_inner_loop signature to take owned extra_tools: Vec<_>, owned allowed_names: HashSet<String>, and lazy_resolver: Option<LazyToolkitResolver>; call sites updated (typed mode passes Some(...), fork mode passes None).
Core Logic src/openhuman/agent/harness/subagent_runner/ops.rs (lines 1103–1143)	Inner per-call resolution: if call.name not in allowed_names, attempt lazy resolution via lazy_resolver; on success insert tool into extra_tools and allowed_names. If still not allowed, include lazy_resolver.known_slugs() in constructed "Available tools" list.
Documentation / Manifest Cargo.toml	Cargo manifest touched (versioning/dependencies context for build).

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant AgentRunner as Runner
    participant Resolver as LazyToolkitResolver
    participant Toolkit as ToolkitCatalogue
    participant Tool as ComposioActionTool

    Note right of Runner: Startup (typed mode)
    Runner->>Toolkit: store full catalogue (lazy)
    Toolkit-->>Resolver: hold slugs & client

    Note right of Runner: During inner loop (tool call)
    Runner->>Resolver: resolve(call.name)?
    alt resolver has slug
        Resolver->>Toolkit: build action tool
        Toolkit-->>Tool: constructed
        Tool-->>Runner: boxed tool added
        Runner->>Runner: insert into extra_tools and allowed_names
        Runner->>Tool: execute tool call
    else not resolvable
        Runner->>Runner: report "tool not available" (include known slugs)
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat(agent): fuzzy-filter skills_agent toolkit actions by task prompt #579 — Introduced fuzzy top-K tool_filter pre-selection of toolkit actions; this PR complements it by keeping the full catalogue and lazily resolving filtered-away actions at runtime.

Suggested reviewers

• graycyrus

Poem

🐰 I stash the tools the clever folks send,
Keep only top picks, but save every friend.
When a call asks for one I once left behind,
I build it on demand — quick, nimble, and kind! 🎩✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: implementing lazy registration of toolkit actions that were filtered out by fuzzy top-K filtering to avoid token waste on retries.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Review rate limit: 1/5 review remaining, refill in 38 minutes and 45 seconds.}

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