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

package/dist/integrations/pi/engine/event-delivery.js

@@ -0,0 +1,184 @@
+import { PendingEngineDelivery } from "./pending-delivery.js";
+/**
+ * Engine events delivered before the queue hands the event loop a turn. Small enough
+ * that a streaming burst never holds input, large enough that an ordinary turn is one
+ * batch.
+ */
+// Performance: deliver at most one engine event per event-loop turn. Transcript updates can
+// be expensive in long sessions; a larger synchronous batch starves terminal
+// input and makes an in-progress mouse selection appear frozen.
+const EVENT_DELIVERY_BATCH = 1;
+const OVERLOAD_CANCELLATION_TIMEOUT_MS = 2000;
+/**
+ * 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 class PiEventDelivery {
+    #listeners = new Map();
+    #queue;
+    #reservedOutcomes = new Map();
+    #ports;
+    #sequence = 0;
+    #processing;
+    #overload;
+    #overloads = 0;
+    #deliveryFailed = false;
+    #invalidatedEvents = 0;
+    constructor(ports) {
+        this.#ports = ports;
+        this.#queue = new PendingEngineDelivery(event => ports.retainEvent(event));
+    }
+    /** The sequence number of the most recently stamped event. */
+    get sequence() {
+        return this.#sequence;
+    }
+    /** True from queue saturation until the adapter's reconciliation ends. */
+    get overloaded() {
+        return this.#overload !== undefined;
+    }
+    /** True once a listener threw or the queue saturated, until the adapter clears it after a flush. */
+    get failed() {
+        return this.#deliveryFailed;
+    }
+    clearFailure() {
+        this.#deliveryFailed = false;
+    }
+    /** Developer-only pressure evidence; never mirrored into visible diagnostic/status arrays. */
+    diagnostics() {
+        return { ...this.#queue.diagnostics(), overloads: this.#overloads, recovering: this.overloaded,
+            reservedOutcomes: this.#reservedOutcomes.size, invalidatedEvents: this.#invalidatedEvents };
+    }
+    /** Give an event its session id and the next sequence number without queueing it. */
+    stamp(value) {
+        this.#sequence += 1;
+        return { ...value, sessionId: this.#ports.sessionId(), sequence: this.#sequence };
+    }
+    /** Register a listener that first receives `initial` and afterwards every later-stamped event. */
+    subscribe(listener, initial) {
+        this.#listeners.set(listener, initial.sequence);
+        listener(initial);
+        return () => this.#listeners.delete(listener);
+    }
+    /** Stamp and queue an event for ordered delivery. */
+    emit(value) {
+        const event = this.stamp(value);
+        this.enqueue(event);
+        return event;
+    }
+    /** Queue an already stamped event; during an overload only pending command outcomes are kept, as reservations. */
+    enqueue(event) {
+        if (this.#overload !== undefined) {
+            if (event.type === "command-outcome" && event.outcome !== "accepted" && this.#ports.isPendingCommand(event.correlationId)) {
+                this.#reservedOutcomes.set(event.correlationId, { outcome: event.outcome, diagnostic: event.diagnostic });
+            }
+            return;
+        }
+        if (!this.#queue.push(event, this.#ports.sessionGeneration(), event.type === "transcript-block"
+            ? this.#blockReconciliation(event.block.id, event.sequence) : undefined)) {
+            this.beginOverload();
+            if (event.type === "command-outcome" && event.outcome !== "accepted" && this.#ports.isPendingCommand(event.correlationId)
+                && !this.#reservedOutcomes.has(event.correlationId)) {
+                this.#reservedOutcomes.set(event.correlationId, { outcome: event.outcome, diagnostic: event.diagnostic });
+            }
+        }
+        this.#processing ??= Promise.resolve().then(() => this.#processQueue());
+    }
+    // Performance: capture only identity, not the complete block/event retained by an earlier revision.
+    #blockReconciliation(id, sequence) {
+        return () => ({ type: "transcript-block", sessionId: this.#ports.sessionId(), sequence, block: this.#ports.transcriptBlock(id) });
+    }
+    /** Freeze lazy snapshots before their source is replaced; false means the queue saturated. */
+    seal() {
+        return this.#queue.seal();
+    }
+    /** Drop queued events from earlier session generations. */
+    discardObsolete(generation) {
+        this.#invalidatedEvents += this.#queue.discardObsolete(generation);
+    }
+    /** Enter the bounded overload transition; a no-op while one is already in progress. */
+    beginOverload() {
+        if (this.#overload !== undefined)
+            return;
+        this.#overloads = Math.min(Number.MAX_SAFE_INTEGER, this.#overloads + 1);
+        this.#deliveryFailed = true;
+        // Concurrency: reserve before cancellation; outcomes produced reentrantly must not enter the saturated queue.
+        this.#overload = Promise.resolve(false);
+        const cancellation = this.#ports.cancelForOverload();
+        this.#overload = new Promise(resolve => {
+            const timer = setTimeout(() => resolve(false), OVERLOAD_CANCELLATION_TIMEOUT_MS);
+            cancellation.then(() => {
+                clearTimeout(timer);
+                resolve(true);
+            }, () => { clearTimeout(timer); resolve(false); });
+        });
+    }
+    /** Deliver out of band, bypassing the queue; used for reconciliation after an overload. */
+    deliverNow(event) {
+        for (const [listener, subscribedAt] of this.#listeners) {
+            if (event.sequence <= subscribedAt)
+                continue;
+            try {
+                listener(event);
+            }
+            catch (error) {
+                this.#deliveryFailed = true;
+                this.#ports.listenerFailed(error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    /** The command outcomes reserved during an overload, in arrival order; clears the reservation. */
+    takeReservedOutcomes() {
+        const reserved = [...this.#reservedOutcomes];
+        this.#reservedOutcomes.clear();
+        return reserved;
+    }
+    /** Resolves once every queued event has been delivered or invalidated. */
+    async settle() {
+        while (this.#processing)
+            await this.#processing;
+    }
+    async #processQueue() {
+        try {
+            let deliveredSinceYield = 0;
+            while (this.#queue.size > 0) {
+                const pending = this.#queue.shift();
+                if (pending === undefined)
+                    continue;
+                if (pending.generation !== this.#ports.sessionGeneration() && pending.event.type !== "command-outcome") {
+                    this.#invalidatedEvents = Math.min(Number.MAX_SAFE_INTEGER, this.#invalidatedEvents + 1);
+                    pending.release?.();
+                    continue;
+                }
+                try {
+                    this.deliverNow(pending.event);
+                }
+                finally {
+                    pending.release?.();
+                }
+                deliveredSinceYield += 1;
+                // Concurrency: a microtask chain runs to exhaustion before the loop turns, so a streaming
+                // burst would hold typed input, pointer reports, and timed indicators until it
+                // drained. Yielding on a macrotask hands those their turn between batches.
+                if (deliveredSinceYield >= EVENT_DELIVERY_BATCH && this.#queue.size > 0) {
+                    deliveredSinceYield = 0;
+                    await new Promise(resolve => { setImmediate(resolve); });
+                }
+            }
+            if (this.#overload !== undefined) {
+                const cancelled = await this.#overload;
+                await this.#ports.reconcileOverload(cancelled);
+                // Invariant: an outcome reserved while reconciliation replayed the earlier ones is dropped with the overload.
+                this.#reservedOutcomes.clear();
+                this.#overload = undefined;
+            }
+        }
+        finally {
+            this.#processing = undefined;
+            if (this.#queue.size > 0) {
+                this.#processing = Promise.resolve().then(() => this.#processQueue());
+            }
+        }
+    }
+}

package/dist/integrations/pi/engine/extension-ui-binding.d.ts

@@ -0,0 +1,35 @@
+import type { AgentSession } from "../startup-public.js";
+import { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, type OwnedUiDiagnostics } from "../../../contracts/owned-ui/index.js";
+export interface OwnedPiVisualExtensionSupport {
+    readonly available: boolean;
+    readonly contractComplete: true;
+    readonly contractVersion: typeof OWNED_UI_EXTENSION_CONTRACT_VERSION;
+    readonly binding: "bound" | "unbound";
+    readonly uiCallbacks: typeof OWNED_UI_EXTENSION_UI_CALLBACKS;
+    readonly uiProperties: typeof OWNED_UI_EXTENSION_UI_PROPERTIES;
+    readonly renderCallbacks: typeof OWNED_UI_EXTENSION_RENDER_CALLBACKS;
+    readonly diagnostic: string;
+}
+export interface PiExtensionUiBindingPorts {
+    session(): AgentSession | undefined;
+    diagnostic(severity: OwnedUiDiagnostics["severity"], code: string, message: string, recoverable: boolean): void;
+    emitView(): void;
+}
+/**
+ * The owned extension UI bridge's attachment to pinned Pi sessions: the bridge the shell hands
+ * over, whether the current session is bound to it, and the rebind that every new session needs.
+ * Extension errors surface as adapter diagnostics through the ports.
+ */
+export declare class PiExtensionUiBinding {
+    #private;
+    constructor(ports: PiExtensionUiBindingPorts);
+    /** True while a bridge is attached, bound or not. */
+    get attached(): boolean;
+    support(): OwnedPiVisualExtensionSupport;
+    /** Attach the owned extension UI bridge and bind it to the current session. */
+    bind(ui: unknown, shutdown?: () => void | Promise<void>): Promise<void>;
+    /** Detach the bridge; the next session binding will not rebind it. */
+    unbind(): Promise<void>;
+    /** Bind the attached bridge to the current session, reporting failures as diagnostics. */
+    rebind(): Promise<void>;
+}

package/dist/integrations/pi/engine/extension-ui-binding.js

@@ -0,0 +1,81 @@
+import { PRODUCT_IDENTITY } from "../../../product-identity.js";
+import { isRecord } from "./message-values.js";
+import { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, assertOwnedUiExtensionUiPort, } from "../../../contracts/owned-ui/index.js";
+/**
+ * The owned extension UI bridge's attachment to pinned Pi sessions: the bridge the shell hands
+ * over, whether the current session is bound to it, and the rebind that every new session needs.
+ * Extension errors surface as adapter diagnostics through the ports.
+ */
+export class PiExtensionUiBinding {
+    #ports;
+    #extensionUi;
+    #extensionShutdown;
+    #extensionBound = false;
+    constructor(ports) {
+        this.#ports = ports;
+    }
+    /** True while a bridge is attached, bound or not. */
+    get attached() {
+        return this.#extensionUi !== undefined;
+    }
+    support() {
+        return {
+            available: this.#extensionBound,
+            contractComplete: true,
+            contractVersion: OWNED_UI_EXTENSION_CONTRACT_VERSION,
+            binding: this.#extensionBound ? "bound" : "unbound",
+            uiCallbacks: OWNED_UI_EXTENSION_UI_CALLBACKS,
+            uiProperties: OWNED_UI_EXTENSION_UI_PROPERTIES,
+            renderCallbacks: OWNED_UI_EXTENSION_RENDER_CALLBACKS,
+            diagnostic: this.#extensionBound
+                ? `Pinned public extension UI lifecycle is bound through the ${PRODUCT_IDENTITY.displayName}-owned bridge.`
+                : `The complete ${PRODUCT_IDENTITY.displayName}-owned extension UI contract is available; the active session has not been bound to the owned UI bridge.`,
+        };
+    }
+    /** Attach the owned extension UI bridge and bind it to the current session. */
+    async bind(ui, shutdown) {
+        assertPiExtensionUiContext(ui);
+        this.#extensionUi = ui;
+        this.#extensionShutdown = shutdown;
+        await this.rebind();
+    }
+    /** Detach the bridge; the next session binding will not rebind it. */
+    async unbind() {
+        this.#extensionUi = undefined;
+        this.#extensionShutdown = undefined;
+        this.#extensionBound = false;
+    }
+    /** Bind the attached bridge to the current session, reporting failures as diagnostics. */
+    async rebind() {
+        const session = this.#ports.session();
+        const ui = this.#extensionUi;
+        if (session === undefined || ui === undefined || session.bindExtensions === undefined) {
+            this.#extensionBound = false;
+            return;
+        }
+        try {
+            await session.bindExtensions({
+                uiContext: ui,
+                mode: "tui",
+                shutdownHandler: () => this.#extensionShutdown?.(),
+                onError: error => {
+                    const message = isRecord(error) && typeof error.error === "string"
+                        ? error.error
+                        : error instanceof Error ? error.message : String(error);
+                    this.#ports.diagnostic("warning", "extension-ui", message, true);
+                    this.#ports.emitView();
+                },
+            });
+            this.#extensionBound = true;
+            this.#ports.emitView();
+        }
+        catch (error) {
+            this.#extensionBound = false;
+            this.#ports.diagnostic("error", "extension-ui-bind", error instanceof Error ? error.message : String(error), true);
+            this.#ports.emitView();
+        }
+    }
+}
+function assertPiExtensionUiContext(value) {
+    assertOwnedUiExtensionUiPort(value);
+}

package/dist/integrations/pi/engine/http-dispatcher.d.ts

@@ -0,0 +1,4 @@
+/** Apply the profile's HTTP timeout to npm undici and its fetch globals. */
+export declare function configureOwnedHttpDispatcher(timeoutMs: number): void;
+/** Test and diagnostics seam; reports configured semantics, not the max-int implementation detail. */
+export declare function configuredOwnedHttpIdleTimeoutMs(): number | null;

package/dist/integrations/pi/engine/http-dispatcher.js

@@ -0,0 +1,25 @@
+// Provenance: mechanically adapted from Pi commit 914cf14
+// packages/coding-agent/src/core/http-dispatcher.ts (MIT).
+// Local modifications: expose only A1's owned timeout seam and retain no private Pi imports.
+import { EnvHttpProxyAgent, install, setGlobalDispatcher } from "undici";
+const MAX_DISABLED_TIMEOUT_MS = 2_147_483_647;
+let configuredTimeoutMs = null;
+/** Apply the profile's HTTP timeout to npm undici and its fetch globals. */
+export function configureOwnedHttpDispatcher(timeoutMs) {
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0)
+        throw new TypeError("HTTP idle timeout is invalid");
+    const effectiveTimeoutMs = timeoutMs === 0 ? MAX_DISABLED_TIMEOUT_MS : timeoutMs;
+    const dispatcher = new EnvHttpProxyAgent({
+        allowH2: false,
+        bodyTimeout: effectiveTimeoutMs,
+        headersTimeout: effectiveTimeoutMs,
+        connect: { autoSelectFamilyAttemptTimeout: 2_000 },
+    });
+    setGlobalDispatcher(dispatcher);
+    install?.();
+    configuredTimeoutMs = timeoutMs;
+}
+/** Test and diagnostics seam; reports configured semantics, not the max-int implementation detail. */
+export function configuredOwnedHttpIdleTimeoutMs() {
+    return configuredTimeoutMs;
+}

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

@@ -0,0 +1,18 @@
+export { EngineDeliveryError, PiEngineAdapter, createPiEngineAdapter } from "./adapter.js";
+export type { AdapterCommandResult, OwnedPiExtensionResourceSummary, OwnedPiExtensionSourceSummary, OwnedPiResourceSummary, OwnedPiVisualExtensionSupport, PiEngineAdapterOptions, PiEngineRuntimeFactory, PiEngineRuntimeFactoryInput, } from "./adapter.js";
+export { bindPiRuntimeSession, createPiRuntimeIntegration, createPiRuntimeServicesAfterTrust, disposePiRuntimeIntegration, replacePiRuntimeSession, resolveConfiguredModelScope, } from "./runtime-integration.js";
+export type { PiRuntimeIntegrationOptions, PiRuntimePreflightDependencies, PiSessionReplacement } from "./runtime-integration.js";
+export { PiSessionSelectionError, openSelectedPiSession, resolveSessionArgumentPath } from "./session-selection.js";
+export type { PiSessionForkPrompt, PiSessionSelection } from "./session-selection.js";
+export { PiSessionCommandIntegration, convertPiSessionEvent, subscribeToPiSessionEvents } from "./session-integration.js";
+export type { PiDocumentedSessionCommands, PiOrderedEventIntegration, PiSessionCommand, PiSessionCommandResult } from "./session-integration.js";
+export { AUTOMATIC_THEME, EXPOSED_SETTING_KEYS, PI_SETTING_EFFECTS, PiSettingsBridge, PiSettingsCoordinator, parseAutomaticTheme, settingsEffectInventoryDrift, settingsInventoryDrift, settingsVisualInventoryViolations, } from "./settings-bridge.js";
+export { assertPiSettingsMetadata, loadPiSettingsMetadata, PI_SETTINGS_METADATA_FILE } from "./settings-metadata.js";
+export type { PiSettingBounds, PiSettingPresentation, PiSettingsMetadata } from "./settings-metadata.js";
+export type { PiSettingEffectDefinition, PiSettingEffectHandler, PiSettingKey, PiSettingOwnerHandlers, PiSettingStorageOperation, PiSettingVisualClass, PiSettingVisualEvidence, PiSettingsCoordinatorOptions, PiSettingsModelChoice, PiSettingsProviders, } from "./settings-bridge.js";
+export { resolvePiProjectTrustPreflight } from "./project-trust-preflight.js";
+export type { PiProjectTrustPreflightPrompt, PiProjectTrustPreflightRequest, PiProjectTrustPreflightResult, ResolvePiProjectTrustPreflightOptions, } from "./project-trust-preflight.js";
+export { configureOwnedHttpDispatcher, configuredOwnedHttpIdleTimeoutMs } from "./http-dispatcher.js";
+export { createPiPackagesPort } from "./package-integration.js";
+export { PINNED_PI_HIDDEN_COMMAND_NAMES, PINNED_PI_SETTINGS_CALLBACKS, PINNED_PI_WORKFLOW_COMMAND_NAMES } from "./workflows.js";
+export type { PiAuthenticationProviderOption, PiAuthenticationProviderStatus, PiBashWorkflowResult, PiHiddenWorkflowCommandName, PiPinnedSettingsCallback, PiPinnedSettingsSnapshot, PiProjectTrustContext, PiProjectTrustUpdate, PiScopedModelDescriptor, PiScopedModelsContext, PiScopedModelsRefreshResult, PiSessionInfoPresentation, PiSessionResumeMetadata, PiSessionSelectorContext, PiTreeSelectorContext, PiWorkflowAutocompleteCommand, PiWorkflowCommandName, PiWorkflowHost, PiWorkflowInteractionHost, PiWorkflowInteractionRequest, PiWorkflowLoginNotification, PiWorkflowLoginStart, PiWorkflowMessage, PiWorkflowMessageKind, PiWorkflowOption, PiWorkflowOutcome, PiWorkflowPresentation, PiWorkflowRequest, PiWorkflowResult, PiWorkflowRoute, } from "./workflows.js";

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

@@ -0,0 +1,10 @@
+export { EngineDeliveryError, PiEngineAdapter, createPiEngineAdapter } from "./adapter.js";
+export { bindPiRuntimeSession, createPiRuntimeIntegration, createPiRuntimeServicesAfterTrust, disposePiRuntimeIntegration, replacePiRuntimeSession, resolveConfiguredModelScope, } from "./runtime-integration.js";
+export { PiSessionSelectionError, openSelectedPiSession, resolveSessionArgumentPath } from "./session-selection.js";
+export { PiSessionCommandIntegration, convertPiSessionEvent, subscribeToPiSessionEvents } from "./session-integration.js";
+export { AUTOMATIC_THEME, EXPOSED_SETTING_KEYS, PI_SETTING_EFFECTS, PiSettingsBridge, PiSettingsCoordinator, parseAutomaticTheme, settingsEffectInventoryDrift, settingsInventoryDrift, settingsVisualInventoryViolations, } from "./settings-bridge.js";
+export { assertPiSettingsMetadata, loadPiSettingsMetadata, PI_SETTINGS_METADATA_FILE } from "./settings-metadata.js";
+export { resolvePiProjectTrustPreflight } from "./project-trust-preflight.js";
+export { configureOwnedHttpDispatcher, configuredOwnedHttpIdleTimeoutMs } from "./http-dispatcher.js";
+export { createPiPackagesPort } from "./package-integration.js";
+export { PINNED_PI_HIDDEN_COMMAND_NAMES, PINNED_PI_SETTINGS_CALLBACKS, PINNED_PI_WORKFLOW_COMMAND_NAMES } from "./workflows.js";

package/dist/integrations/pi/engine/message-values.d.ts

@@ -0,0 +1,29 @@
+/** Pure readers over Pi's untyped session messages and the blocks projected from them. */
+import type { OwnedUiModelInfo, OwnedUiThinkingLevel, OwnedUiTranscriptBlock } from "../../../contracts/owned-ui/index.js";
+export declare function stringValue(value: unknown): string | undefined;
+export declare function messageFallbackKey(message: unknown, fallbackIndex: number): string;
+/** A later error may restate a declaration, but cannot make completed arguments incomplete. */
+export declare function retainCompletedArguments(current: OwnedUiTranscriptBlock, next: OwnedUiTranscriptBlock): OwnedUiTranscriptBlock;
+/**
+ * Whether two blocks say the same thing. A block that says what it already said is not a
+ * new revision: the shell renders a block once per revision, so bumping one it did not
+ * need re-renders it for nothing.
+ */
+export declare function sameBlockContent(left: OwnedUiTranscriptBlock, right: OwnedUiTranscriptBlock): boolean;
+export declare function sameValue(left: unknown, right: unknown): boolean;
+export declare function textFromContent(content: unknown): string;
+export declare function assistantContent(content: readonly unknown[]): readonly Record<string, unknown>[];
+export declare function contentImageCount(content: unknown): number;
+export declare function jsonSummary(value: unknown): {
+    readonly summary: string;
+    readonly json: unknown;
+};
+export declare function sanitizeJson(value: unknown, depth?: number): unknown;
+export declare function finiteNumber(value: unknown): number;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function dynamicObject(value: unknown, key?: string): Record<string, unknown>;
+export declare function requireCapability<T>(capability: T | undefined, name: string): T;
+export declare function readModel(value: unknown): OwnedUiModelInfo | null;
+export declare function readThinkingLevel(value: unknown): OwnedUiThinkingLevel;
+export declare function stringProperty(value: unknown, key: string): string | undefined;
+export declare function readStringArray(value: unknown): readonly string[];

package/dist/integrations/pi/engine/message-values.js

@@ -0,0 +1,168 @@
+export function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+export function messageFallbackKey(message, fallbackIndex) {
+    if (!isRecord(message))
+        return `message-unknown-${fallbackIndex}`;
+    const timestamp = typeof message.timestamp === "number" && Number.isSafeInteger(message.timestamp)
+        ? message.timestamp
+        : `index-${fallbackIndex}`;
+    return `message-${stringValue(message.role) ?? "unknown"}-${timestamp}`;
+}
+/** A later error may restate a declaration, but cannot make completed arguments incomplete. */
+export function retainCompletedArguments(current, next) {
+    if (current.toolState?.argsComplete !== true || next.toolState === undefined || next.toolState.argsComplete)
+        return next;
+    return { ...next, toolState: { ...next.toolState, argsComplete: true },
+        ...(next.toolRendering === undefined || current.toolRendering === undefined ? {} : {
+            toolRendering: { ...next.toolRendering, arguments: current.toolRendering.arguments },
+        }),
+        payload: { ...(isRecord(next.payload) ? next.payload : {}), argsComplete: true } };
+}
+/**
+ * Whether two blocks say the same thing. A block that says what it already said is not a
+ * new revision: the shell renders a block once per revision, so bumping one it did not
+ * need re-renders it for nothing.
+ */
+export function sameBlockContent(left, right) {
+    return left.kind === right.kind
+        && left.status === right.status
+        && left.title === right.title
+        && left.text === right.text
+        && sameValue(left.toolState, right.toolState)
+        && sameValue(left.toolRendering, right.toolRendering)
+        && sameValue(left.payload, right.payload)
+        && sameValue(left.imageReferences ?? [], right.imageReferences ?? []);
+}
+export function sameValue(left, right) {
+    if (left === right)
+        return true;
+    if (typeof left !== typeof right || left === null || right === null)
+        return false;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length)
+            return false;
+        return left.every((value, index) => sameValue(value, right[index]));
+    }
+    if (typeof left !== "object")
+        return false;
+    const leftKeys = Object.keys(left);
+    const rightRecord = right;
+    if (leftKeys.length !== Object.keys(rightRecord).length)
+        return false;
+    return leftKeys.every(key => Object.hasOwn(rightRecord, key) && sameValue(left[key], rightRecord[key]));
+}
+export function textFromContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map(item => isRecord(item) && item.type === "text" ? stringValue(item.text) ?? "" : "")
+        .filter(text => text.length > 0)
+        .join("\n");
+}
+export function assistantContent(content) {
+    const result = [];
+    for (const item of content) {
+        if (!isRecord(item))
+            continue;
+        if (item.type === "text")
+            result.push({ type: "text", text: stringValue(item.text) ?? "" });
+        else if (item.type === "thinking") {
+            result.push({
+                type: "thinking",
+                thinking: stringValue(item.thinking) ?? "",
+                ...(item.redacted === true ? { redacted: true } : {}),
+            });
+        }
+        else if (item.type === "toolCall") {
+            result.push({
+                type: "toolCall",
+                id: stringValue(item.id) ?? "",
+                name: stringValue(item.name) ?? "unknown",
+                arguments: sanitizeJson(item.arguments),
+            });
+        }
+    }
+    return result;
+}
+export function contentImageCount(content) {
+    return Array.isArray(content)
+        ? content.filter(item => isRecord(item) && item.type === "image").length
+        : 0;
+}
+export function jsonSummary(value) {
+    const json = sanitizeJson(value);
+    let summary = "";
+    try {
+        summary = JSON.stringify(json);
+    }
+    catch {
+        summary = String(value);
+    }
+    if (summary.length > 512)
+        summary = `${summary.slice(0, 509)}...`;
+    return { summary, json };
+}
+export function sanitizeJson(value, depth = 0) {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (value === null || ["string", "number", "boolean"].includes(typeof value))
+        return value;
+    if (depth >= 8)
+        return "[truncated]";
+    if (Array.isArray(value))
+        return value.slice(0, 100).map(item => sanitizeJson(item, depth + 1));
+    if (isRecord(value)) {
+        const output = {};
+        for (const [key, item] of Object.entries(value).slice(0, 100)) {
+            output[key] = sanitizeJson(item, depth + 1);
+        }
+        return output;
+    }
+    return String(value);
+}
+export function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+export function dynamicObject(value, key) {
+    const candidate = key === undefined ? value : isRecord(value) ? value[key] : undefined;
+    return isRecord(candidate) ? candidate : {};
+}
+export function requireCapability(capability, name) {
+    if (typeof capability !== "function")
+        throw new Error(`Pi workflow capability is unavailable: ${name}`);
+    return capability;
+}
+export function readModel(value) {
+    if (!isRecord(value))
+        return null;
+    const providerId = stringValue(value.provider) ?? stringValue(value.providerId);
+    const modelId = stringValue(value.id) ?? stringValue(value.modelId);
+    if (!providerId || !modelId)
+        return null;
+    return {
+        providerId,
+        modelId,
+        displayName: stringValue(value.name) ?? modelId,
+    };
+}
+export function readThinkingLevel(value) {
+    return value === "off" || value === "minimal" || value === "low" || value === "medium"
+        || value === "high" || value === "xhigh"
+        ? value
+        : "medium";
+}
+export function stringProperty(value, key) {
+    if (!isRecord(value))
+        return undefined;
+    const item = value[key];
+    return typeof item === "string" && item.length > 0 ? item : undefined;
+}
+export function readStringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}

package/dist/integrations/pi/engine/package-integration.d.ts

@@ -0,0 +1,13 @@
+import { type AgentPackagesPort, type AgentPackagesPortInput } from "../../../contracts/agent-engine/index.js";
+/**
+ * Pinned Pi's package manager already takes the profile root as an argument, so
+ * this binds it to the root A1 chose rather than to whatever the configuration-root
+ * environment variable happens to say. Pi's own package command handler is not used:
+ * it prints Pi's command names and ends the process, and both of those belong to
+ * whichever A1 command is running.
+ *
+ * The settings manager is created with project trust withheld, which is what keeps
+ * every operation to the user scope of the selected profile — a project-local
+ * `packages` list is never read, so it can never be written either.
+ */
+export declare function createPiPackagesPort(input: AgentPackagesPortInput): AgentPackagesPort;