@byok-sdk/client 0.1.0

package/dist/adapters/codex/codex-adapter.d.ts

@@ -0,0 +1,97 @@
+import type { TaskOfferPayload } from '@byok-sdk/protocol';
+import { type RuntimeAdapter, type RuntimeCapabilities, type RuntimeDetectResult, type RuntimeEnvironmentRequirements, type Session, type TaskContext } from '../../types';
+import { type ResolvedBin } from './resolve-bin';
+import { type SpawnFn } from './process-runner';
+export interface CodexAdapterOptions {
+    /** Override bin resolution — tests substitute the fake-codex fixture script. */
+    resolveBin?: () => ResolvedBin;
+    /** Override process spawning — tests substitute a fake spawn. */
+    spawnFn?: SpawnFn;
+}
+/**
+ * `RuntimeAdapter` for the OpenAI Codex CLI (`codex exec --json`), the M2-b
+ * counterpart to `../pi/pi-adapter.ts`. Every empirical claim in this file
+ * and its sibling modules (`events.ts`, `permission-mapping.ts`,
+ * `process-runner.ts`) was driven live against the real installed `codex-cli
+ * 0.144.5` in a scratch directory before being encoded — repeating the pi
+ * adapter's own M0-3 discipline ("docs lied and shipped a nonexistent flag")
+ * independently found the exact same bug class on codex:
+ *
+ *   - `codex exec --help` documents `-a`/`--ask-for-approval`; the real
+ *     parser rejects it outright on `codex exec` ("unexpected argument").
+ *   - `-s`/`--sandbox` works on a fresh `codex exec` but is rejected outright
+ *     on `codex exec resume` (whose own --help correctly omits it).
+ *   - `codex exec resume` does NOT auto-inherit the sandbox mode a session
+ *     was originally started with — a read-only-started session's write
+ *     SUCCEEDED on a bare resume with no sandbox override re-passed,
+ *     silently falling back to this machine's own ambient config default.
+ *   - This task's own brief assumed SIGINT for `interrupt()`; empirically,
+ *     `codex exec` ignores SIGINT entirely (a 60s `sleep` ran to completion
+ *     despite SIGINT at t=4s) — SIGTERM is used instead (confirmed to work:
+ *     immediate exit, no orphaned children, thread stays resumable after).
+ *
+ * See `./permission-mapping.ts` and `./process-runner.ts` for the full
+ * per-finding writeups (sandbox scope, network, approval model, resume
+ * mechanics, stdin handling).
+ *
+ * Architecture, and how it differs from pi: pi is one long-lived `pi --mode
+ * rpc` process for a whole session's lifetime, driven by a bidirectional
+ * JSONL request/response protocol (`../pi/rpc-client.ts`). `codex exec` has
+ * no such thing — it's a one-shot batch process per turn, prompt in via
+ * argv, JSONL out via stdout, process exits. `CodexSession` here instead
+ * spawns a fresh `CodexProcessRunner` for every turn (the initial `start()`
+ * and every later `followUp()`), and forwards each one's mapped events into
+ * one shared, session-lifetime `AsyncQueue` — the thing `Session.events`
+ * actually exposes. `sessionRef` is codex's own `thread_id`, learned from
+ * `thread.started`, which is reliably the first JSONL line codex ever prints
+ * (confirmed across every empirical capture, fresh starts and resumes
+ * alike) — `runCodexTurn` below awaits specifically for that line before
+ * resolving, mirroring pi's own "resolve a real session id before
+ * constructing the Session, fail closed if you can't" discipline
+ * (`../pi/pi-adapter.ts`'s `resolveFreshSessionId`, finding F8).
+ */
+export declare class CodexAdapter implements RuntimeAdapter {
+    private readonly options;
+    readonly id = "codex";
+    constructor(options?: CodexAdapterOptions);
+    detect(): Promise<RuntimeDetectResult>;
+    /**
+     * `authPresent` without ever reading `~/.codex/auth.json` (credential-
+     * isolation rule, `../../types.ts`): spawns codex's OWN `login status`
+     * subcommand and interprets its human-readable report — the exact
+     * "non-secret signal" this adapter is required to use, and cleaner than
+     * pi's env-var-name check since codex's real credential model (on the
+     * reference machine) is a ChatGPT OAuth session, not an env var.
+     *
+     * Two independently-verified channel gotchas apply here, the "pi lesson"
+     * yet again:
+     *   - `codex login status`'s human-readable "Logged in using ChatGPT"
+     *     message prints on STDERR, not stdout (the opposite-channel
+     *     counterpart of pi's own `--version`-goes-to-stderr surprise) — both
+     *     streams are checked here for exactly that reason.
+     *   - The NOT-logged-in message/exit-code shape was deliberately never
+     *     empirically tested: this machine has a real, live ChatGPT login, and
+     *     running `codex logout` to observe the negative case would have
+     *     broken that login for the rest of this session/machine. The match
+     *     below is intentionally conservative (`/logged in (using|with)/i`,
+     *     not a bare `"logged in"` substring) specifically because a bare
+     *     substring check would false-positive on a plausible negative message
+     *     like "Not logged in" (itself containing the substring "logged in").
+     *     This is a documented, known gap — flagged for M2-c / a follow-up
+     *     empirical pass on a logged-out machine, not asserted as verified.
+     */
+    private probeAuthPresent;
+    capabilities(): RuntimeCapabilities;
+    /**
+     * M5: same deliberate posture as the claude adapter (see its own doc
+     * comment) — codex authenticates via its own `codex login`-managed
+     * ChatGPT OAuth session (`probeAuthPresent` above), not an env var, so
+     * there is no credential env var this adapter needs forwarded; env-based
+     * API-key passthrough remains a separate, pending product decision. No
+     * `baseNames` either: nothing in this adapter reads a codex-specific
+     * config-discovery variable (e.g. `CODEX_HOME`) today.
+     */
+    environmentRequirements(): RuntimeEnvironmentRequirements;
+    start(task: TaskOfferPayload, ctx: TaskContext): Promise<Session>;
+    private resolveBin;
+}

package/dist/adapters/codex/events.d.ts

@@ -0,0 +1,41 @@
+import type { AgentEvent } from '@byok-sdk/protocol';
+import type { CodexRawEvent } from './process-runner';
+/**
+ * `codex exec --json` event catalog, empirically captured (raw JSONL frames,
+ * not inferred from docs) driving the real installed `codex-cli 0.144.5`
+ * across: plain chat, file writes (`apply_patch`-style), shell commands,
+ * network attempts, sandbox denials, an invalid-model API error, and a
+ * SIGTERM-killed-then-resumed thread. Two nesting levels: top-level frames
+ * (`thread.started`, `turn.started`, `item.started`, `item.completed`,
+ * `turn.completed`, `turn.failed`, and a top-level `error` distinct from any
+ * item), and — inside `item.started`/`item.completed` — a nested `item.type`
+ * (`agent_message`, `command_execution`, `file_change`, `error`).
+ *
+ * `thread.started` (always the first line codex ever prints, both for a
+ * fresh `codex exec` and for `codex exec resume`) is deliberately NOT
+ * handled here — it's consumed directly by `../codex-adapter.ts`'s
+ * `runCodexTurn` to resolve `Session.sessionRef` before this mapper ever
+ * sees a line, mirroring how pi's adapter resolves a fresh session id via
+ * `get_state` before constructing its `Session` (`../pi/pi-adapter.ts`'s
+ * `resolveFreshSessionId`). It's still listed in
+ * {@link ROUTINE_CODEX_EVENT_TYPES} for defensiveness, in case it were ever
+ * unexpectedly seen again mid-stream.
+ *
+ * No case here ever produces `{type: 'needs_approval'}` — deliberately, not
+ * an oversight. `codex exec` (this build) has no wire-visible signal for it
+ * at all: a sandbox-denied action under any approval policy resolves
+ * internally with no pause an external caller could ever answer — confirmed
+ * empirically (a `sandbox_mode=read-only` write attempt, and separately an
+ * `approval_policy=untrusted` shell command outside the sandbox's own
+ * trusted-command allowlist, both either just ran when the sandbox allowed
+ * it or were silently auto-denied when it didn't, narrated only as a normal
+ * `agent_message` — never a distinct event this mapper could hook). See
+ * `../codex-adapter.ts`'s `resolveApproval`, which throws rather than
+ * pretending to support a resume path that cannot exist on the wire.
+ */
+export declare function mapCodexEventToAgentEvents(evt: CodexRawEvent, workspaceDir: string): AgentEvent[];
+/** Top-level codex event types with no `AgentEvent` equivalent, by design (not "not yet handled") — kept in sync with the switch cases above sharing this comment. Used only for observability, mirroring pi's `ROUTINE_PI_EVENT_TYPES`: `codex-adapter.ts`'s per-line pump only records a frame as genuinely unmapped (`unmappedFrameKey` + a one-time console.warn) when it maps to an empty array AND its type isn't in this set. */
+export declare const ROUTINE_CODEX_EVENT_TYPES: ReadonlySet<string>;
+export declare function isRoutineCodexEvent(evt: CodexRawEvent): boolean;
+/** Diagnostic key for unmapped-frame accounting: for `item.*` frames, folds in the nested `item.type` (e.g. `"item.completed:reasoning"`) so a never-seen item shape is distinguishable from a never-seen top-level type. */
+export declare function unmappedFrameKey(evt: CodexRawEvent): string;

package/dist/adapters/codex/permission-mapping.d.ts

@@ -0,0 +1,107 @@
+import type { PermissionPolicy } from '@byok-sdk/protocol';
+export interface CodexPermissionMapping {
+    ok: boolean;
+    /** `-c key=value` args (as separate argv entries, e.g. `['-c', 'sandbox_mode=read-only']`) to append to `codex exec`/`codex exec resume`. Only meaningful when `ok` is true. */
+    args: string[];
+    /** Present when `ok` is false. */
+    reason?: string;
+}
+/**
+ * Map an effective {@link PermissionPolicy} to `codex exec`/`codex exec
+ * resume` CLI args, fail-closed. Empirically grounded against the real
+ * installed `codex exec --json` (`codex-cli 0.144.5`) — every claim below was
+ * driven live in a scratch directory before being encoded here, exactly like
+ * the pi adapter's own M0-3 findings (`../pi/permission-mapping.ts`), and the
+ * same class of "the CLI's own --help lies" bug showed up again independently
+ * (see the confirm/plan case below).
+ *
+ * - Uses `-c sandbox_mode=<value>` (a config-override key), NEVER the `-s`/
+ *   `--sandbox` CLI flag, and NEVER `-a`/`--ask-for-approval`:
+ *     - `-s`/`--sandbox` works on a fresh `codex exec` but is REJECTED
+ *       outright ("error: unexpected argument '-s' found") on `codex exec
+ *       resume` — confirmed against the real binary, not inferred from
+ *       --help (which lists `-s` for `exec` but, correctly for once, omits
+ *       it entirely from `resume`'s own --help).
+ *     - `-a`/`--ask-for-approval` is documented in `codex exec --help`
+ *       itself, yet REJECTED outright by `codex exec`'s real arg parser
+ *       ("error: unexpected argument '-a' found") — a second, independent
+ *       instance of the exact doc/binary mismatch class the pi adapter's own
+ *       `--session-id`/`--exclude-tools` findings already hit. Never used.
+ *     - `-c sandbox_mode=...` was confirmed empirically to produce the
+ *       IDENTICAL restriction as `-s` on a fresh `exec` (a read-only-sandbox
+ *       write attempt fails the same way either way), and to also work on
+ *       `resume` (where `-s` cannot be used at all) — so this one mechanism
+ *       is used everywhere, for both a fresh start and every later resume,
+ *       instead of switching mechanisms depending on call site.
+ *     - CRITICAL: `codex exec resume` does NOT auto-inherit the sandbox mode
+ *       the session was originally started with. Empirically confirmed: a
+ *       session started with `sandbox_mode=read-only` (which correctly
+ *       denied a write on its first turn) had that SAME write SUCCEED on a
+ *       later `codex exec resume` with no sandbox flag re-passed — silently
+ *       falling back to this machine's own ambient `~/.codex/config.toml`
+ *       default. This is exactly the "silently widens" failure this whole
+ *       mapping exists to prevent, so this adapter re-pins
+ *       `-c sandbox_mode=...` (and `-c approval_policy=never`, see below) on
+ *       *every* invocation — the initial `start()` AND every `followUp()` —
+ *       never relying on "it was already set once."
+ * - `auto` -> `sandbox_mode=workspace-write`. Empirically, this permits
+ *   writes inside the given cwd (the task workspace) AND the OS temp dir
+ *   (e.g. `/tmp`/`$TMPDIR`) — NOT strictly confined to the workspace, a
+ *   real, non-obvious scope worth knowing about (confirmed: a shell write to
+ *   `/tmp/...` succeeds even though it's outside `ctx.workspaceDir`; a write
+ *   to `$HOME` is correctly denied with a clean "operation not permitted",
+ *   not a hang or silent no-op).
+ * - `readonly` -> `sandbox_mode=read-only`. Empirically denies every write —
+ *   both `apply_patch`-style file edits and shell-redirection writes — with
+ *   an immediate, clean, non-interactive denial (real stderr: "writing is
+ *   blocked by read-only sandbox; rejected by user approval settings").
+ *   Never a hang, never a silent bypass.
+ * - `confirm` / `plan` are NOT expressible and fail closed. `codex exec` has
+ *   no interactive approval channel at all in this build — confirmed two
+ *   independent ways: (1) the flag that would request one (`-a`/
+ *   `--ask-for-approval`) is rejected outright by the real parser (see
+ *   above); (2) even reaching the underlying setting via the `-c
+ *   approval_policy=...` config-key path (which IS accepted), a
+ *   sandbox-denied action under a non-`never` policy resolves the "ask"
+ *   *internally* with no wire-visible pause and no way for an external
+ *   caller to answer it: it just auto-denies, and the model narrates the
+ *   denial as a normal `agent_message` — there is no `needs_approval`-
+ *   equivalent signal anywhere in the `--json` stream to map to (see
+ *   `../codex/events.ts`'s module doc comment). `plan` has no dedicated
+ *   codex equivalent either (no plan-only/no-exec CLI mode exists on this
+ *   build). Rather than pretend either is supported, both fail closed here —
+ *   the same posture as pi's own `confirm`/`plan` rejection.
+ * - `network: true` is NOT expressible and fails closed. The one config key
+ *   that should enable network under `workspace-write`
+ *   (`sandbox_workspace_write.network_access=true`) was tested three times
+ *   against the real binary — including a pure `-c`-only invocation with no
+ *   `-s` flag mixed in, ruling out CLI-flag/config-table interference as the
+ *   cause — and never restored real network access: a `curl` to a live host
+ *   still failed every time, though its failure mode shifted from a
+ *   DNS-level block (exit 6, "Could not resolve host") to a data-level block
+ *   (exit 56, "Failure receiving network data"), hinting the override does
+ *   *something* internally but not enough to trust as a real grant. A
+ *   control run under `sandbox_mode=danger-full-access` confirmed network
+ *   genuinely works from this environment (HTTP 200), so the gap is in this
+ *   specific override on this codex build, not the test methodology. This
+ *   adapter never silently proceeds without the grant it was asked for, so
+ *   `network: true` is rejected rather than quietly running with no network
+ *   and no explanation. `network: false`/unset needs no special handling:
+ *   both sandbox modes this adapter ever selects have NO network by default
+ *   (confirmed empirically for both `read-only` and plain `workspace-write`)
+ *   — the safe case is also the default case, so nothing to enforce.
+ * - `allowTools`/`denyTools` are NOT expressible and fail closed when
+ *   non-empty. `codex exec` has no verified per-tool allow/deny surface —
+ *   only the coarse `sandbox_mode` dial — unlike pi's real `--tools`/
+ *   `--no-tools`. Rather than silently drop a requested tool restriction,
+ *   this rejects it outright.
+ * - `approval_policy=never` is pinned unconditionally on every `ok: true`
+ *   result, for the same "never trust the ambient default" reason as
+ *   `sandbox_mode` above: a fresh `codex exec` invoked with NO sandbox/
+ *   approval flags at all on the reference machine successfully ran a live
+ *   network `curl` with zero prompting — proof this machine's own
+ *   `~/.codex/config.toml` default is more permissive than anything this
+ *   adapter should ever grant implicitly. Every invocation pins both keys
+ *   explicitly so behavior never depends on the end user's own codex config.
+ */
+export declare function mapPermissionPolicyToCodexArgs(policy: PermissionPolicy): CodexPermissionMapping;

package/dist/adapters/codex/process-runner.d.ts

@@ -0,0 +1,86 @@
+import { spawn } from 'node:child_process';
+export type SpawnFn = typeof spawn;
+/**
+ * One parsed line of `codex exec --json` / `codex exec resume --json`
+ * output. Field shapes vary by `type` (see `./events.ts`'s module doc
+ * comment for the empirically-captured catalog), so this stays a loose bag
+ * rather than a full discriminated union, mirroring `PiRpcMessage` in
+ * `../pi/rpc-client.ts`.
+ */
+export interface CodexRawEvent {
+    type: string;
+    [key: string]: unknown;
+}
+export interface CodexProcessOptions {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    spawnFn?: SpawnFn;
+    /** Called once per parsed JSONL line, in arrival order. */
+    onEvent: (evt: CodexRawEvent) => void;
+}
+/**
+ * Spawns and streams ONE `codex exec` / `codex exec resume` invocation — i.e.
+ * exactly one turn.
+ *
+ * Unlike pi (a single long-lived RPC server process for a whole session's
+ * lifetime — see `../pi/rpc-client.ts`), `codex exec` is a one-shot batch
+ * process per turn with no persistent request/response channel: it takes its
+ * prompt as an argv positional, streams JSONL to stdout for the one turn
+ * it's running, and exits. `../codex-adapter.ts`'s `CodexSession` constructs
+ * a fresh `CodexProcessRunner` for every turn (the initial `start()` and
+ * every later `followUp()`), forwarding each one's lines into the same
+ * long-lived event queue.
+ *
+ * stdin is deliberately never piped to the child (`stdio: ['ignore', 'pipe',
+ * 'pipe']`): `codex exec --help` documents that a piped, non-TTY stdin is
+ * read and appended to the prompt as a `<stdin>` block even when a prompt was
+ * ALSO given as an argv positional, and empirically every single real
+ * invocation made while building this adapter logged "Reading additional
+ * input from stdin..." on stderr regardless of whether a prompt argument was
+ * given. Leaving `stdio: ['pipe', ...]` open for stdin and never closing it
+ * risks codex blocking on that read forever — exactly the hang class this
+ * task was built to avoid (the pi adapter's own `agent_end`/`agent_settled`
+ * mismatch left a task stuck `Running` forever in the M0/M1 GLM run).
+ * `'ignore'` presents immediate EOF instead, which was verified live with a
+ * dedicated Node `child_process` probe before this was written: no hang,
+ * clean completion at normal model latency. This adapter never needs to
+ * SEND codex anything over stdin — there is no in-band steer/approval
+ * protocol (see `../codex-adapter.ts`'s `steer`/`resolveApproval`).
+ */
+export declare class CodexProcessRunner {
+    private readonly child;
+    private readonly onEvent;
+    private buffer;
+    private readonly stderrRing;
+    private closed;
+    private exitCode;
+    private exitSignal;
+    private readonly closedPromise;
+    private resolveClosed;
+    constructor(options: CodexProcessOptions);
+    private finishClosing;
+    /** Resolves once the child process has fully exited (both exit and stdio-flush guaranteed — see the `close` listener above). Never rejects. */
+    waitClosed(): Promise<void>;
+    get isClosed(): boolean;
+    /**
+     * Best-effort teardown. SIGTERM on POSIX: SIGINT was empirically confirmed
+     * to be silently ignored by `codex exec` (a real, direct test — a 60s
+     * shell `sleep` ran to full, unaffected completion despite SIGINT sent at
+     * t=4s) — a genuine, evidence-based correction to this task's own initial
+     * assumption ("interrupt: SIGINT — POSIX here"). SIGTERM was separately
+     * confirmed to terminate the process immediately (exit code 143) with no
+     * orphaned child processes left behind (the shell command it was running
+     * died with it), and — critically — the underlying codex thread remained
+     * cleanly resumable afterward via `codex exec resume` (no corruption from
+     * killing mid-turn). `taskkill /T /F` on Windows, mirroring
+     * `../pi/rpc-client.ts`'s own cross-platform convention.
+     */
+    kill(): void;
+    /** Builds a descriptive error folding in the exit code/signal and the stderr tail — mirrors `PiRpcClient.buildExitError`'s reasoning: a post-mortem on a failed start/resume should never need separately re-running codex by hand with a raw JSONL logger to learn why. */
+    buildExitError(context: string): Error;
+    private onData;
+    private parseLine;
+    private onStderr;
+}

package/dist/adapters/codex/resolve-bin.d.ts

@@ -0,0 +1,25 @@
+export interface ResolvedBin {
+    command: string;
+    source: 'env' | 'path';
+}
+/**
+ * Resolve the codex CLI executable.
+ *
+ * Unlike pi (bundled as an npm optionalDependency — see
+ * `../pi/resolve-bin.ts`), the real OpenAI Codex CLI (empirically `codex-cli
+ * 0.144.5` on the machine this adapter was built/verified against, installed
+ * at a plain PATH location — not inside this repo's `node_modules`) is not
+ * published as an npm package this SDK could sensibly depend on: it's a
+ * standalone global install (native installer / `npm i -g @openai/codex` /
+ * homebrew, depending on platform and version). There is no package-relative
+ * resolution to attempt, so this is simpler than pi's version: an explicit
+ * override for tests, else a bare PATH lookup.
+ *
+ * `BYOK_CODEX_BIN` overrides PATH lookup — substituting the fake-codex test
+ * fixture, exactly like `BYOK_PI_BIN` does for pi. The `byok-agent` CLI bin
+ * only ever constructs `new CodexAdapter()` with no options (mirroring
+ * `createDaemon`'s pi wiring), so an out-of-process substitution (e.g. a
+ * future e2e harness swapping in a fake binary ahead of a real codex install)
+ * has no other seam to use.
+ */
+export declare function resolveCodexBin(): ResolvedBin;

package/dist/adapters/pi/events.d.ts

@@ -0,0 +1,58 @@
+import type { AgentEvent } from '@byok-sdk/protocol';
+import type { PiRpcMessage } from './rpc-client';
+/**
+ * ROOT CAUSE of the 2026-07-16 live GLM run's "finding #2" hang (task stuck
+ * `Running` forever after pi streamed its final answer; pi process alive,
+ * idle, no sockets, only stdio pipes): this mapper used to listen for a pi
+ * event type `agent_settled` to know a whole run had finished. That type
+ * does not exist anywhere in the real, installed
+ * `@earendil-works/pi-coding-agent@0.74.2` package — not in its bundled
+ * `docs/rpc.md`, not in `dist/modes/rpc/rpc-types.d.ts`, not in
+ * `pi-agent-core`'s own `AgentEvent` union (`dist/types.d.ts`), and not
+ * observed even once across live probes against real GLM traffic (raw JSONL
+ * frame capture). The real "whole run is done, pi is idle again" signal is
+ * `agent_end` — confirmed both by `pi-agent-core`'s own doc comment ("
+ * `agent_end` is the last event emitted for a run... The agent becomes idle
+ * only after those listeners finish") and empirically: a live run's frame
+ * sequence ended `...turn_end (tool call), ..., turn_end (final text),
+ * agent_end` with nothing further arriving even after an 8s idle-grace
+ * window. Because this switch had no `agent_end` case, it fell to
+ * `default: return undefined` — silently dropped — so `task-runner.ts`'s
+ * `pump()` loop never saw a `turn_end` `AgentEvent` and blocked forever on
+ * the next one. This repo's own fixture (`fake-pi.mjs`) masked the bug for
+ * the whole M0/M1 test suite by emitting a fictional `agent_settled` frame
+ * of its own alongside the real `agent_end` one — fixed alongside this
+ * change (see fake-pi.mjs's doc comment).
+ *
+ * `agent_end` (not pi's own per-LLM-turn `turn_end`) is what maps to our
+ * `turn_end`: a single pi prompt can produce several internal turns (tool
+ * round-trips, each ending its own real `turn_end`); only once the whole
+ * run is settled (no auto-retry, compaction-retry, or queued continuation
+ * left) is the task actually done. Forwarding pi's own `turn_end` 1:1 would
+ * emit multiple confusing `turn_end`s for what the daemon must treat as one
+ * task — empirically confirmed: a single-tool-call prompt produced two real
+ * `turn_end` frames (one after the tool call, one after the final text) and
+ * exactly one `agent_end`.
+ *
+ * Returns undefined for pi messages with no protocol equivalent (session/
+ * compaction/retry bookkeeping — see `ROUTINE_PI_EVENT_TYPES` below —
+ * extension UI dialogs, which never reach here at all in production since
+ * `PiRpcClient` answers them itself before they'd ever be queued as an
+ * event; see rpc-client.ts).
+ */
+export declare function mapPiMessageToAgentEvent(msg: PiRpcMessage): AgentEvent | undefined;
+/**
+ * Pi RPC message types that are routine, expected, and deliberately have no
+ * `AgentEvent` equivalent (kept in sync with the switch cases above sharing
+ * this comment). Used only for observability: `PiSession`'s event iterator
+ * (pi-adapter.ts) calls `PiRpcClient.recordUnmappedFrame` for any message
+ * type that maps to `undefined` AND isn't in this set — i.e. traffic nobody
+ * has ever told this adapter to expect. That distinction is what makes a
+ * regression like this file's root-cause bug (`agent_end` going unhandled)
+ * self-diagnosing: a warning fires the first time the new/renamed settle
+ * event shows up, instead of the daemon just quietly hanging. `default`-only
+ * unknowns (a type not listed in the switch at all) are equally "not
+ * routine" and get flagged the same way — this set exists so *routine*
+ * traffic doesn't also trip that alarm on every single task.
+ */
+export declare const ROUTINE_PI_EVENT_TYPES: ReadonlySet<string>;

package/dist/adapters/pi/permission-mapping.d.ts

@@ -0,0 +1,46 @@
+import type { PermissionPolicy } from '@byok-sdk/protocol';
+export interface PiPermissionMapping {
+    ok: boolean;
+    /** CLI args to append to `pi --mode rpc ...`. Only meaningful when `ok` is true. */
+    args: string[];
+    /** Present when `ok` is false. */
+    reason?: string;
+}
+/**
+ * Map an effective {@link PermissionPolicy} to `pi --mode rpc` CLI args,
+ * fail-closed. Empirically grounded (see the M0-3 report):
+ *
+ * - `auto` / `readonly` are expressible via `--tools` / `--no-tools`.
+ * - `confirm` and `plan` are NOT expressible: pi ships no built-in per-call
+ *   approval gate and explicitly "skips ... plan mode" (README); both exist
+ *   only as example third-party extensions (`examples/extensions/
+ *   permission-gate.ts`, `examples/extensions/plan-mode/`), which is
+ *   out-of-scope, speculative surface for M0.
+ * - `network: false` is NOT expressible: pi has no network sandbox for its
+ *   bash tool ("Pi does not include a built-in sandbox" — docs/security.md).
+ *   `network: true` or unset proceeds, since nothing needs enforcing then.
+ *
+ * Workspace confinement is NOT a pi flag — the caller spawns pi with
+ * `cwd: ctx.workspaceDir`, the daemon-created per-task directory.
+ *
+ * SECOND SELF-DISCOVERED FINDING, same class as the pi-adapter.ts
+ * `--session-id` bug (this task, while hardening argv validation):
+ * `--exclude-tools` — what `denyTools` used to map to — is ALSO not a real
+ * pi CLI flag. Confirmed against real pi 0.74.2: `pi --mode rpc
+ * --exclude-tools bash` → `Error: Unknown option: --exclude-tools`, exit
+ * code 1, before any model call — and it's absent from both `pi --help`'s
+ * own listing and the CLI's actual arg parser (`dist/cli/args.js`), which
+ * recognizes only `--tools`/`-t`, `--no-tools`/`-nt`, `--no-builtin-tools`/
+ * `-nbt` for tool control. This crashed EVERY real pi invocation for any
+ * policy with a non-empty `denyTools`, unconditionally — never caught by
+ * this repo's own test suite for the exact same reason as the
+ * `--session-id` bug (`fake-pi.mjs` never validated argv; fixed alongside
+ * this change). pi has no "start from the default set, minus these" flag at
+ * all — `--tools` always REPLACES the active set wholesale — so `denyTools`
+ * is now resolved to an equivalent allowlist in-process: readonly mode
+ * intersects with `READONLY_TOOLS` (as before), any other mode starts from
+ * an explicit `allowTools` or pi's own `DEFAULT_ACTIVE_TOOLS`, and
+ * `denyTools` is subtracted from that resolved set before it's ever handed
+ * to pi as a single `--tools`/`--no-tools` pair of args.
+ */
+export declare function mapPermissionPolicyToPiArgs(policy: PermissionPolicy): PiPermissionMapping;

package/dist/adapters/pi/pi-adapter.d.ts

@@ -0,0 +1,29 @@
+import type { TaskOfferPayload } from '@byok-sdk/protocol';
+import { type RuntimeAdapter, type RuntimeCapabilities, type RuntimeDetectResult, type RuntimeEnvironmentRequirements, type Session, type TaskContext } from '../../types';
+import { type ResolvedBin } from './resolve-bin';
+import { type SpawnFn } from './rpc-client';
+export interface PiAdapterOptions {
+    /** Override bin resolution — tests substitute the fake-pi fixture script. */
+    resolveBin?: () => ResolvedBin;
+    /** Override process spawning — tests substitute a fake spawn. */
+    spawnFn?: SpawnFn;
+}
+export declare class PiAdapter implements RuntimeAdapter {
+    private readonly options;
+    readonly id = "pi";
+    constructor(options?: PiAdapterOptions);
+    detect(): Promise<RuntimeDetectResult>;
+    capabilities(): RuntimeCapabilities;
+    /**
+     * M5: pi authenticates to its ~30 supported providers via env-var API
+     * keys — `detect()`'s own `authPresent` probe above checks this identical
+     * list — so these MUST keep flowing into pi's spawned process or pi auth
+     * breaks entirely. `KNOWN_PROVIDER_ENV_VARS` above is the single source
+     * of truth, reused here rather than duplicated. No `baseNames`: nothing
+     * in this adapter or `rpc-client.ts` reads a pi-specific config-discovery
+     * variable beyond the platform baseline (`daemon/environment.ts`).
+     */
+    environmentRequirements(): RuntimeEnvironmentRequirements;
+    start(task: TaskOfferPayload, ctx: TaskContext): Promise<Session>;
+    private resolveBin;
+}

package/dist/adapters/pi/resolve-bin.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The pi coding-agent CLI's real npm package name.
+ *
+ * IMPORTANT (empirically verified 2026-07-16, see the M0-3 report): the name
+ * `@mariozechner/pi` — the identifier this task was originally briefed with —
+ * is NOT the coding agent. On npm it resolves to an unrelated "CLI tool for
+ * managing vLLM deployments on GPU pods" (bin: `pi-pods`). The real coding
+ * agent was `@mariozechner/pi-coding-agent`, which is now itself deprecated
+ * in favor of this package (same maintainers: badlogic, mitsuhiko), as of
+ * literally the day before this was written. `package.json` pins the
+ * `legacy-node20` dist-tag (0.74.2) rather than `latest` (0.80.7), because
+ * `latest` requires Node >=22.19 while this SDK's baseline is Node >=20;
+ * both versions were empirically confirmed to speak the identical RPC-mode
+ * frame shapes this adapter depends on.
+ */
+export declare const PI_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
+export interface ResolvedBin {
+    command: string;
+    source: 'package' | 'path';
+}
+/**
+ * Resolve the pi CLI executable. Prefers the optionalDependency installed
+ * alongside @byok-sdk/client (guarantees a known-good, version-matched build);
+ * falls back to whatever `pi` is on PATH so users with a pre-existing global
+ * pi install still work even when the optionalDependency didn't install.
+ *
+ * `BYOK_PI_BIN` overrides both of the above when set: `PiAdapterOptions.resolveBin`
+ * is the injectable seam for in-process tests, but the `byok-agent` CLI bin
+ * only ever constructs `new PiAdapter()` with no options (see `createDaemon`),
+ * so an out-of-process substitution (e.g. examples/basic's e2e run swapping
+ * in the fake-pi fixture ahead of a real pi install) has no other seam to use.
+ *
+ * Deliberately does NOT use `createRequire(...).resolve()`: this package is
+ * pure ESM with no `require` export condition (`exports["."]` only offers
+ * `import`), so CJS-style resolution fails outright with
+ * `ERR_PACKAGE_PATH_NOT_EXPORTED` — empirically confirmed, not a hypothetical.
+ * It also does NOT resolve the `./package.json` subpath directly (also not
+ * exported by this package); instead it resolves the package's main entry
+ * via `import.meta.resolve` and walks up parent directories to find the
+ * package root (identified by a `package.json` whose `name` matches), which
+ * is robust to `dist/` layout changes and to whether `./package.json` is
+ * ever exported.
+ */
+export declare function resolvePiBin(): ResolvedBin;

package/dist/adapters/pi/rpc-client.d.ts

@@ -0,0 +1,101 @@
+import { spawn } from 'node:child_process';
+export type SpawnFn = typeof spawn;
+/**
+ * A pi RPC-mode message: either a `{type:"response", id, success, ...}` reply
+ * to a command we sent, or an unsolicited event/extension-UI-request. Field
+ * shapes vary by `type` (see docs.md / this task's live probes), so this
+ * stays a loose bag rather than a full discriminated union — M0 only needs
+ * a handful of fields off of each.
+ */
+export interface PiRpcMessage {
+    type: string;
+    id?: string;
+    [key: string]: unknown;
+}
+export interface PiRpcClientOptions {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    spawnFn?: SpawnFn;
+}
+/**
+ * JSONL request/response + event-stream client for `pi --mode rpc`.
+ *
+ * Framing per pi's own docs/rpc.md: strict JSONL, LF (`\n`) as the only
+ * record delimiter (a trailing `\r` is stripped; this deliberately does NOT
+ * use `node:readline`, which pi's docs call out as non-compliant because it
+ * also splits on U+2028/U+2029 — valid inside JSON strings).
+ *
+ * Responses are correlated by `id`, never by arrival order: empirically,
+ * pi's responses do not preserve request order (an immediate parse-failure
+ * response can overtake a slower in-flight command's response).
+ */
+export declare class PiRpcClient {
+    private readonly child;
+    private buffer;
+    private nextId;
+    private readonly pending;
+    private readonly eventQueue;
+    private closed;
+    private exitError;
+    /** Bounded tail of recent stderr lines — pi discarded this entirely before (nothing ever read `child.stderr`), which is exactly why finding #1 (`Error: Unknown option: --session-id`, exit 1) had to be root-caused by hand instead of reading it off a thrown error. See `buildExitError`. */
+    private readonly stderrRing;
+    /** Count of pi RPC message types `PiSession` (pi-adapter.ts) has told us have no `AgentEvent` mapping and aren't routine bookkeeping — see `recordUnmappedFrame`. */
+    private readonly unmappedFrameCounts;
+    constructor(options: PiRpcClientOptions);
+    /** Send a command, resolved with its correlated `response` message. */
+    send(command: Record<string, unknown> & {
+        type: string;
+        id?: string;
+    }): Promise<PiRpcMessage>;
+    /** Every non-response, non-`extension_ui_request` line — the latter is answered directly by this client (see `respondToExtensionUiRequest`) and never enqueued. */
+    get events(): AsyncIterable<PiRpcMessage>;
+    /**
+     * Record a pi RPC message `type` that `PiSession` (pi-adapter.ts) decided
+     * has no `AgentEvent` mapping and isn't routine bookkeeping (see
+     * `events.ts`'s `ROUTINE_PI_EVENT_TYPES`) — i.e. genuinely unexpected
+     * traffic. Logs once per distinct type (not per occurrence, so a
+     * repeating unmapped type can't spam stdout); the running tally is also
+     * folded into this client's exit-time error message (`buildExitError`) so
+     * a post-mortem on a failed/hung task has it without needing separate log
+     * scraping. This is the exact mechanism that would have turned this
+     * task's root-cause hang (`agent_end` arriving with no mapping) into a
+     * one-line, immediate warning instead of a silent stall.
+     */
+    recordUnmappedFrame(type: string): void;
+    /** Best-effort teardown. SIGTERM on POSIX; `taskkill /T /F` on Windows to also reap child processes pi itself spawned (e.g. bash). */
+    kill(): void;
+    private onData;
+    private onLine;
+    /**
+     * Answer pi's extension-UI blocking protocol headlessly (rpc.md's
+     * "Extension UI Protocol"). Fail-closed policy, stated explicitly because
+     * it's a security-relevant default, not an incidental one: this NEVER
+     * approves or picks a value on the caller's behalf — every dialog method
+     * (`select`/`confirm`/`input`/`editor`) gets `{cancelled: true}`, the one
+     * response shape rpc.md documents as valid for all four uniformly
+     * ("Dismiss any dialog method... the extension receives `undefined` (for
+     * select/input/editor) or `false` (for confirm)"). An extension asking
+     * e.g. `confirm("Delete everything?")` gets a firm decline, never a
+     * guessed approval — this adapter has no human in the loop to ask, and
+     * silently approving would defeat any extension that uses these dialogs
+     * specifically as a permission gate. Fire-and-forget methods
+     * (`notify`/`setStatus`/`setWidget`/`setTitle`/`set_editor_text`) get no
+     * reply at all — sending one would itself violate rpc.md ("Responses are
+     * sent for dialog methods only").
+     */
+    private respondToExtensionUiRequest;
+    private onStderr;
+    /**
+     * finding #1 ("bad flag → instant exit", e.g. the `--session-id`/
+     * `--exclude-tools` bugs this task fixes): the daemon used to report only
+     * `pi process exited (code=1, signal=null)` — accurate but useless for
+     * diagnosing *why* without re-running pi by hand with a raw JSONL logger,
+     * exactly as this task's own root-cause investigation had to. Folding in
+     * the stderr tail and any unmapped-frame tally makes that self-diagnosing
+     * from the thrown error alone.
+     */
+    private buildExitError;
+    private onClosed;
+}