91 lines
2.2 KiB
Markdown
91 lines
2.2 KiB
Markdown
# Lobster
|
|
|
|
Lobster executes multi-step workflows with approval checkpoints. Use it when:
|
|
|
|
- User wants a repeatable automation (triage, monitor, sync)
|
|
- Actions need human approval before executing (send, post, delete)
|
|
- Multiple tool calls should run as one deterministic operation
|
|
|
|
## When to use Lobster
|
|
|
|
| User intent | Use Lobster? |
|
|
|-------------|--------------|
|
|
| "Triage my email" | Yes — multi-step, may send replies |
|
|
| "Send a message" | No — single action, use message tool directly |
|
|
| "Check my email every morning and ask before replying" | Yes — scheduled workflow with approval |
|
|
| "What's the weather?" | No — simple query |
|
|
| "Monitor this PR and notify me of changes" | Yes — stateful, recurring |
|
|
|
|
## Basic usage
|
|
|
|
### Run a pipeline
|
|
|
|
```json
|
|
{
|
|
"action": "run",
|
|
"pipeline": "gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage"
|
|
}
|
|
```
|
|
|
|
Returns structured result:
|
|
```json
|
|
{
|
|
"protocolVersion": 1,
|
|
"ok": true,
|
|
"status": "ok",
|
|
"output": [{ "summary": {...}, "items": [...] }],
|
|
"requiresApproval": null
|
|
}
|
|
```
|
|
|
|
### Handle approval
|
|
|
|
If the workflow needs approval:
|
|
```json
|
|
{
|
|
"status": "needs_approval",
|
|
"output": [],
|
|
"requiresApproval": {
|
|
"prompt": "Send 3 draft replies?",
|
|
"items": [...],
|
|
"resumeToken": "..."
|
|
}
|
|
}
|
|
```
|
|
|
|
Present the prompt to the user. If they approve:
|
|
```json
|
|
{
|
|
"action": "resume",
|
|
"token": "<resumeToken>",
|
|
"approve": true
|
|
}
|
|
```
|
|
|
|
## Example workflows
|
|
|
|
### Email triage
|
|
```
|
|
gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage
|
|
```
|
|
Fetches recent emails, classifies into buckets (needs_reply, needs_action, fyi).
|
|
|
|
### Email triage with approval gate
|
|
```
|
|
gog.gmail.search --query 'newer_than:1d' | email.triage | approve --prompt 'Process these?'
|
|
```
|
|
Same as above, but halts for approval before returning.
|
|
|
|
## Key behaviors
|
|
|
|
- **Deterministic**: Same input → same output (no LLM variance in pipeline execution)
|
|
- **Approval gates**: `approve` command halts execution, returns token
|
|
- **Resumable**: Use `resume` action with token to continue
|
|
- **Structured output**: Always returns JSON envelope with `protocolVersion`
|
|
|
|
## Don't use Lobster for
|
|
|
|
- Simple single-action requests (just use the tool directly)
|
|
- Queries that need LLM interpretation mid-flow
|
|
- One-off tasks that won't be repeated
|