feat(app): mark offloaded tool placeholders with structured metadata - #3853

Part of #3845 (see "About the issue link" below)

AgentScope Version

main @ d8ebf89 (rebased; originally opened against 782bd43)

Description

Problem

After ToolOffloadMiddleware offloads a timed-out tool call, it yields a synthetic ToolChunk/ToolResponse with state=ToolResultState.SUCCESS and instructions in plain text. The only way for downstream code to tell "still running in background" from "done" is to parse the placeholder text — exactly the text-based detection called out in #3845. Concretely, gate middlewares such as SOPStepSubmitMiddleware._submitted / TeamMemberMiddleware compare state == ToolResultState.SUCCESS, so a still-running offloaded submit is currently indistinguishable from a completed one.

Changes

src/agentscope/app/middleware/_tool_offload_middleware.py:

• The placeholder ToolChunk/ToolResponse now carry structured metadata — background_task_id, tool_name, tool_state: "running", offloaded_at — which flows into the context ToolResultBlock like any tool metadata. Zero behavior change; the state stays SUCCESS because ToolResponse.state is typed as a Literal of the four terminal states, so introducing a non-terminal state here would be a breaking design change left to the maintainers ([Bug]: ToolOffloadMiddleware reports a still-running tool as SUCCESS and may deliver the result after the agent has finalized #3845 asks for it, but it reaches far beyond this middleware).
• With this marker, downstream consumers (UIs, gate middlewares, user code) can distinguish a pending offloaded call from a real success without text parsing.

About the issue link

This PR intentionally does not use Fixes #3845: that issue also asks for a persistent result store, per-tool execution policies, and a task management API — none of which belong in this change, and the issue should stay open for them. #3845 is confirmed and assigned to @konlue (this PR's author).

Note on the original second commit

This PR originally also fixed stopped background tools being reported as "has completed" — while it was open, that misreport was independently fixed on main (interrupted responses now render as "has been cancelled"), so the commit was dropped in the rebase to avoid duplicating it. Two small gaps remain there if anyone wants to pick them up: a raw (non-absorbed) cancellation of the drain task is still silently skipped, and the completion notification's source JSON does not carry the background task_id.

How to test

pytest tests/tool_offload_middleware_test.py — 7 passed (includes the upstream-added tests).

• test_slow_tool_offloaded_to_background now asserts the placeholder metadata (background_task_id equals the registered background task id, tool_state == "running"); verified to fail against the unpatched middleware (metadata was {}).
• black --line-length=79 and flake8 clean on both changed files.

Checklist

• An issue has been created for this PR
• I have read the CONTRIBUTING.md
• Related documentation has been updated (e.g. links, examples, etc.) in documentation repository — no documentation change needed
• Code is ready for review

/cc @lins — happy to hear whether this matches the direction you had in mind for #3845; the metadata marker is the slice that can land without design decisions, the remaining items there (persistent result store, per-tool execution policy) are untouched.