Workflow sessions: YAML-defined orchestration with reviewed agent results

[waldemort-auto]

Summary

Introduce workflow sessions as a first-class, additive PilotSwarm session type. An ordinary agent session is driven by an agent definition and conversation. A workflow session is driven by a versioned YAML definition and a deterministic controller that invokes ordinary agent sessions as children.

The goal is a small, prescriptive layer for repeatable work, not another general-purpose workflow platform. Reuse PilotSwarm session identity, permissions, packages, artifacts, parent/child relationships, and existing durable execution. A workflow controller has no supervising LLM or conversational transcript of its own.

A workflow session persists across iterations. Each new stage execution or scheduled occurrence normally creates a fresh agent child. Within a reviewed stage, retain the same child for human discussion, evaluation feedback, and revisions. Completed work and retained session lifetime are separate concepts.

Initial scope

The initial definition supports:

• Cron triggers/waits: await the next occurrence using an explicit timezone.
• Predefined question triggers/waits: present fixed choices and optional feedback, then follow declared outcomes.
• Agent nodes: execute a named workflow-compatible agent with explicit inputs, required result, and completion policy.
• Explicit loops and sequential transitions: repeat scheduled work or revise a candidate until accepted, within declared limits.

Start with one active work stage at a time. A machine reviewer can be another ordinary agent node returning a structured evaluation; it does not require a separate evaluation engine.

Do not require script nodes, arbitrary executable expressions, parallel scheduling, a new event bus, dynamic graph mutation, compensation machinery, or a separate workflow-run product. Do not replace existing conversational sessions or require a new orchestration service.

Session and control model

Add a session-kind distinction while treating existing sessions and omitted kind values as ordinary agent sessions. Workflow sessions retain the existing ownership and parent/child model but expose their actual capabilities rather than pretending to have a controller model or chat.

The deterministic controller owns the current node, iteration, attempt, durable waits, accepted results, and lifecycle decisions. Nondeterministic agent reasoning stays inside child sessions. Agents return data and outcomes; the definition determines the permitted transition.

A node invocation is distinct from its backing session. The controller records which child belongs to an invocation, so recovery can resume that same child instead of launching another. A later stage or cron occurrence creates a new invocation with fresh context. A revision within an open stage normally resumes its existing child.

Workflow-agent base and result contract

Introduce a separate, versioned workflow-agent base that domain agents can derive from or compose with. It supplies the finite-task and explicit-result contract. Domain definitions retain their expertise, tools, and skills; node inputs supply the particular task, result schema, review policy, and deadline. Avoid duplicating every domain agent merely to change its lifecycle instructions.

Ordinary conversational agents remain unchanged. Initially, a workflow node references an explicitly workflow-compatible agent.

The base requires the agent to perform the assignment, preserve required outputs, submit a result, and yield. It must not invent the next stage, create independent schedules, or leave untracked work continuing after submission. Runtime enforcement is required; prompt instructions alone are insufficient.

A proposed submit_workflow_result tool accepts a common envelope:

{
  "outcome": "succeeded",
  "summary": "The candidate plan is ready for review.",
  "result": {
    "plan": "a versioned result or artifact reference"
  }
}

The result object follows the node's declared schema. The tool's name and final schema remain design choices. It is bound to the current invocation by the runtime; the agent cannot select another workflow, impersonate an evaluator, or supply an authoritative next-node command.

A valid submission durably records a candidate revision and returns control to the workflow. Invalid submissions return actionable validation errors. Idle state and final chat prose never establish completion. A successful submission means the requested output was produced, not that a reviewer has accepted it or that its factual correctness is proven.

Two completion policies

Policy	On successful result submission	Advancement
One-shot	Validate and seal the submitted result, yield the child, and mark the invocation complete	Advance without a review gate
Reviewed	Preserve a candidate revision and yield while the declared human or machine evaluator reviews it	Advance only after the required evaluator accepts that exact candidate

blocked and failed are explicit unsuccessful outcomes. They do not satisfy either policy. The simple default is to pause for attention rather than automatically retry work that may have external effects.

Review and correction

Decision	Meaning
Accept	Seal the current candidate and advance
Reject / request changes	Record feedback and resume the same producing agent for correction
Abort	End pursuit of the stage or workflow according to the definition

Rejecting a candidate is not the same as aborting the workflow. The agent can submit subsequent candidate revisions until accepted or a bound is reached.

A human can converse with the producing agent while the stage is open. Acceptance remains an explicit authenticated action, not an inference from conversational phrasing. Starting a revision supersedes the pending approval before correction begins.

A machine evaluation returns a typed decision and feedback through the ordinary agent/result mechanism. An explicitly required human gate cannot be satisfied by a machine's passing assessment. Evaluation failures and missing responses never imply acceptance.

After completion, keep the child session idle and available for introspection, subject to retention. Later inspection or chat cannot mutate the accepted result, reopen the completed invocation, or silently restart downstream work. Any subsequent corrective work requires an explicit new invocation.

Authoring, packages, and runtime creation

Workflow YAML can be distributed in a versioned package alongside agent definitions. A New session -> Workflow picker selects a packaged definition, collects declared inputs, previews the graph, and starts a workflow session. Installing or publishing a package never activates schedules.

An ordinary agent may also generate a definition and pass it to proposed spawn_workflow(). This accepts either an accessible package definition reference or inline YAML, plus inputs. Both paths use the same validation and execution contract. A tool-created workflow is linked to its caller as a child; the New session experience can create a top-level workflow. First-class type does not mean every instance must be parentless.

Before execution, validate and freeze the YAML and resolved agent/package versions. Definitions are data, not authority: they cannot grant additional credentials, tools, sharing rights, or execution privileges. Bound document size, nesting, and node count; reject unknown constructs and unsafe includes, aliases, or arbitrary evaluation.

Keep authoring text-first with graph preview. An initial visual programming editor is unnecessary. Active definitions remain immutable; editing starts a new workflow session rather than reinterpreting existing history.

Illustrative YAML

This demonstrates the intended scope, not a finalized schema:

kind: workflow
version: 1
name: scheduled-report
steps:
  - loop:
      repeat: until_stopped
      steps:
        - id: tick
          cron: "0 * * * *"
          timezone: UTC
        - id: report
          agent: health-reporter
          task: Produce one assessment and return its report reference.
          completion: one_shot

Bindings between nodes should use a small set of declared inputs and accepted output references, not arbitrary expressions or implicit access to ambient conversation history.

End-to-end examples

Scheduled one-shot report

1. One workflow session waits for its next cron occurrence.
2. It creates a fresh reporting child with the observation window and explicit inputs.
3. The child produces its assessment and submits the required result.
4. The workflow accepts the one-shot result, retains the idle child, and returns to the cron wait.
5. The next occurrence creates another fresh child under the same workflow session.

The controller consumes no LLM turns while waiting. Completed children and their reports remain discoverable by occurrence.

Collaborative planning followed by implementation

1. A predefined question collects the requested feature, then a planner child prepares a candidate plan.
2. The planner submits revision 1 and yields. Its node shows Awaiting review.
3. The human opens the planner chat, asks questions, and explicitly requests changes with feedback.
4. The controller resumes the same planner. It submits revision 2, preserving the earlier candidate and discussion.
5. The human accepts revision 2. Only then does the workflow start a fresh implementation child with the approved plan reference.
6. The implementation result supplies an exact change revision to a separate testing child.
7. The workflow records the outcome. External publication or other consequential actions still require their applicable authorization; successful testing is not universal permission.

A machine-reviewed variant replaces or supplements the review step with a bounded evaluator agent. Rejection sends correlated feedback to the producing agent; acceptance follows the declared policy. Machine-only correction loops have explicit bounds.

User experience

Workflow sessions appear in the existing session list with a distinct icon and useful status: waiting for schedule, awaiting answer, agent running, completed, or needs attention.

Opening a workflow replaces the central chat pane with its graph. Selecting a node opens the right-hand inspector in place of the canvas presentation:

Selected node	Inspector content
Cron	Schedule, timezone, next occurrence, and missed-occurrence policy
Question/review	Predefined question, candidate reference, permitted decisions, and recorded response
Agent	The actual child chat component, with submitted-result/review header
Loop	Current iteration, repeat rule, limits, and prior invocations

Pending agent nodes show no fabricated chat. Repeated nodes need an iteration/attempt selector; candidate revisions within one stage retain the same child conversation. A stable link opens the child's full session view, including its files and canvas.

All agent children also appear as ordinary subagents in the session list. Group, collapse, and paginate historical occurrences to avoid an ever-expanding flat list. Temporarily replacing the canvas panel must not destroy stored canvas state.

Active-child chat supports authorized discussion. Accepted outputs remain immutable. Graph access must not bypass child read/write permissions or artifact permissions. Older clients should expose truthful status and navigation or an unsupported-view fallback, not fabricate an agent conversation.

Correctness and lifecycle requirements

• Result identity: Bind each submission and decision to an invocation, candidate revision, and exact output snapshot. Preserve bytes or a genuinely immutable version; a filename plus an unchecked hash is not enough if the bytes can disappear or change.
• Approval races: Recheck respondent authority and consume each question occurrence once. Stale, duplicate, conflicting, or late events must not approve changed content or advance twice.
• Recovery: Resume already-admitted work. A deliberate retry is a new attempt and may repeat effects; durability does not guarantee exactly-once arbitrary external actions.
• Scheduling: Require an explicit timezone and documented daylight-saving behavior. Initially allow one active work stage, skip unstarted missed occurrences, and avoid overlap/catch-up backlogs.
• Loop limits: Indefinite scheduled repetition is allowed when repeating paths await a fresh cron occurrence or human action. Immediate or machine-only loops require a finite bound or deadline.
• Pause and cancellation: Pause prevents new admissions while current work settles. Cancellation fences waits, results, and future spawns and propagates to active children. Show pending cancellation honestly; it does not undo external effects.
• Retention: Keep small workflow state and explicit result/artifact references rather than copying transcripts into orchestration history. Preserve required evidence for its lifecycle or visibly report expiry; never substitute a newer result.
• Compatibility: Preserve ordinary agent-session behavior. Session APIs, model fields, lifecycle commands, and UI dispatch must account for workflow capabilities without breaking existing callers.

Explore existing frameworks and DSLs before committing to the implementation

Evaluate reuse before selecting the interpreter and authoring implementation. Consider LangGraph, which is a code-first Python/TypeScript graph framework rather than a YAML DSL; declarative specifications such as Open Workflow Specification / Serverless Workflow; and state-machine libraries such as XState.

Assess whether reusable schemas, validators, graph models, viewer components, or scoped adapters reduce work. Compare actual replay/resume and versioning semantics, retained child-session lifecycle, approval/correction loops, package and runtime-generated definitions, licensing, deployment requirements, and operational integration.

Reusing an authoring/model layer and replacing a durable runtime are different decisions. Do not assume a checkpoint adapter transfers execution ownership, a standards-valid document supplies an engine, or a framework automatically implements PilotSwarm permissions and session lifecycle.

Record the reuse-versus-small-native-interpreter decision and its tradeoffs. Do not prescribe adoption or make a broad framework integration, runtime migration, or full DSL conformance project a prerequisite for this additive initial feature. A supported subset must be explicit and reject unsupported constructs.

Acceptance criteria

• Existing agent sessions behave as before; workflow sessions have a distinct list entry and graph-first view.
• Both packaged YAML and spawn_workflow() definitions pass the same validation and are frozen before execution; package installation starts nothing.
• Cron and predefined questions drive explicit sequential loops and agent nodes without a controller LLM.
• A new stage or scheduled occurrence receives a fresh child; within-stage review resumes the same child with recorded feedback.
• Every agent invocation submits a schema-checked result through a runtime-bound tool and yields; idle state alone cannot advance the workflow.
• One-shot and reviewed completion are distinct. Accept advances, reject requests correction, and abort is separate. Required human sign-off cannot be replaced by machine output.
• Accepted results are version-bound and immutable; stale approvals, duplicate submissions, and recovery cannot cause duplicate advancement or child admission.
• The inspector embeds the actual child conversation; children remain accessible as subagents and retain their history without leaking permissions.
• Failures, timeouts, cancellation, missed schedules, loop bounds, and retention have explicit behavior.
• Framework/DSL reuse is evaluated and the decision documented without expanding the initial scope by default.

Open questions

• What is the smallest stable YAML shape and workflow-agent result schema?
• How should workflow-agent base composition be declared while keeping domain agents reusable?
• What default stage deadlines, revision limits, and child-history retention should apply?
• How should post-completion discussion be presented without suggesting the accepted result can change?
• Which framework, specification, or UI components provide net simplification, and which should remain outside the initial implementation?

[waldemort-auto]

Analysis / recommendation: native DSL with LangGraph import

Make the PilotSwarm-native DSL the authoritative workflow language, with supported LangGraph applications as an additional authoring input. This is a proposed direction to evaluate, not a commitment to universal compatibility or an expansion of the initial release requirements.

Architecture

Native YAML/JSON and a versioned LangGraph importer should produce the same native workflow representation. PilotSwarm workflow sessions and Duroxide remain responsible for control flow and durability. Do not silently fall back to running the LangGraph scheduler when translation is incomplete.

A compiled workflow package would contain its native definition, immutable executable bindings and dependencies, source mapping, and a compatibility report. Separate three responsibilities:

• Graph compilation: translate nodes, routes, loops, waits, and supported synchronization semantics.
• State compilation: translate supported schemas, partial updates, reducers, and serialization rules.
• Code packaging: preserve ordinary node functions as versioned code bindings where computation cannot usefully become declarative syntax.

Transpilation does not mean converting arbitrary Python or TypeScript into YAML. Python functions still require a Python execution environment. Imported functions also do not automatically become PilotSwarm agent sessions; explicit adapters can provide native child-chat, result-submission, and reviewed-stage behavior.

Keep the native language independently useful

Preserve the simple workflow-session experience in this issue: cron/questions, agent nodes, loops, and one-shot or reviewed results. Richer state, function calls, branches, map/fork/join, and subworkflow semantics can be added deliberately as later native capabilities. Avoid compatibility-only machinery that makes ordinary workflows difficult to author.

Main risks

Concern	Recommendation
Arbitrary source code	Begin with a declared, versioned Graph API profile and named function bindings. Evaluate an opt-in recording builder/export adapter. Do not assume a visualization export captures executable semantics or that importing application code is safe.
Parallel state and reducers	Preserve input snapshots, merge boundaries, update conflicts, and join behavior. Serializing parallel nodes or changing reducer order can change results; unsupported behavior must fail explicitly.
Interrupts and replay	LangGraph resumes by restarting the containing node. Automatically lifting arbitrary mid-function interrupts into native waits can repeat or omit effects. Initially support dedicated wait boundaries and require manual adaptation for complex interruptions.
Effects and recovery	A whole-node activity does not reproduce every internal checkpoint. Require explicit retry/idempotency behavior; do not promise exactly-once external effects.
Environment and lifecycle	Declare dependencies, codecs, context requirements, and code versions. Model credentials, hosted APIs, retained child sessions, and approval authorization are not automatically portable.

Compatibility and scope

Each import should classify constructs as supported within the profile, adapter required, manual change required, or unsupported. Never deploy an approximation without disclosing it. Compare source and target behavior using deterministic substitutes for models and external effects, rather than executing real writes twice.

The first importer should target straightforward TypeScript Graph API applications with supported state and explicit routing. Arbitrary Functional API programs, hidden nested runtime execution, and migration of live LangGraph checkpoints should not be initial promises.

Recommendation: deliver the small native workflow-session foundation independently, then evaluate a narrow LangGraph compiler frontend against representative applications. Record the engineering cost and semantic coverage before broadening the profile. The intended portability promise is supported graph conversion with preserved node code and actionable diagnostics—not universal zero-change conversion.

Relevant semantics: LangGraph runtime, interrupt/resume behavior, and Graph API.