@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

package/dist/integrations/pi/engine/changelog.js

@@ -0,0 +1,63 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { posix } from "node:path";
+const REPOSITORY = "https://github.com/earendil-works/pi";
+export async function readPinnedCommandChangelog(sinceVersion) {
+    const path = new URL("./resources/changelog.json", import.meta.url);
+    if (!existsSync(path))
+        return sinceVersion === undefined ? "No changelog entries found." : "";
+    try {
+        const resource = JSON.parse(await readFile(path, "utf8"));
+        if (!resource || typeof resource !== "object" || !("data" in resource) || typeof resource.data !== "string")
+            throw new TypeError("Invalid owned changelog resource");
+        const markdown = resource.data;
+        return formatPinnedCommandChangelog(markdown, sinceVersion);
+    }
+    catch (error) {
+        // Compatibility: Pi's data-file parser reports a warning and supplies an empty changelog.
+        console.error(`Warning: Could not parse changelog: ${error}`);
+        return sinceVersion === undefined ? "No changelog entries found." : "";
+    }
+}
+export function formatPinnedCommandChangelog(content, sinceVersion) {
+    // Provenance: behavior follows Pi 0.84.2 utils/changelog.ts at 914cf1472e715297caa30db4b9535d534a9eb718.
+    // Runtime reads only the owned data resource; maintenance tooling verifies its pinned provenance.
+    let releases = content.split(/(?=^## )/m).flatMap((section) => {
+        const version = /^##\s+\[?(\d+)\.(\d+)\.(\d+)\]?/.exec(section);
+        return version ? [{ version: version.slice(1).map(Number), markdown: section.trim() }] : [];
+    });
+    if (sinceVersion !== undefined) {
+        const previous = sinceVersion.split(".").map(value => Number(value) || 0);
+        releases = releases.filter(release => {
+            for (let index = 0; index < 3; index++) {
+                const difference = release.version[index] - (previous[index] ?? 0);
+                if (difference !== 0)
+                    return difference > 0;
+            }
+            return false;
+        });
+    }
+    else
+        releases.reverse();
+    if (releases.length === 0)
+        return sinceVersion === undefined ? "No changelog entries found." : "";
+    return releases.map(release => release.markdown.replace(/(!?\[[^\]\n]+\]\()([^\s)]+)((?:\s+[^)]*)?\))/g, (_match, prefix, target, suffix) => `${prefix}${releaseLink(target, `v${release.version.join(".")}`)}${suffix}`)).join("\n\n");
+}
+function releaseLink(target, tag) {
+    const canonical = target
+        .replace(/^https:\/\/github\.com\/(?:badlogic|earendil-works)\/pi-mono(?=\/|$)/, REPOSITORY)
+        .replace(/^(https:\/\/github\.com\/earendil-works\/pi\/(?:blob|tree)\/)(?:main|master)\//, `$1${tag}/`);
+    if (/^(?:#|\/\/|[a-z][a-z0-9+.-]*:)/i.test(canonical))
+        return canonical;
+    const boundary = canonical.search(/[?#]/);
+    const path = boundary === -1 ? canonical : canonical.slice(0, boundary);
+    const suffix = boundary === -1 ? "" : canonical.slice(boundary);
+    if (!path)
+        return canonical;
+    const normalized = path.replaceAll("\\", "/");
+    const repositoryPath = posix.normalize(normalized.startsWith("/") ? normalized.replace(/^\/+/, "") : posix.join("packages/coding-agent", normalized));
+    if (repositoryPath === "." || repositoryPath === ".." || repositoryPath.startsWith("../"))
+        return canonical;
+    const route = path.endsWith("/") || !posix.basename(repositoryPath).includes(".") ? "tree" : "blob";
+    return `${REPOSITORY}/${route}/${tag}/${encodeURI(repositoryPath)}${suffix}`;
+}

package/dist/integrations/pi/engine/command-dispatch.d.ts

@@ -0,0 +1,41 @@
+import { type OwnedUiCommand, type OwnedUiCommandOutcome, type OwnedUiDiagnostics } from "../../../contracts/owned-ui/index.js";
+import type { PiEmittedEvent } from "./event-delivery.js";
+export interface AdapterCommandResult {
+    readonly outcome: OwnedUiCommandOutcome;
+    readonly diagnostic: string | null;
+}
+export interface PiCommandDispatchPorts {
+    sessionId(): string;
+    /** True before the runtime and session exist or after disposal: commands are rejected, not queued. */
+    notRunning(): boolean;
+    /** True while delivery is overloaded or admission is stopped. */
+    admissionStopped(): boolean;
+    /** Workflows currently admitted; they share the admission budget with commands. */
+    pendingWorkflowCount(): number;
+    sessionGeneration(): number;
+    beginRunning(): void;
+    endRunning(): void;
+    /** Carry out one admitted command against the engine; a throw becomes a failed outcome. */
+    perform(command: OwnedUiCommand): Promise<void>;
+    emit(value: PiEmittedEvent): void;
+    emitView(): void;
+    diagnostic(severity: OwnedUiDiagnostics["severity"], code: string, message: string, recoverable: boolean): void;
+}
+/**
+ * Admission and settlement of owned UI commands: the accepted/completed/failed/rejected outcome
+ * events, the bounded pending set with its out-of-band cancellation slot per command, the active
+ * ids the view reports, and the remembered results that make a retried correlation id idempotent.
+ * What a command does to the engine is the adapter's `perform` port.
+ */
+export declare class PiCommandDispatch {
+    #private;
+    constructor(ports: PiCommandDispatchPorts);
+    get activeCommandIds(): readonly string[];
+    get pendingCount(): number;
+    isPending(correlationId: string): boolean;
+    /** Resolve every admitted command as failed, except the listed types. */
+    cancelPending(except?: readonly OwnedUiCommand["type"][]): void;
+    /** Forget active ids and remembered results; a new session binding cannot inherit them. */
+    reset(): void;
+    execute(command: OwnedUiCommand): Promise<AdapterCommandResult>;
+}

package/dist/integrations/pi/engine/command-dispatch.js

@@ -0,0 +1,125 @@
+import { assertOwnedUiCommand } from "../../../contracts/owned-ui/index.js";
+/** How many commands and workflows may be admitted together before new work is rejected. */
+const MAX_PENDING_WORK = 32;
+/** Completed results remembered so a retried correlation id gets its original outcome. */
+const MAX_COMPLETED_COMMANDS = 256;
+/**
+ * Admission and settlement of owned UI commands: the accepted/completed/failed/rejected outcome
+ * events, the bounded pending set with its out-of-band cancellation slot per command, the active
+ * ids the view reports, and the remembered results that make a retried correlation id idempotent.
+ * What a command does to the engine is the adapter's `perform` port.
+ */
+export class PiCommandDispatch {
+    #ports;
+    #activeCommandIds = [];
+    #completedCommands = new Map();
+    #pendingCommands = new Map();
+    constructor(ports) {
+        this.#ports = ports;
+    }
+    get activeCommandIds() {
+        return this.#activeCommandIds;
+    }
+    get pendingCount() {
+        return this.#pendingCommands.size;
+    }
+    isPending(correlationId) {
+        return this.#pendingCommands.has(correlationId);
+    }
+    /** Resolve every admitted command as failed, except the listed types. */
+    cancelPending(except = []) {
+        for (const pending of this.#pendingCommands.values())
+            if (!except.includes(pending.type))
+                pending.cancel();
+    }
+    /** Forget active ids and remembered results; a new session binding cannot inherit them. */
+    reset() {
+        this.#activeCommandIds = [];
+        this.#completedCommands.clear();
+    }
+    async execute(command) {
+        assertOwnedUiCommand(command);
+        if (command.sessionId !== this.#ports.sessionId()) {
+            return this.#finishCommand(command, "rejected", "command targets a different owned session");
+        }
+        if (this.#ports.notRunning()) {
+            return this.#finishCommand(command, "rejected", "engine adapter is not running");
+        }
+        // Invariant: the bounded out-of-band cancellation path has one slot per admitted command.
+        if (this.#ports.admissionStopped() || this.#pendingCommands.size + this.#ports.pendingWorkflowCount() >= MAX_PENDING_WORK)
+            return { outcome: "rejected", diagnostic: null };
+        const existing = this.#completedCommands.get(command.correlationId);
+        if (existing)
+            return existing;
+        if (this.#activeCommandIds.includes(command.correlationId)) {
+            return this.#finishCommand(command, "rejected", "duplicate engine command correlation id");
+        }
+        this.#activeCommandIds.push(command.correlationId);
+        const generation = this.#ports.sessionGeneration();
+        let cancelled = false;
+        const cancellation = new Promise(resolve => {
+            this.#pendingCommands.set(command.correlationId, { type: command.type, cancel: () => {
+                    if (cancelled)
+                        return;
+                    cancelled = true;
+                    resolve(this.#recordCommand(command, "failed", null));
+                } });
+        });
+        this.#ports.emit({ type: "command-outcome", correlationId: command.correlationId, outcome: "accepted", diagnostic: null });
+        const operation = async () => {
+            try {
+                if (cancelled)
+                    return { outcome: "failed", diagnostic: null };
+                this.#ports.beginRunning();
+                try {
+                    await this.#ports.perform(command);
+                }
+                finally {
+                    this.#ports.endRunning();
+                }
+                if (cancelled)
+                    return { outcome: "failed", diagnostic: null };
+                if (generation === this.#ports.sessionGeneration())
+                    this.#ports.emitView();
+                if (cancelled)
+                    return { outcome: "failed", diagnostic: null };
+                return this.#recordCommand(command, "completed", null);
+            }
+            catch (error) {
+                if (cancelled)
+                    return { outcome: "failed", diagnostic: null };
+                const diagnostic = error instanceof Error ? error.message : String(error);
+                this.#ports.diagnostic("error", "engine-command", diagnostic, true);
+                if (generation === this.#ports.sessionGeneration())
+                    this.#ports.emitView();
+                return this.#recordCommand(command, "failed", diagnostic);
+            }
+        };
+        try {
+            return await Promise.race([operation(), cancellation]);
+        }
+        finally {
+            this.#pendingCommands.delete(command.correlationId);
+        }
+    }
+    #recordCommand(command, outcome, diagnostic) {
+        const result = this.#finishCommand(command, outcome, diagnostic);
+        this.#completedCommands.set(command.correlationId, result);
+        if (this.#completedCommands.size > MAX_COMPLETED_COMMANDS) {
+            const oldest = this.#completedCommands.keys().next().value;
+            if (oldest)
+                this.#completedCommands.delete(oldest);
+        }
+        return result;
+    }
+    #finishCommand(command, outcome, diagnostic) {
+        this.#activeCommandIds = this.#activeCommandIds.filter(id => id !== command.correlationId);
+        this.#ports.emit({
+            type: "command-outcome",
+            correlationId: command.correlationId,
+            outcome,
+            diagnostic,
+        });
+        return { outcome, diagnostic };
+    }
+}

package/dist/integrations/pi/engine/compaction-progress.d.ts

@@ -0,0 +1,28 @@
+/** Expected summary size for a first compaction, when no previous summary on the branch can serve as the estimate. */
+export declare const DEFAULT_EXPECTED_COMPACTION_SUMMARY_CHARS = 4000;
+/** The public session surface compaction progress reads: the agent's stream function and the branch entries. */
+export interface CompactionProgressSession {
+    readonly agent?: {
+        streamFunction?: unknown;
+    } | undefined;
+    readonly sessionManager?: {
+        getBranch?(): readonly unknown[];
+    } | undefined;
+}
+export interface CompactionProgressObserver {
+    /** Marks `compaction_start`: resets the streamed count and captures the expected summary size. */
+    begin(): void;
+    /** Marks `compaction_end`: later stream chunks are ignored. */
+    end(): void;
+    /** Restores the original stream function; the observer reports nothing afterwards. */
+    dispose(): void;
+}
+/**
+ * Observes the summarization stream of a compaction through the session agent's public stream
+ * function and reports an estimated integer percent. Pi never iterates that stream itself (it
+ * reads only its final result), so the observer iterates it in the background between
+ * `begin()` and `end()` and returns the same stream object to Pi. Outside that window the
+ * wrapper is a pass-through. Returns null when the agent exposes no callable stream function,
+ * in which case compaction proceeds without progress.
+ */
+export declare function observeCompactionProgress(session: CompactionProgressSession, onProgress: (percent: number) => void): CompactionProgressObserver | null;

package/dist/integrations/pi/engine/compaction-progress.js

@@ -0,0 +1,96 @@
+/** Expected summary size for a first compaction, when no previous summary on the branch can serve as the estimate. */
+export const DEFAULT_EXPECTED_COMPACTION_SUMMARY_CHARS = 4000;
+/** The percent shown while a compaction is still running never reaches this value. */
+const MAX_RUNNING_PERCENT = 99;
+/**
+ * Observes the summarization stream of a compaction through the session agent's public stream
+ * function and reports an estimated integer percent. Pi never iterates that stream itself (it
+ * reads only its final result), so the observer iterates it in the background between
+ * `begin()` and `end()` and returns the same stream object to Pi. Outside that window the
+ * wrapper is a pass-through. Returns null when the agent exposes no callable stream function,
+ * in which case compaction proceeds without progress.
+ */
+export function observeCompactionProgress(session, onProgress) {
+    const agent = session.agent;
+    if (agent === undefined || typeof agent.streamFunction !== "function")
+        return null;
+    const original = agent.streamFunction;
+    let active = false;
+    let disposed = false;
+    let generation = 0;
+    let streamed = 0;
+    let expected = DEFAULT_EXPECTED_COMPACTION_SUMMARY_CHARS;
+    let reported = null;
+    const report = () => {
+        const percent = Math.min(MAX_RUNNING_PERCENT, Math.floor((100 * streamed) / expected));
+        if (percent === reported)
+            return;
+        reported = percent;
+        onProgress(percent);
+    };
+    const wrapped = async (model, context, options) => {
+        const stream = await original(model, context, options);
+        if (!active || disposed)
+            return stream;
+        const observed = generation;
+        void (async () => {
+            report();
+            // Invariant: observation never affects the request; a stream that cannot be iterated ends observation only.
+            try {
+                for await (const event of stream) {
+                    if (observed !== generation || !active)
+                        return;
+                    if (event.type === "text_delta") {
+                        streamed += event.delta.length;
+                        report();
+                    }
+                }
+            }
+            catch {
+                return;
+            }
+        })();
+        return stream;
+    };
+    agent.streamFunction = wrapped;
+    return {
+        begin() {
+            generation += 1;
+            streamed = 0;
+            reported = null;
+            expected = latestCompactionSummaryLength(session) ?? DEFAULT_EXPECTED_COMPACTION_SUMMARY_CHARS;
+            active = true;
+        },
+        end() {
+            active = false;
+            generation += 1;
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            active = false;
+            generation += 1;
+            if (agent.streamFunction === wrapped)
+                agent.streamFunction = original;
+        },
+    };
+}
+function latestCompactionSummaryLength(session) {
+    let entries;
+    try {
+        entries = session.sessionManager?.getBranch?.() ?? [];
+    }
+    catch {
+        return null;
+    }
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const { type, summary } = entry;
+        if (type === "compaction" && typeof summary === "string" && summary.length > 0)
+            return summary.length;
+    }
+    return null;
+}

package/dist/integrations/pi/engine/conformance.d.ts

@@ -0,0 +1,39 @@
+export interface PiCapabilityConformanceResult {
+    readonly capability: string;
+    readonly operations: readonly string[];
+    readonly passed: boolean;
+}
+export declare const REQUIRED_PI_CAPABILITY_OPERATIONS: Readonly<{
+    readonly "public-exports": readonly ["services.create", "session.create", "runtime.create"];
+    readonly "session-lifecycle": readonly ["session.new", "session.resume", "session.rebind", "session.dispose"];
+    readonly "commands-events": readonly ["prompt", "steer", "followUp", "clearQueue", "abort", "compact", "setModel", "setThinkingLevel", "subscribe", "dispose"];
+    readonly "models-authentication": readonly ["models.list", "models.refresh", "models.completeSimple", "auth.status", "auth.login", "auth.logout", "auth.cancel"];
+    readonly settings: readonly ["settings.read", "settings.write", "settings.flush"];
+    readonly "resources-extensions": readonly ["resources.discover", "extensions.inline", "extensions.bind", "extensions.reload", "renderers.invoke"];
+    readonly workflows: readonly ["workflow.route", "workflow.validate", "workflow.diagnostics"];
+    readonly disposal: readonly ["subscription.dispose", "session.dispose", "services.cleanup"];
+}>;
+/** Identifies one required Pi capability operation that differs from the accepted integration contract. */
+export declare class PiCapabilityCompatibilityError extends Error {
+    readonly packageVersion: string;
+    readonly capability: string;
+    readonly operation: string;
+    constructor(packageVersion: string, capability: string, operation: string, detail: string);
+}
+export interface PiUpgradeConformanceReport {
+    readonly schema: "pi-engine-conformance-v1";
+    readonly packageName: "@earendil-works/pi-coding-agent";
+    readonly packageVersion: string;
+    readonly ownedUiContractVersion: number;
+    readonly serviceDiagnostics: number;
+    readonly sessionId: string;
+    readonly commandSurface: readonly string[];
+    readonly capabilities: readonly PiCapabilityConformanceResult[];
+}
+/** Identifies the public Pi SDK stage that failed during upgrade conformance. */
+export declare class PiUpgradeConformanceError extends Error {
+    readonly stage: "exports" | "services" | "session";
+    constructor(stage: "exports" | "services" | "session", cause: unknown);
+}
+export declare function runPiUpgradeConformance(): Promise<PiUpgradeConformanceReport>;
+export declare function validatePiCapabilityResults(packageVersion: string, results: readonly PiCapabilityConformanceResult[]): void;

package/dist/integrations/pi/engine/conformance.js

@@ -0,0 +1,140 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, ModelRuntime, SessionManager, VERSION, } from "@earendil-works/pi-coding-agent";
+import { OWNED_UI_CONTRACT_VERSION } from "../../../contracts/owned-ui/index.js";
+import { PRODUCT_IDENTITY } from "../../../product-identity.js";
+import { createWindowsNulCleanupExtension } from "./windows-filesystem-hygiene.js";
+export const REQUIRED_PI_CAPABILITY_OPERATIONS = Object.freeze({
+    "public-exports": ["services.create", "session.create", "runtime.create"],
+    "session-lifecycle": ["session.new", "session.resume", "session.rebind", "session.dispose"],
+    "commands-events": ["prompt", "steer", "followUp", "clearQueue", "abort", "compact", "setModel", "setThinkingLevel", "subscribe", "dispose"],
+    "models-authentication": ["models.list", "models.refresh", "models.completeSimple", "auth.status", "auth.login", "auth.logout", "auth.cancel"],
+    settings: ["settings.read", "settings.write", "settings.flush"],
+    "resources-extensions": ["resources.discover", "extensions.inline", "extensions.bind", "extensions.reload", "renderers.invoke"],
+    workflows: ["workflow.route", "workflow.validate", "workflow.diagnostics"],
+    disposal: ["subscription.dispose", "session.dispose", "services.cleanup"],
+});
+/** Identifies one required Pi capability operation that differs from the accepted integration contract. */
+export class PiCapabilityCompatibilityError extends Error {
+    packageVersion;
+    capability;
+    operation;
+    constructor(packageVersion, capability, operation, detail) {
+        super(`Pi ${packageVersion} capability ${capability} operation ${operation} is incompatible: ${detail}`);
+        this.packageVersion = packageVersion;
+        this.capability = capability;
+        this.operation = operation;
+        this.name = "PiCapabilityCompatibilityError";
+    }
+}
+/** Identifies the public Pi SDK stage that failed during upgrade conformance. */
+export class PiUpgradeConformanceError extends Error {
+    stage;
+    constructor(stage, cause) {
+        super(`Pi upgrade conformance failed during ${stage}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        this.stage = stage;
+        this.name = "PiUpgradeConformanceError";
+    }
+}
+export async function runPiUpgradeConformance() {
+    try {
+        if (typeof createAgentSessionRuntime !== "function"
+            || typeof createAgentSessionServices !== "function"
+            || typeof createAgentSessionFromServices !== "function"
+            || typeof ModelRuntime.create !== "function"
+            || typeof SessionManager.inMemory !== "function") {
+            throw new Error("required public SDK exports are missing");
+        }
+    }
+    catch (error) {
+        throw new PiUpgradeConformanceError("exports", error);
+    }
+    const root = await mkdtemp(join(tmpdir(), `${PRODUCT_IDENTITY.filesystem.temporaryPrefix}pi-conformance-`));
+    try {
+        let services;
+        try {
+            const modelRuntime = await ModelRuntime.create({
+                authPath: join(root, "agent", "auth.json"),
+                modelsPath: null,
+                refreshOnCreate: false,
+                allowModelNetwork: false,
+            });
+            const cleanupExtension = createWindowsNulCleanupExtension({ platform: "win32" });
+            if (cleanupExtension === null)
+                throw new Error("Windows NUL cleanup extension is unavailable");
+            services = await createAgentSessionServices({
+                cwd: root,
+                agentDir: join(root, "agent"),
+                modelRuntime,
+                resourceLoaderOptions: { extensionFactories: [cleanupExtension] },
+            });
+            if (!services.resourceLoader.getExtensions().extensions.some(extension => extension.path === "<inline:windows-nul-file-cleanup>")) {
+                throw new Error("named inline extension factory was not loaded");
+            }
+        }
+        catch (error) {
+            throw new PiUpgradeConformanceError("services", error);
+        }
+        let sessionId;
+        try {
+            const created = await createAgentSessionFromServices({
+                services,
+                sessionManager: SessionManager.inMemory(root),
+                noTools: "all",
+            });
+            const session = created.session;
+            sessionId = session.sessionId;
+            requireMethods(session, "session commands", ["prompt", "steer", "followUp", "clearQueue", "abort", "compact", "setModel", "setThinkingLevel", "subscribe", "dispose"]);
+            requireMethods(services.modelRuntime, "models/authentication", ["getModels", "getModel", "completeSimple", "checkAuth", "login", "logout", "refresh"]);
+            requireMethods(services.settingsManager, "settings", ["getGlobalSettings", "getProjectSettings", "flush"]);
+            requireMethods(services.resourceLoader, "resources/extensions", ["getExtensions", "getSkills", "getPrompts", "getThemes", "reload"]);
+            const unsubscribe = session.subscribe(() => undefined);
+            unsubscribe();
+            session.dispose();
+        }
+        catch (error) {
+            throw new PiUpgradeConformanceError("session", error);
+        }
+        const commandSurface = ["prompt", "steer", "followUp", "clearQueue", "abort", "compact", "setModel", "setThinkingLevel", "subscribe", "dispose"];
+        const capabilities = Object.entries(REQUIRED_PI_CAPABILITY_OPERATIONS)
+            .map(([capabilityName, operations]) => capability(capabilityName, operations));
+        validatePiCapabilityResults(VERSION, capabilities);
+        return {
+            schema: "pi-engine-conformance-v1",
+            packageName: "@earendil-works/pi-coding-agent",
+            packageVersion: VERSION,
+            ownedUiContractVersion: OWNED_UI_CONTRACT_VERSION,
+            serviceDiagnostics: services.diagnostics.length,
+            sessionId,
+            commandSurface,
+            capabilities,
+        };
+    }
+    finally {
+        await rm(root, { recursive: true, force: true });
+    }
+}
+function requireMethods(target, capabilityName, operations) {
+    const surface = target;
+    for (const operation of operations) {
+        if (typeof surface[operation] !== "function")
+            throw new Error(`${capabilityName}.${operation} is unavailable`);
+    }
+}
+function capability(capabilityName, operations) {
+    return { capability: capabilityName, operations, passed: true };
+}
+export function validatePiCapabilityResults(packageVersion, results) {
+    for (const [capabilityName, requiredOperations] of Object.entries(REQUIRED_PI_CAPABILITY_OPERATIONS)) {
+        const result = results.find(candidate => candidate.capability === capabilityName);
+        if (!result)
+            throw new PiCapabilityCompatibilityError(packageVersion, capabilityName, requiredOperations[0], "capability result is missing");
+        if (!result.passed)
+            throw new PiCapabilityCompatibilityError(packageVersion, capabilityName, requiredOperations[0], "capability reported failure");
+        for (const operation of requiredOperations) {
+            if (!result.operations.includes(operation))
+                throw new PiCapabilityCompatibilityError(packageVersion, capabilityName, operation, "required operation is missing");
+        }
+    }
+}

package/dist/integrations/pi/engine/event-delivery.d.ts

@@ -0,0 +1,100 @@
+import type { OwnedUiEvent, OwnedUiTranscriptBlock } from "../../../contracts/owned-ui/index.js";
+/** An event the adapter emits before delivery stamps it with the session id and sequence. */
+export type PiEmittedEvent = Omit<Extract<OwnedUiEvent, {
+    type: "session-lifecycle";
+}>, "sessionId" | "sequence"> | Omit<Extract<OwnedUiEvent, {
+    type: "session-view";
+}>, "sessionId" | "sequence"> | Omit<Extract<OwnedUiEvent, {
+    type: "transcript-block";
+}>, "sessionId" | "sequence"> | Omit<Extract<OwnedUiEvent, {
+    type: "assistant-message-completed";
+}>, "sessionId" | "sequence"> | Omit<Extract<OwnedUiEvent, {
+    type: "agent-run-started";
+}>, "sessionId" | "sequence"> | Omit<Extract<OwnedUiEvent, {
+    type: "agent-run-settled";
+}>, "sessionId" | "sequence"> | Omit<Extract<OwnedUiEvent, {
+    type: "editor-state";
+}>, "sessionId" | "sequence"> | Omit<Extract<OwnedUiEvent, {
+    type: "status";
+}>, "sessionId" | "sequence"> | Omit<Extract<OwnedUiEvent, {
+    type: "command-outcome";
+}>, "sessionId" | "sequence"> | Omit<Extract<OwnedUiEvent, {
+    type: "terminal-surface";
+}>, "sessionId" | "sequence"> | Omit<Extract<OwnedUiEvent, {
+    type: "diagnostic";
+}>, "sessionId" | "sequence">;
+/** A command outcome held back during an overload so its command can still settle after recovery. */
+export interface ReservedCommandOutcome {
+    readonly outcome: Extract<OwnedUiEvent, {
+        type: "command-outcome";
+    }>["outcome"];
+    readonly diagnostic: Extract<OwnedUiEvent, {
+        type: "command-outcome";
+    }>["diagnostic"];
+}
+export interface PiEventDeliveryPorts {
+    sessionId(): string;
+    sessionGeneration(): number;
+    /** The current block for a lazily materialized transcript event. */
+    transcriptBlock(id: string): OwnedUiTranscriptBlock | undefined;
+    /** Retain the image assets an event references until the returned release runs. */
+    retainEvent(event: OwnedUiEvent): () => void;
+    /** Whether a command outcome still has an admitted command waiting for it. */
+    isPendingCommand(correlationId: string): boolean;
+    /** Cancel admitted work when the queue saturates; resolves once the engine session aborted. */
+    cancelForOverload(): Promise<void>;
+    /** Rebuild session state once the saturated queue drained; `cancelled` says whether the abort completed. */
+    reconcileOverload(cancelled: boolean): Promise<void>;
+    /** A listener threw; the adapter records the warning. */
+    listenerFailed(message: string): void;
+}
+/**
+ * Bounded delivery of owned UI events: stamps sequence numbers, keeps subscribers, queues events
+ * through the replaceable pending buffer, yields to the event loop between batches, and when the
+ * buffer saturates declares an overload that the adapter reconciles once the queue drains. The
+ * adapter decides what an event means; this class decides only when it reaches a listener.
+ */
+export declare class PiEventDelivery {
+    #private;
+    constructor(ports: PiEventDeliveryPorts);
+    /** The sequence number of the most recently stamped event. */
+    get sequence(): number;
+    /** True from queue saturation until the adapter's reconciliation ends. */
+    get overloaded(): boolean;
+    /** True once a listener threw or the queue saturated, until the adapter clears it after a flush. */
+    get failed(): boolean;
+    clearFailure(): void;
+    /** Developer-only pressure evidence; never mirrored into visible diagnostic/status arrays. */
+    diagnostics(): {
+        overloads: number;
+        recovering: boolean;
+        reservedOutcomes: number;
+        invalidatedEvents: number;
+        pending: number;
+        bytes: number;
+        protected: number;
+        superseded: number;
+        peakNodes: number;
+        peakBytes: number;
+    };
+    /** Give an event its session id and the next sequence number without queueing it. */
+    stamp(value: PiEmittedEvent): OwnedUiEvent;
+    /** Register a listener that first receives `initial` and afterwards every later-stamped event. */
+    subscribe(listener: (event: OwnedUiEvent) => void, initial: OwnedUiEvent): () => void;
+    /** Stamp and queue an event for ordered delivery. */
+    emit(value: PiEmittedEvent): OwnedUiEvent;
+    /** Queue an already stamped event; during an overload only pending command outcomes are kept, as reservations. */
+    enqueue(event: OwnedUiEvent): void;
+    /** Freeze lazy snapshots before their source is replaced; false means the queue saturated. */
+    seal(): boolean;
+    /** Drop queued events from earlier session generations. */
+    discardObsolete(generation: number): void;
+    /** Enter the bounded overload transition; a no-op while one is already in progress. */
+    beginOverload(): void;
+    /** Deliver out of band, bypassing the queue; used for reconciliation after an overload. */
+    deliverNow(event: OwnedUiEvent): void;
+    /** The command outcomes reserved during an overload, in arrival order; clears the reservation. */
+    takeReservedOutcomes(): [string, ReservedCommandOutcome][];
+    /** Resolves once every queued event has been delivered or invalidated. */
+    settle(): Promise<void>;
+}