git:20260715.f00df98 to git:20260723.741cff2

---

name: operator-inbox

description: Maintain a provider-neutral local action queue from bounded provider observations and explicit human dispositions.

runx:

category: ops

---

# Operator Inbox

Maintain a durable action queue without turning a connector into the owner of

operator state.

The caller fetches bounded, grant-authorized provider pages and passes their

normalized observations to this skill. The skill owns work-item identity,

status, dispositions, replay suppression, reopen rules, and scan coverage. Every

read and write is composed through `data-store`; the skill does not call Slack,

SQLite, Postgres, or another provider directly.

## What this skill does

Use `local://runx/operator-inbox/default` unless the operator selects another

logical source. Unbound local refs resolve to SQLite under

`.runx/data/local-sources/`. A hosted database is opt-in through the same

`data_source_ref` binding. Runx Connect may still own OAuth, grants, and provider

execution; that does not move this queue into the hosted control plane.

Observations and resumable checkpoints live in `operator_inbox_scans`, partitioned

by query digest. Action snapshots live in `operator_inbox_actions`, with one

stream per stable thread digest. Queue reads use bounded `list_stream_heads`

pages; no command folds or transports the complete queue.

## When to use this skill

- Build or revisit a local action queue from bounded connector observations.

- Preserve an explicit `resolved`, `dismissed`, `waiting`, or `followed_up`

decision across repeated provider scans.

- Reopen a completed item when a newer external occurrence arrives.

- Inspect bounded action or scan state without handing queue ownership to the

provider or hosted control plane.

## When not to use this skill

- Do not fetch provider data, reply, send, or mutate a remote account here.

- Do not infer that an item is complete from message text or provider state.

- Do not use it as an unbounded archive of raw messages or credentials.

- Do not place a private operator's routing policy or identity in this public

package; pass normalized observations and explicit dispositions as inputs.

## Status rules

Items use `open`, `waiting`, `followed_up`, `resolved`, or `dismissed`.

- Provider observations never infer completion.

- A human disposition records actor, reason, time, the latest external

occurrence it covers, and optional HTTPS evidence.

- Replaying old search history preserves the human status.

- An external message newer than the covered occurrence reopens the item to

`open`, including unseen work that arrived before the disposition was saved.

- Scan coverage is explicit: `running`, `complete`, `truncated`, or `failed`.

- Direct mentions are actionable structural evidence. Author and keyword scans

remain observation-only unless the operator explicitly marks the query

actionable. The skill does not contain provider-specific keyword heuristics.

The provider-neutral thread locator is the item key. Stored previews are bounded;

credentials, tokens, and full provider response envelopes are forbidden.

## Procedure

1. Read the latest checkpoint for the bounded query digest.

2. Resume its provider cursor when the prior scan was interrupted or truncated.

3. Fetch one bounded provider page through the caller's authorized connector.

4. Record actionable messages against their per-thread streams and append the

scan page with its next cursor.

5. On a version conflict, reload only the affected scan or action stream and

retry the idempotent transition.

6. List queue state through bounded action-head pages and use

`record_disposition` only for an explicit operator correction.

The loop is outside the kernel. Each page or disposition remains one governed,

receipt-backed Runx turn.

## Edge cases and stop conditions

- `needs_input`: missing query identity, observation, disposition,

actor, reason, or scan coverage.

- `conflict`: the projection version is stale; reload before retrying.

- `provider_unavailable`: the caller cannot prove provider read coverage.

- `too_broad`: a page exceeds the bounded message count or contains unnormalized

provider data.

- `refused`: a caller asks this skill to send, reply, broaden a grant, store a

token, or silently claim complete coverage.

## Output schema

Write runners emit `runx.effect.transition.v1`, containing the effect family,

operation, expected projection version, idempotency key, and one normalized

event. Read and list runners return the corresponding bounded `data-store`

event result; they never synthesize provider coverage or completion.

## Worked example

Given a normalized direct mention from a teammate in one provider thread,

`record_action_observation` derives the stable action id from the provider-neutral

thread locator and appends an `open` action snapshot. If the operator later

records `resolved` with a reason, replaying that mention preserves `resolved`;

a newer external reply in the same thread appends a reopened `open` snapshot.

## Inputs

All runners require `data_source_ref`. Write runners also take the target id,

`expected_version`, and `observed_at`, plus exactly the normalized payload for

their operation: `scan` and `messages`, `message` and `triage`, `disposition`,

or an imported `action`. Reads take `action_id` or `query_digest`; list runners

take bounded `limit` and optional cursor or filter fields.