Taskflow

Canonical plugin/runtime entrypoint:

• api.runtime.tasks.flow
• api.runtime.taskFlow still exists as an alias, but api.runtime.tasks.flow is the canonical shape

Binding:

• api.runtime.tasks.flow.fromToolContext(ctx) when you already have trusted tool context with sessionKey
• api.runtime.tasks.flow.bindSession({ sessionKey, requesterOrigin }) when your binding layer already resolved the session and delivery context

Managed-flow lifecycle:

1. createManaged(...)
2. runTask(...)
3. setWaiting(...) when waiting on a person or an external system
4. resume(...) when work can continue
5. finish(...) or fail(...)
6. 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.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,
});

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) 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