taskflow

name taskflow description Coordinate multi-step detached tasks as one durable TaskFlow job with owner context, state, waits, and child tasks. metadata {"openclaw":{"emoji":"🪝"}} TaskFlow Use TaskFlow when a job needs to outlive one prompt or one detached run, but you still want one owner session, one return context, and one place to inspect or resume the work. When to use it Multi-step background work with one owner Work that waits on detached ACP or subagent tasks Jobs that may need to emit one clear update back to the owner Jobs that need small persisted state between steps Plugin or tool work that must survive restarts and revision conflicts cleanly What TaskFlow owns flow identity owner session and requester origin currentStep , stateJson , and waitJson linked child tasks and their parent flow id finish, fail, cancel, waiting, and blocked state revision tracking for conflict-safe mutations It does not own branching or business logic. Put that in Lobster, acpx, or the calling code. Current runtime shape Canonical plugin/runtime entrypoint: api.runtime.tasks.managedFlows is mutation-capable: create, advance, and cancel Task Flows. api.runtime.tasks.flows is the read-only DTO view for listing and status lookups ( get , list , findLatest , resolve , getTaskSummary ). Binding: api.runtime.tasks.managedFlows.fromToolContext(ctx) when you already have trusted tool context with sessionKey api.runtime.tasks.managedFlows.bindSession({ sessionKey, requesterOrigin }) when your binding layer already resolved the session and delivery context Managed-flow lifecycle: createManaged(...) runTask(...) setWaiting(...) when waiting on a person or an external system resume(...) when work can continue finish(...) or fail(...) requestCancel(...) or cancel(...) when the whole job should stop Design constraints Use managed TaskFlows when your code owns the orchestration. One-task mirrored flows are created by core runtime for detached ACP/subagent work; this skill is mainly about managed flows. Treat stateJson as the persisted state bag. There is no separate setFlowOutput or appendFlowOutput API. Every mutating method after creation is revision-checked. Carry forward the latest flow.revision after each successful mutation. runTask(...) links the child task to the flow. Use it instead of manually creating detached tasks when you want parent orchestration. Example shape const taskFlow = api. runtime . tasks . managedFlows . fromToolContext (ctx); const created = taskFlow. createManaged ({ controllerId : "my-plugin/inbox-triage" , goal : "triage inbox" , currentStep : "classify" , stateJson : { businessThreads : [], personalItems : [], eodSummary : [], }, }); const classify = taskFlow. runTask ({ flowId : created. flowId , runtime : "acp" , childSessionKey : "agent:main:subagent:classifier" , runId : "inbox-classify-1" , task : "Classify inbox messages" , status : "running" , startedAt : Date . now (), lastEventAt : Date . now (), }); if (!classify. created ) { throw new Error (classify. reason ); } const waiting = taskFlow. setWaiting ({ flowId : created. flowId , expectedRevision : created. revision , currentStep : "await_business_reply" , stateJson : { businessThreads : [ "slack:thread-1" ], personalItems : [], eodSummary : [], }, waitJson : { kind : "reply" , channel : "slack" , threadKey : "slack:thread-1" , }, }); if (!waiting. applied ) { throw new Error (waiting. code ); } const resumed = taskFlow. resume ({ flowId : waiting. flow . flowId , expectedRevision : waiting. flow . revision , status : "running" , currentStep : "finalize" , stateJson : waiting. flow . stateJson , }); if (!resumed. applied ) { throw new Error (resumed. code ); } taskFlow. finish ({ flowId : resumed. flow . flowId , expectedRevision : resumed. flow . revision , stateJson : resumed. flow . stateJson , }); Keep conditionals above the runtime Use the flow runtime for state and task linkage. Keep decisions in the authoring layer: business -> post to Slack and wait personal -> notify the owner now later -> append to an end-of-day summary bucket Operational pattern Store only the minimum state needed to resume. Put human-readable wait reasons in blockedSummary or structured wait metadata in waitJson . Use getTaskSummary(flowId) on api.runtime.tasks.flows when the orchestrator needs a compact health view of child work. Use requestCancel(...) when a caller wants the flow to stop scheduling immediately. Use cancel(...) when you also want active linked child tasks cancelled. Examples See skills/taskflow/examples/inbox-triage.lobster See skills/taskflow/examples/pr-intake.lobster See skills/taskflow-inbox-triage/SKILL.md for a concrete routing pattern