@remits/remits-cli 0.1.91 → 0.1.93

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.91",
+  "version": "0.1.93",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,

package/skills/remits-cli/SKILL.md

@@ -95,6 +95,7 @@ description: Use remits-cli for fast branch-scoped component staging, test execu
 - Line 2169: `mcp_run_agent`
 - Line 2205: `mcp_system_logs`
 - Line 2228: `mcp_performance_trace`
+- Line 2260: `mcp_event_diagnostics`
 - Line 2263: `mcp_component_view`
 - Line 2286: `mcp_component_grep`
 - Line 2299: `mcp_support_ticket`
@@ -1179,9 +1180,17 @@ the compile cache without colliding.
 That signature is logged. Querying for it is the single most reliable way to know what ran:
 
 ```bash
-remits-cli tool --name mcp_system_logs --input '{"node":"remitsAdmin-east5","timeRange":"1h","filter":"textPayload:\"Using Cached BCD\""}' --data-mode prod
+remits-cli tool --name mcp_system_logs --input '{"node":"remitsAdmin-east5","timeRange":"1h","filter":"Using Cached BCD"}' --data-mode prod
 ```
 
+> **Pass the bare phrase — never hand-write a `textPayload:` filter.** In production the platform's
+> logback encoder writes every `log.*` line to **`jsonPayload.message`**; only `println`/stdout lands in
+> `textPayload`. A `textPayload:"..."` filter therefore matches **zero** rows for nearly every platform
+> log line, and zero rows is indistinguishable from "it never happened" — which has already caused a real
+> misdiagnosis. `mcp_system_logs` now widens a bare phrase (and any `textPayload:"..."` clause) to cover
+> both shapes, and echoes the executed filter back as `filterApplied`. A filter that names `jsonPayload`
+> explicitly is passed through untouched.
+
 `Using Cached BCD [ID: 230, Type: Action, Signature: cli:08cc...]` → ran a **staged** override.
 `...Signature: variant:14:9f2c1a...]` → ran a **committed branch variant**.
 `...Signature: version:37:abc123def456]` → ran the **committed trunk** version.
@@ -1739,8 +1748,13 @@ Before starting an investigation outside the confirmed current repo:
 **Stuck / failed / recovered Event:**
 
 Do **not** open the Action source first. The platform records each attempt's delivery envelope (which
-queue delivered it, which delivery attempt this was, which instance owned it, how long it was ever
-allowed to run) and will classify the failure for you. From a Test or any component:
+queue delivered it, which delivery attempt this was, and how long it was ever allowed to run) and will classify the failure for you. From remits-cli / MCP, use `mcp_event_diagnostics` first:
+
+```bash
+remits-cli tool --name mcp_event_diagnostics --input '{"accountId":49,"eventId":18838}' --data-mode prod
+```
+
+From a Test or any component, the same platform classifier is available directly:
 
 ```groovy
 eventDiagnostics(18838)
@@ -1764,6 +1778,8 @@ Read `classification` before anything else:
 non-idempotent side effect may have run more than once — check for duplicate records before concluding
 the component "ran twice for no reason".
 
+`mcp_event_diagnostics` returns the same classification, `delivery.threadGroupingId`, and ready-to-run
+`pivots` for `mcp_performance_trace`, `mcp_system_logs`, `mcp_record_listing`, and `mcp_object_activity`.
 `delivery.threadGroupingId` is the same id everything else uses, so you can pivot straight into
 `mcp_performance_trace` (`action:"trace"`) or `mcp_system_logs` with it. `logQuery` in the response
 carries ready-made Cloud Logging filters, including the container-lifecycle and 504 queries.
@@ -1889,9 +1905,10 @@ account).
   tells you when the fields shown belong to a different account.
 - `action: 'account_update'` — write Account-schema configuration `fields`, and/or `name`/`status`
   (`ACTIVE`/`ON_HOLD`/`PENDING`).
-- `action: 'user_update'` — write User-schema `fields` under the named account (refused unless the user is a
-  member or you pass `addAccount: true`, because the write would otherwise land on another account), plus
-  `name`/`enabled` and membership add/remove.
+- `action: 'user_update'` — write User-schema `fields` under the named account, plus `name`/`enabled` and
+  membership add/remove. Refused unless the user is a member or you pass `addAccount: true`, because the
+  write would otherwise land on another account. If an email does not exist globally, `addAccount: true`
+  intentionally creates that user first, then binds them to the named account before writing fields.
 
 **Building an account hierarchy** (the structural writes — this is how a coding agent provisions accounts
 without a browser):
@@ -2169,6 +2186,41 @@ Returned fields on the async/event start: `actionRunId`, `status:"running"`, `ex
 `threadGroupingId`, `componentSource`, `componentSignature`, and (event mode) `eventId`/`eventStatus`. The
 `status` poll adds `result` on completion, or `message`/`error` on failure.
 
+> **In event mode the EVENT is the source of truth, not the promise.** `status` is driven by the Event's
+> own state; the value the dispatch call returned is reported separately as `dispatchResult` and is **not**
+> the Action's result. Read `eventStatus` for the outcome.
+
+#### Stopping a run — `controlAction:'interrupt'`
+
+The tool counterpart of the **Interrupt** button on the admin Events page. Use it when an investigation
+turns up a run that is consuming resources and should not finish — the case this exists for is finding a
+`PROCESSING` event that has been running far too long.
+
+```bash
+# the usual path: you found the event in mcp_record_listing / mcp_object_activity
+remits-cli tool --name mcp_run_action --data-mode prod --input '{"controlAction":"interrupt","accountId":49,"eventId":19102,"reason":"runaway extraction, 45min"}'
+
+# or stop a run you started yourself (executionMode:'event' only)
+remits-cli tool --name mcp_run_action --data-mode prod --input '{"controlAction":"interrupt","accountId":4,"actionRunId":"my-run-id"}'
+```
+
+Aliases `cancel` / `stop` / `kill` all work. What you need to know before using it:
+
+- **It is COOPERATIVE cancellation, not a thread kill.** It sets a flag the running work observes at its
+  next checkpoint, then throws. Checkpoints are dense across everything that matters — every Firestore
+  read/write, outbound HTTP call, AI turn, and front-stage DSL call — so a normal run stops promptly. A
+  run blocked inside a *single* long call (one slow AI turn) stops when that call returns, not instantly.
+- **Work already committed is NOT rolled back.** This stops further work; it does not undo what has run.
+- **Only `PENDING`/`QUEUED`/`PROCESSING` can be interrupted.** A terminal event is reported back with its
+  status rather than being silently reported as "interrupted".
+- **Event-scoped.** A `direct` or `async` run has no Event and cannot be stopped this way.
+- Tenant-scoped: you cannot interrupt another account's event.
+- The response returns `previousStatus`, `eventStatus`, and `threadGroupingId`, so you can pivot straight
+  into `mcp_performance_trace` / `mcp_system_logs` to see what it was doing when you stopped it.
+
+**AI sessions are stopped separately** with `mcp_ai_session_search` (`action:'interrupt'`, plus
+`pause`/`unpause`) — that controls an agent's conversation loop, whereas this controls an Action's Event.
+
 ### `mcp_run_agent`
 Run one real Agent turn on a target account. The Agent hooks and tools execute for real against the requested
 `dataMode`; pass `dataMode:"test"` for safer tuning.
@@ -2205,6 +2257,24 @@ remits-cli tool --name mcp_ai_session_search --input '{"action":"detail","sessio
 Key returned fields: `agentRunId`, `sessionId`, `status`, `threadGroupingId`, runtime pause/interruption
 hints, `lastAssistantMessage`, `toolCallCount`, `result`, `message`, and `error`.
 
+#### Controlling a live agent — `pause` / `unpause` / `interrupt`
+
+```bash
+remits-cli tool --name mcp_run_agent --data-mode prod --input '{"controlAction":"pause","accountId":49,"agentRunId":"my-run-id"}'
+remits-cli tool --name mcp_run_agent --data-mode prod --input '{"controlAction":"interrupt","accountId":49,"sessionId":"<sessionId>"}'
+```
+
+Target the session with the `agentRunId` an async start returned, or the `sessionId` directly.
+
+- **`interrupt` is TERMINAL** (aliases `stop`/`cancel`/`kill`). It clears any pending resume and pending
+  guardrails and persists a terminal lifecycle status. An interrupted session **cannot be unpaused** —
+  attempting it is refused with that reason rather than silently doing nothing. Use `pause` if you intend
+  to resume.
+- If the session is not resident on the serving node, it is rehydrated by agent name — so pass `agentName`
+  (or an `agentRunId`, which carries it) when controlling a session you did not just start.
+- The same controls remain available on `mcp_ai_session_search`, which is the right tool when you are
+  *searching* for the session; this is the right one when you *started* the run.
+
 ### `mcp_system_logs`
 Query Cloud Run service logs.
 
@@ -2218,7 +2288,8 @@ Query Cloud Run service logs.
 | `endTime` | no | ISO 8601 upper bound (defaults to now) |
 | `severity` | no | Minimum: `INFO`, `WARNING`, `ERROR`, etc. |
 | `threadGroupingId` | no | Filter by processing chain ID |
-| `filter` | no | Additional Cloud Logging filter (LQL) |
+| `filter` | no | Additional Cloud Logging filter (LQL). **To search message text, pass the bare phrase** — it is widened automatically to match both `jsonPayload.message` (all `log.*` output) and `textPayload` (`println`/stdout). See the warning under "Diagnosing which version is in play". |
+| `maxPreviewChars` | no | Per-entry truncation width. Default 512, max 8000. Raise it when an entry carries a structured payload (a serialized `RemitsTrace`, a long stack frame) that the default cuts mid-JSON. |
 | `pageSize` | no | Default 25, max 100. Also accepts `limit`. |
 
 *Provide either `node` or `serviceName`+`region`. Provide either `timeRange` or `startTime`.
@@ -2252,17 +2323,64 @@ remits-cli tool --name mcp_performance_trace --input '{"action":"snapshot","limi
 | `traceId` / `threadGroupingId` | for `trace` | Request/grouping id to open across local ring and Cloud Logging. |
 | `lookbackHours` | no | Cloud Logging window for `trace`/`slowest`. Defaults are 6 and 4 hours. |
 | `accountId` | no | Account filter for `slowest`. |
-| `kind` | no | Operation kind filter for `slowest`, e.g. `embeddable`, `action`, `reader`. |
+| `kind` | no | Operation kind filter for `slowest`. **Rarely what you want** — see the note below. |
+| `componentType` | no | Filter `slowest` by the component that did the work: `Action`, `Reader`, `Rule`, `Embeddable`, `Tool`, `Test`. **This is the right axis for "which Actions/Rules are slow".** |
+| `componentId` / `componentName` | no | Narrow `slowest` to one component. |
+
+> **Filter by `componentType`, not `kind`.** `kind` is set by whoever OPENS the trace. An Action delivered
+> by Cloud Tasks arrives over HTTP, so the trace is `kind:'web'` and the Action is a `component.Action`
+> *span inside it*; a Rule fired during a request and a Tool invoked by an agent are the same. So
+> `kind:'action'` matches almost nothing in production. Every component execution annotates
+> `componentType`/`componentId`/`componentName` — filter on those.
 | `minMs` | no | Minimum duration for `slowest`. Default: 1500. |
 | `limit` | no | Result limit. |
 | `format` / `markdown` | no | Set `format:"markdown"` or `markdown:true` for a rendered trace report. |
 
+> **Tools are components, so availability is per ACCOUNT.** `Tool not found: mcp_performance_trace` does
+> not mean the tool is broken or that tracing is off — it means that tool has not been synced to the
+> account you are resolving against. This bites most often on **localhost** (a Test Account that has not
+> pulled the System Account's tool set) and on **client accounts**. Run `remits-cli tools` for the account
+> in question, or re-run against an account that owns the tool (`--account-id 4` for the System Account).
+> The same is true of every `mcp_*` tool, including the component tools noted below.
+
 Reading rule: first use `slowest` to get candidate trace ids, then call `trace` on the suspicious id, then use
 `mcp_system_logs` only if you need surrounding log lines. A trace dominated by `firestore.*`, `http.*`,
 `gorm.save.*`, or component spans points you at the relevant platform seam or front-stage component. Large
 unaccounted wall time is itself a finding: check cold compile, queueing, blocking I/O, or missing
 `measure(...)` instrumentation.
 
+### `mcp_event_diagnostics`
+Diagnose one Event's infrastructure outcome through the same `eventDiagnostics(eventId)` DSL described in
+`docs/guides/features/observability.md`. Use this before opening Action source when an Event is stuck,
+recovered, timed out, retried, or appears to have been killed.
+
+```bash
+remits-cli tool --name mcp_event_diagnostics --input '{"accountId":49,"eventId":18838}' --data-mode prod
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `accountId` | yes | Tenant scope. The Event must belong to this account unless `includeChildren:true`. |
+| `eventId` / `id` | yes | Event primary key to diagnose. |
+| `includeChildren` | no | Allow the Event to belong to the requested account or one of its child accounts. Default: `false`. |
+
+Read `classification` first:
+
+- `APPLICATION_FAILURE` — the Action failed in application code; read `event.errorMessage`, correlated
+  alerts, and the producing component.
+- `ORPHANED_*` / `RECOVERED_*` — the attempt was abandoned; read `abandonmentCause`.
+- `REQUEST_TIMEOUT_LIKELY` means the work likely used its whole deadline, so split it into resumable batches.
+- `PROCESS_TERMINATED_LIKELY` means the worker likely disappeared before its deadline; inspect JVM/node
+  health and container lifecycle logs.
+- `UNKNOWN_NO_DEADLINE_EVIDENCE` means the platform refuses to guess; use the returned `logQuery` filters.
+- `AWAITING_DELIVERY` means the Event has not been claimed; check queue delivery and action-node health.
+- `IN_FLIGHT_HEALTHY` means the Event is still heartbeating; inspect trace/logs before interrupting.
+
+The response returns `threadGroupingId`, the full `result` map, `diagnosisHints`, and `pivots` containing
+ready-to-run inputs for `mcp_performance_trace`, `mcp_system_logs`, `mcp_record_listing`, and
+`mcp_object_activity` when those handles are present. For a performance question, open the returned
+`mcp_performance_trace` pivot next; for raw failure context, open logs and records by `threadGroupingId`.
+
 ### `mcp_component_view`
 Read component field content with line numbers.
 
@@ -2367,6 +2485,34 @@ Execute a Test component.
 | `accountId` | yes | Account ID |
 | `testId` | yes | Test component ID |
 | `testNames` | no | Array of specific test case names |
+| `taskId` | no | Stable id for the run. **Declare your own if you may need to stop it** — see below. Echoed back either way. |
+| `controlAction` | no | `interrupt` (aliases `stop`/`cancel`/`kill`) stops a running suite identified by `taskId`. |
+
+#### Stopping a running suite
+
+A suite that loops dozens of cases — or sits in one slow AI/HTTP call — used to have to be waited out.
+It can now be stopped, from the admin test runner's **Stop** button or from here.
+
+```bash
+# declare the id when you start, so the run is addressable while it is still going
+remits-cli tool --name mcp_run_test --data-mode test --input '{"accountId":1,"testId":7,"taskId":"my-run"}'
+
+# ...then from another call/session:
+remits-cli tool --name mcp_run_test --data-mode test --input '{"controlAction":"interrupt","accountId":1,"taskId":"my-run"}'
+```
+
+> **This tool runs the suite SYNCHRONOUSLY**, so you cannot stop a run you are yourself blocked on —
+> which is exactly why you declare `taskId` up front. Without one, a run gets a generated id you never see.
+
+Semantics, same as everywhere else in the platform:
+
+- **Cooperative.** The suite ends at its next checkpoint — between cases, or mid-case at any
+  Firestore/HTTP/AI/DSL call. A case stuck in one long external call stops when that call returns.
+- **Cases already completed keep their results**, and committed work is **not** rolled back.
+- An interrupted run returns `interrupted: true` and its partial results. A stop is reported as
+  **INTERRUPTED, never as a test failure** — so it can't be mistaken for a broken suite.
+- Keyed per RUN, not per Test: the same Test can be running concurrently (different users, branches, or
+  data modes), and stopping one never stops another.
 
 ### `mcp_component_edit`
 Edit a component field, server-side, with stage or commit semantics. The agent counterpart to local file