Skip to main content

​
Playbooks and flows

Playbooks and Flows add a coordination view on top of existing Kheish primitives. They do not introduce a second runtime. Use this model when you want a durable, reviewable procedure that starts normal session runs and then tracks the daemon evidence those runs produce.

​
Model

A Playbook is an immutable, digest-covered manifest version. It describes:
  • the objective
  • expected inputs
  • preconditions
  • roles
  • phases
  • acceptance criteria
  • evidence expectations
  • optional enforced tool policy
  • provider and model defaults
  • capability and credential scope requirements/guidance
Runtime defaults are applied through the normal route selection path. Required capability and credential scopes are checked against the target session before a Flow starts. Enforced tool policies are evaluated from scoped session journals and make the Flow fail closed if the run used a blocked or non-allowed tool. Playbook version content is immutable. Its mutable release state lives separately and can be draft, verified, canary, active, or revoked. A Flow is one durable projection of a started Playbook version. It stores correlation data and references to Kheish primitives such as:
  • session_id
  • the root run_id
  • root and sidechain agent ids linked to the root run
  • runs in sidechain sessions spawned from the root run
  • session task ids created by scoped runs or legacy scoped agents
  • pending and historical approval/question ids visible through run state and run events
  • output and debug evidence reachable through the normal run APIs
The Flow status is derived on read from the scoped primitives. It is not persisted on the Flow record. Failed, cancelled, or interrupted scoped runs make the Flow fail closed instead of reporting success from a root answer alone. Phase states are also derived on read. Each manifest phase can require evidence, and missing required evidence blocks a terminal success until an operator appends resolving evidence.

​
Why this is not a workflow engine

Kheish still executes work through sessions and runs. A Flow start wraps a normal SubmitInputRequest, attaches daemon-owned kheish_flow metadata, and schedules the underlying session run through the existing run path. This avoids duplicating:
  • run scheduling
  • approvals and questions
  • background task tracking
  • sidechain agents and mailboxes
  • MCP and tool exposure
  • connector and output routing
  • debug artifacts
  • restart recovery
Flow projections do not retry shell commands, resume processes, schedule child work by themselves, or create a second approval system. They only correlate and summarize daemon primitives that already exist. When a Flow first reaches a terminal projection, the daemon records a terminal boundary timestamp. Later child-session reuse does not mutate the historical Flow.

​
Release safety

Only startable Playbook versions can start Flows. Startable states are:
  • verified
  • canary
  • active
Publishing into one of those states requires evidence references. Structural validation alone does not make a Playbook verified.

​
Correlation metadata

Flow start reserves the metadata key kheish_flow. Callers cannot provide that key themselves on normal run input. The daemon writes it when starting a Flow so run views and debug evidence can be correlated back to:
  • flow_id
  • playbook_id
  • version
  • digest
  • a daemon-generated correlation nonce
The metadata is for daemon correlation. It is not a prompt feature and should not be used by Playbook authors as user-facing content.

​
Evidence Used

​
Evidence Note

  • Code verified: crates/kheish-daemon/src/playbooks.rs, crates/kheish-daemon/src/state/playbook_workflow.rs, crates/kheish-daemon/src/control_tools/helpers.rs, crates/kheish-daemon/src/control_tools/tasks.rs, crates/kheish-daemon/src/control_tools/bash.rs.
  • CLI/API verified: playbooks ..., flows ..., agents list, runs events, tasks list/output surfaces checked against command and handler code.
  • Daemon live tested for this note: yes; OpenAI gpt-5.4 real-daemon smoke covered Flow start, completed run projection, required-evidence fail-closed behavior, and evidence append recovery.
  • Provider-specific tested for this note: OpenAI gpt-5.4 smoke for the provider-backed root run.