F
Flowman docsWorkflow SDK
Back to app
All docs

Durable Sub-agent runs

A Sub-agent is an independently executing child workflow run with its own run slug, immutable execution snapshot, attempts, artifacts, and observability. Parent and child lifecycles are independent.

Dispatch contract

Call dispatchSubAgent() from a parent workflow, authenticated HTTP route, retry, or regeneration action. Provide a stable task key, subject, versioned context, system instructions, and user message. An idempotency key reuses an existing run instead of starting a duplicate.

Interactive dispatch requires project-member access. Parent workflows use Flowman's configured internal dispatch capability; Sub-agent creation and artifact writes reject unauthenticated public Convex calls.

Subjects and context are generic: the voice summary uses a Jira ticket, while ready-for-review operations attach the parent run and every linked pull request without changing persistence or run routes.

Cursor pull requests ready for review

After an initial Cursor Cloud implementation records its complete pull-request set, Flowman atomically publishes an internal coding.implementation.completed lifecycle event. A code-owned trigger starts one idempotent pull-request-ready child from that event. The child uses the connected Flowman GitHub App directly—no model or speech API—to mark every linked draft ready for review, including polyrepo siblings. Pull requests that are already ready succeed as no-ops, and closed or merged pull requests are skipped.

When a draft pull request is successfully marked ready, the Sub-agent checks that pull request's comments for an exact match to the code-owned review-trigger setting (initially @codex review). If no exact match exists, it posts the configured comment to trigger a Codex review. Mark-ready still uses the connected Flowman GitHub App, but the review comment is posted with GITHUB_REVIEW_COMMENT_TOKEN when configured so it appears as that GitHub user (for example qualipsolutions) rather than the app bot—Codex and similar bots often ignore app-authored comments. Optionally set GITHUB_REVIEW_COMMENT_USERNAME to require a specific login. Without the user token, Flowman falls back to the GitHub App installation token. If an exact match already exists, no duplicate comment is posted and the comment step is recorded as deduplicated. Pull requests that were already ready, closed, or merged retain their outcomes and receive no comment. If checking or posting a comment fails after a pull request was marked ready, the pull request remains ready and the Sub-agent completes with a non-fatal warning.

The built-in Mark pull requests ready definition appears as Flowman-managed on the project's Workflows page. Its read-only details identify the coding.implementation.completed lifecycle event that triggers it, along with the GitHub App integration, PR scope, billing, and retry behavior; it remains unavailable in the coding-run picker because it is dispatched automatically.

The lifecycle delivery is asynchronous, so the child can appear just before or after the parent run reaches its terminal state. The parent never waits for the child and remains completed if dispatch or GitHub work fails. Managed dispatch retries use bounded backoff and the parent-run idempotency key; missing GitHub connections, insufficient pull-request write permission, and individual GitHub errors appear on the failed child, which project members can retry safely.

Subscription-first reasoning

  • A compatible subscription-backed executor is inherited from the parent: Codex Local or Cursor Local for local work, or Cursor Cloud when repository context exists.
  • Otherwise the workflow uses its configured Codex Local, Cursor Local, or Cursor Cloud fallback.
  • API-key-backed reasoning is never an automatic fallback. Missing compatible configuration fails clearly without incurring paid reasoning charges.
  • Offline Codex Local work stays queued in the existing runtime queue until the configured runtime resumes.

Ticket voice summary

After an approved refinement is verified in Jira, Flowman dispatches ticket-voice-summary directly; this path does not currently consume a lifecycle event. For tickets refined before voice summaries were enabled, project members can start generation manually from the Jira ticket drawer; Flowman reuses the latest saved, completed refinement plan and does not bulk-generate historical audio. Subscription-backed reasoning produces a 60–90 second narration. Only that narration is sent to the explicitly API-billed speech stage.

The voice-summary card appears on the Jira ticket drawer and, once the ticket is promoted to a coding session, on that session's run details page. The coding-session surface shows only the ticket's current refinement summary—never an earlier refinement's audio—and offers no generation prompt; members keep status-appropriate retry and regenerate controls while customers get read-only playback.

  • Default speech model: gpt-4o-mini-tts; voice: marin; MP3; speed 1.0.
  • Speed accepts 0.25–4.0 and is persisted in the immutable attempt snapshot and artifact metadata.
  • The stage reads OPENAI_API_KEY from the project environment snapshot or server environment. Missing credentials fail only the child run.
  • Audio is stored in Convex storage and served through authorized signed URLs. Every player includes an AI-generated-voice disclosure.

Observability and attempts

Open Work → Sub-agents to search and filter active tasks (running, waiting, paused, failed, and cancelled). Completed runs leave this list once they finish. Run details show the parent, subject, executor or Flowman-operation selection reason, billing classification, output, audio, and attempt history. Failed or cancelled runs can be retried using their original snapshot or the latest workflow configuration. Successful voice summaries—and only voice summaries—can be regenerated as a new attempt; previous runs are never overwritten.

Project members can permanently delete an individual Sub-agent attempt from its run-details menu. Deletion removes that attempt, its execution records, and stored artifacts; parent runs remain protected from deletion while they still have Sub-agent attempts.

Customer views expose permitted status, narration, and audio only. Prompts, execution snapshots, internal context, executor diagnostics, and retry controls remain member-only.