mirror of
https://github.com/openclaw/openclaw.git
synced 2026-04-03 05:12:15 +00:00
chore(skills): align taskflow skill with runtime
This commit is contained in:
Vincent Koc
@@ -1,62 +0,0 @@
|
||||
---
|
||||
name: clawflow-inbox-triage
|
||||
description: Example ClawFlow authoring pattern for inbox triage. Use when messages need different treatment based on intent, with some routes notifying immediately, some waiting on outside answers, and others rolling into a later summary.
|
||||
metadata: { "openclaw": { "emoji": "📥" } }
|
||||
---
|
||||
|
||||
# ClawFlow inbox triage
|
||||
|
||||
This is a concrete example of how to think about ClawFlow without turning the core runtime into a DSL.
|
||||
|
||||
## Goal
|
||||
|
||||
Triage inbox items with one owner flow:
|
||||
|
||||
- business → post to Slack and wait for reply
|
||||
- personal → notify the owner now
|
||||
- everything else → keep for end-of-day summary
|
||||
|
||||
## Pattern
|
||||
|
||||
1. Create one flow for the inbox batch.
|
||||
2. Run one detached task to classify new items.
|
||||
3. Resume the flow when classification completes.
|
||||
4. Route each item in the calling logic.
|
||||
5. Persist only the summary bucket and the current wait target.
|
||||
|
||||
## Suggested flow outputs
|
||||
|
||||
- `business_threads`
|
||||
- `personal_items`
|
||||
- `eod_summary`
|
||||
|
||||
## Minimal runtime calls
|
||||
|
||||
```ts
|
||||
const flow = createFlow({
|
||||
ownerSessionKey,
|
||||
goal: "triage inbox",
|
||||
});
|
||||
|
||||
runTaskInFlow({
|
||||
flowId: flow.flowId,
|
||||
runtime: "acp",
|
||||
task: "Classify inbox messages",
|
||||
currentStep: "wait_for_classification",
|
||||
});
|
||||
|
||||
resumeFlow({
|
||||
flowId: flow.flowId,
|
||||
currentStep: "route_items",
|
||||
});
|
||||
|
||||
appendFlowOutput({
|
||||
flowId: flow.flowId,
|
||||
key: "eod_summary",
|
||||
value: { subject: "Newsletter", route: "later" },
|
||||
});
|
||||
```
|
||||
|
||||
## Related example
|
||||
|
||||
- `skills/clawflow/examples/inbox-triage.lobster`
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
name: clawflow
|
||||
description: Use when work should span one or more detached tasks but still behave like one job with a single owner context. ClawFlow is the runtime substrate under authoring layers like Lobster, acpx, or plain code. Keep conditional logic in the caller; use ClawFlow for flow identity, waiting, outputs, and user-facing emergence.
|
||||
metadata: { "openclaw": { "emoji": "🪝" } }
|
||||
---
|
||||
|
||||
# ClawFlow
|
||||
|
||||
Use ClawFlow when a job needs to outlive one prompt or one detached run, but you still want one owner session, one thread 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 a small persisted output bag between steps
|
||||
|
||||
## What ClawFlow owns
|
||||
|
||||
- flow identity
|
||||
- owner session and return context
|
||||
- waiting state
|
||||
- small persisted outputs
|
||||
- finish, fail, cancel, and blocked state
|
||||
|
||||
It does **not** own branching or business logic. Put that in Lobster, acpx, or the calling code.
|
||||
|
||||
## Runtime pattern
|
||||
|
||||
1. `createFlow(...)`
|
||||
2. `runTaskInFlow(...)`
|
||||
3. `setFlowWaiting(...)` or `setFlowOutput(...)`
|
||||
4. `resumeFlow(...)`
|
||||
5. `emitFlowUpdate(...)` only when needed
|
||||
6. `finishFlow(...)` or `failFlow(...)`
|
||||
|
||||
## Example shape
|
||||
|
||||
```ts
|
||||
const flow = createFlow({
|
||||
ownerSessionKey,
|
||||
goal: "triage inbox",
|
||||
});
|
||||
|
||||
const classify = runTaskInFlow({
|
||||
flowId: flow.flowId,
|
||||
runtime: "acp",
|
||||
task: "Classify inbox messages",
|
||||
currentStep: "wait_for_classification",
|
||||
});
|
||||
|
||||
resumeFlow({
|
||||
flowId: flow.flowId,
|
||||
currentStep: "route_results",
|
||||
});
|
||||
|
||||
setFlowOutput({
|
||||
flowId: flow.flowId,
|
||||
key: "classification",
|
||||
value: { route: "business" },
|
||||
});
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
## Examples
|
||||
|
||||
- See `skills/clawflow/examples/inbox-triage.lobster`
|
||||
- See `skills/clawflow/examples/pr-intake.lobster`
|
||||
- See `skills/clawflow-inbox-triage/SKILL.md` for a concrete routing pattern
|
||||
119
skills/taskflow-inbox-triage/SKILL.md
Normal file
119
skills/taskflow-inbox-triage/SKILL.md
Normal file
@@ -0,0 +1,119 @@
|
||||
name: taskflow-inbox-triage
|
||||
description: Example TaskFlow authoring pattern for inbox triage. Use when messages need different treatment based on intent, with some routes notifying immediately, some waiting on outside answers, and others rolling into a later summary.
|
||||
metadata: { "openclaw": { "emoji": "📥" } }
|
||||
|
||||
---
|
||||
|
||||
# TaskFlow inbox triage
|
||||
|
||||
This is a concrete example of how to think about TaskFlow without turning the core runtime into a DSL.
|
||||
|
||||
## Goal
|
||||
|
||||
Triage inbox items with one owner flow:
|
||||
|
||||
- business → post to Slack and wait for reply
|
||||
- personal → notify the owner now
|
||||
- everything else → keep for end-of-day summary
|
||||
|
||||
## Pattern
|
||||
|
||||
1. Create one flow for the inbox batch.
|
||||
2. Run one detached task to classify new items.
|
||||
3. Persist the routing state in `stateJson`.
|
||||
4. Move to `waiting` only when an outside reply is required.
|
||||
5. Resume the flow when classification or human input completes.
|
||||
6. Finish when the batch has been routed.
|
||||
|
||||
## Suggested `stateJson` shape
|
||||
|
||||
```json
|
||||
{
|
||||
"businessThreads": [],
|
||||
"personalItems": [],
|
||||
"eodSummary": []
|
||||
}
|
||||
```
|
||||
|
||||
Suggested `waitJson` when blocked on Slack:
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "reply",
|
||||
"channel": "slack",
|
||||
"threadKey": "slack:thread-1"
|
||||
}
|
||||
```
|
||||
|
||||
## Minimal runtime calls
|
||||
|
||||
```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 child = taskFlow.runTask({
|
||||
flowId: created.flowId,
|
||||
runtime: "acp",
|
||||
childSessionKey: "agent:main:subagent:classifier",
|
||||
task: "Classify inbox messages",
|
||||
status: "running",
|
||||
startedAt: Date.now(),
|
||||
lastEventAt: Date.now(),
|
||||
});
|
||||
|
||||
if (!child.created) {
|
||||
throw new Error(child.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: "route_items",
|
||||
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,
|
||||
});
|
||||
```
|
||||
|
||||
## Related example
|
||||
|
||||
- `skills/taskflow/examples/inbox-triage.lobster`
|
||||
149
skills/taskflow/SKILL.md
Normal file
149
skills/taskflow/SKILL.md
Normal file
@@ -0,0 +1,149 @@
|
||||
name: taskflow
|
||||
description: 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.
|
||||
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.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
|
||||
@@ -1,4 +1,4 @@
|
||||
# Illustrative Lobster authoring example for a ClawFlow-style inbox triage job.
|
||||
# Illustrative Lobster authoring example for a TaskFlow-style inbox triage job.
|
||||
# Swap the placeholder commands for your own tools or scripts.
|
||||
|
||||
name: inbox-triage
|
||||
@@ -1,4 +1,4 @@
|
||||
# Illustrative Lobster authoring example for a ClawFlow-style PR intake lane.
|
||||
# Illustrative Lobster authoring example for a TaskFlow-style PR intake lane.
|
||||
# Replace the placeholder commands with repo-specific tooling.
|
||||
|
||||
name: pr-intake
|
||||
Reference in New Issue
Block a user