larkin 0.3.3 → 0.4.2

package/dist/runtime/pi-rpc-client.cjs

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PiRpcClient = void 0;
-/** A strict, bounded LF-delimited client for Pi's public RPC protocol. */
+/** A strict LF-delimited client for Pi's public RPC protocol. */
 class PiRpcClient {
     process;
     pending = new Map();
@@ -11,9 +11,10 @@ class PiRpcClient {
     inputTimeoutMs;
     inputProgressTimeoutMs;
     inputMaxTimeoutMs;
-    maxFrameBytes;
     maxStderrBytes;
     shutdownGraceMs;
+    compactTimeoutMs;
+    expiredRequestIds = new Set();
     stdoutBuffer = Buffer.alloc(0);
     stderrBuffer = Buffer.alloc(0);
     exited = false;
@@ -29,9 +30,11 @@ class PiRpcClient {
         if (this.requestTimeoutMs <= 0 || this.inputTimeoutMs <= 0 || this.inputProgressTimeoutMs <= 0
             || this.inputMaxTimeoutMs < this.inputTimeoutMs)
             throw new Error("Pi RPC timeout options are invalid");
-        this.maxFrameBytes = options.maxFrameBytes ?? 1024 * 1024;
         this.maxStderrBytes = options.maxStderrBytes ?? 64 * 1024;
         this.shutdownGraceMs = options.shutdownGraceMs ?? 2_000;
+        this.compactTimeoutMs = options.compactTimeoutMs ?? 120_000;
+        if (this.compactTimeoutMs <= 0)
+            throw new Error("Pi compact timeout must be positive");
         process.stdout?.on("data", (chunk) => this.consume(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))));
         process.stdout?.on("end", () => {
             if (this.stdoutBuffer.length)
@@ -61,19 +64,26 @@ class PiRpcClient {
         return () => this.failureListeners.delete(listener);
     }
     request(command, fields = {}) {
+        const input = isInputCommand(command);
+        return this.requestInternal(command, fields, input ? this.inputTimeoutMs : this.requestTimeoutMs, input ? Date.now() + this.inputMaxTimeoutMs : undefined, true);
+    }
+    /** Send the documented compact RPC with a Larkin-owned absolute deadline. */
+    requestCompact(customInstructions) {
+        const startedAt = Date.now();
+        return this.requestInternal("compact", customInstructions === undefined ? {} : { customInstructions }, this.compactTimeoutMs, startedAt + this.compactTimeoutMs, false);
+    }
+    requestInternal(command, fields, timeoutMs, absoluteDeadlineAt, failClientOnTimeout) {
         if (this.failed)
             return Promise.reject(this.failed);
         const id = `larkin-${++this.nextId}`;
         return new Promise((resolve, reject) => {
             const startedAt = Date.now();
-            const input = isInputCommand(command);
             const pending = {
-                command, startedAt,
-                ...(input ? { absoluteDeadlineAt: startedAt + this.inputMaxTimeoutMs } : {}),
-                resolve: resolve, reject,
+                command, startedAt, ...(absoluteDeadlineAt !== undefined ? { absoluteDeadlineAt } : {}),
+                failClientOnTimeout, resolve: resolve, reject,
             };
             this.pending.set(id, pending);
-            this.armTimeout(id, pending, input ? this.inputTimeoutMs : this.requestTimeoutMs);
+            this.armTimeout(id, pending, timeoutMs);
             try {
                 if (!this.process.stdin || this.process.stdin.destroyed)
                     throw new Error("stdin is unavailable");
@@ -103,15 +113,8 @@ class PiRpcClient {
         this.stdoutBuffer = Buffer.concat([this.stdoutBuffer, chunk]);
         while (true) {
             const newline = this.stdoutBuffer.indexOf(0x0a);
-            if (newline < 0) {
-                if (this.stdoutBuffer.length > this.maxFrameBytes)
-                    this.protocolFailure(`frame exceeds ${this.maxFrameBytes} bytes`);
-                return;
-            }
-            if (newline > this.maxFrameBytes) {
-                this.protocolFailure(`frame exceeds ${this.maxFrameBytes} bytes`);
+            if (newline < 0)
                 return;
-            }
             let frame = this.stdoutBuffer.subarray(0, newline);
             this.stdoutBuffer = this.stdoutBuffer.subarray(newline + 1);
             if (frame.at(-1) === 0x0d)
@@ -140,6 +143,8 @@ class PiRpcClient {
         if (message.type === "response" && typeof message.id === "string") {
             const pending = this.pending.get(message.id);
             if (!pending) {
+                if (this.expiredRequestIds.delete(message.id))
+                    return;
                 this.protocolFailure(`unexpected response id ${message.id}`);
                 return;
             }
@@ -181,12 +186,24 @@ class PiRpcClient {
                 return;
             const elapsed = Date.now() - pending.startedAt;
             const absolute = pending.absoluteDeadlineAt !== undefined && Date.now() >= pending.absoluteDeadlineAt;
-            const error = isInputCommand(pending.command)
-                ? new Error(absolute
-                    ? `Pi RPC ${pending.command} preflight timed out at absolute ${this.inputMaxTimeoutMs}ms limit`
-                    : `Pi RPC ${pending.command} preflight timed out after ${elapsed}ms without progress`)
-                : new Error(`Pi RPC ${pending.command} timed out after ${this.requestTimeoutMs}ms`);
-            this.fail(error, true);
+            this.pending.delete(id);
+            this.expiredRequestIds.add(id);
+            while (this.expiredRequestIds.size > 256) {
+                const oldest = this.expiredRequestIds.values().next().value;
+                if (!oldest)
+                    break;
+                this.expiredRequestIds.delete(oldest);
+            }
+            const error = pending.command === "compact"
+                ? new Error(`Pi RPC compact timed out at absolute compact deadline ${elapsed}ms`)
+                : isInputCommand(pending.command)
+                    ? new Error(absolute
+                        ? `Pi RPC ${pending.command} preflight timed out at absolute ${this.inputMaxTimeoutMs}ms limit`
+                        : `Pi RPC ${pending.command} preflight timed out after ${elapsed}ms without progress`)
+                    : new Error(`Pi RPC ${pending.command} timed out after ${this.requestTimeoutMs}ms`);
+            pending.reject(error);
+            if (pending.failClientOnTimeout !== false)
+                this.fail(error, true);
         }, delay);
         pending.timer.unref?.();
     }

package/dist/runtime/pi-rpc-client.mjs

@@ -1,4 +1,4 @@
-/** A strict, bounded LF-delimited client for Pi's public RPC protocol. */
+/** A strict LF-delimited client for Pi's public RPC protocol. */
 export class PiRpcClient {
     process;
     pending = new Map();
@@ -8,9 +8,10 @@ export class PiRpcClient {
     inputTimeoutMs;
     inputProgressTimeoutMs;
     inputMaxTimeoutMs;
-    maxFrameBytes;
     maxStderrBytes;
     shutdownGraceMs;
+    compactTimeoutMs;
+    expiredRequestIds = new Set();
     stdoutBuffer = Buffer.alloc(0);
     stderrBuffer = Buffer.alloc(0);
     exited = false;
@@ -26,9 +27,11 @@ export class PiRpcClient {
         if (this.requestTimeoutMs <= 0 || this.inputTimeoutMs <= 0 || this.inputProgressTimeoutMs <= 0
             || this.inputMaxTimeoutMs < this.inputTimeoutMs)
             throw new Error("Pi RPC timeout options are invalid");
-        this.maxFrameBytes = options.maxFrameBytes ?? 1024 * 1024;
         this.maxStderrBytes = options.maxStderrBytes ?? 64 * 1024;
         this.shutdownGraceMs = options.shutdownGraceMs ?? 2_000;
+        this.compactTimeoutMs = options.compactTimeoutMs ?? 120_000;
+        if (this.compactTimeoutMs <= 0)
+            throw new Error("Pi compact timeout must be positive");
         process.stdout?.on("data", (chunk) => this.consume(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))));
         process.stdout?.on("end", () => {
             if (this.stdoutBuffer.length)
@@ -58,19 +61,26 @@ export class PiRpcClient {
         return () => this.failureListeners.delete(listener);
     }
     request(command, fields = {}) {
+        const input = isInputCommand(command);
+        return this.requestInternal(command, fields, input ? this.inputTimeoutMs : this.requestTimeoutMs, input ? Date.now() + this.inputMaxTimeoutMs : undefined, true);
+    }
+    /** Send the documented compact RPC with a Larkin-owned absolute deadline. */
+    requestCompact(customInstructions) {
+        const startedAt = Date.now();
+        return this.requestInternal("compact", customInstructions === undefined ? {} : { customInstructions }, this.compactTimeoutMs, startedAt + this.compactTimeoutMs, false);
+    }
+    requestInternal(command, fields, timeoutMs, absoluteDeadlineAt, failClientOnTimeout) {
         if (this.failed)
             return Promise.reject(this.failed);
         const id = `larkin-${++this.nextId}`;
         return new Promise((resolve, reject) => {
             const startedAt = Date.now();
-            const input = isInputCommand(command);
             const pending = {
-                command, startedAt,
-                ...(input ? { absoluteDeadlineAt: startedAt + this.inputMaxTimeoutMs } : {}),
-                resolve: resolve, reject,
+                command, startedAt, ...(absoluteDeadlineAt !== undefined ? { absoluteDeadlineAt } : {}),
+                failClientOnTimeout, resolve: resolve, reject,
             };
             this.pending.set(id, pending);
-            this.armTimeout(id, pending, input ? this.inputTimeoutMs : this.requestTimeoutMs);
+            this.armTimeout(id, pending, timeoutMs);
             try {
                 if (!this.process.stdin || this.process.stdin.destroyed)
                     throw new Error("stdin is unavailable");
@@ -100,15 +110,8 @@ export class PiRpcClient {
         this.stdoutBuffer = Buffer.concat([this.stdoutBuffer, chunk]);
         while (true) {
             const newline = this.stdoutBuffer.indexOf(0x0a);
-            if (newline < 0) {
-                if (this.stdoutBuffer.length > this.maxFrameBytes)
-                    this.protocolFailure(`frame exceeds ${this.maxFrameBytes} bytes`);
-                return;
-            }
-            if (newline > this.maxFrameBytes) {
-                this.protocolFailure(`frame exceeds ${this.maxFrameBytes} bytes`);
+            if (newline < 0)
                 return;
-            }
             let frame = this.stdoutBuffer.subarray(0, newline);
             this.stdoutBuffer = this.stdoutBuffer.subarray(newline + 1);
             if (frame.at(-1) === 0x0d)
@@ -137,6 +140,8 @@ export class PiRpcClient {
         if (message.type === "response" && typeof message.id === "string") {
             const pending = this.pending.get(message.id);
             if (!pending) {
+                if (this.expiredRequestIds.delete(message.id))
+                    return;
                 this.protocolFailure(`unexpected response id ${message.id}`);
                 return;
             }
@@ -178,12 +183,24 @@ export class PiRpcClient {
                 return;
             const elapsed = Date.now() - pending.startedAt;
             const absolute = pending.absoluteDeadlineAt !== undefined && Date.now() >= pending.absoluteDeadlineAt;
-            const error = isInputCommand(pending.command)
-                ? new Error(absolute
-                    ? `Pi RPC ${pending.command} preflight timed out at absolute ${this.inputMaxTimeoutMs}ms limit`
-                    : `Pi RPC ${pending.command} preflight timed out after ${elapsed}ms without progress`)
-                : new Error(`Pi RPC ${pending.command} timed out after ${this.requestTimeoutMs}ms`);
-            this.fail(error, true);
+            this.pending.delete(id);
+            this.expiredRequestIds.add(id);
+            while (this.expiredRequestIds.size > 256) {
+                const oldest = this.expiredRequestIds.values().next().value;
+                if (!oldest)
+                    break;
+                this.expiredRequestIds.delete(oldest);
+            }
+            const error = pending.command === "compact"
+                ? new Error(`Pi RPC compact timed out at absolute compact deadline ${elapsed}ms`)
+                : isInputCommand(pending.command)
+                    ? new Error(absolute
+                        ? `Pi RPC ${pending.command} preflight timed out at absolute ${this.inputMaxTimeoutMs}ms limit`
+                        : `Pi RPC ${pending.command} preflight timed out after ${elapsed}ms without progress`)
+                    : new Error(`Pi RPC ${pending.command} timed out after ${this.requestTimeoutMs}ms`);
+            pending.reject(error);
+            if (pending.failClientOnTimeout !== false)
+                this.fail(error, true);
         }, delay);
         pending.timer.unref?.();
     }

package/dist/runtime/provider-error-classifier.cjs

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON = exports.CANONICAL_CONTEXT_WINDOW_MESSAGE = exports.CODEX_ERROR_PREFIX = void 0;
+exports.buildStrictProviderErrorInput = buildStrictProviderErrorInput;
+exports.classifyStrictProviderError = classifyStrictProviderError;
+exports.CODEX_ERROR_PREFIX = "Codex error: ";
+exports.CANONICAL_CONTEXT_WINDOW_MESSAGE = "Your input exceeds the context window of this model. Please adjust your input and try again.";
+exports.INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON = "provider rejected the input because the context window was exceeded";
+/** Build the one structured provider-error shape shared by ingestion and recovery. */
+function buildStrictProviderErrorInput(source) {
+    const upstream = source.upstream && typeof source.upstream === "object" && !Array.isArray(source.upstream)
+        ? source.upstream : {};
+    return {
+        message: source.reason !== undefined ? source.reason : source.message,
+        code: source.code ?? upstream.code,
+        type: source.type ?? upstream.type,
+        errorCategory: source.errorCategory,
+    };
+}
+/**
+ * The recovery path intentionally recognizes only the complete canonical
+ * provider message, or the exact internal projection when its category is
+ * persisted alongside it. The Codex wrapper is the only normalization
+ * permitted for the provider message.
+ */
+function classifyStrictProviderError(error) {
+    if (typeof error.message !== "string")
+        return undefined;
+    if (error.errorCategory !== undefined && error.errorCategory !== "context_window")
+        return undefined;
+    const message = error.message.startsWith(exports.CODEX_ERROR_PREFIX)
+        ? error.message.slice(exports.CODEX_ERROR_PREFIX.length) : error.message;
+    if (message === exports.CANONICAL_CONTEXT_WINDOW_MESSAGE)
+        return "context_window";
+    if (error.errorCategory === "context_window" && error.message === exports.INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON) {
+        return "context_window";
+    }
+    return undefined;
+}

package/dist/runtime/provider-error-classifier.mjs

@@ -0,0 +1,34 @@
+export const CODEX_ERROR_PREFIX = "Codex error: ";
+export const CANONICAL_CONTEXT_WINDOW_MESSAGE = "Your input exceeds the context window of this model. Please adjust your input and try again.";
+export const INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON = "provider rejected the input because the context window was exceeded";
+/** Build the one structured provider-error shape shared by ingestion and recovery. */
+export function buildStrictProviderErrorInput(source) {
+    const upstream = source.upstream && typeof source.upstream === "object" && !Array.isArray(source.upstream)
+        ? source.upstream : {};
+    return {
+        message: source.reason !== undefined ? source.reason : source.message,
+        code: source.code ?? upstream.code,
+        type: source.type ?? upstream.type,
+        errorCategory: source.errorCategory,
+    };
+}
+/**
+ * The recovery path intentionally recognizes only the complete canonical
+ * provider message, or the exact internal projection when its category is
+ * persisted alongside it. The Codex wrapper is the only normalization
+ * permitted for the provider message.
+ */
+export function classifyStrictProviderError(error) {
+    if (typeof error.message !== "string")
+        return undefined;
+    if (error.errorCategory !== undefined && error.errorCategory !== "context_window")
+        return undefined;
+    const message = error.message.startsWith(CODEX_ERROR_PREFIX)
+        ? error.message.slice(CODEX_ERROR_PREFIX.length) : error.message;
+    if (message === CANONICAL_CONTEXT_WINDOW_MESSAGE)
+        return "context_window";
+    if (error.errorCategory === "context_window" && error.message === INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON) {
+        return "context_window";
+    }
+    return undefined;
+}

package/dist/runtime/runtime-adapters.mjs

@@ -1,4 +1,4 @@
-import { spawn as nodeSpawn } from "node:child_process";
+import { spawn as nodeSpawn, spawnSync } from "node:child_process";
 import crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -10,6 +10,8 @@ import { piAgentDirectory } from "./pi-provider-config.mjs";
 import { resolvePiSubagentExtensionArg } from "./pi-subagent-injection.mjs";
 import { resolvePiBashTimeoutExtensionArg } from "./pi-bash-timeout-injection.mjs";
 import { classifyRuntimePrerequisite, probeNativeRuntimeReadiness, providerAuthenticationFailureReadiness, RuntimePrerequisiteError, } from "./runtime-readiness.mjs";
+import { buildStrictProviderErrorInput, classifyStrictProviderError, INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON, } from "./provider-error-classifier.mjs";
+import { assertEffectivePiCompactionSettings, assertNoProjectPiCompactionOverride, prepareOwnedPiDirectory, readOwnedPiSettings, verifyPiCapabilities, } from "./pi-compaction-recovery.mjs";
 class EventSession {
     listeners = new Set();
     subscribe(listener) {
@@ -447,6 +449,7 @@ class PiSession extends EventSession {
     observedSubmitEpochs = new Set();
     observedAcceptedEpochs = new Set();
     observedCompletedEpochs = new Set();
+    observedAgentEndEpochs = new Set();
     firstOutputObserved = false;
     toolCallOpen = false;
     constructor(sdk, distribution) {
@@ -470,6 +473,11 @@ class PiSession extends EventSession {
     async prompt(input) { return this.enqueue(input, () => this.sdk.prompt(input.text)); }
     async busyInput(input) { return this.enqueue(input, () => this.sdk.steer(input.text)); }
     async cancel(_reason) { await this.sdk.abort(); }
+    async compact(customInstructions) {
+        if (!this.sdk.compact)
+            throw new Error("Pi compact RPC is unavailable");
+        return this.sdk.compact(customInstructions);
+    }
     async close(_reason) { this.unsubscribe?.(); await this.sdk.dispose?.(); }
     async enqueue(input, operation) {
         if (this.ownedInputIds.size === 0)
@@ -481,14 +489,14 @@ class PiSession extends EventSession {
         const ownsRpcObservation = !this.observedSubmitEpochs.has(epoch);
         if (ownsRpcObservation) {
             this.observedSubmitEpochs.add(epoch);
-            this.emit({ type: "runtime-observation", runtime: "pi", distribution: this.distribution, phase: "rpc_submit" });
+            this.emitObservation("rpc_submit");
         }
         try {
             await operation();
             this.awaitingAcknowledgement.delete(input.inputId);
             if (ownsRpcObservation && !this.observedAcceptedEpochs.has(epoch)) {
                 this.observedAcceptedEpochs.add(epoch);
-                this.emit({ type: "runtime-observation", runtime: "pi", distribution: this.distribution, phase: "rpc_accepted" });
+                this.emitObservation("rpc_accepted");
             }
             return { status: "accepted", inputId: input.inputId };
         }
@@ -524,19 +532,23 @@ class PiSession extends EventSession {
             this.observedSubmitEpochs.clear();
             this.observedAcceptedEpochs.clear();
             this.observedCompletedEpochs.clear();
+            this.observedAgentEndEpochs.clear();
             this.activeEpoch = null;
             this.settleArmedEpoch = null;
             this.emit({ type: "error", message });
         }
-        else if (event?.type === "compaction_start" && this.awaitingAcknowledgement.size > 0) {
-            this.emit({ type: "runtime-observation", runtime: "pi", distribution: this.distribution, phase: "compaction_start" });
+        else if (event?.type === "compaction_start") {
+            this.emitObservation("compaction_start", event.reason === "manual" || event.reason === "threshold" || event.reason === "overflow" ? { reason: event.reason } : {});
         }
-        else if (event?.type === "compaction_end" && this.awaitingAcknowledgement.size > 0) {
-            this.emit({ type: "runtime-observation", runtime: "pi", distribution: this.distribution, phase: "compaction_end" });
+        else if (event?.type === "compaction_end") {
+            this.emitObservation("compaction_end", {
+                ...(event.reason === "manual" || event.reason === "threshold" || event.reason === "overflow" ? { reason: event.reason } : {}),
+                willRetry: event.willRetry === true, success: event.aborted !== true && event.result !== undefined,
+            });
         }
         else if ((event?.type === "auto_retry_start" || event?.type === "auto_retry_end"
             || String(event?.type || "").startsWith("summarization_retry_")) && this.awaitingAcknowledgement.size > 0) {
-            this.emit({ type: "runtime-observation", runtime: "pi", distribution: this.distribution, phase: "retry_progress" });
+            this.emitObservation("retry_progress");
         }
         else if (event?.type === "turn_start") {
             const epoch = this.oldestOwnedEpoch();
@@ -546,7 +558,7 @@ class PiSession extends EventSession {
             this.settleArmedEpoch = null;
             this.firstOutputObserved = false;
             this.toolCallOpen = false;
-            this.emit({ type: "runtime-observation", runtime: "pi", distribution: this.distribution, phase: "turn_start" });
+            this.emitObservation("turn_start");
             this.emit({ type: "turn-start", ...(Number.isInteger(event.turnIndex) ? { turnId: `pi-${event.turnIndex}` } : {}) });
         }
         else if (event?.type === "agent_end") {
@@ -557,9 +569,17 @@ class PiSession extends EventSession {
                 ? piAssistantProviderError(assistant)
                 : null;
             this.settleArmedEpoch = this.activeEpoch;
+            if (this.activeEpoch !== null && !this.observedAgentEndEpochs.has(this.activeEpoch)) {
+                this.observedAgentEndEpochs.add(this.activeEpoch);
+                this.emitObservation("agent_end", { willRetry: event.willRetry === true });
+            }
+            if (event.willRetry === true && this.finalAssistantError?.upstream.message === "Your input exceeds the context window of this model. Please adjust your input and try again.") {
+                this.emit({ type: "input-error", inputId: this.oldestOwnedInput(), retryable: true, willRetry: true,
+                    message: "Pi owns the context-overflow retry", errorCategory: "context_window" });
+            }
             if (event.willRetry !== true && this.activeEpoch !== null && !this.observedCompletedEpochs.has(this.activeEpoch)) {
                 this.observedCompletedEpochs.add(this.activeEpoch);
-                this.emit({ type: "runtime-observation", runtime: "pi", distribution: this.distribution, phase: "completed" });
+                this.emitObservation("completed");
             }
         }
         else if (event?.type === "agent_settled") {
@@ -576,7 +596,7 @@ class PiSession extends EventSession {
                 this.toolCallOpen = false;
                 this.emit({ type: "runtime-observation", runtime: "pi", distribution: this.distribution, phase: "tool_result" });
             }
-            this.emit({ type: "runtime-observation", runtime: "pi", distribution: this.distribution, phase: "settled" });
+            this.emitObservation("settled");
             const owned = [...this.ownedInputIds].filter((inputId) => this.inputEpochs.get(inputId) === epoch);
             if (error) {
                 const classified = classifyPiProviderError(error);
@@ -605,6 +625,7 @@ class PiSession extends EventSession {
             this.observedSubmitEpochs.delete(epoch);
             this.observedAcceptedEpochs.delete(epoch);
             this.observedCompletedEpochs.delete(epoch);
+            this.observedAgentEndEpochs.delete(epoch);
         }
         else if (event?.type === "tool_execution_start") {
             if (!this.firstOutputObserved) {
@@ -632,6 +653,20 @@ class PiSession extends EventSession {
             this.emit({ type: "activity", activity: kind, text: String(event.assistantMessageEvent.delta) });
         }
     }
+    emitObservation(phase, fields = {}) {
+        const inputId = this.oldestOwnedInput();
+        const observation = { type: "runtime-observation", runtime: "pi",
+            distribution: this.distribution, phase, ...fields };
+        // Correlation is host-internal metadata, not telemetry payload.
+        if (this.sessionId)
+            Object.defineProperty(observation, "sessionId", { value: this.sessionId, enumerable: false });
+        if (inputId)
+            Object.defineProperty(observation, "inputId", { value: inputId, enumerable: false });
+        this.emit(observation);
+    }
+    oldestOwnedInput() {
+        return this.ownedInputIds.values().next().value;
+    }
     oldestOwnedEpoch() {
         for (const inputId of this.ownedInputIds) {
             const epoch = this.inputEpochs.get(inputId);
@@ -675,6 +710,13 @@ export function classifyPiProviderError(error) {
     const errorType = "type" in error ? error.type : undefined;
     const reason = safeProviderText(upstream.message, "Pi provider request failed");
     const signal = new Set([String(upstream.code ?? "").trim().toLowerCase(), String(errorType ?? "").trim().toLowerCase()].filter(Boolean));
+    if (classifyStrictProviderError(buildStrictProviderErrorInput({
+        message: reason, type: errorType, upstream,
+    })) === "context_window")
+        return {
+            category: "context_window", reason: INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON,
+            nextAction: "Start a fresh Runtime session, then replay the retained Inbox deliveries.",
+        };
     if (upstream.status === 402 || [...signal].some((value) => ["payment_required", "billing_hard_limit_reached", "insufficient_balance"].includes(value)))
         return {
             category: "billing", reason, nextAction: "Update the provider billing method or balance, then retry.",
@@ -787,6 +829,8 @@ class PiRpcBackend {
     prompt(text) { return this.client.request("prompt", { message: text }); }
     steer(text) { return this.client.request("steer", { message: text }); }
     abort() { return this.client.request("abort"); }
+    compact(customInstructions) { return this.client.requestCompact(customInstructions); }
+    getState() { return this.client.request("get_state"); }
     dispose() { return this.client.close(); }
     subscribe(listener) {
         const offEvent = this.client.subscribe(listener);
@@ -809,8 +853,14 @@ export function resolvePiProcessExtensionArgs(input, resolvers = {}) {
         args.push("-e", bashTimeout);
     return args;
 }
-async function createPiRpcBackend(input, dependencies, spawn) {
+async function createPiRpcBackend(input, dependencies, spawn, productionSpawn = true) {
     const stateRoot = input.stateDir ?? path.join(input.workspaceDir, ".larkin");
+    const mergedEnv = { ...globalThis.process.env, ...dependencies.env, ...input.env, NO_COLOR: "1" };
+    assertNoProjectPiCompactionOverride(input.workspaceDir);
+    const ownedPiDirectory = mergedEnv.LARKIN_CONFIG_DIR
+        ? piAgentDirectory(mergedEnv.LARKIN_CONFIG_DIR, input.agentId)
+        : path.join(stateRoot, "pi-agent");
+    prepareOwnedPiDirectory(ownedPiDirectory);
     const runtimeDir = path.join(stateRoot, "runtime");
     fs.mkdirSync(runtimeDir, { recursive: true, mode: 0o700 });
     const promptFile = path.join(runtimeDir, "pi-standing-prompt.md");
@@ -824,17 +874,16 @@ async function createPiRpcBackend(input, dependencies, spawn) {
         ...(session.sessionFile ? ["--session", session.sessionFile] : []),
         ...(requestedModel ? ["--model", requestedModel] : []),
         ...(requestedEffort ? ["--thinking", requestedEffort] : [])];
-    const mergedEnv = { ...globalThis.process.env, ...dependencies.env, ...input.env, NO_COLOR: "1" };
     const builtin = mergedEnv.LARKIN_PI_DISTRIBUTION === "builtin";
     const builtinSpec = builtin ? internalCommandSpec("pi-rpc", [], mergedEnv) : null;
     const command = builtinSpec?.command ?? dependencies.piCommand ?? dependencies.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
     const commandArgs = [...(builtinSpec?.args ?? []), ...args];
-    if (builtin) {
-        if (!mergedEnv.LARKIN_CONFIG_DIR)
-            throw new Error("内置 Pi 缺少 LARKIN_CONFIG_DIR");
-        mergedEnv.PI_CODING_AGENT_DIR = piAgentDirectory(mergedEnv.LARKIN_CONFIG_DIR, input.agentId);
+    const reportedVersion = productionSpawn && !builtin
+        ? String(spawnSync(command, ["--version"], { cwd: input.workspaceDir, env: mergedEnv, encoding: "utf8", timeout: 5_000 }).stdout || "").trim()
+        : "0.83.0";
+    mergedEnv.PI_CODING_AGENT_DIR = ownedPiDirectory;
+    if (builtin)
         mergedEnv.PI_TELEMETRY = "0";
-    }
     commandArgs.push(...(dependencies.resolvePiProcessExtensionArgs ?? resolvePiProcessExtensionArgs)({
         distribution: builtin ? "builtin" : "external",
         piCommand: command,
@@ -855,6 +904,20 @@ async function createPiRpcBackend(input, dependencies, spawn) {
         if (!available?.models?.length)
             throw new Error("Pi has no authenticated available models. Run the official `pi` login flow or configure provider credentials; Larkin will not create a fallback session.");
         const effectiveModel = state.model?.provider && state.model.id ? `${state.model.provider}/${state.model.id}` : null;
+        if (productionSpawn) {
+            const ownedSettings = readOwnedPiSettings(ownedPiDirectory);
+            assertEffectivePiCompactionSettings({ contextWindow: state.model?.contextWindow, compaction: {
+                    enabled: state.autoCompactionEnabled,
+                    reserveTokens: ownedSettings.compaction?.reserveTokens,
+                    keepRecentTokens: ownedSettings.compaction?.keepRecentTokens,
+                } });
+            const handshake = state.compactionCapabilities;
+            verifyPiCapabilities({ distribution: builtin ? "builtin" : "external", version: reportedVersion,
+                contextWindow: state.model?.contextWindow, autoCompactionEnabled: state.autoCompactionEnabled,
+                reserveTokens: handshake?.reserveTokens, keepRecentTokens: handshake?.keepRecentTokens,
+                compactRpc: true, events: handshake?.events,
+                trustedProtocol: builtin });
+        }
         // 严格对账（Owner 决策）：模型必须来自 pi 的权威可用列表，不做后缀猜测——
         // 配置的模型与 pi 可用列表不符即报错，并在错误里列出可用模型。
         const availableEntries = (available.models ?? []).map((entry) => ({
@@ -988,7 +1051,7 @@ export function createNativeRuntimeAdapter(id, dependencies = {}) {
                     ? "builtin" : "external";
                 return new PiSession(await (dependencies.createPiSession
                     ? dependencies.createPiSession(input)
-                    : createPiRpcBackend(input, { ...dependencies, piCommand: resolvedExecutable }, spawn)), distribution);
+                    : createPiRpcBackend(input, { ...dependencies, piCommand: resolvedExecutable }, spawn, productionSpawn)), distribution);
             }
             if (id === "codex") {
                 const codexInput = dependencies.codexModelOverride?.trim()