wenjin272 opened a new pull request, #1401:
URL: https://github.com/apache/flink-agents/pull/1401

   Linked issue: Closes #1399
   
   ### Purpose of change
   
   Models can execute only tools and sub-agents enabled for that model. 
BashTool remains available without registration, but requires `tools=["bash"]`; 
enabling Skills automatically adds only `load_skill`.
   
   #### Runtime flow
   
   `ChatModelAction` identifies the model that produced the response. 
`ToolCallAction` obtains that model's initialized tool names and checks each 
call before resolving its TOOL/AGENT resource or injecting tool arguments. 
Disabled calls produce individual error responses; enabled calls follow the 
existing execution path. Java/Python model wrappers expose the same name lookup 
across the language bridge.
   
   `AgentPlan` supplies a default BashTool independently of Skills. Model setup 
includes it only when explicitly configured.
   
   #### Key decisions
   
   Reuse Java `getToolNames()` and add Python `get_tool_names()`, including 
generated sub-agent names. Keep resource registration separate from model 
permission. Provide BashTool by default rather than requiring callers to 
register its implementation class; preserve explicit same-name registrations in 
the current Agent.
   
   ### Behavioral Semantics
   
   #### Interaction decisions
   
   | Configuration / call | Result |
   |---|---|
   | Registered tool or sub-agent, disabled on originating model | Tool error; 
no resource lookup or invocation |
   | Enabled and disabled calls in one response | Enabled calls still execute |
   | Skills enabled, `bash` omitted | `load_skill` exposed; `bash` disabled |
   | `bash` explicitly enabled, with or without Skills | Built-in BashTool 
available with existing command/directory policy |
   | Current Agent explicitly registers `bash` | Its provider replaces the 
built-in default |
   
   #### Behavioral contracts
   
   - Check against the actual originating model, including routed/fallback 
selections.
   - Reject each disabled call independently before resolving its resource or 
injected arguments.
   - Include sub-agent call names and framework-added `load_skill` in the 
callable set.
   - Require explicit BashTool enablement, regardless of Skills configuration.
   - Preserve current-Agent explicit `bash` registrations. Each child Agent 
also receives a local built-in default, which can shadow a parent's custom 
`bash`.
   
   #### Failure behavior
   
   Disabled calls return `Tool '<name>' is not enabled for model '<model>'.`. 
Failure to resolve the originating model propagates. Existing enabled-tool 
failures, framework-fault and cancellation behavior remain unchanged.
   
   Known limitation: MCP tools are discovered at runtime. A remote tool named 
`bash` conflicts with the built-in provider and fails startup, even if no model 
enabled `bash`. This PR does not change MCP collision handling.
   
   ### Tests
   
   | Contract | Coverage |
   |---|---|
   | Disabled calls rejected before lookup; valid siblings continue | Java 
`ToolCallActionTest` / `ToolCallActionReportTest`; Python 
`test_tool_call_action.py` |
   | Model lookup failure propagates | Python 
`test_model_lookup_failure_propagates_without_executing_tools` |
   | Sub-agent and framework tool names included | Java/Python chat-model setup 
and tool-call tests |
   | Name lookup crosses both language bridges | `PythonChatModelSetupTest`, 
`test_java_chat_model.py`; real Pemja wrapper probes |
   | Bash requires opt-in with/without Skills | Java/Python 
`ReActAgentSkillsTest` equivalents, including actual `echo` execution |
   | Local explicit `bash` preserved | `AgentPlanDeclareSkillsTest`, Python 
Skills plan tests |
   | Plan serialization includes built-in providers | Updated Java/Python 
cross-language snapshots and round-trip tests |
   | Runtime failure, cleanup and recovery assertions still execute | Four 
adapted Runtime test classes: 136 passed |
   | MCP collision and parent-tool shadowing | Local ResourceCache/discovery 
probes; no committed regression tests |
   
   Validation: full Java API and Plan suites passed; Python API/Plan/Runtime: 
**2,614 passed, 18 skipped**. After adapting Runtime fixtures, all **136 
tests** in the four affected classes passed. Spotless, Ruff, and example/E2E 
fixture compilation passed.
   
   Not verified: the complete Java Runtime suite was not rerun after the final 
test-fixture updates; live external-model and deployed Flink cross-language E2E 
runs were not performed.
   
   <details>
   <summary>Validation commands and implementation details</summary>
   
   - `mvn --batch-mode --no-transfer-progress -pl runtime -am test`: API/Plan 
passed; the Runtime run identified 20 fixture failures addressed by this PR's 
test updates.
   - `mvn --batch-mode --no-transfer-progress -pl runtime -am test 
-Dtest=SubagentAwaitCleanupTest,InternalSubagentFrameworkFaultTest,ActionExecutionOperatorTest,ResourceCacheTest
 -Dsurefire.failIfNoSpecifiedTests=false`: 136 passed after adaptation.
   - From `python/`, with the active environment's purelib exported as 
`PYTHONPATH`: `.venv/bin/python -m pytest flink_agents/api flink_agents/plan 
flink_agents/runtime -m 'not integration' -q --tb=short`.
   - Java stores configured and generated tool names in its mutable list; 
membership checking uses a set. Python derives names from initialized tool 
objects. The bridge transports a flat string list.
   - No state/event schema changes. Plan snapshots reflect the new built-in 
resource providers.
   
   </details>
   
   ### API
   
   Java `getToolNames()` now includes sub-agent callable names; Python adds 
`get_tool_names()`. Java `toolNames` is initialized as a final mutable list. 
Model-generated calls to registered but disabled resources now fail. Models 
that used automatically exposed BashTool must add `bash` to `tools`. Skill 
discovery, `load_skill`, and BashTool command/directory policy are unchanged.
   
   ### Documentation
   
   - [ ] `doc-needed`
   - [ ] `doc-not-needed`
   - [x] `doc-included`
   
   ### Was this patch authored or co-authored using generative AI tooling?
   
   - [x] Yes
   - [ ] No
   
   Generated-by: Codex CLI 0.153.4 (GPT-6)
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to