durar-ai 2026.4.4

package/skills/songsee/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: songsee
+description: Generate spectrograms and feature-panel visualizations from audio with the songsee CLI.
+homepage: https://github.com/steipete/songsee
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🌊",
+        "requires": { "bins": ["songsee"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/songsee",
+              "bins": ["songsee"],
+              "label": "Install songsee (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# songsee
+
+Generate spectrograms + feature panels from audio.
+
+Quick start
+
+- Spectrogram: `songsee track.mp3`
+- Multi-panel: `songsee track.mp3 --viz spectrogram,mel,chroma,hpss,selfsim,loudness,tempogram,mfcc,flux`
+- Time slice: `songsee track.mp3 --start 12.5 --duration 8 -o slice.jpg`
+- Stdin: `cat track.mp3 | songsee - --format png -o out.png`
+
+Common flags
+
+- `--viz` list (repeatable or comma-separated)
+- `--style` palette (classic, magma, inferno, viridis, gray)
+- `--width` / `--height` output size
+- `--window` / `--hop` FFT settings
+- `--min-freq` / `--max-freq` frequency range
+- `--start` / `--duration` time slice
+- `--format` jpg|png
+
+Notes
+
+- WAV/MP3 decode native; other formats use ffmpeg if available.
+- Multiple `--viz` renders a grid.

package/skills/sonoscli/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: sonoscli
+description: Control Sonos speakers (discover/status/play/volume/group).
+homepage: https://sonoscli.sh
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🔊",
+        "requires": { "bins": ["sonos"] },
+        "install":
+          [
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/steipete/sonoscli/cmd/sonos@latest",
+              "bins": ["sonos"],
+              "label": "Install sonoscli (go)",
+            },
+          ],
+      },
+  }
+---
+
+# Sonos CLI
+
+Use `sonos` to control Sonos speakers on the local network.
+
+## Quick start
+
+- `sonos discover`
+- `sonos status --name "Kitchen"`
+- `sonos play|pause|stop --name "Kitchen"`
+- `sonos volume set 15 --name "Kitchen"`
+
+## Common tasks
+
+- Grouping: `sonos group status|join|unjoin|party|solo`
+- Favorites: `sonos favorites list|open`
+- Queue: `sonos queue list|play|clear`
+- Spotify search (via SMAPI): `sonos smapi search --service "Spotify" --category tracks "query"`
+
+## Notes
+
+- If SSDP fails, specify `--ip <speaker-ip>`.
+- Spotify Web API search is optional and requires `SPOTIFY_CLIENT_ID/SECRET`.
+- If there is an error, check the troubleshooting section and offer advice if there is a decent match.
+
+## Troubleshooting
+
+### `sonos discover` - `no route to host`
+
+- On error `Error: write udp4 0.0.0.0:64326->239.255.255.250:1900: sendto: no route to host (Command exited with code 1)`
+  - Note that the port number after `0.0.0.0:` is ephemeral and will change and the netmask may not match exactly either
+  - The `sendto: no route to host` should stay consistent
+- Advise the user that in `direct` (no Docker sandbox) mode on Mac OS that Settings -> Privacy & Security -> Local Network will need to be enabled for the top-level host parent process of the Gateway
+  - `node` if running via `launchd`
+  - `Terminal` if running the gateway directly in the terminal
+  - `Visual Studio Code` if running via terminal in VS Code
+- An alternative option is to use `sandbox` (docker container) with network access allowed for that sandbox
+
+### `sonos discover` - `bind: operation not permitted`
+
+- On error `Error: listen udp4 0.0.0.0:0: bind: operation not permitted`
+- Advise the user that they may be running via a Codex or other sandbox that does not permit network access (this can be replicated by running `sonos discover` within a Codex CLI session with sandbox enabled and not approving the escalation request)

package/skills/spotify-player/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: spotify-player
+description: Terminal Spotify playback/search via spogo (preferred) or spotify_player.
+homepage: https://www.spotify.com
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🎵",
+        "requires": { "anyBins": ["spogo", "spotify_player"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "spogo",
+              "tap": "steipete/tap",
+              "bins": ["spogo"],
+              "label": "Install spogo (brew)",
+            },
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "spotify_player",
+              "bins": ["spotify_player"],
+              "label": "Install spotify_player (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# spogo / spotify_player
+
+Use `spogo` **(preferred)** for Spotify playback/search. Fall back to `spotify_player` if needed.
+
+Requirements
+
+- Spotify Premium account.
+- Either `spogo` or `spotify_player` installed.
+
+spogo setup
+
+- Import cookies: `spogo auth import --browser chrome`
+
+Common CLI commands
+
+- Search: `spogo search track "query"`
+- Playback: `spogo play|pause|next|prev`
+- Devices: `spogo device list`, `spogo device set "<name|id>"`
+- Status: `spogo status`
+
+spotify_player commands (fallback)
+
+- Search: `spotify_player search "query"`
+- Playback: `spotify_player playback play|pause|next|previous`
+- Connect device: `spotify_player connect`
+- Like track: `spotify_player like`
+
+Notes
+
+- Config folder: `~/.config/spotify-player` (e.g., `app.toml`).
+- For Spotify Connect integration, set a user `client_id` in config.
+- TUI shortcuts are available via `?` in the app.

package/skills/summarize/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: summarize
+description: Summarize or extract text/transcripts from URLs, podcasts, and local files (great fallback for “transcribe this YouTube/video”).
+homepage: https://summarize.sh
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🧾",
+        "requires": { "bins": ["summarize"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/summarize",
+              "bins": ["summarize"],
+              "label": "Install summarize (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Summarize
+
+Fast CLI to summarize URLs, local files, and YouTube links.
+
+## When to use (trigger phrases)
+
+Use this skill immediately when the user asks any of:
+
+- “use summarize.sh”
+- “what’s this link/video about?”
+- “summarize this URL/article”
+- “transcribe this YouTube/video” (best-effort transcript extraction; no `yt-dlp` needed)
+
+## Quick start
+
+```bash
+summarize "https://example.com" --model google/gemini-3-flash-preview
+summarize "/path/to/file.pdf" --model google/gemini-3-flash-preview
+summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto
+```
+
+## YouTube: summary vs transcript
+
+Best-effort transcript (URLs only):
+
+```bash
+summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto --extract-only
+```
+
+If the user asked for a transcript but it’s huge, return a tight summary first, then ask which section/time range to expand.
+
+## Model + keys
+
+Set the API key for your chosen provider:
+
+- OpenAI: `OPENAI_API_KEY`
+- Anthropic: `ANTHROPIC_API_KEY`
+- xAI: `XAI_API_KEY`
+- Google: `GEMINI_API_KEY` (aliases: `GOOGLE_GENERATIVE_AI_API_KEY`, `GOOGLE_API_KEY`)
+
+Default model is `google/gemini-3-flash-preview` if none is set.
+
+## Useful flags
+
+- `--length short|medium|long|xl|xxl|<chars>`
+- `--max-output-tokens <count>`
+- `--extract-only` (URLs only)
+- `--json` (machine readable)
+- `--firecrawl auto|off|always` (fallback extraction)
+- `--youtube auto` (Apify fallback if `APIFY_API_TOKEN` set)
+
+## Config
+
+Optional config file: `~/.summarize/config.json`
+
+```json
+{ "model": "openai/gpt-5.2" }
+```
+
+Optional services:
+
+- `FIRECRAWL_API_KEY` for blocked sites
+- `APIFY_API_TOKEN` for YouTube fallback

package/skills/taskflow/SKILL.md

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

package/skills/taskflow/examples/inbox-triage.lobster

@@ -0,0 +1,33 @@
+# Illustrative Lobster authoring example for a TaskFlow-style inbox triage job.
+# Swap the placeholder commands for your own tools or scripts.
+
+name: inbox-triage
+steps:
+  - id: fetch
+    command: gog.gmail.search --query 'newer_than:1d' --max 20
+
+  - id: classify
+    command: >-
+      openclaw.invoke --tool llm-task --action json --args-json
+      '{"prompt":"Classify each inbox item as business, personal, or later. Return one JSON object per item with route and summary.","thinking":"low","schema":{"type":"object","properties":{"items":{"type":"array"}},"required":["items"],"additionalProperties":false}}'
+    stdin: $fetch.stdout
+
+  - id: post_business
+    command: slack-route --bucket business
+    stdin: $classify.stdout
+    condition: $classify.json.items[0].route == "business"
+
+  - id: wait_for_business_reply
+    command: echo '{"status":"waiting","reason":"slack_reply"}'
+    condition: $classify.json.items[0].route == "business"
+
+  - id: notify_personal
+    command: >-
+      openclaw.invoke --tool message --action send --args-json
+      '{"provider":"telegram","to":"owner-thread","content":"Personal inbox item needs attention."}'
+    condition: $classify.json.items[0].route == "personal"
+
+  - id: stash_for_eod
+    command: summary-append --bucket eod
+    stdin: $classify.stdout
+    condition: $classify.json.items[0].route == "later"

package/skills/taskflow/examples/pr-intake.lobster

@@ -0,0 +1,32 @@
+# Illustrative Lobster authoring example for a TaskFlow-style PR intake lane.
+# Replace the placeholder commands with repo-specific tooling.
+
+name: pr-intake
+steps:
+  - id: fetch
+    command: gh pr list --repo owner/repo --state open --json number,title,body,headRefName
+
+  - id: classify
+    command: >-
+      openclaw.invoke --tool llm-task --action json --args-json
+      '{"prompt":"Classify each PR as close, request_changes, refactor, or maintainer_review. Return intent and recommended next action.","thinking":"low","schema":{"type":"object","properties":{"items":{"type":"array"}},"required":["items"],"additionalProperties":false}}'
+    stdin: $fetch.stdout
+
+  - id: close_low_signal
+    command: pr-close-low-signal
+    stdin: $classify.stdout
+    condition: $classify.json.items[0].nextAction == "close"
+
+  - id: request_changes
+    command: pr-request-changes
+    stdin: $classify.stdout
+    condition: $classify.json.items[0].nextAction == "request_changes"
+
+  - id: refactor_branch
+    command: pr-refactor-branch
+    stdin: $classify.stdout
+    condition: $classify.json.items[0].nextAction == "refactor"
+
+  - id: escalate
+    command: echo '{"status":"notify","target":"maintainer"}'
+    condition: $classify.json.items[0].nextAction == "maintainer_review"

package/skills/taskflow-inbox-triage/SKILL.md

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

package/skills/things-mac/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: things-mac
+description: Manage Things 3 via the `things` CLI on macOS (add/update projects+todos via URL scheme; read/search/list from the local Things database). Use when a user asks OpenClaw to add a task to Things, list inbox/today/upcoming, search tasks, or inspect projects/areas/tags.
+homepage: https://github.com/ossianhempel/things3-cli
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "✅",
+        "os": ["darwin"],
+        "requires": { "bins": ["things"] },
+        "install":
+          [
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/ossianhempel/things3-cli/cmd/things@latest",
+              "bins": ["things"],
+              "label": "Install things3-cli (go)",
+            },
+          ],
+      },
+  }
+---
+
+# Things 3 CLI
+
+Use `things` to read your local Things database (inbox/today/search/projects/areas/tags) and to add/update todos via the Things URL scheme.
+
+Setup
+
+- Install (recommended, Apple Silicon): `GOBIN=/opt/homebrew/bin go install github.com/ossianhempel/things3-cli/cmd/things@latest`
+- If DB reads fail: grant **Full Disk Access** to the calling app (Terminal for manual runs; `OpenClaw.app` for gateway runs).
+- Optional: set `THINGSDB` (or pass `--db`) to point at your `ThingsData-*` folder.
+- Optional: set `THINGS_AUTH_TOKEN` to avoid passing `--auth-token` for update ops.
+
+Read-only (DB)
+
+- `things inbox --limit 50`
+- `things today`
+- `things upcoming`
+- `things search "query"`
+- `things projects` / `things areas` / `things tags`
+
+Write (URL scheme)
+
+- Prefer safe preview: `things --dry-run add "Title"`
+- Add: `things add "Title" --notes "..." --when today --deadline 2026-01-02`
+- Bring Things to front: `things --foreground add "Title"`
+
+Examples: add a todo
+
+- Basic: `things add "Buy milk"`
+- With notes: `things add "Buy milk" --notes "2% + bananas"`
+- Into a project/area: `things add "Book flights" --list "Travel"`
+- Into a project heading: `things add "Pack charger" --list "Travel" --heading "Before"`
+- With tags: `things add "Call dentist" --tags "health,phone"`
+- Checklist: `things add "Trip prep" --checklist-item "Passport" --checklist-item "Tickets"`
+- From STDIN (multi-line => title + notes):
+  - `cat <<'EOF' | things add -`
+  - `Title line`
+  - `Notes line 1`
+  - `Notes line 2`
+  - `EOF`
+
+Examples: modify a todo (needs auth token)
+
+- First: get the ID (UUID column): `things search "milk" --limit 5`
+- Auth: set `THINGS_AUTH_TOKEN` or pass `--auth-token <TOKEN>`
+- Title: `things update --id <UUID> --auth-token <TOKEN> "New title"`
+- Notes replace: `things update --id <UUID> --auth-token <TOKEN> --notes "New notes"`
+- Notes append/prepend: `things update --id <UUID> --auth-token <TOKEN> --append-notes "..."` / `--prepend-notes "..."`
+- Move lists: `things update --id <UUID> --auth-token <TOKEN> --list "Travel" --heading "Before"`
+- Tags replace/add: `things update --id <UUID> --auth-token <TOKEN> --tags "a,b"` / `things update --id <UUID> --auth-token <TOKEN> --add-tags "a,b"`
+- Complete/cancel (soft-delete-ish): `things update --id <UUID> --auth-token <TOKEN> --completed` / `--canceled`
+- Safe preview: `things --dry-run update --id <UUID> --auth-token <TOKEN> --completed`
+
+Delete a todo?
+
+- Not supported by `things3-cli` right now (no “delete/move-to-trash” write command; `things trash` is read-only listing).
+- Options: use Things UI to delete/trash, or mark as `--completed` / `--canceled` via `things update`.
+
+Notes
+
+- macOS-only.
+- `--dry-run` prints the URL and does not open Things.