feat: Add public plan-then-run API, event metadata enrichment, and task tree consistency to Workforce

[fengju0213]

Add public plan-then-run API and stronger event/state guarantees to Workforce

Summary

• Introduce a public two-phase execution API: plan_task_async() → edit → run_plan_async()
• Strengthen workforce event metadata so external adapters can observe task and worker state without reading private internals
• Keep task.subtasks[*].state/result synchronized automatically

Changes

workforce.py:

• WorkforcePlan dataclass — holds the task, planned subtasks, dependency graph, and planner output summary
• _plan_task_internal() — shared internal planning path used by both public API and existing execution flow
• plan_task_async() — public headless planning API returning WorkforcePlan without starting execution
• run_plan_async(plan) — public API to execute a previously created or application-edited plan
• _emit_plan_events() / _append_plan_to_pending() / _finalize_task_from_subtasks() — extracted orchestration helpers
• _sync_task_to_parent() — keeps parent task.subtasks[*] state/result/failure_count aligned with canonical task state
• _build_worker_event_metadata() — centralizes neutral worker metadata construction
• TaskAssignedEvent / TaskStartedEvent / TaskCompletedEvent metadata improved so adapters do not need to reconstruct common state from private fields
• process_task_async() refactored to reuse _plan_task_internal() internally while preserving existing behavior

Tests:

• test_workforce_callbacks.py — validates event metadata population through callback flow
• test_workforce.py — validates editable planning, plan execution, and parent/subtask synchronization

Design boundary

What is intentionally in CAMEL:

• headless planning and execution primitives
• task tree consistency guarantees
• neutral event/state metadata for external adapters

What stays outside CAMEL:

• product-specific UI or SSE payload shapes
• planning-only prompt adaptations such as eigent-specific coordinator context injection
• frontend-facing state mapping conventions

Backward compatibility

• process_task_async() API remains unchanged
• handle_decompose_append_task() remains available and delegates internally
• plan_task_async() / run_plan_async() are additive public APIs

[claude]

⚠️ Code review skipped — your organization's overage spend limit has been reached.

Code review is billed via overage credits. To resume reviews, an organization admin can raise the monthly limit at claude.ai/admin-settings/claude-code.

Once credits are available, reopen this pull request to trigger a review.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 97542898-8a52-42c1-9026-6e25e6305c70

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/workforce-plan-state-events

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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