* Strip Grok user query wrapper from status prompts
* Document PR evidence image handling
* Surface Grok final responses in agent status
* Harden Grok status result extraction
* feat(agent-dashboard): persist hook status across Orca restart
Hydrates the hook server's per-pane lastStatusByPaneKey from
userData/agent-hooks/last-status.json before binding the HTTP listener,
mirrors mutations to disk via a 250ms trailing debounce, and flushes
synchronously on stop(). Renderer dismissals fan out a new
agentStatus:drop IPC so the on-disk file evicts the entry and a
relaunch cannot resurrect it. Adds a bounded bootstrap queue in
useIpcEvents so events replayed by setListener() during window creation
are not dropped while App.tsx is still hydrating tabsByWorktree.
Gated on settings.experimentalAgentDashboard. Done, blocked, and quiet
working rows now all survive across restart.
Co-authored-by: Orca <help@stably.ai>
* fix(agent-dashboard): harden hook persistence IPC and gate-off deletion
Address review findings on the retention-restart branch:
- Wrap agentStatus:getSnapshot and agentStatus:drop IPC handlers in
try/catch so a throw cannot surface as an unhandled invoke rejection
(silent startup-hydration failure) or crash main from a fire-and-
forget listener.
- runStatusPersist no longer permanently suppresses gate-off deletion
retries on transient unlink errors (e.g. EPERM); deletedOnDisable
now flips only on success or ENOENT.
- Tighten tests: stale-version-hydrate now asserts the warn message
content; getSnapshot test uses toEqual; drop-handler test rejects
null/{}/[] in addition to the prior bad inputs.
Co-authored-by: Orca <help@stably.ai>
* fix(agent-dashboard): bound on-disk hydrate growth and reject tabId/paneKey drift
- Drop hydrate entries older than 7 days (HYDRATE_MAX_AGE_MS) so stale
rows from worktrees archived weeks ago do not pile up forever. PTY-
teardown eviction handles closed panes; the TTL covers daemon-restored
PTYs that never re-attach and crash-recovery paths.
- Reject hydrate entries whose `tabId` field diverges from the paneKey's
tab segment. Cheap defensive add against future renamer/shape drift.
Doc updated to move TTL out of the follow-ups list (now in scope).
Tests: new "drops hydrate entries older than the TTL cutoff" and "drops
a hydrate entry whose tabId disagrees with the paneKey prefix"; existing
hydrate fixtures now use a `recentTs()` helper instead of fixed 2023
timestamps.
Co-authored-by: Orca <help@stably.ai>
* fix(agent-dashboard): post-review polish on hook status persistence
Apply review-fix corrections on the agent-dashboard restart-persistence
work:
- Split dropStatusEntry from clearPaneState so renderer-driven dismiss
IPC no longer wipes lastPromptByPaneKey/lastToolByPaneKey for a
still-alive pane.
- Validate paneKey shape at the IPC boundary (isValidPaneKey).
- Let getSnapshot errors propagate instead of silently returning [] —
matches the renderer's existing .catch and avoids masking a broken
persistence path.
- Trust main's authoritative timing.stateStartedAt unconditionally on
same-state pings; fall back to existing only when timing is absent.
- Use strict < on the snapshot/live updatedAt guard so two events in
the same millisecond don't drop the second one (a <= guard regressed
two existing slice tests).
- Don't reset snapshotRequestedForReadyWindow in the catch handler;
combined with the per-store-update subscriber it would retry-storm
on persistent IPC failure.
- scheduleStatusPersist now resets the timer on each call (true
trailing-edge debounce) instead of leading-edge throttle.
- Fix doc references that named clearPaneState in dismiss/IPC context
where the implementation uses dropStatusEntry; add type-level JSDoc
on AgentStatusIpcPayload.
109/109 in-scope tests pass.
Co-authored-by: Orca <help@stably.ai>
* fix(agent-dashboard): clean stale on-disk entries during hydrate
- Defensive `lastStatusByPaneKey.clear()` at top of `hydrateLastStatusFromDisk` keeps repeat-start() calls from silently merging prior-session state.
- When sanitize drops entries (drift, TTL, schema), log a single `[agent-hooks] last-status hydrate dropped N entries (kept M)` warn and synchronously rewrite the file. Pre-fix, stale entries stayed on disk until a fresh hook event triggered a debounced write — users who hadn't run an agent in 8+ days would re-drop the same entries every cold boot.
- Prime `lastWrittenJson` from the raw on-disk bytes (instead of re-serializing) when hydration is lossless — robust against future shape drift in `serializeStatusFile`.
- `LAST_STATUS_FILE_VERSION = 2` comment now records why v1 was skipped (in-flight branch shape).
- IPC test mock uses `vi.importActual` for `isValidPaneKey` so it stays in sync with the real validator.
Co-authored-by: Orca <help@stably.ai>
* fix(agent-dashboard): persist acknowledgedAgentsByPaneKey across restart
Without this, agent rows the user already visited come back bold every relaunch now that the rows themselves survive restart (per docs/agent-dashboard-retention-restart.md). Hydrate sanitizes input field-by-field (rejects null/non-object/array, prototype-pollution keys, non-finite/non-positive values) and applies a 7-day TTL paralleling HYDRATE_MAX_AGE_MS in agent-hooks/server.ts so hard-quit/crash paths can't grow the persisted map forever.
Co-authored-by: Orca <help@stably.ai>
* docs(agent-dashboard): drop in-tree retention/restart design doc
Doc was a working artifact for this branch; the rationale lives in commit
history and the comments next to the persistence/hydrate code. Scrubs the
three call-site references that named it.
Co-authored-by: Orca <help@stably.ai>
---------
Co-authored-by: Orca <help@stably.ai>
* feat(agent-hooks): introduce relay wire envelope + connectionId stamping
Adds the shared `agent-hook-relay.ts` module with the `agent.hook` JSON-RPC
notification envelope, the `agent_hook.requestReplay` /
`agent_hook.installPlugins` method names, and the
`ORCA_FEATURE_REMOTE_AGENT_HOOKS` flag helper. Promotes `AgentHookSource` to
`shared/` so the relay can import it without dragging Electron in.
Threads a `connectionId: string | null` field through `AgentHookEventPayload`,
the `agentStatus:set` IPC contract, and the renderer-bound preload listener.
Local hook posts stamp `null`; the relay-forwarded path will stamp from `mux`
identity in a later commit. Renderer uses the stamp for stale-event filtering
when an SSH connection tears down with notifications still in flight.
See docs/design/agent-status-over-ssh.md §1, §5, §8 (commit #1).
Co-authored-by: Orca <help@stably.ai>
* refactor(agent-hooks): extract shared listener; add relay-side adapter
Extracts the listener internals (request parsing, payload normalization,
endpoint-file writing, per-CLI extractors, warn-once Sets, slowloris timer
helper, request size cap, paneKey caches) from `src/main/agent-hooks/server.ts`
into a new transport-agnostic `src/shared/agent-hook-listener.ts`. The shared
module uses only Node builtins (no Electron) so it is safe to import from
`src/relay/`.
Adds `src/relay/agent-hook-server.ts` — a thin HTTP-loopback adapter that
wires the shared listener to a `forward(envelope)` callback so `relay.ts` can
re-emit each parsed payload as an `agent.hook` JSON-RPC notification on the
existing SshChannelMultiplexer. The adapter owns:
- 127.0.0.1:0 socket + bearer-token auth, identical shape to the local server
- per-paneKey last-payload cache + replayCachedPayloadsForPanes() for the
request-driven replay path used after `--connect` reattach (see §5 Path 3)
- clearPaneState(paneKey) for PTY-exit eviction (symmetric with local server)
- buildPtyEnv() / endpoint-file writing for relay-spawned PTYs
Orca's `AgentHookServer` is now a ~200-LoC adapter over the shared listener
that owns the IPC fanout, listener replay, and `ingestRemote(envelope, connId)`
entry point that bypasses the HTTP path for relay-forwarded events.
See docs/design/agent-status-over-ssh.md §3, §8 (commit #2).
Co-authored-by: Orca <help@stably.ai>
* fix(preload): expose connectionId on agentStatus.onSet type
src/preload/index.ts already passes through `connectionId?: string | null`
from main, but the PreloadApi declaration in api-types.ts was missing the
field. Align the type with the runtime contract so renderer call sites
can read connectionId without an `as` cast.
Co-authored-by: Orca <help@stably.ai>
* fix(agent-hooks): harden ingestRemote + relay replay; review-driven cleanup
- ingestRemote: re-run normalizeAgentStatusPayload at trust boundary;
trim+validate connectionId/paneKey/tabId/worktreeId
- relay: preserve source/env/version through replay via sidecar map;
drop sourceFromAgentType fallback that mis-tagged unknown agents
- shared listener: exhaustive switch+never on AgentHookSource dispatch
chains; extractPromptText returns trimmed values; export MAX_PANE_KEY_LEN
- preload: tighten connectionId from optional to required (always sent)
- main IPC: reorder spread so explicit envelope fields win on collision
Co-authored-by: Orca <help@stably.ai>
* chore(docs): drop agent-status-over-ssh design doc from PR
The design RFC was useful for authoring this PR series but doesn't belong
in-tree — keeping it here would freeze line-number references and design
prose against future churn. Folding it into the PR description instead.
Co-authored-by: Orca <help@stably.ai>
* chore(agent-hooks): widen ingestRemote type for env/version (PR2 prep)
Declares `env?: string` and `version?: string` on the `ingestRemote` envelope
parameter so PR2 only needs to add the `warnOnHookEnvOrVersionMismatch`
callsite, not also widen the type. The fields are forwarded verbatim from
the agent CLI POST body on the remote and let Orca's warn-once cross-build
/ dev-vs-prod diagnostics fire identically on remote-sourced events.
Type-only addition; no runtime consumer in this PR.
Co-authored-by: Orca <help@stably.ai>
---------
Co-authored-by: Orca <help@stably.ai>
* feat(cursor): first-class Cursor CLI agent status via ~/.cursor/hooks.json
Give cursor-agent the same hook-driven status pipeline Claude/Codex/Gemini/
OpenCode already use so working/done/permission transitions show the proper
sidebar spinner instead of falling back to title heuristics — cursor-agent
only sets its OSC title to the literal string "Cursor Agent" during a turn,
so title-based detection cannot see working→done transitions on its own.
- New CursorHookService installs a managed shell script and registers it
under ~/.cursor/hooks.json for beforeSubmitPrompt, preToolUse, postToolUse,
postToolUseFailure, beforeShellExecution, beforeMCPExecution, stop, and
afterAgentResponse (the subset that marks turn boundaries and surfaces
in-flight tool context).
- AgentHookServer gains a /hook/cursor route and a normalizeCursorEvent
mapping the camelCase cursor events to working/done/waiting, with tool
previews for preToolUse/shell/MCP and lastAssistantMessage from
afterAgentResponse. stop with status != "completed" surfaces as
interrupted (matches Claude's is_interrupt behavior).
- cursorHookService joins the startup install loop alongside Claude/Codex/
Gemini, and the IPC status handler is exposed via preload.
- 'cursor' added to WellKnownAgentType and to the renderer's
WELL_KNOWN_LABELS so the dashboard prints "Cursor" rather than the raw
'cursor' id.
Verified end-to-end against a real cursor-agent 2026.04.17-787b533 binary:
a mock hook receiver pointed at by ~/.cursor/hooks.json observes
beforeSubmitPrompt → stop for a live turn.
Co-authored-by: Orca <help@stably.ai>
* feat(cursor): wire hook events into sidebar spinner + unread pipeline
The initial hook wiring landed behind AGENT_DASHBOARD_ENABLED, which is
still false. That meant cursor-agent panes lit up no spinner and no
unread indicator — cursor's native OSC title stays literally "Cursor
Agent" across a turn, so title-based detection cannot transition.
Plumb cursor's hook stream into the existing, shipped title-tracker
pipeline (the one Claude/Codex/Pi drive working/idle/unread off) by
synthesizing OSC title sequences in the main-process hook listener:
- `working` → `\x1b]0;⠋ Cursor Agent\x07` (braille prefix → working)
- `waiting` → `\x1b]0;Cursor - action required\x07\x07`
- `done` → `\x1b]0;Cursor ready\x07\x07`
The two trailing BELs on done/waiting are load-bearing: the unread badge
keys off BEL (0x07 outside any OSC), and cursor-agent emits none on its
own. The first BEL is consumed as the OSC terminator; the second fires
the bell detector.
Also treats the bare native "Cursor Agent" title as a no-op in
`detectAgentStatusFromTitle` so cursor's own per-turn re-emissions cannot
stomp our synthesized working state back to idle. `isClaudeAgent`
excludes cursor-bearing braille titles so the Claude prompt-cache timer
doesn't fire for cursor panes.
Scope: the hook server + cursor install run unconditionally now, but
Claude/Codex/Gemini installs stay gated behind AGENT_DASHBOARD_ENABLED,
so only cursor events flow through the pipeline. No dashboard surface
is turned on.
Verified end-to-end in Electron (dev build): launched cursor-agent via
the Cursor menu item, submitted three prompts (including a tool-use
turn reading package.json). Observed tab title flip to "Cursor ready"
on done, and the tab + worktree both transitioned to unread
(unreadTerminalTabs[tabId]=true, worktree.isUnread=true). Parallel
Claude Code pane untouched.
Co-authored-by: Orca <help@stably.ai>
* fix(cursor): animate spinner frames + filter bare native title so the spinner doesn't go solid mid-turn
cursor-agent re-emits its bare "Cursor Agent" OSC title on every internal
redraw, which was stomping the single synthesized "⠋ Cursor Agent" frame
in runtimePaneTitlesByTabId within milliseconds and flipping the sidebar
dot back to solid. Two-part fix:
- Main: drive an 80ms Pi-style braille spinner from the cursor hook
channel, keyed by paneKey, torn down on pty exit via a new
registerPaneKeyTeardownListener hook in ipc/pty.
- Renderer: drop bare "Cursor Agent" titles in pty-transport so cursor's
native re-emissions cannot overwrite the synthesized working/idle
titles.
Co-authored-by: Orca <help@stably.ai>
---------
Co-authored-by: Orca <help@stably.ai>
Brennan BensonandOrca
Neil