@timurproko/a1 0.1.8-dev.235df0e → 0.1.8-dev.260

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/conformance.d.ts

@@ -13,6 +13,7 @@ export declare const REQUIRED_PI_CAPABILITY_OPERATIONS: Readonly<{
     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;
@@ -29,6 +30,7 @@ export interface PiUpgradeConformanceReport {
     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);

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/conformance.js

@@ -2,8 +2,8 @@ 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 "../owned-ui-contracts/index.js";
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { OWNED_UI_CONTRACT_VERSION } from "../../../contracts/owned-ui/index.js";
+import { PRODUCT_IDENTITY } from "../../../product-identity.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"],
@@ -14,6 +14,7 @@ export const REQUIRED_PI_CAPABILITY_OPERATIONS = Object.freeze({
     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;
@@ -26,6 +27,7 @@ export class PiCapabilityCompatibilityError extends Error {
         this.name = "PiCapabilityCompatibilityError";
     }
 }
+/** Identifies the public Pi SDK stage that failed during upgrade conformance. */
 export class PiUpgradeConformanceError extends Error {
     stage;
     constructor(stage, cause) {

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/{src/foundation/pi-engine-adapter → integrations/pi/engine}/index.d.ts

@@ -1,9 +1,13 @@
 export * from "./adapter.js";
 export * from "./conformance.js";
 export * from "./runtime-integration.js";
+export * from "./session-selection.js";
 export * from "./session-integration.js";
 export * from "./model-auth-integration.js";
 export * from "./settings-integration.js";
+export * from "./settings-effects.js";
+export * from "./project-trust-preflight.js";
+export * from "./http-dispatcher.js";
 export * from "./package-integration.js";
 export * from "./resource-extension-integration.js";
 export * from "./workflow-controllers.js";

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/index.js

@@ -1,9 +1,13 @@
 export * from "./adapter.js";
 export * from "./conformance.js";
 export * from "./runtime-integration.js";
+export * from "./session-selection.js";
 export * from "./session-integration.js";
 export * from "./model-auth-integration.js";
 export * from "./settings-integration.js";
+export * from "./settings-effects.js";
+export * from "./project-trust-preflight.js";
+export * from "./http-dispatcher.js";
 export * from "./package-integration.js";
 export * from "./resource-extension-integration.js";
 export * from "./workflow-controllers.js";

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/model-auth-integration.d.ts

@@ -1,5 +1,5 @@
 import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
-import type { AgentAuthenticationPort, AgentModelDescriptor, AgentModelPort } from "../agent-engine-contracts/index.js";
+import type { AgentAuthenticationPort, AgentModelDescriptor, AgentModelPort } from "../../../contracts/agent-engine/index.js";
 export type PiDocumentedModelRuntime = Pick<ModelRuntime, "getAvailableSnapshot" | "getModel" | "getProvider" | "hasConfiguredAuth" | "refresh" | "logout">;
 export interface PiModelAuthenticationOptions {
     readonly runtime: PiDocumentedModelRuntime;
@@ -9,6 +9,7 @@ export interface PiModelAuthenticationOptions {
     readonly timeoutMs?: number;
     readonly scopedModelIds?: () => readonly string[] | undefined;
 }
+/** Adapts the pinned model runtime to neutral model selection and authentication operations. */
 export declare class PiModelAuthenticationIntegration implements AgentModelPort, AgentAuthenticationPort {
     #private;
     private readonly options;

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/model-auth-integration.js

@@ -1,3 +1,4 @@
+/** Adapts the pinned model runtime to neutral model selection and authentication operations. */
 export class PiModelAuthenticationIntegration {
     options;
     capabilities = { selection: true, refresh: true, scopedCatalog: true, login: true, logout: true };

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/package-integration.d.ts

@@ -1,4 +1,4 @@
-import { type AgentPackagesPort, type AgentPackagesPortInput } from "../agent-engine-contracts/index.js";
+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

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/package-integration.js

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { DefaultPackageManager, ModelRuntime, SettingsManager } from "@earendil-works/pi-coding-agent";
-import { agentPackageOutcome, } from "../agent-engine-contracts/index.js";
+import { agentPackageOutcome, } from "../../../contracts/agent-engine/index.js";
 const MODEL_REFRESH_TIMEOUT_MS = 15_000;
 /**
  * Pinned Pi's package manager already takes the profile root as an argument, so
@@ -15,21 +15,33 @@ const MODEL_REFRESH_TIMEOUT_MS = 15_000;
  */
 export function createPiPackagesPort(input) {
     const { profileRoot, cwd } = input;
-    const settingsManager = SettingsManager.create(cwd, profileRoot, { projectTrusted: false });
-    const packageManager = new DefaultPackageManager({ cwd, agentDir: profileRoot, settingsManager });
-    packageManager.setProgressCallback(event => {
-        if (event.type !== "start" || !event.message)
-            return;
-        input.onProgress?.({ operation: operationFor(event.action), message: event.message });
-    });
-    const configured = () => packageManager.listConfiguredPackages()
+    // Compatibility: model-only refresh bypasses package settings and their diagnostics, as Pi does.
+    let packageManager;
+    const manager = () => {
+        if (packageManager)
+            return packageManager;
+        const settingsManager = SettingsManager.create(cwd, profileRoot, { projectTrusted: false });
+        for (const { scope, error } of settingsManager.drainErrors()) {
+            input.onDiagnostic?.({
+                message: `Warning (package command, ${scope} settings): ${error.message}`,
+                ...(error.stack ? { detail: error.stack } : {}),
+            });
+        }
+        packageManager = new DefaultPackageManager({ cwd, agentDir: profileRoot, settingsManager });
+        packageManager.setProgressCallback(event => {
+            if (event.type !== "start")
+                return;
+            input.onProgress?.({ operation: operationFor(event.action), message: String(event.message) });
+        });
+        return packageManager;
+    };
+    const configured = () => manager().listConfiguredPackages()
         .filter(entry => entry.scope === "user")
         .map(entry => Object.freeze({
         source: entry.source,
         installedPath: entry.installedPath ?? null,
         filtered: entry.filtered,
     }));
-    const isConfigured = (source) => configured().some(entry => entry.source === source || entry.source.startsWith(`${source}@`));
     return Object.freeze({
         capabilities: Object.freeze({ install: true, remove: true, update: true, refreshModels: true }),
         profileRoot,
@@ -38,13 +50,13 @@ export function createPiPackagesPort(input) {
         },
         async install(source) {
             return await attempt("install", source, async () => {
-                await packageManager.installAndPersist(source);
+                await manager().installAndPersist(source);
                 return agentPackageOutcome("install", "completed", null, source, configured());
             });
         },
         async remove(source) {
             return await attempt("remove", source, async () => {
-                const removed = await packageManager.removeAndPersist(source);
+                const removed = await manager().removeAndPersist(source);
                 if (!removed)
                     return agentPackageOutcome("remove", "not-found", null, source);
                 return agentPackageOutcome("remove", "completed", null, source, configured());
@@ -52,11 +64,8 @@ export function createPiPackagesPort(input) {
         },
         async update(source) {
             return await attempt("update", source ?? null, async () => {
-                // Asking first keeps "that package is not installed here" a structural
-                // answer rather than a string a caller would have to recognize.
-                if (source !== undefined && !isConfigured(source))
-                    return agentPackageOutcome("update", "not-found", null, source);
-                await packageManager.update(source);
+                // Compatibility: Pi owns source identity and its contextual no-match suggestions.
+                await manager().update(source);
                 return agentPackageOutcome("update", "completed", null, source ?? null, configured());
             });
         },
@@ -73,7 +82,9 @@ async function attempt(operation, source, run) {
         return await run();
     }
     catch (error) {
-        return agentPackageOutcome(operation, "failed", describe(error), source);
+        const detail = error instanceof Error ? error.message : operation === "refresh-models"
+            ? "Unknown model catalog refresh error" : "Unknown package command error";
+        return agentPackageOutcome(operation, "failed", detail, source);
     }
 }
 async function refreshModelCatalogs(profileRoot) {
@@ -88,9 +99,10 @@ async function refreshModelCatalogs(profileRoot) {
         });
         const result = await modelRuntime.refresh({ allowNetwork: true, force: true, signal: controller.signal });
         if (result.aborted)
-            throw new Error(`model catalog refresh timed out after ${MODEL_REFRESH_TIMEOUT_MS}ms`);
+            throw new Error("Model catalog refresh timed out.");
         if (result.errors.size > 0) {
-            throw new Error(Array.from(result.errors, ([provider, error]) => `${provider}: ${error.message}`).join("; "));
+            const details = Array.from(result.errors, ([provider, error]) => `${provider}: ${error.message}`).join("; ");
+            throw new Error(`Could not refresh model catalogs: ${details}`);
         }
     }
     finally {
@@ -104,9 +116,3 @@ function operationFor(action) {
         return "remove";
     return "update";
 }
-function describe(error) {
-    const message = (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ").trim();
-    if (message.length === 0)
-        return "unknown package failure";
-    return message.length > 600 ? `${message.slice(0, 597)}...` : message;
-}

package/dist/integrations/pi/engine/project-trust-preflight.d.ts

@@ -0,0 +1,22 @@
+export interface PiProjectTrustPreflightRequest {
+    readonly cwd: string;
+    readonly defaultDecision: "ask" | "always" | "never";
+}
+export type PiProjectTrustPreflightPrompt = (request: PiProjectTrustPreflightRequest) => Promise<boolean | null>;
+export interface PiProjectTrustPreflightResult {
+    readonly trusted: boolean;
+    readonly source: "no-project-resources" | "saved" | "default" | "interactive" | "fail-closed";
+    readonly diagnostic: string | null;
+}
+export interface ResolvePiProjectTrustPreflightOptions {
+    readonly cwd: string;
+    readonly agentDir: string;
+    readonly prompt?: PiProjectTrustPreflightPrompt;
+    readonly hasProjectResources?: (cwd: string) => boolean;
+}
+/**
+ * Resolves trust from global state only. It never constructs a project-trusted
+ * settings manager or resource loader; callers may do that only after this
+ * result exists.
+ */
+export declare function resolvePiProjectTrustPreflight(options: ResolvePiProjectTrustPreflightOptions): Promise<PiProjectTrustPreflightResult>;

package/dist/integrations/pi/engine/project-trust-preflight.js

@@ -0,0 +1,50 @@
+import { hasTrustRequiringProjectResources, ProjectTrustStore, SettingsManager, } from "@earendil-works/pi-coding-agent";
+/**
+ * Resolves trust from global state only. It never constructs a project-trusted
+ * settings manager or resource loader; callers may do that only after this
+ * result exists.
+ */
+export async function resolvePiProjectTrustPreflight(options) {
+    const hasProjectResources = options.hasProjectResources ?? hasTrustRequiringProjectResources;
+    if (!hasProjectResources(options.cwd)) {
+        return { trusted: true, source: "no-project-resources", diagnostic: null };
+    }
+    const trustStore = new ProjectTrustStore(options.agentDir);
+    const saved = trustStore.get(options.cwd);
+    if (saved !== null)
+        return { trusted: saved, source: "saved", diagnostic: null };
+    // Security: projectTrusted:false is the boundary: this read may see global
+    // settings but cannot consume project settings or construct project resources.
+    const globalSettings = SettingsManager.create(options.cwd, options.agentDir, { projectTrusted: false });
+    const fallback = globalSettings.getDefaultProjectTrust();
+    if (fallback === "always")
+        return { trusted: true, source: "default", diagnostic: null };
+    if (fallback === "never")
+        return { trusted: false, source: "default", diagnostic: null };
+    if (options.prompt === undefined) {
+        return {
+            trusted: false,
+            source: "fail-closed",
+            diagnostic: `Project resources in ${options.cwd} were withheld because trust requires interaction`,
+        };
+    }
+    try {
+        const decision = await options.prompt({ cwd: options.cwd, defaultDecision: fallback });
+        if (decision === null) {
+            return {
+                trusted: false,
+                source: "fail-closed",
+                diagnostic: `Project resources in ${options.cwd} were withheld because trust selection was cancelled`,
+            };
+        }
+        trustStore.set(options.cwd, decision);
+        return { trusted: decision, source: "interactive", diagnostic: null };
+    }
+    catch (error) {
+        return {
+            trusted: false,
+            source: "fail-closed",
+            diagnostic: `Project resources in ${options.cwd} were withheld because trust resolution failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/resource-extension-integration.d.ts

@@ -1,10 +1,11 @@
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
-import type { AgentExtensionBinding, AgentExtensionFailure, AgentExtensionPort, AgentResourceDescriptor, AgentResourcesPort, AgentSessionMetadata } from "../agent-engine-contracts/index.js";
+import type { AgentExtensionBinding, AgentExtensionFailure, AgentExtensionPort, AgentResourceDescriptor, AgentResourcesPort, AgentSessionMetadata } from "../../../contracts/agent-engine/index.js";
 export interface PiResourceExtensionOptions {
     readonly session: AgentSession;
     readonly bindUi: () => Promise<void>;
     readonly unbindUi: () => Promise<void>;
 }
+/** Adapts Pi resource discovery and extension binding while containing extension failures at the port. */
 export declare class PiResourceExtensionIntegration implements AgentResourcesPort, AgentExtensionPort {
     #private;
     private readonly options;

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/resource-extension-integration.js

@@ -1,3 +1,4 @@
+/** Adapts Pi resource discovery and extension binding while containing extension failures at the port. */
 export class PiResourceExtensionIntegration {
     options;
     capabilities = { reload: true, extensionBinding: true, binding: true, renderers: true };

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/runtime-integration.d.ts

@@ -1,8 +1,20 @@
-import { type AgentSession, type AgentSessionRuntime, type AgentSessionServices, type ScopedModel } from "@earendil-works/pi-coding-agent";
+import { createAgentSessionServices, SettingsManager, type AgentSession, type AgentSessionRuntime, type AgentSessionServices, type ScopedModel } from "@earendil-works/pi-coding-agent";
+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";
@@ -26,6 +38,12 @@ interface ConfiguredModelScope {
  * 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<{

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/runtime-integration.js

@@ -1,4 +1,7 @@
-import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, resolveModelScopeWithDiagnostics, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, resolveModelScopeWithDiagnostics, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { resolvePiProjectTrustPreflight, } from "./project-trust-preflight.js";
+import { openSelectedPiSession, resolveSessionArgumentPath } from "./session-selection.js";
+import { markStartupPhase } from "../../../foundation/startup/index.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
@@ -29,10 +32,41 @@ export async function resolveConfiguredModelScope(services) {
         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 services = await createServices({ cwd: options.cwd, agentDir: options.agentDir, settingsManager });
+    await markStartupPhase(process.env, "pi-services");
+    await markStartupPhase(process.env, "resource-discovery");
+    return { services, trust };
+}
 export async function createPiRuntimeIntegration(options) {
-    const sessionManager = SessionManager.create(options.cwd, options.sessionDir ?? process.env.PI_CODING_AGENT_SESSION_DIR);
+    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 = await createAgentSessionServices({ cwd, agentDir: options.agentDir });
+        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({
@@ -43,10 +77,18 @@ export async function createPiRuntimeIntegration(options) {
             ...(modelScope.thinkingLevel && !hasExistingSession ? { thinkingLevel: modelScope.thinkingLevel } : {}),
             ...(modelScope.scopedModels.length > 0 ? { scopedModels: [...modelScope.scopedModels] } : {}),
         });
-        return { ...created, services, diagnostics: [...modelScope.diagnostics] };
+        await markStartupPhase(process.env, "session-created");
+        return {
+            ...created,
+            services,
+            diagnostics: [
+                ...(trust.diagnostic === null ? [] : [{ type: "warning", message: trust.diagnostic }]),
+                ...modelScope.diagnostics,
+            ],
+        };
     };
     return createAgentSessionRuntime(createRuntime, {
-        cwd: options.cwd,
+        cwd: sessionManager.getCwd(),
         agentDir: options.agentDir,
         sessionManager,
     });

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/session-integration.d.ts

@@ -1,5 +1,5 @@
-import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
-import { type AgentCommandOutcome, type AgentEvent } from "../agent-engine-contracts/index.js";
+import type { AgentSession, AgentSessionEvent, PromptOptions } from "@earendil-works/pi-coding-agent";
+import { type AgentCommandOutcome, type AgentEvent } from "../../../contracts/agent-engine/index.js";
 export interface PiDocumentedSessionCommands {
     readonly isStreaming: AgentSession["isStreaming"];
     readonly isRetrying: AgentSession["isRetrying"];
@@ -18,6 +18,7 @@ export interface PiDocumentedSessionCommands {
 export type PiSessionCommand = {
     readonly type: "prompt" | "steer" | "follow-up";
     readonly text: string;
+    readonly images?: NonNullable<PromptOptions["images"]>;
 } | {
     readonly type: "abort" | "retry" | "compact";
 } | {
@@ -30,6 +31,7 @@ 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;

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/session-integration.js

@@ -1,4 +1,5 @@
-import { AGENT_ENGINE_CONTRACT_VERSION, } from "../agent-engine-contracts/index.js";
+import { AGENT_ENGINE_CONTRACT_VERSION, } from "../../../contracts/agent-engine/index.js";
+/** Routes neutral session commands to Pi while preserving Pi streaming and retry semantics. */
 export class PiSessionCommandIntegration {
     session;
     #lastPrompt = null;
@@ -9,15 +10,29 @@ export class PiSessionCommandIntegration {
         switch (command.type) {
             case "prompt":
                 this.#lastPrompt = command.text;
-                await this.session.prompt(command.text, this.session.isStreaming ? { streamingBehavior: "followUp" } : undefined);
+                await this.session.prompt(command.text, command.images === undefined
+                    ? this.session.isStreaming ? { streamingBehavior: "followUp" } : undefined
+                    : {
+                        ...(this.session.isStreaming ? { streamingBehavior: "followUp" } : {}),
+                        images: [...command.images],
+                    });
                 return { outcome: "completed" };
             case "steer":
                 this.#lastPrompt = command.text;
-                await this.session.steer(command.text);
+                // Compatibility: match interactive Pi: prompt() owns template/extension expansion and
+                // turns the accepted steering message into the visible user row while
+                // later messages remain in the pending queue.
+                await this.session.prompt(command.text, {
+                    streamingBehavior: "steer",
+                    ...(command.images === undefined ? {} : { images: [...command.images] }),
+                });
                 return { outcome: "completed" };
             case "follow-up":
                 this.#lastPrompt = command.text;
-                await this.session.followUp(command.text);
+                await this.session.prompt(command.text, {
+                    streamingBehavior: "followUp",
+                    ...(command.images === undefined ? {} : { images: [...command.images] }),
+                });
                 return { outcome: "completed" };
             case "abort":
                 if (this.session.isRetrying)

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

@@ -0,0 +1,28 @@
+import { SessionManager, type SessionInfo } from "@earendil-works/pi-coding-agent";
+export interface PiSessionSelection {
+    readonly target: string;
+    readonly sessionDir?: string;
+}
+export type PiSessionForkPrompt = (request: {
+    readonly sourceCwd: string;
+}) => Promise<boolean>;
+/** Expected resume outcomes are concise CLI diagnostics, not engine crashes. */
+export declare class PiSessionSelectionError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+interface SessionSelectionOptions {
+    readonly cwd: string;
+    readonly selection: PiSessionSelection;
+    readonly sessionDir?: string;
+    readonly forkPrompt?: PiSessionForkPrompt;
+    /** Public API seam for deterministic lookup/open race and listing-order evidence. */
+    readonly sessions?: Pick<typeof SessionManager, "list" | "open" | "forkFrom"> & {
+        readonly listAll: (sessionDir?: string) => Promise<SessionInfo[]>;
+    };
+}
+/** Pinned Pi 0.84.2 main.ts policy, using SDK APIs rather than importing the CLI. */
+export declare function openSelectedPiSession(options: SessionSelectionOptions): Promise<SessionManager>;
+/** Resolve before switching effective cwd, including quoted home-relative paths. */
+export declare function resolveSessionArgumentPath(path: string, cwd: string): string;
+export {};

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

@@ -0,0 +1,90 @@
+import { accessSync, constants, existsSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+/** Expected resume outcomes are concise CLI diagnostics, not engine crashes. */
+export class PiSessionSelectionError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "PiSessionSelectionError";
+    }
+}
+/** Pinned Pi 0.84.2 main.ts policy, using SDK APIs rather than importing the CLI. */
+export async function openSelectedPiSession(options) {
+    try {
+        const sessions = options.sessions ?? SessionManager;
+        const cwd = resolve(options.cwd);
+        const directory = options.selection.sessionDir ?? options.sessionDir ?? process.env.PI_CODING_AGENT_SESSION_DIR;
+        const sessionDir = directory === undefined ? undefined : resolveSessionArgumentPath(directory, cwd);
+        const target = options.selection.target;
+        let path;
+        let global;
+        if (target.includes("/") || target.includes("\\") || target.endsWith(".jsonl")) {
+            path = resolveSessionArgumentPath(target, cwd);
+        }
+        else {
+            const local = matchSession(await sessions.list(cwd, sessionDir), target);
+            const globalMatch = local ? undefined : matchSession(await sessions.listAll(sessionDir), target);
+            // Compatibility: macOS may expose one temporary directory as /var to one process
+            // and /private/var to another. Physical path identity must not turn that alias into
+            // a cross-project fork prompt.
+            global = globalMatch && !sameProjectDirectory(globalMatch.cwd, cwd) ? globalMatch : undefined;
+            const matched = local ?? globalMatch;
+            if (!matched)
+                throw new PiSessionSelectionError(`No session found matching '${target}'`);
+            path = matched.path;
+        }
+        assertResumeFile(path);
+        if (global) {
+            if (!options.forkPrompt || !await options.forkPrompt({ sourceCwd: global.cwd })) {
+                throw new PiSessionSelectionError("Session resume cancelled.", 0);
+            }
+            assertResumeFile(path);
+            assertCwd(cwd);
+            return sessions.forkFrom(path, cwd, sessionDir);
+        }
+        // Invariant: no await between the final guard and SDK open. A disappeared target
+        // can otherwise produce a new in-memory header instead of an existing session.
+        const manager = sessions.open(path, sessionDir);
+        assertResumeFile(path);
+        assertCwd(manager.getCwd());
+        return manager;
+    }
+    catch (error) {
+        if (error instanceof PiSessionSelectionError)
+            throw error;
+        throw new PiSessionSelectionError(`Could not resume session: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function sameProjectDirectory(left, right) {
+    try {
+        const first = realpathSync.native(resolve(left));
+        const second = realpathSync.native(resolve(right));
+        return process.platform === "win32" ? first.toLowerCase() === second.toLowerCase() : first === second;
+    }
+    catch {
+        return resolve(left) === resolve(right);
+    }
+}
+function matchSession(sessions, target) {
+    return sessions.find(session => session.id === target) ?? sessions.find(session => session.id.startsWith(target));
+}
+/** Resolve before switching effective cwd, including quoted home-relative paths. */
+export function resolveSessionArgumentPath(path, cwd) {
+    const expanded = path === "~" ? homedir() : /^~[/\\]/.test(path) ? resolve(homedir(), path.slice(2)) : path;
+    return resolve(cwd, expanded);
+}
+function assertResumeFile(path) {
+    if (!existsSync(path))
+        throw new PiSessionSelectionError(`Session file does not exist: ${path}`);
+    const metadata = statSync(path);
+    if (!metadata.isFile() || metadata.size === 0)
+        throw new PiSessionSelectionError(`Session file is empty or not a regular file: ${path}`);
+    accessSync(path, constants.R_OK);
+}
+function assertCwd(cwd) {
+    if (!existsSync(cwd) || !statSync(cwd).isDirectory())
+        throw new PiSessionSelectionError(`Session working directory does not exist: ${cwd}`);
+}