Taskflow

# 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.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

```ts
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