feat: Strategy.PLAN_EXECUTE — PAC/PAE compile-and-execute for LLM plans

[v1r3n]

Summary

Introduces Plan-And-Compile / Plan-And-Execute (PAC/PAE) for agents: a planner LLM produces a structured JSON plan (DAG of operations), the plan is compiled to a deterministic Conductor sub-workflow, and the sub-workflow runs without further LLM involvement except where the plan explicitly calls a generate op. Optional fallback agent runs agentically when the plan can't compile or fails at execution.

Split from PR #163 (which kept the full coding-agent work). #237 (stateful-tools + tool-output fix) lands first; this PR adds PAC/PAE on top.

How PAC/PAE works (deterministic by construction)

The whole point is to draw a hard line between the non-deterministic part (one planner LLM call deciding what to do) and the deterministic part (Conductor running the compiled DAG). Once the plan is compiled, the executor is replay-safe, branch-stable, and free of LLM randomness.

flowchart TB
    subgraph ND["LLM (non-deterministic)"]
        direction LR
        Planner["planner agent<br/>emits JSON plan"]
    end

    subgraph PAC["PAC compile step (server, pure function)"]
        direction LR
        ExtractJSON["extract_json<br/>(static_plan → markdown_plan → planSource)"]
        Compile["compile to<br/>WorkflowDef"]
        ExtractJSON --> Compile
    end

    subgraph DET["Conductor sub-workflow (deterministic)"]
        direction LR
        Setup["SET_VARIABLE<br/>_ctx_init"]
        Fork["FORK_JOIN<br/>(parallel steps)"]
        Join["JOIN<br/>(aggregate)"]
        Validate["validation +<br/>SWITCH gate"]
        Setup --> Fork --> Join --> Validate
    end

    Prompt[["user prompt"]] --> Planner
    Planner -- "JSON plan in fenced block" --> ExtractJSON
    Compile -- "workflowDef (Conductor JSON)" --> Setup

    StaticPlan[["static_plan=<br/>(skip planner)"]] -.->|"Case 0:<br/>overrides LLM"| ExtractJSON
    Validate -- pass --> Done(["COMPLETED"])
    Validate -- fail --> Fallback{{"fallback agent?"}}
    Fallback -- yes --> FallbackRun["LLM-loop recovery"]
    Fallback -- no --> Failed(["FAILED"])

    classDef llm fill:#fff3e0,stroke:#e65100,stroke-width:2px;
    classDef pure fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px;
    classDef det fill:#e3f2fd,stroke:#0d47a1,stroke-width:2px;
    class Planner,FallbackRun llm;
    class ExtractJSON,Compile pure;
    class Setup,Fork,Join,Validate det;

Loading

Why this shape gives you determinism:

• One planner call, then the LLM is gone. The plan is a value; everything downstream is a pure function of that value.
• Ref("step_id") is resolved at compile time, not run time. {"$ref": "fetch"} becomes a Conductor template (${fetch.output.result}) once, in PAC — there is no runtime "interpret the plan" loop that could diverge.
• Branching is a SWITCH, not a re-prompt. success_condition is a JS expression — same input, same branch, every time.
• Parallelism is FORK_JOIN. A 5-section parallel report has exactly 5 branches, deterministically.
• plan= (static plan) bypasses the LLM entirely. Workflow shape and execution are fully determined by your code. Use this for tests, replays, or any pipeline where planning lives outside the agent.

What PAC actually emits

For a 3-section parallel-write plan with one validator:

flowchart TB
    Start([start]) --> Init["SET_VARIABLE<br/>_ctx_init"]
    Init --> Fork{{"FORK_JOIN"}}

    Fork --> S1L["LLM_CHAT_COMPLETE<br/>section_1 generate"]
    S1L --> S1P["INLINE<br/>parse JSON"]
    S1P --> S1S{"SWITCH<br/>parse ok?"}
    S1S -- ok --> S1T["SIMPLE<br/>write_file"]
    S1S -- fail --> S1F["TERMINATE"]

    Fork --> S2L["LLM_CHAT_COMPLETE<br/>section_2 generate"]
    S2L --> S2P["INLINE<br/>parse JSON"]
    S2P --> S2S{"SWITCH<br/>parse ok?"}
    S2S -- ok --> S2T["SIMPLE<br/>write_file"]
    S2S -- fail --> S2F["TERMINATE"]

    Fork --> S3L["LLM_CHAT_COMPLETE<br/>section_3 generate"]
    S3L --> S3P["INLINE<br/>parse JSON"]
    S3P --> S3S{"SWITCH<br/>parse ok?"}
    S3S -- ok --> S3T["SIMPLE<br/>write_file"]
    S3S -- fail --> S3F["TERMINATE"]

    S1T --> Join((JOIN))
    S2T --> Join
    S3T --> Join

    Join --> Agg["INLINE<br/>step_output_write_all<br/>(Ref normaliser)"]
    Agg --> Val["SIMPLE<br/>check_word_count"]
    Val --> VEval["INLINE<br/>val_eval"]
    VEval --> VSW{"SWITCH<br/>passed?"}
    VSW -- passed --> OK([COMPLETED])
    VSW -- failed --> Bad([TERMINATE / on_failure])

    classDef llm fill:#fff3e0,stroke:#e65100;
    classDef pure fill:#e8f5e9,stroke:#1b5e20;
    classDef tool fill:#e3f2fd,stroke:#0d47a1;
    classDef gate fill:#fce4ec,stroke:#880e4f;
    class S1L,S2L,S3L llm;
    class S1P,S2P,S3P,Agg,VEval,Init pure;
    class S1T,S2T,S3T,Val tool;
    class S1S,S2S,S3S,VSW,Fork,Join gate;

Loading

Only the orange LLM_CHAT_COMPLETE nodes are non-deterministic — and even those go away when you pass a static plan=. Everything else (parse, gate, tool call, aggregate, validate, branch) is pure Conductor and replay-safe.

Full write-up: docs/concepts/plan-execute.md.

Server

• PlanAndCompileTask / PlanAndCompileTaskConfig — new SIMPLE task that runs the planner, extracts the JSON plan from its output (with markdown_plan + planSource fallback), and compiles it into a sub-workflow definition.
• Custom Join task override — dev.agentspan.runtime.tasks.Join replaces Conductor's built-in JOIN to produce compact output (only _state_updates + state) for the parallel FORK_JOIN aggregator. AgentRuntime @ComponentScan excludes Conductor's Join so our @Component is the sole "JOIN" bean.
• MultiAgentCompiler — dispatch on Strategy.PLAN_EXECUTE; named planner / fallback slots replace the legacy agents=[planner, fallback] indexing.
• JavaScriptBuilder — synth_output_script generator and a new knownToolNames param on enrichToolsScript so the compiled JS rejects hallucinated tool names with a clear error.
• AgentConfig — fallbackMaxTurns, planSource, planner (AgentConfig), fallback (AgentConfig) fields.
• WorkflowTaskUtils + PrefillToolCallConfig — supporting types.
• GraalVM polyglot test deps — needed for SynthOutputScriptTest and EnrichToolsScriptTest.
• Tests: PlanAndCompileTaskTest, SynthOutputScriptTest, EnrichToolsScriptTest, ModelContextWindowsTest.

SDK (Python / TypeScript / Java / C#)

• Strategy.PLAN_EXECUTE — new enum value across all four SDKs.
• Typed Plan / Step / Op / Ref / Generate / Validation / Action builders — same wire format in all SDKs (Python dataclasses, TS classes, Java builder, C# records).
• Ref("step_id") — cross-step output piping primitive. Wire form: {"$ref": "step_id"}. PAC rewrites it at compile time against an INLINE step_output_<id> wrapper that normalises dict-vs-string worker returns.
• planner=, fallback=, fallback_max_turns=, plan_source= — Agent() kwargs for the new strategy.
• prefill_tools= + ToolDef.call() / PrefillToolCall — declarative tool calls executed before the first LLM turn; results land in context. TS interface exposes call?() as optional so CodeExecutor.asTool() literals don't have to supply it.
• success_condition — declarative gate for plan-step validations (e.g. JSON-output-passed-true / text-mention) that the compiled FORK_JOIN aggregator evaluates.
• runtime.run(harness, prompt, plan=plan) — static-plan path. Server's PAC extract_json reads workflow.input.static_plan as Case-0 (highest priority) and discards the planner LLM's output — the workflow shape is fixed but no LLM round-trip for planning.

Examples + docs

• 103_plan_and_compile.py, 104_plan_execute_guardrails.py, 106_plan_execute_agent_fanout.py, 107_pac_mcp_proof.py — Python examples.
• 85_plan_execute_harness.py, 86_coding_agent.py — research report and coding agent examples using PLAN_EXECUTE.
• 108_plan_execute_refs.py — typed Plan + Ref pipeline (three-step record passing without JSONPath).
• docs/concepts/plan-execute.md — feature documentation, including the two diagrams above.

Deterministic e2e (no LLM in the assertion path)

Per CLAUDE.md (algorithmic validation only), each SDK ships a Plan-Execute Refs suite that runs a produce → enrich → report pipeline with static_plan= and asserts on byte-exact worker outputs. The planner sub-agent is built but its output is discarded by the static-plan path, so no LLM nondeterminism reaches the assertions.

SDK	File	Tests	Counterfactual
Python	sdk/python/e2e/test_suite20_plan_execute.py (TestSuite20PlanExecuteRefs)	3	value_squared = 1764 proves Ref('a') carried the whole upstream dict; if Ref were unwired enrich would see {"$ref":"a"} and squared = 0
TypeScript	sdk/typescript/tests/e2e/test_suite20_plan_execute.test.ts ("Plan-Execute Refs (deterministic)")	2	same pipeline + independence assertion (squared=1764 ≠ original_value=42 rules out two Refs collapsing to one)
Java	sdk/java/e2e/PlanExecuteTest.java (@Order(10/11))	2	same
C#	sdk/csharp/tests/AgentspanE2eTests/Suite16_PlanExecuteRefs.cs	2	same

Test plan

• ./gradlew test (server) → 569 tests pass
• pytest tests/unit/ (Python SDK) → 1537 tests pass
• npm run build (TypeScript SDK) → full build + DTS pass
• Python Plan-Execute Refs e2e → 3 tests pass locally (19.10s)
• TypeScript Plan-Execute Refs e2e → 2 tests pass locally (7.40s)
• Java Plan-Execute Refs e2e → 2 tests pass locally (12.24s)
• CI exercises C# Suite16 + all four SDK e2e against the freshly-built server

Merge order

This PR is intended to merge after #237 (stateful-tools + tool-output fix). Because both PRs branched from main and touch some of the same files (e.g. agent.py, config_serializer.py), the diff against main currently shows some overlap with #237. After #237 merges, the GitHub view of this PR will shrink to PAC/PAE-only changes.

If preferred, this PR can be re-targeted to base on feat/stateful-tools-and-tool-output-fix for a cleaner stacked-PR view — say the word and I'll switch the base.