Support invoke_agent in direct runtimes

[kwakayama]

What changed

• materialize tools: { invoke_agent: true } as a runtime-local platform tool in direct runtimes
• resolve project agents lazily, reject self-invocation, forward structured context, and propagate cancellation
• preserve explicit delegates capability boundaries, including empty delegate scopes
• keep hosted and direct terminology aligned around generic invoke_agent
• keep hosted skill child-run overrides out of direct tools that cannot consume them
• document invoke_agent as a first-class multi-agent communication tool
• add portable regression coverage across Deno, Node, and Bun

Root cause

Direct-runtime MCP discovery deliberately excluded invoke_agent because it is runtime-provided, but the direct agent factory never materialized the tool. Explicit declarations therefore reached tool assembly as unresolved booleans and failed with Unknown tool reference: invoke_agent.

Impact

Projects pulled from Studio can retain tools: { invoke_agent: true } and run the same generic multi-agent communication pattern locally without converting to fixed delegate bindings. Explicit delegates configurations remain the capability boundary and cannot expose generic agent selection.

Validation

• repository-pinned Deno 2.7.7 full pre-push gate passed: formatting, lint, typecheck, unit tests, and cwd tests
• 3,780 unit tests passed, 0 failed, 1 ignored
• focused Node delegation/composition suite passed: 41 tests, 0 failures
• generated API reference check passed
• git diff --check passed
• all 27 required PR checks passed, including Node, Bun, integration, binary E2E, browser E2E, coverage, and CodeQL
• sample Salesforce project build passed
• browser regression verified invoke_agent completed and invoked the case-ingest child; the prior unknown-tool failure no longer occurred

Review follow-ups

Addressed delegate scoping, direct-runtime override behavior, cross-runtime test execution, generated documentation, and child cancellation propagation.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

The PR adds a runtime-local invoke_agent tool. Direct runtimes can configure it explicitly. Hosted runtimes use a generic binding when no explicit delegate list exists. Skill-delegation override handling now respects tool capabilities.

Generic agent delegation

Layer / File(s)	Summary
Runtime invoke_agent tool src/agent/runtime/agent-delegation.ts, src/agent/runtime/agent-delegation.test.ts, src/agent/runtime/mcp-server-tool-sources.ts, src/agent/runtime/skill-metadata.test.ts	Adds input validation, lazy target resolution, self-invocation rejection, structured context, abort propagation, and test coverage.
Tool override and streaming integration src/agent/runtime/local-tool.ts, src/agent/runtime/skill-delegation-overrides.ts, src/agent/runtime/skill-delegation-overrides.test.ts, src/agent/runtime/index.ts, src/agent/composition/composition.ts	Tracks tools that do not support hosted skill overrides and passes configured tools and abort signals through execution paths.
Direct runtime tool registration src/agent/factory.ts, src/agent/factory.test.ts	Creates agent-aware invoke_agent tools, handles scoped delegates, and validates tools: true combinations.
Hosted binding and documentation updates src/agent/hosted/..., docs/guides/multi-agent.md, docs/api-reference/veryfront/agent.md	Renames the fallback hosted binding to generic, updates related expectations and comments, and refreshes API source links and delegation documentation.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CallingAgent
  participant invoke_agent
  participant AgentResolver
  participant TargetAgent
  CallingAgent->>invoke_agent: Provide target, task, prompt, and context
  invoke_agent->>AgentResolver: Resolve target at call time
  AgentResolver-->>invoke_agent: Return target agent
  invoke_agent->>TargetAgent: Execute augmented prompt
  TargetAgent-->>CallingAgent: Return delegated result

Loading

Possibly related PRs

• veryfront/veryfront-code#3464: Both PRs modify skill-delegation override behavior and runtime tests.
• veryfront/veryfront-code#3485: Both PRs modify invoke_agent delegation and override-forwarding behavior.

Suggested reviewers: kojiwakayama

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 78.57% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: adding invoke_agent support in direct runtimes.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/support-invoke-agent

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6d379f8214

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/agent/runtime/agent-delegation.test.ts`:
- Around line 122-192: Replace the three Deno.test declarations in
src/agent/runtime/agent-delegation.test.ts lines 122-192 with describe() and
it() from `#veryfront/testing/bdd.ts`, and use assertions from
`#veryfront/testing/assert.ts`. Apply the same BDD test API conversion to the
changed declaration in src/agent/runtime/skill-metadata.test.ts line 974; update
imports as needed and preserve each test’s existing behavior.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8b149e02-c2ac-4c6b-8dfd-5c3dba32a68e

📥 Commits

Reviewing files that changed from the base of the PR and between a043100 and 6d379f8.

📒 Files selected for processing (10)

• docs/guides/multi-agent.md
• src/agent/factory.test.ts
• src/agent/factory.ts
• src/agent/hosted/cloud-agent-chat-execution.ts
• src/agent/hosted/cloud-agent-child-tools.ts
• src/agent/hosted/veryfront-cloud-agent-service.test.ts
• src/agent/runtime/agent-delegation.test.ts
• src/agent/runtime/agent-delegation.ts
• src/agent/runtime/mcp-server-tool-sources.ts
• src/agent/runtime/skill-metadata.test.ts

[kwakayama]

Codex independent review

Reviewed SHA: 6d379f8214f91c2793c1dd922325ac7777b8acad

Findings

1. HIGH — Explicit delegate boundaries can be bypassed by the generic tool. src/agent/factory.ts:314-348 materializes invoke_agent before processing delegates, and the later branch only adds fixed-target tools when delegates?.length is nonzero. As a result, delegates: [] still exposes unrestricted agent selection and delegates: ["writer"] can invoke any other registered project agent through agent_id. This contradicts the documented capability boundary in docs/guides/multi-agent.md:133-140 and can transitively expose a child's broader tools/integrations. Fix: reject or remove generic invoke_agent whenever delegates !== undefined, including an empty list, and add regression cases for both empty and nonempty delegate lists.

2. MEDIUM — Loaded-skill child overrides are silently discarded in direct execution. The runtime applies model, thinking, and max_steps to every invoke_agent call (src/agent/runtime/skill-delegation-overrides.ts:66-89), but the new direct executor only forwards a synthesized input string to agentAsTool (src/agent/runtime/agent-delegation.ts:88-90), whose child call uses configured defaults. Fix: either carry supported overrides into the direct child run, or explicitly exclude direct invoke_agent from override injection; cover the chosen contract in generate and stream tests.

3. MEDIUM — The execution regressions are Deno-only, so Node/Bun CI does not exercise this direct-runtime feature. The new cases use Deno.test at src/agent/runtime/agent-delegation.test.ts:122, :152, and :172; tests/node/run-tests.mjs deliberately drops every test file containing Deno. (the Bun runner shares the exclusion). The green Node/Bun jobs therefore prove neither child execution nor self-invocation for this change. Fix: put the new cases in a portable BDD test file, or convert the file to describe/it from #veryfront/testing/bdd.ts so the cross-runtime runners execute them.

4. MEDIUM — Required generated API documentation is stale. docs/api-reference/veryfront/agent.md:548 still links buildAgentDelegateTools to its old source line, and ci (lint) fails docs:api-reference:check with outdated: veryfront/agent.md. Fix: run deno task docs, commit the generated reference update, and rerun CI.

Verification

• Reviewed only a043100b45767333027dd1a0b87b7da8f072907f...6d379f8214f91c2793c1dd922325ac7777b8acad (10 files, 193 additions, 19 deletions); git diff --check passed.
• Exact-head deno lint passed for all 9 changed TypeScript files. No LSP diagnostics tool was available in this reviewer environment; exact-head CI ci (typecheck) passed.
• CI snapshot was complete and head-stable: 26 passed, 1 failed (ci (lint), investigated above), 0 pending, 6 intentional release/split-mode skips. Unit, integration, Node, Bun, coverage, CodeQL, format, and binary/smoke jobs passed.
• Three unresolved review threads remain; they cover the delegate boundary, override mismatch, and portable test API.
• Local focused execution was attempted from an isolated exact-head archive. Deno 2.9.4 failed during module load with the known node:util/types brand-check environment error (0 tests executed), so no local test-pass claim is made.

Verdict: REQUEST_CHANGES
Score: 58/100 (correctness 23/40, tests 10/20, reliability/security 6/15, standards/maintainability 11/15, scope/docs/rollout 8/10)

Review-Gate:
Reviewer: Codex
Reviewed-SHA: 6d379f8
Score: 58/100
Actionable-Findings: 4
Verdict: REQUEST_CHANGES

[kwakayama]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dfc38e39f6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kwakayama]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: d339b92620

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kwakayama]

Addressed the four findings from the 58/100 review against 6d379f8:

1. Explicit delegate boundaries: generic invoke_agent is removed whenever delegates is explicitly configured, including an empty list; tools: true is rejected for explicit delegate scopes. Regression coverage includes empty and non-empty scopes. Fixed in 02f4df8.
2. Direct-runtime skill overrides: direct invoke_agent is explicitly marked as not supporting hosted child overrides, while hosted invoke_agent retains override support. Generate and stream behavior is covered. Fixed in 02f4df8.
3. Cross-runtime coverage: delegation execution tests now use the portable BDD API and run under Node/Bun as well as Deno. Fixed in dfc38e3.
4. Generated API documentation: regenerated and docs:api-reference:check passes. Fixed in 02f4df8.

A subsequent review also identified cancellation propagation; the parent abort signal now reaches the invoked child and has regression coverage in d339b92.

Current head: d339b92. Verification: 27 PR checks passed, 0 failed, 0 pending; full local pre-push validation passed with 3,780 tests; 0 unresolved review threads. The latest Codex review on this head reported no major issues.

[kwakayama]

Codex exact-head review

Reviewed SHA: d339b9262053eeea80f26af15d78a2a8d6281d7a

Findings

No blocking or unresolved actionable findings.

The original four findings are fixed at this head: explicit delegate scopes suppress generic selection, direct tools do not receive unsupported hosted overrides, execution coverage runs across runtimes, and generated API documentation is current. Parent cancellation also propagates into child execution.

Verification

• Reviewed the complete base-to-head diff: 16 files, 350 additions, 59 deletions.
• Fresh focused Deno run: 72 tests passed, 0 failed.
• Fresh changed-file lint: 9 files checked successfully.
• Fresh API-reference generation check: 43 files current.
• Exact-head CI: 27 passed, 0 failed, 0 pending; 6 conditional release/split jobs skipped as expected.
• Full local pre-push gate: formatting, lint, typecheck, and 3,780 unit tests passed.
• Review pagination complete; 0 unresolved threads.
• PR is non-draft, cleanly mergeable, and the local branch matches the remote head.

Scoring

• Correctness and completeness: 39/40
• Regression tests and verification: 19/20
• Reliability and security: 14/15
• Repository standards and maintainability: 14/15
• Scope, documentation, and rollout clarity: 10/10

Minor deductions are non-blocking: direct runtimes retain the documented acyclic-authoring expectation instead of the hosted depth cap, and the generic unavailable-target branch is straightforward but lacks its own dedicated assertion.

Verdict: APPROVE
Score: 96/100

Review-Gate:
Reviewer: Codex
Reviewed-SHA: d339b92
Score: 96/100
Actionable-Findings: 0
Verdict: APPROVE