Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 60 additions & 0 deletions src/relay/agent-hook-cached-pane-status.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
import type { AgentHookEventPayload } from '../shared/agent-hook-listener/listener-event'
import type { AgentHookSource } from '../shared/agent-hook-relay'

export type CachedPaneEnvelopeMeta = { source: AgentHookSource; env?: string; version?: string }

export type CachedPaneReplaySelection = {
event: AgentHookEventPayload
meta: CachedPaneEnvelopeMeta
}

/**
* Chooses which cached pane statuses a reconnecting client may be re-told about, and drops the rest.
*
* Two panes are refused, for opposite reasons:
* - a pane whose surface has been retired — the tab is gone, so replaying its status would hand the
* client a live agent pane nobody owns, which is what drives an auto-resume onto a transcript an
* orphaned agent is still writing;
* - a pane whose envelope metadata is missing — the status cache and the metadata map are populated
* and cleared in lockstep, so a key present in one and not the other is drift. Skip rather than
* guess a source that mis-tags the replay downstream.
*/
export function selectReplayableCachedPanes(input: {
cachedByPaneKey: ReadonlyMap<string, AgentHookEventPayload>
metaByPaneKey: ReadonlyMap<string, CachedPaneEnvelopeMeta>
isPaneSurfaceRetired: (paneKey: string) => boolean
dropPane: (paneKey: string) => void
}): CachedPaneReplaySelection[] {
const selected: CachedPaneReplaySelection[] = []
// Snapshot: dropping a retired pane mutates the map being read.
for (const [paneKey, event] of Array.from(input.cachedByPaneKey.entries())) {
if (input.isPaneSurfaceRetired(paneKey)) {
input.dropPane(paneKey)
continue
}
const meta = input.metaByPaneKey.get(paneKey)
if (meta) {
selected.push({ event, meta })
}
}
return selected
}

/** How many panes keep a cached status. Bounds a long-lived relay's per-pane state. */
export const MAX_CACHED_PANES = 256

/** Drop the longest-idle panes until the cache is back under its cap. Map insertion order is
* recency (writers delete-then-set), so the first key is always the oldest. */
export function evictCachedPanesOverCap(
cachedByPaneKey: ReadonlyMap<string, unknown>,
dropPane: (paneKey: string) => void,
maxPanes: number = MAX_CACHED_PANES
): void {
while (cachedByPaneKey.size > maxPanes) {
const oldest = cachedByPaneKey.keys().next().value
if (oldest === undefined) {
return
}
dropPane(oldest)
}
}
206 changes: 206 additions & 0 deletions src/relay/agent-hook-retired-pane-suppression.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,206 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { mkdtempSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { RelayAgentHookServer } from './agent-hook-server'
import { RelayAgentHookRuntime } from './relay-agent-hook-runtime'
import { RetiredPaneSurfaceRegistry } from './retired-pane-surfaces'
import type { AgentHookRelayEnvelope } from '../shared/agent-hook-relay'
import { makePaneKey } from '../shared/stable-pane-id'
import type { PtyHandler, PtySurfaceRetiredListener } from './pty-handler'
import type { RelayDispatcher } from './dispatcher'

const LEAF_ID = '11111111-1111-4111-8111-111111111111'
const PANE_KEY = makePaneKey('tab-1', LEAF_ID)

function hookMeta(paneKey: string): string {
return Buffer.from([paneKey, 'tab-1', '', 'wt-1', 'remote', '1'].join('\x1f')).toString('base64')
}

async function postHook(
server: RelayAgentHookServer,
paneKey: string,
prompt = 'hi'
): Promise<number> {
const { port, token } = server.getCoordinates()
const res = await fetch(`http://127.0.0.1:${port}/hook/claude`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Orca-Agent-Hook-Token': token,
'X-Orca-Agent-Hook-Meta-Encoding': 'base64',
'X-Orca-Agent-Hook-Meta': hookMeta(paneKey)
},
body: JSON.stringify({ hook_event_name: 'UserPromptSubmit', prompt })
})
return res.status
}

type CachedPanes = { state: { lastStatusByPaneKey: Map<string, unknown> } }

function cachedPaneKeys(server: RelayAgentHookServer): string[] {
return [...(server as unknown as CachedPanes).state.lastStatusByPaneKey.keys()]
}

describe('relay hook forwarding for a retired pane surface', () => {
let dir: string
let servers: RelayAgentHookServer[]

beforeEach(() => {
dir = mkdtempSync(join(tmpdir(), 'relay-retired-pane-'))
servers = []
})

afterEach(() => {
for (const server of servers) {
server.stop()
}
rmSync(dir, { recursive: true, force: true })
})

async function startServer(options: {
forward: (envelope: AgentHookRelayEnvelope) => void
isPaneSurfaceRetired?: (paneKey: string) => boolean
}): Promise<RelayAgentHookServer> {
const server = new RelayAgentHookServer({ endpointDir: dir, ...options })
servers.push(server)
await server.start({ publishEndpoint: false })
return server
}

it('forwards and caches a post from a pane that still has a tab', async () => {
const retired = new RetiredPaneSurfaceRegistry()
const forward = vi.fn<(envelope: AgentHookRelayEnvelope) => void>()
const server = await startServer({
forward,
isPaneSurfaceRetired: (paneKey) => retired.isRetired(paneKey)
})

expect(await postHook(server, PANE_KEY)).toBe(204)

expect(forward).toHaveBeenCalledTimes(1)
expect(cachedPaneKeys(server)).toEqual([PANE_KEY])
})

it('does not advertise an orphan agent whose tab was closed', async () => {
const retired = new RetiredPaneSurfaceRegistry()
const forward = vi.fn<(envelope: AgentHookRelayEnvelope) => void>()
const server = await startServer({
forward,
isPaneSurfaceRetired: (paneKey) => retired.isRetired(paneKey)
})

expect(await postHook(server, PANE_KEY, 'first')).toBe(204)
forward.mockClear()

// The user closes the tab; the agent inside the pane shell survives and keeps posting.
retired.retire(PANE_KEY)
expect(await postHook(server, PANE_KEY, 'orphan')).toBe(204)

expect(forward).not.toHaveBeenCalled()
// The pre-close status must go too, or a reconnect replays it as a live agent pane.
expect(cachedPaneKeys(server)).toEqual([])
})

it('does not replay a cached status for a pane retired after it was cached', async () => {
const retired = new RetiredPaneSurfaceRegistry()
const forward = vi.fn<(envelope: AgentHookRelayEnvelope) => void>()
const server = await startServer({
forward,
isPaneSurfaceRetired: (paneKey) => retired.isRetired(paneKey)
})

expect(await postHook(server, PANE_KEY)).toBe(204)
forward.mockClear()
retired.retire(PANE_KEY)

expect(server.replayCachedPayloadsForPanes()).toBe(0)
expect(forward).not.toHaveBeenCalled()
expect(cachedPaneKeys(server)).toEqual([])
})

it('forwards again once the pane key is bound by a new PTY', async () => {
const retired = new RetiredPaneSurfaceRegistry()
const forward = vi.fn<(envelope: AgentHookRelayEnvelope) => void>()
const server = await startServer({
forward,
isPaneSurfaceRetired: (paneKey) => retired.isRetired(paneKey)
})

retired.retire(PANE_KEY)
expect(await postHook(server, PANE_KEY, 'orphan')).toBe(204)
expect(forward).not.toHaveBeenCalled()

retired.restore(PANE_KEY)
expect(await postHook(server, PANE_KEY, 'reopened')).toBe(204)

expect(forward).toHaveBeenCalledTimes(1)
})

it('an embedder that supplies no retirement source keeps forwarding everything', async () => {
const forward = vi.fn<(envelope: AgentHookRelayEnvelope) => void>()
const server = await startServer({ forward })

expect(await postHook(server, PANE_KEY)).toBe(204)

expect(forward).toHaveBeenCalledTimes(1)
expect(cachedPaneKeys(server)).toEqual([PANE_KEY])
})
})

describe('RelayAgentHookRuntime wiring', () => {
let dir: string

beforeEach(() => {
dir = mkdtempSync(join(tmpdir(), 'relay-retired-pane-runtime-'))
})

afterEach(() => {
rmSync(dir, { recursive: true, force: true })
})

it('routes hook admission through the PTY handler and drops the cache on retirement', async () => {
const retired = new RetiredPaneSurfaceRegistry()
const surfaceRetiredListeners: PtySurfaceRetiredListener[] = []
const ptyHandler = {
addEnvAugmenter: vi.fn(),
setExitListener: vi.fn(),
setSurfaceRetiredListener: vi.fn((listener: PtySurfaceRetiredListener | null) => {
if (listener) {
surfaceRetiredListeners.push(listener)
}
}),
isPaneSurfaceRetired: (paneKey: string) => retired.isRetired(paneKey)
} as unknown as PtyHandler
// Zero attached clients: publishAgentHookEnvelope returns before touching any sink.
const dispatcher = {
onRequest: vi.fn(),
activeClientIds: () => [] as number[]
} as unknown as RelayDispatcher

const runtime = new RelayAgentHookRuntime(
dispatcher,
ptyHandler,
join(dir, 'relay.sock'),
join(dir, 'hooks')
)
await runtime.start()
try {
const server = (runtime as unknown as { hookServer: RelayAgentHookServer }).hookServer
expect(await postHook(server, PANE_KEY)).toBe(204)
expect(cachedPaneKeys(server)).toEqual([PANE_KEY])

// The PTY handler retires the surface: the runtime must drop the cached status immediately,
// rather than waiting for a process exit a surviving shell never produces.
retired.retire(PANE_KEY)
expect(surfaceRetiredListeners).toHaveLength(1)
surfaceRetiredListeners[0]({ id: 'pty-1', paneKey: PANE_KEY })
expect(cachedPaneKeys(server)).toEqual([])

expect(await postHook(server, PANE_KEY, 'orphan')).toBe(204)
expect(cachedPaneKeys(server)).toEqual([])
} finally {
runtime.stop()
}
})
})
48 changes: 30 additions & 18 deletions src/relay/agent-hook-server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,11 +41,13 @@ import {
import { buildRelayHookPtyEnv, defaultEndpointDir } from './agent-hook-endpoint-coordinates'
import { buildRelayHookEnvelope, hookBodyEnv, hookBodyVersion } from './agent-hook-envelope-build'
import { AgentHookResultRetryScheduler } from './agent-hook-result-retry-scheduler'
import {
evictCachedPanesOverCap,
selectReplayableCachedPanes
} from './agent-hook-cached-pane-status'

export type RelayHookForward = (envelope: AgentHookRelayEnvelope) => void

const MAX_CACHED_PANES = 256

export type RelayHookServerOptions = {
/** Where to put endpoint.env / endpoint.cmd. Defaults to `$HOME/.orca-relay/agent-hooks`. */
endpointDir?: string
Expand All @@ -56,6 +58,13 @@ export type RelayHookServerOptions = {
/** Preferred bind port. WSL relay passes the Windows listener's port so env-sourced client coords stay truthful; falls back to :0 if occupied. Defaults to :0. */
preferredPort?: number
forward: RelayHookForward
/**
* True when the host has been told this pane's tab is gone and no PTY has re-bound the paneKey.
* Posts from such a pane come from a process the user already closed, so they describe no surface
* any client owns. Defaults to "never retired", which is the pre-existing behaviour — a listener
* with no PTY handler behind it (the WSL relay) keeps forwarding everything.
*/
isPaneSurfaceRetired?: (paneKey: string) => boolean
}

export type RelayHookServerStartOptions = {
Expand All @@ -81,6 +90,7 @@ export class RelayAgentHookServer {
{ source: AgentHookSource; env?: string; version?: string }
>()
private forward: RelayHookForward
private isPaneSurfaceRetired: (paneKey: string) => boolean
private fixedToken: string | undefined
private preferredPort: number
private portFallbackApplied = false
Expand All @@ -93,6 +103,7 @@ export class RelayAgentHookServer {
this.fixedToken = options.token
this.preferredPort = options.preferredPort ?? 0
this.forward = options.forward
this.isPaneSurfaceRetired = options.isPaneSurfaceRetired ?? (() => false)
this.retryScheduler = new AgentHookResultRetryScheduler({
state: this.state,
env: this.env,
Expand Down Expand Up @@ -198,19 +209,18 @@ export class RelayAgentHookServer {
/** Request-driven replay: re-forwards each cached paneKey payload as a fresh notification. Forwards are
* issued before the request handler returns, so the response trails all replayed notifications. */
replayCachedPayloadsForPanes(): number {
let count = 0
for (const [paneKey, event] of this.state.lastStatusByPaneKey.entries()) {
const meta = this.lastEnvelopeMetaByPaneKey.get(paneKey)
// Why: invariant — status-cache keys always have meta; if it drifted, skip rather than guess a source that mis-tags downstream.
if (!meta) {
continue
}
const replayable = selectReplayableCachedPanes({
cachedByPaneKey: this.state.lastStatusByPaneKey,
metaByPaneKey: this.lastEnvelopeMetaByPaneKey,
isPaneSurfaceRetired: this.isPaneSurfaceRetired,
dropPane: (paneKey) => this.clearPaneState(paneKey)
})
for (const { event, meta } of replayable) {
this.forward(
buildRelayHookEnvelope(event, meta.source, meta.env, meta.version, { isReplay: true })
)
count++
}
return count
return replayable.length
}

/** Drop a paneKey's cached entries on PTY exit so a terminated pane can't resurface as a ghost event on reconnect. */
Expand Down Expand Up @@ -301,6 +311,14 @@ export class RelayAgentHookServer {
version?: string,
options: { isReplay?: boolean } = {}
): void {
// Why: this post came from a process still running inside a pane whose tab the user closed.
// Caching or forwarding it makes every connected client advertise a live, resumable agent pane
// that no tab owns — the advertisement that ends up auto-typing a second `--resume` onto a
// transcript the orphan is still writing (#12447). Drop the stale cache with it.
if (this.isPaneSurfaceRetired(event.paneKey)) {
this.clearPaneState(event.paneKey)
return
Comment on lines +318 to +320

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🔎 Supported by static analysis

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect whether retry scheduling can re-enter applyEvent after a retired post.
rg -n -C 10 '\bscheduleAssistantMessageRetry\s*\(|\bscheduleCodexSubagentPoll\s*\(|\bapplyEvent\s*\(' src/relay

Repository: stablyai/orca

Length of output: 12088


🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- repository conventions ---'
find /tmp/coderabbit-repo-knowledge/stablyai-orca-89dc44e4 -maxdepth 2 -type f -name '*.md' -print \
  -exec sh -c 'echo "--- $1"; head -80 "$1"' _ {} \;

printf '%s\n' '--- agent hook server ---'
sed -n '300,355p' src/relay/agent-hook-server.ts

printf '%s\n' '--- retry scheduler ---'
sed -n '1,215p' src/relay/agent-hook-result-retry-scheduler.ts

printf '%s\n' '--- pane-state cleanup and scheduler clearing ---'
rg -n -C 8 '\bclearPaneState\b|\bclearAssistantMessageRetry\b|\bclearCodexSubagentPoll\b|new AgentHookResultRetryScheduler' src/relay src

Repository: stablyai/orca

Length of output: 50370


🏁 Script executed:

#!/bin/bash
set -euo pipefail
log=/tmp/coderabbit-shell-logs/shell-output-Q1J5hU

for marker in '--- agent hook server ---' '--- retry scheduler ---' '--- pane-state cleanup and scheduler clearing ---'; do
  echo "$marker"
  line=$(rg -n -F -- "$marker" "$log" | head -1 | cut -d: -f1 || true)
  if [ -n "$line" ]; then
    end=$((line + 230))
    sed -n "${line},${end}p" "$log"
  else
    echo "marker not found"
  fi
done

Repository: stablyai/orca

Length of output: 35310


🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- cache cleanup ---'
rg -n -C 12 'function clearPaneCacheState|const clearPaneCacheState|export .*clearPaneCacheState|clearPaneCacheState' src/shared src/relay

printf '%s\n' '--- codex subagent predicate ---'
rg -n -C 16 'function hasCodexTranscriptSubagents|const hasCodexTranscriptSubagents|export .*hasCodexTranscriptSubagents|hasCodexTranscriptSubagents' src/shared src/relay

printf '%s\n' '--- request admission and scheduler calls ---'
sed -n '270,292p' src/relay/agent-hook-server.ts
sed -n '220,233p' src/relay/agent-hook-server.ts

Repository: stablyai/orca

Length of output: 40887


Stop assistant retry scheduling for retired panes.

applyEvent() clears the pane state and returns, but handleRequest() still calls scheduleAssistantMessageRetry(). That method can arm a timer from the request body. If the pane key is restored before the callback, the callback can apply the orphan event. Skip this scheduler call when the pane is retired.

}
if (event.payload.state !== 'done' || event.payload.lastAssistantMessage) {
this.retryScheduler.clearAssistantMessageRetry(event.paneKey)
}
Expand All @@ -313,13 +331,7 @@ export class RelayAgentHookServer {
this.state.lastStatusByPaneKey.set(event.paneKey, cachedEvent)
this.lastEnvelopeMetaByPaneKey.delete(event.paneKey)
this.lastEnvelopeMetaByPaneKey.set(event.paneKey, { source, env, version })
while (this.state.lastStatusByPaneKey.size > MAX_CACHED_PANES) {
const oldest = this.state.lastStatusByPaneKey.keys().next().value
if (oldest === undefined) {
break
}
this.clearPaneState(oldest)
}
evictCachedPanesOverCap(this.state.lastStatusByPaneKey, (key) => this.clearPaneState(key))
this.forward(buildRelayHookEnvelope(event, source, env, version, options))
}

Expand Down
Loading
Loading