loop

# /openloomi:loop

Thin doorway into the [`openloomi-loop`](../skills/openloomi-loop/SKILL.md)
sub-skill. With no arguments it prints the dashboard snapshot from
`GET /api/loop/state`. To force-refresh the connector snapshot (which the
dashboard reads but caches), say **"loop refresh"**, **"refresh
connectors"**, **"force refresh"**, **"check connections"**, or pass
`refresh` as the slash argument (`/openloomi:loop refresh`). For
everything else (run a tick, schedule a decision, register a custom type /
channel / classifier rule), say "loop tick", "loop schedule", "register
loop type", "add loop rule" — the sub-skill's frontmatter triggers on
those phrases and walks Claude through the full API.

Base URL: `http://localhost:3414` (fallback `http://localhost:3515`).
The skill doc spells out which port is which.

## Steps

1. Read the bearer token (base64-encoded JWT stored at
   `~/.openloomi/token`) and decode it:

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

2. Decide the mode:
   - **Refresh mode** (user said "refresh connectors" / "force refresh"
     / "check connections" / passed `/openloomi:loop refresh`) → go to
     the [Refresh connectors](#refresh-connectors) section below, not
     this one.
   - **Default dashboard mode** (no args, or "loop dashboard" / "loop
     state") → continue.

3. Fetch the dashboard:

   ```bash
   curl -sS "$BASE/api/loop/state" -H "Authorization: Bearer $TOKEN" | jq .
   ```

4. Print the JSON to the user. Highlight:
   - `pending` — number of decisions waiting for Run / Dry / Dismiss
   - `connectors` — integration health (one entry per signal channel;
     **note**: this is the cached snapshot — see Refresh below)
   - `lastTickAt` — when the last signal pull ran
   - `prefs` — current interval / brief time / wrap time / timezone

5. If `pending > 0`, suggest the natural-language follow-up:

   > Say **"loop inbox"** to list them, or **"loop tick"** to pull new
   > signals and classify them now.

6. If any connector shows `connected: false` with a `lastError` like
   `"no composio surface reachable"` and the user actually has those
   connectors configured through Composio (check with
   `composio connections list`), suggest:

   > The dashboard is reading a stale snapshot. Say **"loop refresh"**
   > to force-refresh connector probes — that bypasses the cache and
   > re-probes every channel through Composio.

---

## Refresh connectors

The Loop dashboard reads a cached connector snapshot
(`~/.openloomi/loop/connectors.json`) that's refreshed on a slow TTL and
re-probed opportunistically by the agent. When the cache is wrong
(common: every connector reports `connected: false` with `lastError: "no
composio surface reachable"` even though `composio connections list`
returns active toolkits), `GET /api/loop/connectors?refresh=1` forces a
fresh probe now and persists the result.

This is **read-only**: nothing is created, scheduled, sent, or deleted.
The probe runs server-side; expect 1–10 seconds per connector.

```bash
curl -sS "$BASE/api/loop/connectors?refresh=1" \
  -H "Authorization: Bearer $TOKEN" | jq .
```

The response shape is `{items: ConnectorHealth[], lastProbeError?: string}`.
Each `ConnectorHealth` has:

| Field       | Meaning                                                            |
| ----------- | ------------------------------------------------------------------ |
| `id`        | stable connector id (e.g. `gmail`, `slack`, `linear`)              |
| `label`     | human-readable name                                                |
| `connected` | `true` iff the most recent probe succeeded                         |
| `lastError` | string when probe failed (`null`/`undefined` on success)           |
| `fetchedAt` | ISO timestamp of the **most recent** probe (proves refresh worked) |

After the response, do the following:

1. **Confirm the refresh actually fired.** Print `fetchedAt` for every
   connector — they should all share the same timestamp from "just now"
   (within the last ~30s). If the timestamps are older, the cache wasn't
   invalidated and the call hit the cache. Re-check the URL: it must end
   in `?refresh=1`, not `?refresh=true`.
2. **Summarize the result.** One line per connector: `gmail ✅ connected`,
   `slack ❌ lastError=...`. Group `connected: true` first; failures last.
3. **If anything is still red**, surface the `lastError` verbatim. Do
   not invent reasons — quote the string the API returned.
4. **The refreshed snapshot is the new cache.** Subsequent
   `/api/loop/state` calls will read it; no further action needed.

### Refresh failure modes

| HTTP / network                               | What to surface                                                                                                                                                                  |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Connection refused on `:3414` and `:3515`    | OpenLoomi isn't running. Point the user at `/openloomi:status` to confirm, then `/openloomi:setup` if needed.                                                                    |
| `401 Unauthorized`                           | Token is stale or missing. Re-run `/openloomi:setup` to mint a fresh guest bearer.                                                                                               |
| `404` on `/api/loop/connectors`              | Runtime is older than Loop. Tell the user to update OpenLoomi Desktop — Loop ships in the desktop bundle.                                                                        |
| Probe runs but every connector still `false` | Real probe failure. Cross-check with `composio connections list` (or whichever CLI the connector expects); if those show healthy toolkits but Loop still fails, surface the gap.