Flowstate Agent Runner Operations

Agent Runner Operations

Status: Active Purpose: Teach FlowState agent harnesses how to operate the co-resident flowstate-runner Rust daemon inside their agent container Scope: Agent sidecars that run the Rust process execution engine, regardless of chat or coding harness Trigger: Agent needs to monitor or control process executions assigned to its team member ID Input: Running agent container with FLOWSTATE_AGENT_ID, FlowState CLI, and flowstate-runner Output: Runner status understood, assigned process executions advanced or safely paused/cancelled, and failures diagnosed

Overview

FlowState agents do not manually walk process steps unless the runner is unavailable or a step explicitly asks for agent reasoning. The Rust runner is the primary process driver. Agents monitor the runner, create or assign work in FlowState, trigger scans/resumes, and handle the small number of inference-heavy agent-task steps only when the process engine delegates them.

Verify Scope -> Check Runner -> List Executions -> Inspect Work
     (0)            (1)              (2)              (3)
                                                        |
                                                        v
Act on Execution <- Diagnose Failure <- Resume/Scan <- Observe Pause
      (6)                (5)             (4)            (4)

Architecture

Each agent sidecar runs two long-lived services under s6:

The runner is scoped by environment:

The runner enforces scope in three places:

1. Scanner looks for entity-triggered processes assigned to metadata.assignedAgent = FLOWSTATE_AGENT_ID.
2. Resumer looks for paused executions with variables.assignedAgent = FLOWSTATE_AGENT_ID.
3. Run guard refuses to execute a record assigned to a different team member.

Step 0: Verify Container Scope

Who: FlowState agent Pause: No

Actions

1. Read the configured agent identity:

   printf 'FLOWSTATE_AGENT_ID=%s\nFLOWSTATE_AGENT_NAME=%s\n' "$FLOWSTATE_AGENT_ID" "$FLOWSTATE_AGENT_NAME"
   

2. Confirm runner tools exist:

   command -v flowstate
   command -v flowstate-runner
   

3. Confirm the control token is available to the agent runtime user:

   test -s /run/runner.token && echo "runner token present"
   

4. If RUNNER_CONTROL_TOKEN is not exported in the shell, export it from the token file for this session:

   export RUNNER_CONTROL_TOKEN="$(cat /run/runner.token)"
   export RUNNER_CONTROL_URL="${RUNNER_CONTROL_URL:-http://localhost:9090}"
   

Done when

• FLOWSTATE_AGENT_ID is non-empty
• flowstate and flowstate-runner are on PATH
• RUNNER_CONTROL_TOKEN is available for CLI control commands

Step 1: Check Runner Health

Who: FlowState agent Pause: No

Actions

1. Use the FlowState CLI first:

   flowstate runner status --format json
   

2. Confirm the response includes:
   • status: "ok"
   • agentId matching FLOWSTATE_AGENT_ID
   • runningExecutions, possibly empty
   • lastActivityAt, if the runner has found work
3. If the CLI fails, check the raw health endpoint:

   curl -fsS http://localhost:9090/health | jq .
   

4. If health fails, inspect s6 service state and recent logs:

   s6-rc -a list | grep flowstate-runner
   s6-svstat /run/service/flowstate-runner
   tail -200 /run/service/flowstate-runner/log/current 2>/dev/null || true
   

Done when

• Runner health is reachable
• Agent scope is verified
• Any active execution IDs are known

Step 2: List Assigned Executions

Who: FlowState agent Pause: No

Actions

1. List executions controlled by this runner:

   flowstate runner ls
   

2. For machine-readable inspection:

   flowstate runner ls --format json
   

3. Filter by status when triaging:

   flowstate runner ls --status running
   flowstate runner ls --status paused
   flowstate runner ls --status failed
   flowstate runner ls --status completed --limit 20
   

4. Treat an empty list as "no scoped executions visible", not as failure. Trigger a scan if new assigned work should exist.

Done when

• The agent knows which scoped executions exist and which need attention

Step 3: Inspect an Execution

Who: FlowState agent Pause: No

Actions

1. Show the execution:

   flowstate runner show <execution_id> --format json
   

2. Inspect:
   • processId
   • status
   • currentStepId
   • variables.assignedAgent
   • variables.entityId, entityType, entityCollection
   • stepHistory
   • error
3. Confirm variables.assignedAgent matches FLOWSTATE_AGENT_ID. If it does not, do not try to bypass the guard.
4. If a process or step needs direct DB inspection, use FlowState collection tools with real IDs from .flowstate/config.json; never guess IDs.

Done when

• Current process, step, entity, pause/failure reason, and ownership are understood

Step 4: Trigger Scan or Resume

Who: FlowState agent Pause: No

Actions

1. Trigger a scan when an entity was newly assigned or tagged:

   flowstate runner scan
   

   This schedules work and returns quickly. Check flowstate runner ls afterwards.
2. Trigger a resume cycle when approvals, human-task responses, or pause conditions were satisfied:

   flowstate runner resume
   

3. Force a single paused execution back to pending only when the pause condition is genuinely satisfied or the operator intentionally wants to retry:

   flowstate runner resume <execution_id>
   

Done when

• New eligible work has a processexecutions row, or paused eligible work has moved to pending/running

Step 5: Diagnose Stalls and Failures

Who: FlowState agent Pause: No

Actions

1. For a paused execution, inspect the pause reason:

   flowstate runner show <execution_id> --format json | jq '.metadata._pause_reason, .currentStepId, .variables'
   

2. If waiting on an approval, query the approval record shown in variables or pause metadata and look for status, response, and comments.
3. For a failed execution, inspect:

   flowstate runner show <execution_id> --format json | jq '.error, .stepHistory[-5:]'
   

4. Try runner logs, but know the current /executions/:id/logs endpoint may return a placeholder until OBS proxying is fully wired:

   flowstate runner logs <execution_id>
   

5. Fall back to container logs when needed:

   ps -ef | grep flowstate-runner
   s6-svstat /run/service/flowstate-runner
   

Done when

• The agent can state whether the execution is waiting, failed due to a step error, mis-scoped, or blocked by runner health/configuration

Step 6: Pause, Cancel, or Restart Safely

Who: FlowState agent Pause: Maybe

Actions

1. Pause only when work must stop without losing persisted state:

   flowstate runner pause <execution_id> --reason "manual: <short reason>"
   

2. Cancel only when the execution should be marked failed and should not continue:

   flowstate runner cancel <execution_id> --reason "manual: <short reason>"
   

3. Restart the runner service only for runner process health issues, not normal paused work:

   s6-svc -r /run/service/flowstate-runner
   

4. After any pause/cancel/restart, re-check:

   flowstate runner status --format json
   flowstate runner ls --format json
   

Done when

• The execution state in FlowState matches the intended operator action
• The runner is healthy after service-level intervention

Creating Runner-Eligible Work

Agents create process-driven work by creating or updating FlowState entities so scanner triggers can match them.

Required entity metadata for agent-scoped process triggers:

{
  "metadata": {
    "assignedAgent": "<FLOWSTATE_AGENT_ID or target team member id>"
  },
  "tags": ["brainstorm"]
}

Guidelines:

• Set metadata.assignedAgent to the target agent team member ID before triggering process scans.
• Include the process trigger tag or status expected by the registered process, such as brainstorm.
• For CEO-to-CTO work, the CEO-created entity should have metadata.assignedAgent set to the CTO team member ID and any approver variables set to the CEO team member ID when the process supports peer approval routing.
• After creating or updating the entity, the target agent runs flowstate runner scan.

Manual Execution Fallback

Manual MCP process execution is the fallback path, not the default.

Use flowstate-process-execution only when:

• flowstate-runner is unavailable and cannot be restarted
• A process definition is being debugged before runner registration
• The runner fails on a step and you need to reproduce the step by hand
• A human explicitly asks for a manual process walkthrough

When using the fallback, record what was done in the execution, entity discussion, or approval trail so the runner and future agents have durable context.

Error Handling

Command Reference

Safety Rules

• Do not clear or forge variables.assignedAgent to bypass scope.
• Do not operate on another agent's execution from this container.
• Do not mutate processexecutions directly. Use runner commands; if a repair path is missing, record a tool-surface gap before changing process execution state.
• Prefer scan/resume over direct flowstate-runner run <id> during normal operations.
• Keep inference work inside agent-task steps or explicit human requests; use CLI/MCP commands for deterministic process actions.

Created: 2026-05-24

Source: epic-digital-im/epic-flowstate-skills — distributed by TomeVault.