feat(runtime): session-setup hook (register_session_setup)

[seanturner83]

Summary

Adds a generic extension point — register_session_setup(callback) — that runs a coroutine once per scan, right after the sandbox session is ready and before the agent's first turn, with the live session and the scan config.

from strix.runtime.session_manager import register_session_setup

async def prepare(session, scan_config):
    await session.exec(...)          # prepare in-sandbox state the agent will use

register_session_setup(prepare)

It mirrors the existing backends.register_backend and agents.factory.register_agent_tools seams.

Why

A @function_tool runs runner-side and only receives a RunContextWrapper — never the sandbox session. So any setup that must session.exec inside the container before the agent starts (build an index against the freshly-materialised target, warm a cache, install a probe) currently has nowhere to hook. This adds that one seam.

run_strix_scan invokes the registered callbacks after create_or_reuse returns and before the root agent is built — the window where the target is materialised but analysis hasn't begun.

Contract

• Callbacks are awaited in registration order.
• Best-effort: an exception in a callback is logged and swallowed, so an optional setup step can never fail the scan.
• Duplicate registrations are ignored (repeated imports don't double-run).

Motivating consumer

A SCIP code-graph addon (separate) that indexes the materialised target in-sandbox and copies the index out for its runner-side query tools. But the hook is deliberately generic — cache warming, sidecar readiness probes, etc. — and adds nothing to the default path (no callbacks registered → a no-op).

Tests

tests/test_session_setup_hooks.py: registration order, session/config passthrough, dedup, failure-is-swallowed, empty-registry no-op. +142 lines across session_manager.py (registry + invoker), runner.py (invocation), and the test.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR adds a session-setup extension point before agent execution. The main changes are:

• A process-wide registry for asynchronous setup callbacks.
• Ordered, deduplicated callback execution with best-effort error handling.
• Runner integration after sandbox creation and before agent construction.
• Unit tests for registry behavior and callback failures.

Confidence Score: 4/5

The cached-session resume path can repeat non-idempotent setup and needs a fix before merging.

• Initial setup runs at the intended point before agent construction.
• Callback ordering, duplicate registration, and failure isolation are covered.
• Resuming a cached scan invokes the hooks again against an already-prepared sandbox.

strix/core/runner.py

Important Files Changed

Filename	Overview
strix/core/runner.py	Invokes setup hooks at the intended lifecycle point, but repeats them when resuming a cached session.
strix/runtime/session_manager.py	Adds the callback registry, duplicate suppression, ordered execution, and per-callback error isolation.
tests/test_session_setup_hooks.py	Covers direct registry behavior but not initial-run versus resume lifecycle behavior.

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
strix/core/runner.py:218
**Resume Repeats Session Setup**

When a scan resumes in the same process, `create_or_reuse` returns its cached sandbox and this unconditional call runs every setup callback against that already-prepared session. Non-idempotent hooks can start duplicate services, append configuration twice, or fail after partial changes; the swallowed exception then lets the resumed agent continue with invalid sandbox state. Track setup completion with the cached session so each materialized session is prepared only once.

_{Reviews (1): Last reviewed commit: "feat(runtime): session-setup hook (regis..." | Re-trigger Greptile}

[greptile-apps]

Resume Repeats Session Setup

When a scan resumes in the same process, create_or_reuse returns its cached sandbox and this unconditional call runs every setup callback against that already-prepared session. Non-idempotent hooks can start duplicate services, append configuration twice, or fail after partial changes; the swallowed exception then lets the resumed agent continue with invalid sandbox state. Track setup completion with the cached session so each materialized session is prepared only once.

Prompt To Fix With AI

This is a comment left during a code review.
Path: strix/core/runner.py
Line: 218

Comment:
**Resume Repeats Session Setup**

When a scan resumes in the same process, `create_or_reuse` returns its cached sandbox and this unconditional call runs every setup callback against that already-prepared session. Non-idempotent hooks can start duplicate services, append configuration twice, or fail after partial changes; the swallowed exception then lets the resumed agent continue with invalid sandbox state. Track setup completion with the cached session so each materialized session is prepared only once.

How can I resolve this? If you propose a fix, please make it concise.

[seanturner83]

Good catch — fixed in 33eb270.

create_or_reuse caches + reuses the session bundle across in-process resumes (the credential-boundary iteration loop), so the unconditional run_session_setups call re-ran every callback against an already-prepared sandbox. run_session_setups now takes the bundle (not the raw session) and stamps it once setups have run, skipping on reuse — stamped before running so a partial/failed hook can't retry-loop either.

On staleness (since setup-derived state like an index is what this is for): the reused bundle is the same container with the same materialised source, so nothing's stale — the code hasn't changed between in-process iterations. A cross-push PR resume runs in a new process against a freshly materialised sandbox → new bundle → setups re-run → the index is rebuilt against the new code. So skipping on reuse never serves a stale artifact.

Added tests: run-once-on-reuse, fresh-bundle-reruns-afresh, and marked-done-even-when-a-callback-fails.