fast-connection-executors

name

fast-connection-executors

description

Rules for touching packages/agensis-cli/src/connectionExecutors.mjs or executor.mjs — the pooled Claude Agent SDK / codex app-server connections that keep one warm session per silo alive across jobs instead of spawning a subprocess per turn. Use this before adding a new option that affects how a session is opened (cwd, model, permissionMode, hostFolders, leanCli, mcp config), before touching the SDK pump loop or the codex JSON-RPC message handler, before changing idle-timeout or session-close logic, and before changing the "confirmedUnavailable" fallback-to-subprocess detection in createPrimaryExecutor. This subsystem pools long-lived state keyed by silo, so bugs here are stale-session or leaked-process bugs that only show up on a SECOND job, not the first.

Fast connection executors (pooled Claude SDK / codex app-server)

connectionExecutors.mjs keeps ONE warm connection per silo (sessionKey = workspace+handle) alive across many daemon jobs, instead of cli.mjs's LocalExecutor which spawns a fresh claude/codex process per job. Both pooled executors and LocalExecutor implement the identical {status, stdout, stderr, error} + onData contract so executor.mjs's createPrimaryExecutor can swap between them transparently (including automatic fallback). Keep these rules in mind whenever editing either file:

1. Any new connection-affecting option MUST go into connectionFingerprint()

Sessions are reused only while connectionFingerprint(opts) stays identical (see ensureSession in both executors: if (session.fingerprint === fingerprint && !session.closed) return session). If you add a new opt that changes how the SDK query() or codex app-server thread/start is configured — a new permission flag, a new MCP field, a new model param — and forget to add it to connectionFingerprint, a job with the new value will silently reuse a stale session built with the OLD value. This bug only shows up on the second job for a silo, never the first (which always creates a fresh session), so it's easy to miss in manual testing.

2. The SDK pump loop must never break the for await

session.pump in createClaudeSdkExecutor deliberately runs for the whole session lifetime, not per turn: for await (const message of query) { ... }. Breaking out of that loop (or letting an early return short-circuit it) calls the async iterator's return(), which tears down the underlying claude process. Turns are completed by calling turn.finish(...), NOT by exiting the loop — the loop keeps running to receive the next queued message on the same process. If you add new message-type handling, add an else if branch inside the existing loop; don't restructure it into a per-turn for await.

3. Idle timers arm only after a turn fully settles

armIdleTimer is called after run() resolves successfully, and clearTimeout(session.idleTimer) is called before starting a turn. If you add a new early-return path out of run() (e.g. a new validation error), make sure it goes through the same finish()/promise-resolution path so the idle timer gets re-armed — an early return that skips armIdleTimer leaves the session's timer cleared forever, so it never self-closes and the process leaks for the life of the daemon.

4. confirmedUnavailable in executor.mjs is sticky for the whole process

createPrimaryExecutor remembers a family (claude/codex) as unavailable the FIRST time an error matches looksLikeUnavailable (Cannot find module|ERR_MODULE_NOT_FOUND|ENOENT|command not found), and every subsequent job for that family goes straight to LocalExecutor for the rest of the daemon's life — it never re-probes. If you add a new error path, make sure its message doesn't accidentally match that regex unless it truly means "not installed on this host" (e.g. don't let a transient ENOENT from an unrelated file operation inside the SDK call propagate through this check — it will permanently disable fast connections for that family until the daemon restarts).

5. Concurrent jobs on one silo queue, they don't race

Both executors serialize run() calls sharing a sessionKey through createKeyedMutex() (withLock). Don't add a code path that reads or mutates sessions.get(sessionKey) outside of run()/ensureSession() — it bypasses the mutex and can race with an in-flight turn on the same session.

6. scrubbedChildEnv must keep stripping secrets from the child process

Every executor that spawns a child process (codex app-server) or passes env into the SDK's query() options routes it through scrubbedChildEnv, which deletes AGENSIS_TOKEN, ANTHROPIC_API_KEY, and ANTHROPIC_AUTH_TOKEN before merging with process.env. If you add a new executor or a new place that builds a child env, reuse this helper rather than hand-rolling the merge — these are the same secrets agensis.mjs scrubs from the coding child elsewhere in the codebase.

Where the tests live

tests/agent-connection-executors.test.cjs and tests/agent-executor.test.cjs cover session reuse per sessionKey, per-silo isolation, and the fallback-to-subprocess path — extend these rather than writing a new test file when changing behavior here.