@standardagents/skill 0.25.7 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/skill",
-  "version": "0.25.7",
+  "version": "0.26.0",
   "private": false,
   "publishConfig": {
     "access": "public",

package/skills/agentbuilder/SKILL.md

@@ -858,6 +858,63 @@ Undeclared thread-only env keys are treated as write-only secrets when scanned f
 
 ---
 
+## Production diagnostics & stuck threads
+
+A thread that shows "working" forever has a precise signature: a request log
+row stuck at `is_complete = 0`. The UI's Live badge reads that durable row; the
+`isExecuting` flag is volatile and resets on every Durable Object restart, so
+"Live badge on + executor actually dead" is the classic lost-execution state.
+Since builder 0.26.0 every executing thread is monitored by a per-thread
+watchdog companion (`ThreadWatchdog` DO) that probes it every 30s and
+finalizes/resumes lost executions automatically — but when you need to see or
+intervene, use the sanctioned tools below. Never guess from the UI alone, and
+never reach for the raw `/rpc` passthrough first.
+
+### `agents diag` (CLI)
+
+All subcommands accept `--endpoint <instance-url>` and `--token <api-key>`
+(defaults: `$STANDARD_AGENTS_INSTANCE_URL` / `$STANDARD_AGENTS_INSTANCE_TOKEN`,
+falling back to `http://localhost:5173` for local dev). The token must belong
+to a user with the `logs` permission (admin keys qualify; customer `api`-role
+keys do not).
+
+```bash
+agents diag instance                  # deployed builder version, watchdog budgets, warnings
+agents diag threads --stuck           # scan recent threads for unrecovered open requests
+agents diag thread 050d96f1           # doctor view (short id prefixes resolve)
+agents diag logs 050d96f1             # recent request logs; add a logId for full detail
+agents diag tail 050d96f1             # live-tail the log stream — are bytes flowing?
+agents diag revive 050d96f1           # run a watchdog check NOW: finalize + resume
+```
+
+### Interpretation guide
+
+- `diag instance` → `builder version` answers "is the fix deployed?" without
+  forensics. `watchdog companion: NOT BOUND` means the deployment predates the
+  0.26 config — rebuild/redeploy to get the binding and migration.
+- `diag thread` → the alarm-queue section is the ground truth the 2026-07-08
+  incident could not see: a turn item stuck `processing` means an execution
+  died mid-item; NO pending `watchdogCheck` row plus an open request log means
+  the thread has no internal recovery scheduled (the companion covers this).
+- An open request past the watchdog ceiling (~3 minutes by default) with
+  `executing: false` is dead, full stop. `diag revive` finalizes it as
+  `execution_lost` and auto-resumes within the resume budget (2 per 15 min).
+- Revive is safe on healthy threads: the assessment re-reads state before
+  acting, so a live execution always wins.
+- The same data drives the UI: Thread Settings → Watchdog card shows the
+  companion's last check-ins and has a "Run check now" button (= revive).
+
+### HTTP equivalents (for scripts)
+
+- `GET /api/diagnostics` → `{ warnings, runtime: { builderVersion, … } }`
+- `GET /api/threads/:id/diagnostics` → execution flags, open logs, alarm queue,
+  message-queue depth, watchdog history
+- `POST /api/threads/:id/revive` → one watchdog assessment, acted on, returned
+
+All three are gated by the `logs` permission on hosted deployments.
+
+---
+
 ## Implementation checking
 
 When you edit `agents/`, `prompts/`, `models/`, `tools/`, `hooks/`, or `worker/`, validate before claiming the change is done.