Use when work should span one or more detached tasks but still behave like one job with a single owner context. TaskFlow is the durable flow substrate under authoring layers like Lobster, ACPX, plugins, or plain code. Keep conditional logic in the caller; use TaskFlow for flow identity, child-task linkage, waiting state, revision-checked mutations, and user-facing emergence.
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.
currentStep, stateJson, and waitJsonIt does not own branching or business logic. Put that in Lobster, acpx, or the calling code.
Canonical plugin/runtime entrypoint:
api.runtime.tasks.flowapi.runtime.taskFlow still exists as an alias, but api.runtime.tasks.flow is the canonical shapeBinding:
api.runtime.tasks.flow.fromToolContext(ctx) when you already have trusted tool context with sessionKeyapi.runtime.tasks.flow.bindSession({ sessionKey, requesterOrigin }) when your binding layer already resolved the session and delivery contextManaged-flow lifecycle:
createManaged(...)runTask(...)setWaiting(...) when waiting on a person or an external systemresume(...) when work can continuefinish(...) or fail(...)requestCancel(...) or cancel(...) when the whole job should stopstateJson as the persisted state bag. There is no separate setFlowOutput or appendFlowOutput API.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.const taskFlow = api.runtime.tasks.flow.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,
});
Use the flow runtime for state and task linkage. Keep decisions in the authoring layer:
business → post to Slack and waitpersonal → notify the owner nowlater → append to an end-of-day summary bucketblockedSummary or structured wait metadata in waitJson.getTaskSummary(flowId) when the orchestrator needs a compact health view of child work.requestCancel(...) when a caller wants the flow to stop scheduling immediately.cancel(...) when you also want active linked child tasks cancelled.skills/taskflow/examples/inbox-triage.lobsterskills/taskflow/examples/pr-intake.lobsterskills/taskflow-inbox-triage/SKILL.md for a concrete routing pattern