feat(btw): own detached work execution and lifecycle

[YUZHEthefool]

Preflight

• Existing Issues and PRs were searched.
• This follows the current-branch, no-legacy, Python 3.14+ policy.
• Exactly one Agent note is provided by the actual author.

Problem

Long work must not hold the conversation pipeline open or leave unowned tasks after cancellation or shutdown.

Proposal

Own detached work under the existing runtime lifecycle. Acknowledge a task, track pending/running/terminal states, and execute through the established Agent executor with bounded concurrency. Keep conversation available while work runs.

Design: PR #28 and its English proposal. Parent: P / #122. PR #28 is documentation only; this issue tracks follow-up implementation or evaluation.

Associated PR: PR #137 (non-draft; base split/btw-entry).

Acceptance criteria

• Acknowledgement precedes detached execution, and another ordinary conversation can progress while work is blocked on a tool or model.
• Concurrency is bounded; distinguish an execution limit from a queue/admission bound and define how excess work is handled.
• Pending, running, completed, failed, and cancelled states reflect outcomes. Test queued cancellation, execution cancellation, and failure without exposing raw provider errors.
• Runtime shutdown and configuration lifecycle changes reclaim owned tasks. Cancellation propagates, and terminal retention never expires an active task.

Dependencies and delivery

Blocked by: B1 / #123

B2 / #124 supplies explicit entry, B4 / #126 delivers results, and B5 / #127 consumes state. The first usable release includes the complete submission/delivery path.

Implementation anchors

Historical prototype 33ee103a62937db3e930c89ba47a648b75cc7772 provides provenance, not code to copy unchanged:

• astrbot/core/agent/btw/work_loop.py: WorkLoop.submit / _execute / _run_detached.
• astrbot/core/agent/btw/work_sessions.py: WorkSessionManager.
• astrbot/core/agent/btw/types.py: WorkSessionStatus.
• astrbot/core/core_lifecycle.py: lifecycle-owned background tasks.

Integrate with the current tool catalog, Skill snapshot assembly, and authorization service, rechecking current master when implementation begins.

Validation

Commands below are required for the implementation PR, not results claimed by this issue.

Existing current-master regression baseline:

uv run pytest tests/unit/test_core_lifecycle.py

Historical prototype tests to adapt with the feature (they are not shipped by documentation-only PR #28):

• tests/unit/test_btw.py

For changed documentation, run pnpm run docs:build from docs/ and make check-md from the repository root. Update OpenAPI and generated outputs together only if the HTTP contract changes.

Out of scope

Persistent jobs, restart recovery, cross-device scheduling, and an automatic retry/rollback platform are separate work.

Repository requirements

Follow AGENTS.md, GOVERNANCE.md, and AI_POLICY.md. This issue uses the feature_request template. Keep Python 3.14+, current configuration shapes, existing authorization boundaries, and bilingual feature documentation. A follow-up PR requires human maintainer review and a separate AI-assisted review. Use the feat PR template for the corresponding work.

Author

Agent

Agent note

Codex prepared this development issue at the user's request from PR #28, its discussion, the referenced source, existing tests, and current-master integration points. AI assisted the research and English drafting. Filing this issue changes no runtime behavior and does not claim feature tests or model trials have passed. Remaining decisions concern implementation details and experimental evidence within the stated scope.