@timurproko/a1 0.1.8-dev.de7821a → 0.2.0

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

@@ -0,0 +1,53 @@
+import { createAgentSessionServices, SettingsManager, type AgentSession, type AgentSessionRuntime, type AgentSessionServices, type ScopedModel } from "../startup-public.js";
+import { resolvePiProjectTrustPreflight, type PiProjectTrustPreflightPrompt } from "./project-trust-preflight.js";
+import { type PiSessionForkPrompt, type PiSessionSelection } from "./session-selection.js";
+export interface PiRuntimeIntegrationOptions {
+    readonly cwd: string;
+    readonly agentDir: string;
+    readonly sessionDir?: string;
+    readonly sessionPath?: string;
+    readonly sessionSelection?: PiSessionSelection;
+    readonly sessionForkPrompt?: PiSessionForkPrompt;
+    readonly projectTrustPrompt?: PiProjectTrustPreflightPrompt;
+    readonly preflightDependencies?: PiRuntimePreflightDependencies;
+}
+export interface PiRuntimePreflightDependencies {
+    readonly resolveTrust?: typeof resolvePiProjectTrustPreflight;
+    readonly createSettingsManager?: (cwd: string, agentDir: string, projectTrusted: boolean) => SettingsManager;
+    readonly createServices?: typeof createAgentSessionServices;
+}
+export type PiSessionReplacement = {
+    readonly kind: "new";
+} | {
+    readonly kind: "resume";
+    readonly sessionPath: string;
+};
+interface ConfiguredModelScope {
+    readonly scopedModels: readonly ScopedModel[];
+    readonly model: ScopedModel["model"] | undefined;
+    readonly thinkingLevel: ScopedModel["thinkingLevel"];
+    readonly diagnostics: readonly {
+        type: "info" | "warning" | "error";
+        message: string;
+    }[];
+}
+/**
+ * Mirrors pinned Pi's CLI startup: resolve the `models` patterns from settings
+ * into a scoped model list, keep the resolver's warnings (e.g. "No models match
+ * pattern ..."), and pick the same initial model pinned Pi would pick — the
+ * saved default when it is in scope, otherwise the first scoped model.
+ */
+export declare function resolveConfiguredModelScope(services: Pick<AgentSessionServices, "settingsManager" | "modelRuntime">): Promise<ConfiguredModelScope>;
+export declare function createPiRuntimeServicesAfterTrust(options: Pick<PiRuntimeIntegrationOptions, "agentDir" | "projectTrustPrompt" | "preflightDependencies"> & {
+    readonly cwd: string;
+}): Promise<{
+    readonly services: AgentSessionServices;
+    readonly trust: Awaited<ReturnType<typeof resolvePiProjectTrustPreflight>>;
+}>;
+export declare function createPiRuntimeIntegration(options: PiRuntimeIntegrationOptions): Promise<AgentSessionRuntime>;
+export declare function bindPiRuntimeSession(runtime: AgentSessionRuntime, rebind: (session: AgentSession) => Promise<void>): () => void;
+export declare function replacePiRuntimeSession(runtime: AgentSessionRuntime, replacement: PiSessionReplacement): Promise<{
+    readonly cancelled: boolean;
+}>;
+export declare function disposePiRuntimeIntegration(runtime: AgentSessionRuntime): Promise<void>;
+export {};

package/dist/integrations/pi/engine/runtime-integration.js

@@ -0,0 +1,118 @@
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, resolveModelScopeWithDiagnostics, SessionManager, SettingsManager, } from "../startup-public.js";
+import { resolvePiProjectTrustPreflight, } from "./project-trust-preflight.js";
+import { openSelectedPiSession, resolveSessionArgumentPath } from "./session-selection.js";
+import { markStartupPhase } from "../../../foundation/startup/startup-runtime.js";
+import { createWindowsNulCleanupExtension } from "./windows-filesystem-hygiene.js";
+/**
+ * Mirrors pinned Pi's CLI startup: resolve the `models` patterns from settings
+ * into a scoped model list, keep the resolver's warnings (e.g. "No models match
+ * pattern ..."), and pick the same initial model pinned Pi would pick — the
+ * saved default when it is in scope, otherwise the first scoped model.
+ */
+export async function resolveConfiguredModelScope(services) {
+    const patterns = services.settingsManager.getEnabledModels();
+    if (!patterns || patterns.length === 0) {
+        return { scopedModels: [], model: undefined, thinkingLevel: undefined, diagnostics: [] };
+    }
+    const { scopedModels, diagnostics } = await resolveModelScopeWithDiagnostics([...patterns], services.modelRuntime, { signal: AbortSignal.timeout(15_000) });
+    let selected;
+    if (scopedModels.length > 0) {
+        const savedProvider = services.settingsManager.getDefaultProvider();
+        const savedModelId = services.settingsManager.getDefaultModel();
+        const savedModel = savedProvider && savedModelId
+            ? services.modelRuntime.getModel(savedProvider, savedModelId)
+            : undefined;
+        selected = (savedModel
+            ? scopedModels.find(scoped => scoped.model.provider === savedModel.provider && scoped.model.id === savedModel.id)
+            : undefined) ?? scopedModels[0];
+    }
+    return {
+        scopedModels,
+        model: selected?.model,
+        thinkingLevel: selected?.thinkingLevel,
+        diagnostics: diagnostics.map(diagnostic => ({ type: diagnostic.type, message: diagnostic.message })),
+    };
+}
+export async function createPiRuntimeServicesAfterTrust(options) {
+    const resolveTrust = options.preflightDependencies?.resolveTrust ?? resolvePiProjectTrustPreflight;
+    const createSettingsManager = options.preflightDependencies?.createSettingsManager
+        ?? ((targetCwd, agentDir, projectTrusted) => SettingsManager.create(targetCwd, agentDir, { projectTrusted }));
+    const createServices = options.preflightDependencies?.createServices ?? createAgentSessionServices;
+    const trust = await resolveTrust({
+        cwd: options.cwd,
+        agentDir: options.agentDir,
+        ...(options.projectTrustPrompt === undefined ? {} : { prompt: options.projectTrustPrompt }),
+    });
+    const settingsManager = createSettingsManager(options.cwd, options.agentDir, trust.trusted);
+    await markStartupPhase(process.env, "settings-loaded");
+    const cleanupExtension = createWindowsNulCleanupExtension();
+    const services = await createServices({
+        cwd: options.cwd,
+        agentDir: options.agentDir,
+        settingsManager,
+        ...(cleanupExtension === null ? {} : {
+            resourceLoaderOptions: { extensionFactories: [cleanupExtension] },
+        }),
+    });
+    await markStartupPhase(process.env, "pi-services");
+    await markStartupPhase(process.env, "resource-discovery");
+    return { services, trust };
+}
+export async function createPiRuntimeIntegration(options) {
+    const directory = options.sessionDir ?? process.env.PI_CODING_AGENT_SESSION_DIR;
+    const sessionDir = directory === undefined ? undefined : resolveSessionArgumentPath(directory, options.cwd);
+    const selection = options.sessionSelection ?? (options.sessionPath === undefined ? undefined : { target: resolveSessionArgumentPath(options.sessionPath, options.cwd) });
+    const sessionManager = selection === undefined
+        ? SessionManager.create(options.cwd, sessionDir)
+        : await openSelectedPiSession({
+            cwd: options.cwd, selection,
+            ...(sessionDir === undefined ? {} : { sessionDir }),
+            ...(options.sessionForkPrompt === undefined ? {} : { forkPrompt: options.sessionForkPrompt }),
+        });
+    const createRuntime = async ({ cwd, sessionManager: targetSessionManager, sessionStartEvent, }) => {
+        const { services, trust } = await createPiRuntimeServicesAfterTrust({
+            cwd,
+            agentDir: options.agentDir,
+            ...(options.projectTrustPrompt === undefined ? {} : { projectTrustPrompt: options.projectTrustPrompt }),
+            ...(options.preflightDependencies === undefined ? {} : { preflightDependencies: options.preflightDependencies }),
+        });
+        const modelScope = await resolveConfiguredModelScope(services);
+        const hasExistingSession = targetSessionManager.buildSessionContext().messages.length > 0;
+        const created = await createAgentSessionFromServices({
+            services,
+            sessionManager: targetSessionManager,
+            ...(sessionStartEvent ? { sessionStartEvent } : {}),
+            ...(modelScope.model && !hasExistingSession ? { model: modelScope.model } : {}),
+            ...(modelScope.thinkingLevel && !hasExistingSession ? { thinkingLevel: modelScope.thinkingLevel } : {}),
+            ...(modelScope.scopedModels.length > 0 ? { scopedModels: [...modelScope.scopedModels] } : {}),
+        });
+        await markStartupPhase(process.env, "session-created");
+        return {
+            ...created,
+            services,
+            diagnostics: [
+                ...(trust.diagnostic === null ? [] : [{ type: "warning", message: trust.diagnostic }]),
+                ...modelScope.diagnostics,
+            ],
+        };
+    };
+    return createAgentSessionRuntime(createRuntime, {
+        cwd: sessionManager.getCwd(),
+        agentDir: options.agentDir,
+        sessionManager,
+    });
+}
+export function bindPiRuntimeSession(runtime, rebind) {
+    runtime.setRebindSession(rebind);
+    return () => runtime.setRebindSession(undefined);
+}
+export async function replacePiRuntimeSession(runtime, replacement) {
+    return replacement.kind === "new"
+        ? runtime.newSession()
+        : runtime.switchSession(replacement.sessionPath);
+}
+export async function disposePiRuntimeIntegration(runtime) {
+    runtime.setRebindSession(undefined);
+    runtime.setBeforeSessionInvalidate(undefined);
+    await runtime.dispose();
+}

package/dist/integrations/pi/engine/session-events.d.ts

@@ -0,0 +1,48 @@
+import { type OwnedUiModelInfo, type OwnedUiThinkingLevel, type OwnedUiTranscriptBlock } from "../../../contracts/owned-ui/index.js";
+import type { PiEmittedEvent } from "./event-delivery.js";
+import type { PiTranscriptProjection } from "./transcript-projection.js";
+export interface PiSessionEventPorts {
+    sessionGeneration(): number;
+    /** The session-authoritative messages, read at settlement. */
+    sessionMessages(): readonly unknown[];
+    activeModel(): OwnedUiModelInfo | null;
+    /** Replace the projected transcript behind the delivery seal. */
+    replaceTranscript(blocks: OwnedUiTranscriptBlock[]): void;
+    emit(value: PiEmittedEvent): void;
+    emitView(): void;
+    /** The session became busy with the named work; the adapter publishes lifecycle and status. */
+    enterWork(message: string): void;
+    /** Every work state ended; the adapter publishes the ready lifecycle and a cleared status. */
+    leaveWork(): void;
+    /** Compaction progress for the status view, in whole percent. */
+    workProgress(percent: number): void;
+    /** The engine's queued steering and follow-up submissions changed. */
+    queueChanged(queuedSubmissions: readonly string[]): void;
+    thinkingLevelChanged(level: OwnedUiThinkingLevel): void;
+    /** Usage moved at a message or lifecycle boundary; the memoized usage view is stale. */
+    usageInvalidated(): void;
+    compactionStarted(): void;
+    compactionEnded(): void;
+    deliverQueuedAfterCompaction(): void;
+}
+/**
+ * Translates pinned Pi's session events into transcript projection updates, run and response
+ * sequencing, work-state transitions, and the semantic owned UI events (run started, message
+ * completed, run settled). It owns the run counters and the current work-state kind; the adapter
+ * owns the lifecycle, status, editor, and model state the ports write.
+ */
+export declare class PiSessionEvents {
+    #private;
+    constructor(projection: PiTranscriptProjection, ports: PiSessionEventPorts);
+    /** Increments at each agent start within the bound session. */
+    get runSequence(): number;
+    /** Increments at each completed assistant message within the bound session. */
+    get responseSequence(): number;
+    /** A new session was bound: no run is active and the counters restart. */
+    reset(): void;
+    /** The run was abandoned by overload recovery; the counters keep their values so stale suggestions stay stale. */
+    abandonRun(): void;
+    compactionProgress(percent: number): void;
+    /** Apply one pinned Pi session event; image assets no block references any more are released afterwards. */
+    handle(event: unknown): void;
+}

package/dist/integrations/pi/engine/session-events.js

@@ -0,0 +1,223 @@
+import { isRecord, readStringArray, readThinkingLevel, stringValue, textFromContent } from "./message-values.js";
+import { transcriptToolState } from "../../../contracts/owned-ui/index.js";
+/**
+ * Translates pinned Pi's session events into transcript projection updates, run and response
+ * sequencing, work-state transitions, and the semantic owned UI events (run started, message
+ * completed, run settled). It owns the run counters and the current work-state kind; the adapter
+ * owns the lifecycle, status, editor, and model state the ports write.
+ */
+export class PiSessionEvents {
+    #projection;
+    #ports;
+    #agentRunActive = false;
+    #agentRunSequence = 0;
+    #assistantResponseSequence = 0;
+    #statusKind = null;
+    constructor(projection, ports) {
+        this.#projection = projection;
+        this.#ports = ports;
+    }
+    /** Increments at each agent start within the bound session. */
+    get runSequence() {
+        return this.#agentRunSequence;
+    }
+    /** Increments at each completed assistant message within the bound session. */
+    get responseSequence() {
+        return this.#assistantResponseSequence;
+    }
+    /** A new session was bound: no run is active and the counters restart. */
+    reset() {
+        this.#agentRunActive = false;
+        this.#agentRunSequence = 0;
+        this.#assistantResponseSequence = 0;
+        this.#statusKind = null;
+    }
+    /** The run was abandoned by overload recovery; the counters keep their values so stale suggestions stay stale. */
+    abandonRun() {
+        this.#agentRunActive = false;
+        this.#statusKind = null;
+    }
+    // Invariant: the named work state is the only state a matching end may clear.
+    #enterWorkState(kind, message) {
+        this.#statusKind = kind;
+        this.#ports.enterWork(message);
+    }
+    // Invariant: ending retry or compaction cannot clear a different active work state.
+    #endWorkState(kind) {
+        if (this.#statusKind !== kind)
+            return;
+        if (this.#agentRunActive) {
+            this.#enterWorkState("working", "Working");
+            return;
+        }
+        this.#leaveWorkStates();
+    }
+    #leaveWorkStates() {
+        this.#statusKind = null;
+        this.#ports.leaveWork();
+    }
+    // Invariant: progress belongs to the compaction state only and is published when the integer changes.
+    compactionProgress(percent) {
+        if (this.#statusKind !== "compaction")
+            return;
+        this.#ports.workProgress(percent);
+    }
+    /** Apply one pinned Pi session event; image assets no block references any more are released afterwards. */
+    handle(event) {
+        try {
+            this.#applyPiEvent(event);
+        }
+        finally {
+            this.#projection.assets.discardUnowned();
+        }
+    }
+    #applyPiEvent(event) {
+        if (!isRecord(event) || typeof event.type !== "string")
+            return;
+        // Invariant: usage moves at message and lifecycle boundaries, not with stream chunks, so the
+        // two streaming event kinds keep the memo and everything else drops it.
+        if (event.type !== "message_update" && event.type !== "tool_execution_update")
+            this.#ports.usageInvalidated();
+        switch (event.type) {
+            case "agent_start":
+                this.#agentRunActive = true;
+                this.#agentRunSequence += 1;
+                this.#ports.emit({ type: "agent-run-started" });
+                this.#enterWorkState("working", "Working");
+                return;
+            case "message_start":
+                this.#projection.upsertMessage(event.message, "live");
+                return;
+            case "message_update": {
+                const delta = isRecord(event.assistantMessageEvent) && typeof event.assistantMessageEvent.delta === "string"
+                    ? event.assistantMessageEvent.delta
+                    : undefined;
+                // Invariant: the delta is folded in before the block is stored, so a chunk is one update to
+                // one block rather than a store without the delta followed by a store with it.
+                const blocks = this.#projection.messageBlocks(event.message, "live", this.#projection.blocks.length);
+                for (const [index, block] of blocks.entries()) {
+                    this.#projection.upsert(index === 0 && delta !== undefined && !block.text.endsWith(delta)
+                        ? { ...block, text: `${block.text}${delta}` }
+                        : block);
+                }
+                return;
+            }
+            case "message_end":
+                this.#projection.upsertMessage(event.message, "finalized");
+                this.#projection.settleFailedDeclarations(event.message);
+                // Compatibility: preserve the same semantic boundary v2 counted. Transcript block
+                // finalization is intentionally not a substitute: rebuilds, retries,
+                // thinking parts, and tool rows can all finalize independently.
+                if (isRecord(event.message) && event.message.role === "assistant") {
+                    this.#assistantResponseSequence += 1;
+                    const content = Array.isArray(event.message.content) ? event.message.content : [];
+                    const stopReason = stringValue(event.message.stopReason) ?? null;
+                    const toolContinuation = stopReason === "toolUse"
+                        || content.some(item => isRecord(item) && item.type === "toolCall");
+                    const successful = stringValue(event.message.errorMessage) === undefined
+                        && stopReason !== "error"
+                        && stopReason !== "aborted"
+                        && textFromContent(content).trim().length > 0;
+                    this.#ports.emit({
+                        type: "assistant-message-completed",
+                        sessionGeneration: this.#ports.sessionGeneration(),
+                        runSequence: this.#agentRunSequence,
+                        responseSequence: this.#assistantResponseSequence,
+                        model: this.#ports.activeModel(),
+                        assistantMessageCount: this.#projection.blocks.filter(block => block.kind === "assistant").length,
+                        successful,
+                        stopReason,
+                        toolContinuation,
+                    });
+                }
+                return;
+            case "turn_end":
+                this.#projection.upsertMessage(event.message, "finalized");
+                if (Array.isArray(event.toolResults)) {
+                    for (const result of event.toolResults)
+                        this.#projection.upsertMessage(result, "finalized");
+                }
+                return;
+            case "tool_execution_start":
+            case "tool_execution_end": {
+                this.#projection.upsertToolExecution(event);
+                return;
+            }
+            case "tool_execution_update":
+                this.#projection.upsertToolExecution(event);
+                return;
+            case "agent_settled":
+            case "agent_end": {
+                if (event.type === "agent_end" && event.willRetry === true)
+                    return;
+                // Protocol: agent_end is run-local; only settlement reads the complete session scope.
+                const finalMessages = event.type === "agent_settled"
+                    ? this.#ports.sessionMessages()
+                    : Array.isArray(event.messages) ? event.messages : [];
+                if (event.type === "agent_end")
+                    this.#projection.mergeRun(finalMessages, this.#ports.sessionMessages());
+                else if (finalMessages.length > 0)
+                    this.#ports.replaceTranscript(this.#projection.rebuild(finalMessages, "finalized"));
+                // Invariant: missing final messages must not erase accumulated content or invent tool outcomes.
+                if (finalMessages.length === 0)
+                    this.#ports.replaceTranscript(this.#projection.blocks.map(block => block.status === "live" && transcriptToolState(block) === undefined
+                        ? { ...block, status: "finalized", revision: block.revision + 1 } : block));
+                // Compatibility: ending a turn leaves the working state, as the recorded pinned baseline does, but
+                // it leaves only that state: a compaction or retry being shown outlives the turn
+                // that ended under it. Settlement ends the run, and with it every state — the
+                // engine ends a turn for each continuation it makes and settles once.
+                if (event.type === "agent_settled") {
+                    this.#agentRunActive = false;
+                    this.#leaveWorkStates();
+                }
+                else if (this.#statusKind === null || this.#statusKind === "working") {
+                    this.#leaveWorkStates();
+                }
+                this.#ports.emitView();
+                if (event.type === "agent_settled") {
+                    const assistants = finalMessages.filter(message => isRecord(message) && message.role === "assistant");
+                    const lastAssistant = assistants.at(-1);
+                    const successful = lastAssistant !== undefined
+                        && stringValue(lastAssistant.errorMessage) === undefined
+                        && stringValue(lastAssistant.stopReason) !== "error"
+                        && stringValue(lastAssistant.stopReason) !== "aborted";
+                    this.#ports.emit({
+                        type: "agent-run-settled",
+                        sessionGeneration: this.#ports.sessionGeneration(),
+                        runSequence: this.#agentRunSequence,
+                        responseSequence: this.#assistantResponseSequence,
+                        model: this.#ports.activeModel(),
+                        assistantMessageCount: assistants.length,
+                        successful,
+                    });
+                }
+                return;
+            }
+            case "queue_update": {
+                this.#ports.queueChanged([...readStringArray(event.steering), ...readStringArray(event.followUp)]);
+                return;
+            }
+            case "auto_retry_start":
+                this.#enterWorkState("retry", "Retrying");
+                return;
+            case "auto_retry_end":
+                this.#endWorkState("retry");
+                return;
+            case "compaction_start":
+                this.#enterWorkState("compaction", "Compacting");
+                this.#ports.compactionStarted();
+                return;
+            case "compaction_end":
+                this.#ports.compactionEnded();
+                this.#endWorkState("compaction");
+                if (event.reason === "manual")
+                    this.#ports.deliverQueuedAfterCompaction();
+                return;
+            case "thinking_level_changed":
+                this.#ports.thinkingLevelChanged(readThinkingLevel(event.level));
+                return;
+            default:
+                return;
+        }
+    }
+}

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

@@ -0,0 +1,67 @@
+import type { AgentSession, AgentSessionEvent, PromptOptions } from "../startup-public.js";
+import { type AgentCommandOutcome, type AgentEvent } from "../../../contracts/agent-engine/index.js";
+type PiPromptImages = NonNullable<PromptOptions["images"]>;
+export interface PiDocumentedSessionCommands {
+    readonly isStreaming: AgentSession["isStreaming"];
+    readonly isRetrying: AgentSession["isRetrying"];
+    readonly isCompacting: AgentSession["isCompacting"];
+    prompt(text: string, options?: Parameters<AgentSession["prompt"]>[1]): Promise<void>;
+    steer(text: string, images?: PiPromptImages): Promise<void>;
+    followUp(text: string, images?: PiPromptImages): Promise<void>;
+    abort(): Promise<void>;
+    abortRetry(): void;
+    abortCompaction(): void;
+    compact(customInstructions?: Parameters<AgentSession["compact"]>[0]): Promise<unknown>;
+    clearQueue(): {
+        readonly steering: readonly string[];
+        readonly followUp: readonly string[];
+    };
+    executeBash?(command: string, onChunk: unknown, options: {
+        readonly excludeFromContext: boolean;
+    }): Promise<unknown>;
+    /** Optional: extension commands cannot be queued, so they run immediately during compaction as in pinned Pi. */
+    readonly extensionRunner?: {
+        getCommand(name: string): unknown;
+    } | undefined;
+}
+export type PiSessionCommand = {
+    readonly type: "prompt" | "steer" | "follow-up";
+    readonly text: string;
+    readonly images?: PiPromptImages;
+} | {
+    readonly type: "abort" | "retry" | "compact";
+} | {
+    readonly type: "bash";
+    readonly command: string;
+    readonly excludeFromContext: boolean;
+    readonly onChunk?: (chunk: string) => void;
+};
+export interface PiSessionCommandResult {
+    readonly outcome: AgentCommandOutcome;
+    readonly value?: unknown;
+}
+/** Routes neutral session commands to Pi while preserving Pi streaming and retry semantics. */
+export declare class PiSessionCommandIntegration {
+    #private;
+    private readonly session;
+    constructor(session: PiDocumentedSessionCommands);
+    execute(command: PiSessionCommand): Promise<PiSessionCommandResult>;
+    /**
+     * Delivers the messages queued during a manual compaction. The session is idle when a manual
+     * compaction ends, so nothing would consume the queue: the first message starts one run
+     * through the ordinary prompt path with its mode, and the rest are re-queued for that run,
+     * whose initial poll injects them in order. Automatic compaction needs no delivery: its
+     * continuing run or pending prompt consumes the queue itself. The run is not awaited; when
+     * the start is refused before the message is accepted, the queue is restored and the error
+     * reported through `onFailure`.
+     */
+    deliverQueuedAfterCompaction(onFailure: (error: unknown) => void): Promise<void>;
+    /** Forgets the attachments kept for queued messages; the queue itself was cleared by the caller. */
+    forgetQueuedImages(): void;
+}
+export interface PiOrderedEventIntegration {
+    dispose(): void;
+}
+export declare function subscribeToPiSessionEvents(session: Pick<AgentSession, "subscribe">, sessionId: string, emit: (event: AgentEvent) => void, malformed: (diagnostic: string) => void): PiOrderedEventIntegration;
+export declare function convertPiSessionEvent(event: AgentSessionEvent, sessionId: string, sequence: number): AgentEvent | null;
+export {};