openloomi-loop

Files (2)

• .gitignore
• SKILL.md

SKILL.md (first lines)

> **Note:** If you haven't downloaded or installed openloomi yet, please refer to [Getting Started](https://openloomi.ai/docs/getting-started) for installation instructions.

# OpenLoomi Loop — The Proactive Execution Brain

Loop pulls signals from connected integrations, classifies them into
typed decisions, and lets the user approve execution from the pet or
the web UI. This skill is a thin Claude-side wrapper around Loop's
HTTP API.

## Where things live

| Concern | Location |
|---|---|
| Business logic | Loop's TypeScript core (closed `DecisionType` + classifier + scheduler) |
| HTTP API | `/api/loop/*` — `state`, `decisions`, `decision/[id]`, `card/[id]`, `connectors`, `brief`, `wrap`, `tick`, `preferences`, `action/*`, `types`, `types/[id]`, `channels`, `channels/[id]`, `classifier-rules`, `classifier-rules/[id]`, `classifier-rules/dry-run` |
| Persistence | `~/.openloomi/loop/{signals.jsonl,decisions.json,status.json,connectors.json,config.json}` |
| Scheduler | Three `ScheduledJob` rows: `loop.tick`, `loop.brief`, `loop.wrap` (registered by the loop scheduler) |
| Pet surface | Tauri Rust thread `loomi-pet-decision-watcher` polls `decisions.json` mtime every 2s and emits `loop:state` / `loop:decision` to bubble + card webviews. The widget supports two built-in themes (`fox`, `capybara`) and a `presenting` state surfaced when a decision moves to `done` before the user has reviewed it — click the bubble to flip back to `happy`. User-editable theme config lives at `~/.openloomi/pet-config.json`. |

## Base URL

| Environment | Base |
|---|---|
| Local desktop (Tauri) — default | `http://localhost:3414` |
| Dev server (`pnpm dev`, `pnpm tauri:dev`) | `http://localhost:3515` |

If unsure, start with `http://localhost:3414`. Loop ships inside the
desktop bundle; the dev port is only relevant when you're running
the web app standalone.

## Auth

Per-user routes (`/tick`, `/decision/[id]` POST, `/preferences`,
`/action/*`) require the same auth as the rest of the app. Token is
the base64-encoded JWT stored at `~/.openloomi/token` — decode it
before use:

```bash
TOKEN=$(cat ~/.openloomi/token | base64 -d)
```

Then pass `-H "Authorization: Bearer $TOKEN"` on every call below.

## API quick reference

| Verb | Path | Use |
|---|---|---|
| GET  | `/api/loop/state` | dashboard payload (prefs + counts + connectors + lastTickAt) |
| GET  | `/api/loop/decisions?status=pending\|done\|dismissed` | inbox |
| GET  | `/api/loop/decision/[id]` | full decision JSON |
| GET  | `/api/loop/card/[id]` | card-shaped JSON (`why` / `source_chain` / `dialogue` / `nextStep`) |
| POST | `/api/loop/tick` | run one tick (signals → classify → enqueue) |
| POST | `/api/loop/action/schedule` | `{decision_id, action:"run\|dry\|dismiss\|promote"}` → `{action_id, fire_at}`. Job fires ~30s later; cancellable. |
| DELETE | `/api/loop/action/[id]` | cancel a not-yet-fired scheduled action (409 if already fired) |
| GET  | `/api/loop/action/by-decision/[id]` | look up `action_id` for a decision (pet "Open" button) |
| POST | `/api/loop/brief` `{force?}` | build morning brief + enqueue card |
| GET  | `/api/loop/brief/content` | render the morning brief as text without enqueuing |
| POST | `/api/loop/wrap` `{force?}` | build evening wrap + enqueue card |
| GET  | `/api/loop/wrap/content` | render the evening wrap as text without enqueuing |
| GET  | `/api/loop/preferences` | read prefs |
| PUT  | `/api/loop/preferences` `{...patch}` | write prefs + sync the 3 `ScheduledJob` rows |
| GET  | `/api/loop/connectors?refresh=1` | list integration health |
| GET  | `/api/loop/types` | list user-defined decision types |
| PUT  | `/api/loop/types` `{id,label,icon,actionKind,description?}` | upsert a custom decision type |
| DELETE | `/api/loop/types/[id]` | remove a custom decision type |
| GET  | `/api/loop/channels` | list user-defined signal channels |
| PUT  | `/api/loop/channels` `{id,label,toolkit,toolSlug,pollIntervalSec,signalType,payloadShape?,eventFilter?}` | upsert a custom channel |
| DELETE | `/api/loop/channels/[id]` | remove a custom signal channel |
| GET  | `/api/loop/classifier-rules` | list user-defined deterministic classifier rules (force `type` / `actionKind` / confidence floor when `when` predicates match) |
| PUT  | `/api/loop/classifier-rules` `{id,label?,when[],then{type,actionKind?,confidence?},description?}` | upsert a rule. `when` is up to 8 `{field,op,value?\|pattern?}` predicates; `signal.type` / `signal.payload.*` paths; ops `eq` `neq` `contains` `matches` `startsWith` `endsWith` `gt` `lt` `gte` `lte` `exists` `absent`. `then.type` can be a built-in/custom `DecisionType` or `"noop"` (suppress). |
| DELETE | `/api/loop/classifier-rules/[id]` | remove a rule |
| POST | `/api/loop/classifier-rules/dry-run` `{signal}` | preview which rules would match a given signal (read-only). Returns `{matches,trace,totalRules}`. |

`agent_goal` is opt-in for an explicit user custom type or classifier rule.
After the user approves its pending decision with Run, the visible decision
title becomes a durable Goal objective. Ordinary todos are never upgraded.

## Examples

```bash
BASE="http://localhost:3414"   # or http://localhost:3515
TOKEN=$(cat ~/.openloomi/token | base64 -d)

# Dashboard snapshot
curl -sS "$BASE/api/loop/state" -H "Authorization: Bearer $TOKEN" | jq .

# Run one tick
curl -sS -X POST "$BASE/api/loop/tick" -H "Authorization: Bearer $TOKEN"

# List pending decisions
curl -sS "$BASE/api/loop/decisions?status=pending" \
  -H "Authorization: Bearer $TOKEN" | jq .

# Read a single decision / card
curl -sS "$BASE/api/loop/decision/dec_xxx" -H "Authorization: Bearer $TOKEN"
curl -sS "$BASE/api/loop/card/dec_xxx"      -H "Authorization: Bearer $TOKEN"

# Run a decision (returns action_id; cron fires it ~30s later)
curl -sS -X POST "$BASE/api/loop/action/schedule" \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"decision_id":"dec_xxx","action":"run"}'

# Cancel before it fires
curl -sS -X DELETE "$BASE/api/loop/action/<action_id>" \
  -H "Authorization: Bearer $TOKEN"

# Force a brief / wrap card now
curl -sS -X POST "$BASE/api/loop/brief" \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"force":true}'

# Tune preferences (intervalSec, briefTime, timezone, ...)
curl -sS -X PUT "$BASE/api/loop/preferences" \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"intervalSec":300,"briefTime":"08:30","wrapTime":"22:30","timezone":"Asia/Shanghai"}'

From melandlabs/openloomi, Apache-2.0.

More from melandlabs/openloomi