Introduce turn-level orchestration across chat capabilities

[paullizer]

Summary

Introduce a turn-level orchestration layer that coordinates SimpleChat's selected and available chat capabilities, gathers relevant evidence, executes bounded multi-step plans, and synthesizes one coherent final response. Grounded image generation will be the first end-to-end proving scenario, not the core abstraction.

User Value

Today, chat capabilities can execute along separate paths without reliably influencing the final response. Users need selected agents, documents, search modes, prior citations, conversation context, actions, and generated artifacts to participate in one intentional workflow that completes the requested outcome without unsupported claims.

Proposed Behavior

• Snapshot the user message, selected chat controls, relevant compacted history, prior citation/artifact lineage, authorization context, and available governed capabilities for each submitted turn.
• Create a lightweight plan for every turn; simple requests use a direct one-step plan without an extra planning model call.
• Treat selected capabilities and sources as required attempts unless they are impossible or unauthorized, and report skips or failures.
• Allow governed read-only capabilities to run automatically when needed; require approval for side effects, sensitive/consequential access, or budget overflow.
• Execute bounded plans with status, dependencies, cancellation, partial failure, and dynamic read-only replanning within the original goal and budget.
• Normalize results into a provenance-aware ledger that preserves conflicts, missing evidence, citations, and source lineage.
• Use a central finalizer to combine executor outputs into the final answer or artifact plan.
• Show concise progress and persist compact plan, status, provenance, and evidence metadata.

Acceptance Criteria

• Every submitted turn has an immutable orchestration context and either a direct or coordinated plan.
• Selected controls are represented as required attempts for that turn, while authorized read-only discovery follows governance and budget policy.
• Relevant conversation history, prior citations, cited source documents, selected documents, agents/actions, search modes, and other chat capabilities can contribute to execution and final synthesis.
• Plans support dependencies, bounded adaptive replanning, cancellation, explicit failure states, and clearly partial outcomes.
• A central finalizer receives normalized outputs and provenance from all executed steps.
• Conflicting or missing evidence is surfaced rather than silently merged or invented.
• Risky, consequential, write, or over-budget steps require user approval.
• Grounded image generation passes as the first end-to-end orchestration scenario without making the core contracts image-specific.
• Functional and security tests cover direct, selected-source, auto-discovery, partial-failure, authorization, and synthesis behavior.

Notes

The implementation should be phased and reuse the existing chat route, agents/actions, workspace and selected-document search, web/deep research, source review, conversation citations, progress UI, artifact persistence, and cancellation mechanisms. Early planning should be deterministic where possible and avoid adding latency to simple turns.

[paullizer]

Phase 1 implementation checkpoint

Work has started on feature/orchestration-foundation-phase-1, based directly on Development.

Completed

• Reframed orchestration as a generic per-turn chat coordinator; grounded image generation is the first proving profile, not the core architecture.
• Added deterministic one-step direct plans and coordinated plans without adding a planning-model call to simple turns.
• Added compact submitted-control snapshots for selected agents, document actions, documents/scopes, retrieval modes, conversation-linked documents, assigned knowledge, model/reasoning selection, and prompt identity.
• Added explicit evidence requirements, origin-aware required source attempts, dependency-aware action/finalizer steps, and policy defaults for governed read-only discovery, bounded replanning, central finalization, and approval classes.
• Persisted orchestration metadata on standard streaming and Analyze/Compare user/assistant messages, including cancellation and partial-error terminal metadata.
• Aligned image proposal guidance with the orchestration image-intent detector and added prompt-level evidence-before-proposal guidance for grounded image requests.
• Added feature documentation and a 0.250.058 release note.

Validation

• Orchestration functional suite: 14/14 passed.
• Image proposal pipeline: 3/3 passed.
• Streaming SSE metadata: 3/3 passed.
• Route policy contracts: 12/12 passed.
• Python compilation and editor diagnostics: clean.
• Scoped broken-access-control scan: passed for all modified backend modules.
• git diff --check: clean.

Known next phases

• Normalize capability outputs into the shared result/evidence ledger.
• Adapt history, prior citations/cited documents, workspace, web/research, agents, and actions to the executor contract.
• Move selected agents beneath a true central finalizer instead of allowing them to own coordinated response streaming.
• Add generic scheduling, per-step reconciliation, automatic governed capability discovery, retry/cancellation, bounded replanning, budget enforcement, and durable resume.

No commit or pull request has been created yet.

[paullizer]

Final Phase 1 review hardening

An independent review and payload audit were completed after the initial checkpoint. The branch now also:

• Reuses one image-intent detector for orchestration and production simpleimage proposal guidance, while keeping chart/analytical requests out of image generation.
• Separates inferred evidence requirements from deduplicated source attempts so selected Web Search/documents can satisfy public-web/workspace requirements without duplicate root steps.
• Makes selected document actions depend on their agent/document/conversation/assigned-knowledge inputs.
• Uses nested document_action.document_ids as the authoritative submitted snapshot when present.
• Returns orchestration metadata consistently in cancellation and partial-error terminal events.
• Creates an evidence-discovery planning step when grounding is requested without a named source.
• Documents that the current live chat payload has no dedicated selected-image-reference list; selected workspace images arrive as documents and explicit reference intent is currently inferred from the message.

Final focused validation is now 15/15 orchestration scenarios plus 3/3 image proposal scenarios. Compilation, editor diagnostics, route policy contracts, streaming SSE metadata, scoped broken-access-control scanning, and git diff --check are clean.

[paullizer]

Phase 2 implementation checkpoint

Phase 2 is implemented in PR #1023, targeting feature/orchestration.

Completed

• Added a generic, output-neutral result/evidence ledger for requirements, permission-aware sources, supported and unsupported facts, computed outputs, citations, artifacts, conflicts, missing evidence, and execution failures.
• Initialized each turn ledger from the immutable Phase 1 plan, including equivalent source/requirement linkage and unspecified-grounding evidence discovery.
• Added provenance validation, denied-source protections, explicit requirement/source state reconciliation, and safe convenience APIs for normalized records.
• Added bounded valid-JSON compaction that cannot retain dangling provenance references and excludes raw payloads, binary data, credential-like metadata, and signed URL query strings/fragments.
• Persisted one plan-linked ledger across standard streaming user/success/cancel/partial-error metadata and Analyze/Compare user/success metadata.
• Updated orchestration documentation, release notes, and version 0.250.059.

Validation

• Evidence ledger: 9/9 passed.
• Phase 1 orchestration plan: 15/15 passed.
• Image proposal pipeline: 3/3 passed.
• Streaming SSE metadata: 3/3 passed.
• Route policy contracts: 12/12 passed.
• Python compilation, VS Code diagnostics, Broken Access Control scanning, XSS scanning, and staged diff checks are clean.

Phase boundary

Phase 2 establishes and persists the contract. Existing conversation, document, workspace, web/research, source-review, selected-image, agent, and action outputs remain on their current paths until the Phase 3 and Phase 4 adapters populate the ledger. Finalizer prompt injection waits for populated normalized evidence so an empty planned ledger cannot compete with existing context.

Refs #1023

[paullizer]

Phase 3 is implemented in PR #1028: #1028

What changed:

• Added generic collectors for authorized conversation facts, prior citation/artifact lineage, selected and conversation-upload documents, workspace search, Web Search, Source Review/Deep Research, and selected-image vision metadata.
• Populated the shared evidence ledger before streaming finalization with explicit no-result, failure, skipped, partial, and unauthorized states.
• Revalidated selected-document access at the collector boundary and omitted prompt-injection-flagged page excerpts from supported facts.
• Updated version and release documentation to 0.250.060.

Validation:

• Phase 3 collectors: 15/15
• Evidence ledger: 9/9
• Turn planning: 15/15
• Image proposal: 3/3
• Streaming metadata: 3/3
• Route policy: 12/12
• Python compile, BAC/XSS guardrails, and whitespace checks passed.

Phase 4 remains responsible for normalizing selected agent and action executor outputs beneath the central finalizer.

[paullizer]

Phase 4 implementation checkpoint

Phase 4 is implemented in PR #1030: #1030

Completed

• Added a connector-neutral evidence_collection task and response contract for selected agents and document actions.
• Passed unresolved evidence requirements, optional capability tags/evidence types/permission metadata, delegated source attempts, and a structured output schema to executors.
• Normalized current-turn tool/action facts, computed results, citations, artifacts, not_found, not_available, failure, and authorization states into the shared ledger.
• Bound private evidence collection to authenticated request context, used per-turn invocation baselines, redacted credential-bearing output, and kept unsupported executor claims out of supported facts.
• Buffered grounded-image selected-agent and document-action output so executors cannot emit a final simpleimage proposal before evidence collection completes.
• Updated orchestration documentation, release notes, and version 0.250.061.

Validation

• Phase 4 contract: 10/10
• Source collectors: 15/15
• Evidence ledger: 9/9
• Turn planning: 15/15
• Image proposal: 3/3
• Streaming metadata: 3/3
• Tabular document actions: 3/3
• Route policy: 12/12
• Python compilation, editor diagnostics, full-file BAC/XSS scans, and staged whitespace checks passed.

Phase boundary

Phase 4 ends with normalized executor evidence and a deterministic status handoff. Phase 5 remains responsible for the separate central synthesis call that turns the completed ledger into evidence-backed image proposals and later output types.

Refs #1021