ai-foreman 1.6.2 → 1.7.1

package/README.md

@@ -110,7 +110,7 @@ What each part does:
 | `--ticket <id>` | `T001` | none | Selects a branch-mode ticket to continue. Repeatable with `--continue`. |
 | `--base <ref>` | `main` / `origin/main` / `HEAD` | current branch or `HEAD` | Base ref for root ticket branches. |
 | `--branch-prefix <prefix>` | `rafi` / `feature` | `rafi` | Prefix for generated ticket branches. |
-| `--max-branch-depth <n>` | `1` / `2` / `3` | `2` | Maximum selected branch stack depth. |
+| `--max-branch-depth <n>` | positive integer | `5` | Maximum selected branch/PR stack depth (root PR is depth 1). |
 
 Auto-detected tracker files:
 
@@ -176,7 +176,7 @@ gh repo view <host>/<owner>/<repo>
 | `--fast` | flag | off | Lower latency. |
 | `-y, --yes` | flag | off | Skips confirmation before builder edits ticket files. |
 
-Use `ai-foreman tickets setup:init` or `setup:update` to save local, Linear, or Jira Cloud ticket sources in `rafi-config.yaml`. Linear imports use `LINEAR_API_KEY`; Jira Cloud imports use `JIRA_EMAIL` and `JIRA_API_TOKEN`. Imported provider payloads are snapshotted under ignored `.tickets/imports/`, and mirrored tickets carry `external_refs`.
+Use `ai-foreman tickets setup:init` or `setup:update` to append local, Linear, or Jira Cloud sources to the project-wide registry in `rafi-config.yaml`. Linear imports use `LINEAR_API_KEY`; Jira Cloud imports use `JIRA_EMAIL` and `JIRA_API_TOKEN`. Credentials are never persisted, and mirrored tickets retain source provenance.
 
 Use `ai-foreman tickets review` to accept, defer, or dismiss pending split/combine/duplicate recommendations rendered in the progress doc.
 

package/dist/adapters/claude.d.ts

@@ -1,6 +1,6 @@
 /** Lazy-load the Claude Agent SDK. Throws an actionable error if not installed. */
 export declare function requireClaudeSDK(): Promise<typeof import("@anthropic-ai/claude-agent-sdk")>;
-import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, TurnResult } from "./types.js";
+import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextUsage, ProviderSettingSwitch, TurnResult } from "./types.js";
 /**
  * Pure function: build the `options` object passed to `query()`.
  * Extracted so tests can assert on the shape without making a live SDK call.
@@ -25,6 +25,7 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private turnSignals;
     private structuredError?;
     private apiErrorStatus?;
+    private compactResult?;
     private pending?;
     private closed;
     static create(opts: BuilderAdapterOptions): Promise<ClaudeAdapter>;
@@ -35,6 +36,9 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     sendTurn(text: string): Promise<TurnResult>;
     private captureStderr;
     sessionId(): string | undefined;
+    compact(): Promise<CompactResult>;
+    contextUsage(): Promise<ContextUsage | undefined>;
+    switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
     events(): AsyncIterable<BuilderEvent>;
     close(): Promise<void>;
 }

package/dist/adapters/claude.js

@@ -55,6 +55,7 @@ export class ClaudeAdapter {
     turnSignals = [];
     structuredError;
     apiErrorStatus;
+    compactResult;
     pending;
     closed = false;
     static async create(opts) {
@@ -142,6 +143,17 @@ export class ClaudeAdapter {
             if (msg.output.length > 0)
                 this.turnSignals.push(...msg.output.map((line) => `auth: ${line}`));
         }
+        else if (msg.type === "system" && msg.subtype === "status") {
+            if (msg.status === "compacting")
+                this.eventQueue.push({ kind: "session-transition", transition: "compacting" });
+            if (msg.compact_result === "success") {
+                this.compactResult = { ok: true };
+                this.eventQueue.push({ kind: "session-transition", transition: "compacted" });
+            }
+            else if (msg.compact_result === "failed") {
+                this.compactResult = { ok: false, error: sanitizeDiagnostics(msg.compact_error ?? "Claude native compaction failed") };
+            }
+        }
         else if (msg.type === "system" && msg.subtype === "api_retry") {
             this.structuredError = msg.error;
             this.apiErrorStatus = msg.error_status;
@@ -210,6 +222,35 @@ export class ClaudeAdapter {
     sessionId() {
         return this._sessionId;
     }
+    async compact() {
+        this.compactResult = undefined;
+        const result = await this.sendTurn("/compact");
+        if (this.compactResult)
+            return this.compactResult;
+        return { ok: false, error: sanitizeDiagnostics(result.text || "Claude did not emit an explicit compact status") };
+    }
+    async contextUsage() {
+        try {
+            const usage = await this.query.getContextUsage();
+            const result = { used: usage.totalTokens, maximum: usage.maxTokens, percentage: usage.percentage };
+            this.eventQueue.push({ kind: "context-usage", ...result });
+            return result;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async switchSettings(settings) {
+        if (settings.effort !== this.opts.effort || settings.fast !== this.opts.fast)
+            return { ok: false, error: "Claude SDK cannot change reasoning/fast controls on an existing transport" };
+        if (settings.model === this.opts.model)
+            return { ok: true };
+        const result = await this.sendTurn(`/model ${settings.model ?? "default"}`);
+        if (result.isError)
+            return { ok: false, error: result.text };
+        this.opts.model = settings.model;
+        return { ok: true };
+    }
     events() {
         return this.eventQueue;
     }

package/dist/adapters/codex.d.ts

@@ -1,47 +1,45 @@
-import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, TurnResult } from "./types.js";
-/** Result of parsing one JSONL line from `codex exec --json` output. */
+import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextUsage, ProviderSettingSwitch, TurnResult } from "./types.js";
 export interface CodexLineResult {
-    /** Events to emit to the BuilderEvent stream. */
     events: BuilderEvent[];
-    /** If set, update the stored session ID to this value. */
     sessionId?: string;
-    /** If set, append this to the turn's accumulated text. */
     text?: string;
 }
-/**
- * Pure function: parse one JSONL event from `codex exec --json` output into
- * structured actions. Exported for unit testing; production code calls this
- * via handleEvent().
- */
+/** Compatibility parser for recorded pre-app-server JSONL fixtures. */
 export declare function parseCodexLine(raw: Record<string, unknown>): CodexLineResult;
-/**
- * Drives Codex CLI as a subprocess. Each sendTurn() spawns `codex exec --json`
- * and reads JSONL from stdout. Session continuity is maintained via the
- * thread_id captured from the first run and passed as `resume <id>` on
- * subsequent turns.
- *
- * NOTE: opts.permission is accepted for interface conformance but is not
- * invoked. Codex manages its own tool sandboxing via --sandbox.
- */
+/** Persistent JSON-RPC controller for one live Codex thread. */
 export declare class CodexAdapter implements BuilderAdapter {
     private readonly opts;
     readonly agent: "codex";
     private readonly eventQueue;
+    private process?;
+    private nextId;
+    private pending;
+    private notificationWaiters;
     private _sessionId?;
-    private _closed;
-    private _activeProc?;
+    private initialized;
+    private closed;
+    private activeText;
+    private usage?;
+    private stderr;
     constructor(opts: BuilderAdapterOptions);
-    /**
-     * Prepend role system text to a turn instruction when `systemPromptAppend` is
-     * set. Codex reads everything from the prompt (no persistent system prompt), so
-     * role guidance must ride along with each turn.
-     */
     buildInstruction(instruction: string): string;
-    /** Build the `codex exec` argument list for the given instruction. */
+    buildAppServerArgs(): string[];
+    /** Deprecated fixture helper. Runtime execution uses only app-server. */
     buildArgs(instruction: string): string[];
-    private buildSkillsAppendix;
     sendTurn(instruction: string): Promise<TurnResult>;
+    compact(): Promise<CompactResult>;
+    contextUsage(): Promise<ContextUsage | undefined>;
+    switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
     sessionId(): string | undefined;
     events(): AsyncIterable<BuilderEvent>;
     close(): Promise<void>;
+    private ensureThread;
+    private threadAttached;
+    private ensureConnection;
+    private request;
+    private write;
+    private handle;
+    private waitFor;
+    private disconnect;
+    private buildSkillsAppendix;
 }

package/dist/adapters/codex.js

@@ -5,195 +5,256 @@ import { createInterface } from "node:readline";
 import { loadSkill } from "special-agents";
 import { AsyncQueue } from "../util/asyncQueue.js";
 import { normalizeRuntimeErrorText } from "../runtimeAuth.js";
-/**
- * Pure function: parse one JSONL event from `codex exec --json` output into
- * structured actions. Exported for unit testing; production code calls this
- * via handleEvent().
- */
+/** Compatibility parser for recorded pre-app-server JSONL fixtures. */
 export function parseCodexLine(raw) {
     const type = raw.type;
-    if (type === "thread.started") {
-        const sessionId = raw.thread_id;
-        return { events: [], sessionId };
-    }
+    if (type === "thread.started")
+        return { events: [], sessionId: raw.thread_id };
     if (type === "item.completed") {
         const item = raw.item;
-        if (!item)
-            return { events: [] };
-        if (item.type === "agent_message") {
-            const text = item.text;
-            if (!text)
-                return { events: [] };
-            return { events: [{ kind: "text", text }], text };
-        }
-        if (item.type === "command_execution") {
-            return {
-                events: [{ kind: "tool", name: "command_execution", input: { command: item.command } }],
-            };
-        }
-        return { events: [] };
-    }
-    if (type === "error") {
-        const msg = raw.error?.message
-            ?? JSON.stringify(raw);
-        return { events: [{ kind: "error", message: msg }] };
+        if (item?.type === "agent_message" && typeof item.text === "string")
+            return { events: [{ kind: "text", text: item.text }], text: item.text };
+        if (item?.type === "command_execution")
+            return { events: [{ kind: "tool", name: "command_execution", input: { command: item.command } }] };
     }
+    if (type === "error")
+        return { events: [{ kind: "error", message: String(raw.error?.message ?? JSON.stringify(raw)) }] };
     return { events: [] };
 }
-/**
- * Drives Codex CLI as a subprocess. Each sendTurn() spawns `codex exec --json`
- * and reads JSONL from stdout. Session continuity is maintained via the
- * thread_id captured from the first run and passed as `resume <id>` on
- * subsequent turns.
- *
- * NOTE: opts.permission is accepted for interface conformance but is not
- * invoked. Codex manages its own tool sandboxing via --sandbox.
- */
+/** Persistent JSON-RPC controller for one live Codex thread. */
 export class CodexAdapter {
     opts;
     agent = "codex";
     eventQueue = new AsyncQueue();
+    process;
+    nextId = 1;
+    pending = new Map();
+    notificationWaiters = new Map();
     _sessionId;
-    _closed = false;
-    _activeProc;
+    initialized = false;
+    closed = false;
+    activeText = [];
+    usage;
+    stderr = "";
     constructor(opts) {
         this.opts = opts;
         this._sessionId = opts.resumeSessionId;
     }
-    /**
-     * Prepend role system text to a turn instruction when `systemPromptAppend` is
-     * set. Codex reads everything from the prompt (no persistent system prompt), so
-     * role guidance must ride along with each turn.
-     */
     buildInstruction(instruction) {
-        return [
-            this.opts.systemPromptAppend,
-            this.buildSkillsAppendix(),
-            instruction,
-        ].filter((part) => Boolean(part)).join("\n\n");
+        return [this.opts.systemPromptAppend, this.buildSkillsAppendix(), instruction]
+            .filter((part) => Boolean(part)).join("\n\n");
     }
-    /** Build the `codex exec` argument list for the given instruction. */
+    buildAppServerArgs() { return ["app-server", "--listen", "stdio://"]; }
+    /** Deprecated fixture helper. Runtime execution uses only app-server. */
     buildArgs(instruction) {
-        const args = [
-            "exec",
-            "--json",
-            "--skip-git-repo-check",
-            "--sandbox",
-            this.opts.sandboxMode ?? "workspace-write",
-            "-C",
-            this.opts.cwd,
-        ];
+        const args = ["exec", "--json", "--skip-git-repo-check", "--sandbox", this.opts.sandboxMode ?? "workspace-write", "-C", this.opts.cwd];
         if (this.opts.model)
             args.push("-m", this.opts.model);
-        if (this.opts.effort) {
+        if (this.opts.effort)
             args.push("-c", `model_reasoning_effort=${this.opts.effort}`);
-        }
-        else if (this.opts.fast) {
+        else if (this.opts.fast)
             args.push("-c", "model_reasoning_effort=low");
-        }
-        if (this._sessionId) {
+        if (this._sessionId)
             args.push("resume", this._sessionId);
-        }
         args.push(instruction);
         return args;
     }
-    buildSkillsAppendix() {
-        if (!this.opts.skills || this.opts.skills.length === 0)
-            return undefined;
-        const blocks = this.opts.skills
-            .map((skill) => loadSkillMarkdown(this.opts.cwd, skill))
-            .filter((block) => Boolean(block));
-        if (blocks.length === 0)
-            return undefined;
-        return [
-            "# Preloaded Skills",
-            "Use the following skills for this run.",
-            ...blocks,
-        ].join("\n\n");
-    }
-    sendTurn(instruction) {
-        if (this._closed)
-            return Promise.reject(new Error("builder is closed"));
-        const args = this.buildArgs(this.buildInstruction(instruction));
-        const textParts = [];
-        const stderrChunks = [];
-        return new Promise((resolve, reject) => {
-            const proc = spawn("codex", args, {
+    async sendTurn(instruction) {
+        if (this.closed)
+            throw new Error("builder is closed");
+        try {
+            await this.ensureThread();
+            this.activeText = [];
+            const completion = this.waitFor("turn/completed", (params) => params.threadId === this._sessionId);
+            await this.request("turn/start", {
+                threadId: this._sessionId,
+                input: [{ type: "text", text: this.buildInstruction(instruction), text_elements: [] }],
                 cwd: this.opts.cwd,
-                stdio: ["ignore", "pipe", "pipe"],
-            });
-            this._activeProc = proc;
-            const rl = createInterface({ input: proc.stdout, crlfDelay: Infinity });
-            rl.on("line", (line) => {
-                if (!line.trim())
-                    return;
-                let raw;
-                try {
-                    raw = JSON.parse(line);
-                }
-                catch {
-                    return;
-                }
-                const result = parseCodexLine(raw);
-                if (result.sessionId)
-                    this._sessionId = result.sessionId;
-                if (result.text)
-                    textParts.push(result.text);
-                for (const ev of result.events)
-                    this.eventQueue.push(ev);
-            });
-            proc.stderr.on("data", (chunk) => {
-                stderrChunks.push(chunk);
-            });
-            proc.on("close", (code) => {
-                this._activeProc = undefined;
-                let text = textParts.join("\n");
-                if (!text && code !== 0) {
-                    text = Buffer.concat(stderrChunks).toString().trim();
-                }
-                if (code !== 0) {
-                    text = normalizeRuntimeErrorText("codex", text, code, "builder turn");
-                }
-                const result = {
-                    text,
-                    isError: code !== 0,
-                    numTurns: 1,
-                    costUsd: 0,
-                };
-                this.eventQueue.push({ kind: "turn-complete", result });
-                resolve(result);
+                model: this.opts.model ?? null,
+                effort: this.opts.effort ?? (this.opts.fast ? "low" : null),
             });
-            proc.on("error", (err) => {
-                this._activeProc = undefined;
-                this.eventQueue.push({ kind: "error", message: err.message });
-                reject(err);
+            const params = await completion;
+            const turn = params.turn;
+            const failed = turn?.status === "failed";
+            const error = turn?.error;
+            const text = this.activeText.join("\n");
+            const result = { text: failed ? normalizeRuntimeErrorText("codex", String(error?.message ?? text), null, "app-server turn") : text, isError: failed, numTurns: 1, costUsd: 0 };
+            this.eventQueue.push({ kind: "turn-complete", result });
+            return result;
+        }
+        catch (error) {
+            const detail = [error instanceof Error ? error.message : String(error), this.stderr].filter(Boolean).join("\n");
+            const text = normalizeRuntimeErrorText("codex", detail, this.process?.exitCode ?? null, "builder turn");
+            this.disconnect(new Error(text));
+            const result = { text, isError: true, numTurns: 1, costUsd: 0 };
+            this.eventQueue.push({ kind: "error", message: text });
+            this.eventQueue.push({ kind: "turn-complete", result });
+            return result;
+        }
+    }
+    async compact() {
+        try {
+            await this.ensureThread();
+            this.eventQueue.push({ kind: "session-transition", transition: "compacting" });
+            const done = this.waitFor("item/completed", (params) => {
+                const item = params.item;
+                return params.threadId === this._sessionId && item?.type === "contextCompaction";
             });
+            await this.request("thread/compact/start", { threadId: this._sessionId });
+            await done;
+            this.usage = undefined;
+            this.eventQueue.push({ kind: "session-transition", transition: "compacted" });
+            return { ok: true };
+        }
+        catch (error) {
+            return { ok: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    async contextUsage() { return this.usage; }
+    async switchSettings(settings) {
+        this.opts.model = settings.model;
+        this.opts.effort = settings.effort;
+        this.opts.fast = settings.fast;
+        return { ok: true };
+    }
+    sessionId() { return this._sessionId; }
+    events() { return this.eventQueue; }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.disconnect(new Error("app-server closed"));
+        this.eventQueue.close();
+    }
+    async ensureThread() {
+        await this.ensureConnection();
+        if (this._sessionId && this.initialized === true && this.threadAttached)
+            return;
+        const method = this._sessionId ? "thread/resume" : "thread/start";
+        const result = await this.request(method, {
+            ...(this._sessionId ? { threadId: this._sessionId } : {}), cwd: this.opts.cwd,
+            model: this.opts.model ?? null, approvalPolicy: "never",
+            sandbox: this.opts.sandboxMode === "read-only" ? "read-only" : "workspace-write",
+            developerInstructions: this.opts.systemPromptAppend ?? null,
         });
+        const thread = result.thread;
+        this._sessionId = String(thread?.id ?? this._sessionId ?? "") || undefined;
+        if (!this._sessionId)
+            throw new Error(`${method} did not return a thread ID`);
+        this.threadAttached = true;
+        this.eventQueue.push({ kind: "session-transition", transition: method === "thread/resume" ? "resumed" : "started" });
     }
-    sessionId() {
-        return this._sessionId;
+    threadAttached = false;
+    async ensureConnection() {
+        if (this.process && this.initialized)
+            return;
+        this.stderr = "";
+        const executable = this.opts.runtimeExecutable ?? "codex";
+        const child = spawn(executable, this.buildAppServerArgs(), { cwd: this.opts.cwd, stdio: ["pipe", "pipe", "pipe"] });
+        this.process = child;
+        // A short-lived server may close stdin before its stderr/exit event. The
+        // close handler owns rejection so diagnostics include the complete stderr.
+        child.stdin.on("error", () => { });
+        const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+        lines.on("line", (line) => { if (line.trim())
+            try {
+                this.handle(JSON.parse(line));
+            }
+            catch { /* ignore non-protocol stdout */ } });
+        child.stderr.on("data", (chunk) => { this.stderr = `${this.stderr}${chunk.toString()}`.slice(-8192); });
+        child.on("error", (error) => this.disconnect(error));
+        child.on("close", (code) => this.disconnect(new Error(`Codex app-server exited with code ${code ?? "unknown"}`)));
+        await this.request("initialize", { clientInfo: { name: "rafi", title: "Rafi", version: "1" }, capabilities: { experimentalApi: true, requestAttestation: false } });
+        this.write({ method: "initialized", params: {} });
+        this.initialized = true;
     }
-    events() {
-        return this.eventQueue;
+    request(method, params) {
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            try {
+                this.write({ id, method, params });
+            }
+            catch (error) {
+                this.pending.delete(id);
+                reject(error);
+            }
+        });
     }
-    close() {
-        if (this._closed)
-            return Promise.resolve();
-        this._closed = true;
-        this._activeProc?.kill("SIGTERM");
-        this.eventQueue.close();
-        return Promise.resolve();
+    write(message) {
+        if (!this.process?.stdin.writable)
+            throw new Error("Codex app-server is not connected");
+        this.process.stdin.write(`${JSON.stringify(message)}\n`);
+    }
+    handle(message) {
+        if (message.id !== undefined) {
+            const pending = this.pending.get(message.id);
+            if (pending) {
+                this.pending.delete(message.id);
+                message.error ? pending.reject(new Error(message.error.message ?? `JSON-RPC error ${message.error.code ?? "unknown"}`)) : pending.resolve(message.result);
+            }
+            return;
+        }
+        if (!message.method)
+            return;
+        const params = message.params ?? {};
+        if (message.method === "item/completed") {
+            const item = params.item;
+            if (item?.type === "agentMessage" && typeof item.text === "string") {
+                this.activeText.push(item.text);
+                this.eventQueue.push({ kind: "text", text: item.text });
+            }
+            else if (item?.type === "commandExecution")
+                this.eventQueue.push({ kind: "tool", name: "command_execution", input: { command: item.command } });
+        }
+        else if (message.method === "thread/tokenUsage/updated") {
+            const tokenUsage = params.tokenUsage;
+            const total = tokenUsage?.total;
+            const used = Number(total?.totalTokens ?? 0);
+            const maximum = Number(tokenUsage?.modelContextWindow ?? 0) || undefined;
+            this.usage = { used, maximum, ...(maximum ? { percentage: used / maximum * 100 } : {}) };
+            this.eventQueue.push({ kind: "context-usage", ...this.usage });
+        }
+        else if (message.method === "error")
+            this.eventQueue.push({ kind: "error", message: String(params.message ?? "Codex app-server error") });
+        const waiters = this.notificationWaiters.get(message.method) ?? [];
+        const remaining = [];
+        for (const waiter of waiters)
+            waiter.predicate(params) ? waiter.resolve(params) : remaining.push(waiter);
+        this.notificationWaiters.set(message.method, remaining);
+    }
+    waitFor(method, predicate) {
+        return new Promise((resolve, reject) => { const waiters = this.notificationWaiters.get(method) ?? []; waiters.push({ predicate, resolve, reject }); this.notificationWaiters.set(method, waiters); });
+    }
+    disconnect(error) {
+        const child = this.process;
+        this.process = undefined;
+        this.initialized = false;
+        this.threadAttached = false;
+        if (child && child.exitCode === null)
+            child.kill("SIGTERM");
+        for (const pending of this.pending.values())
+            pending.reject(error);
+        this.pending.clear();
+        for (const waiters of this.notificationWaiters.values())
+            for (const waiter of waiters)
+                waiter.reject(error);
+        this.notificationWaiters.clear();
+    }
+    buildSkillsAppendix() {
+        if (!this.opts.skills?.length)
+            return undefined;
+        const blocks = this.opts.skills.map((skill) => loadSkillMarkdown(this.opts.cwd, skill)).filter((block) => Boolean(block));
+        return blocks.length ? ["# Preloaded Skills", "Use the following skills for this run.", ...blocks].join("\n\n") : undefined;
     }
 }
 function loadSkillMarkdown(cwd, skill) {
     const projectPath = join(cwd, ".agents", "skills", skill, "SKILL.md");
-    if (existsSync(projectPath)) {
+    if (existsSync(projectPath))
         return `## ${skill}\n${readFileSync(projectPath, "utf8").trim()}`;
-    }
     try {
         const bundled = loadSkill(skill);
-        const body = bundled.body?.trim();
-        return body ? `## ${bundled.name}\n${body}` : undefined;
+        return bundled.body?.trim() ? `## ${bundled.name}\n${bundled.body.trim()}` : undefined;
     }
     catch {
         return undefined;

package/dist/adapters/recovering.d.ts

@@ -1,5 +1,5 @@
 import type { AgentRuntime } from "../runtimeAuth.js";
-import type { BuilderAdapter, BuilderEvent, TurnResult } from "./types.js";
+import type { BuilderAdapter, BuilderEvent, CompactResult, ContextUsage, TurnResult } from "./types.js";
 export type TurnRecoveryChoice = "retry" | "switch" | "cancel";
 export interface RecoveringAdapterOptions {
     initial: BuilderAdapter;
@@ -23,6 +23,8 @@ export declare class RecoveringAdapter implements BuilderAdapter {
     get agent(): "claude" | "codex";
     sendTurn(text: string): Promise<TurnResult>;
     sessionId(): string | undefined;
+    compact(): Promise<CompactResult>;
+    contextUsage(): Promise<ContextUsage | undefined>;
     events(): AsyncIterable<BuilderEvent>;
     close(): Promise<void>;
     private replaceAdapter;

package/dist/adapters/recovering.js

@@ -41,6 +41,8 @@ export class RecoveringAdapter {
     sessionId() {
         return this.adapter.sessionId();
     }
+    compact() { return this.adapter.compact?.() ?? Promise.resolve({ ok: false, error: "native compaction unavailable" }); }
+    contextUsage() { return this.adapter.contextUsage?.() ?? Promise.resolve(undefined); }
     events() {
         return this.eventQueue;
     }

package/dist/adapters/types.d.ts

@@ -45,10 +45,33 @@ export type BuilderEvent = {
 } | {
     kind: "turn-complete";
     result: TurnResult;
+} | {
+    kind: "session-transition";
+    transition: "started" | "resumed" | "compacting" | "compacted" | "fresh-fallback";
+    detail?: string;
+} | {
+    kind: "context-usage";
+    used: number;
+    maximum?: number;
+    percentage?: number;
 } | {
     kind: "error";
     message: string;
 };
+export interface ContextUsage {
+    used: number;
+    maximum?: number;
+    percentage?: number;
+}
+export interface CompactResult {
+    ok: boolean;
+    error?: string;
+}
+export interface ProviderSettingSwitch {
+    model?: string;
+    effort?: EffortLevel;
+    fast?: boolean;
+}
 export type EffortLevel = "low" | "medium" | "high" | "xhigh";
 export interface BuilderAdapterOptions {
     /** Working directory the builder operates in. */
@@ -80,6 +103,12 @@ export interface BuilderAdapter {
     sendTurn(text: string): Promise<TurnResult>;
     /** Current session id, once known — used for resume. */
     sessionId(): string | undefined;
+    /** Provider-native compaction on the exact live conversation. */
+    compact?(): Promise<CompactResult>;
+    /** Truthful provider context occupancy, when exposed by the provider. */
+    contextUsage?(): Promise<ContextUsage | undefined>;
+    /** Attempt a provider-supported in-conversation model/reasoning transition. */
+    switchSettings?(settings: ProviderSettingSwitch): Promise<CompactResult>;
     /** Stream of observability events. Iterate to drive a live view. */
     events(): AsyncIterable<BuilderEvent>;
     /** Shut the builder down and release resources. */