@timurproko/a1 0.1.0 → 0.1.1-dev.2

package/dist/src/foundation/pi-engine-adapter/conformance.js

@@ -3,6 +3,29 @@ 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";
+export const REQUIRED_PI_CAPABILITY_OPERATIONS = Object.freeze({
+    "public-exports": ["services.create", "session.create", "runtime.create"],
+    "session-lifecycle": ["session.new", "session.resume", "session.rebind", "session.dispose"],
+    "commands-events": ["prompt", "steer", "followUp", "abort", "compact", "setModel", "setThinkingLevel", "subscribe", "dispose"],
+    "models-authentication": ["models.list", "models.refresh", "auth.status", "auth.login", "auth.logout", "auth.cancel"],
+    settings: ["settings.read", "settings.write", "settings.flush"],
+    "resources-extensions": ["resources.discover", "extensions.bind", "extensions.reload", "renderers.invoke"],
+    workflows: ["workflow.route", "workflow.validate", "workflow.diagnostics"],
+    disposal: ["subscription.dispose", "session.dispose", "services.cleanup"],
+});
+export class PiCapabilityCompatibilityError extends Error {
+    packageVersion;
+    capability;
+    operation;
+    constructor(packageVersion, capability, operation, detail) {
+        super(`Pi ${packageVersion} capability ${capability} operation ${operation} is incompatible: ${detail}`);
+        this.packageVersion = packageVersion;
+        this.capability = capability;
+        this.operation = operation;
+        this.name = "PiCapabilityCompatibilityError";
+    }
+}
 export class PiUpgradeConformanceError extends Error {
     stage;
     constructor(stage, cause) {
@@ -24,7 +47,7 @@ export async function runPiUpgradeConformance() {
     catch (error) {
         throw new PiUpgradeConformanceError("exports", error);
     }
-    const root = await mkdtemp(join(tmpdir(), "addone-pi-conformance-"));
+    const root = await mkdtemp(join(tmpdir(), `${PRODUCT_IDENTITY.filesystem.temporaryPrefix}pi-conformance-`));
     try {
         let services;
         try {
@@ -52,34 +75,56 @@ export async function runPiUpgradeConformance() {
             });
             const session = created.session;
             sessionId = session.sessionId;
-            for (const method of [
-                session.prompt,
-                session.abort,
-                session.compact,
-                session.setModel,
-                session.setThinkingLevel,
-                session.subscribe,
-                session.dispose,
-            ]) {
-                if (typeof method !== "function")
-                    throw new Error("session command surface is incomplete");
-            }
+            requireMethods(session, "session commands", ["prompt", "steer", "followUp", "abort", "compact", "setModel", "setThinkingLevel", "subscribe", "dispose"]);
+            requireMethods(services.modelRuntime, "models/authentication", ["getModels", "getModel", "checkAuth", "login", "logout", "refresh"]);
+            requireMethods(services.settingsManager, "settings", ["getGlobalSettings", "getProjectSettings", "flush"]);
+            requireMethods(services.resourceLoader, "resources/extensions", ["getExtensions", "getSkills", "getPrompts", "getThemes", "reload"]);
+            const unsubscribe = session.subscribe(() => undefined);
+            unsubscribe();
             session.dispose();
         }
         catch (error) {
             throw new PiUpgradeConformanceError("session", error);
         }
+        const commandSurface = ["prompt", "steer", "followUp", "abort", "compact", "setModel", "setThinkingLevel", "subscribe", "dispose"];
+        const capabilities = Object.entries(REQUIRED_PI_CAPABILITY_OPERATIONS)
+            .map(([capabilityName, operations]) => capability(capabilityName, operations));
+        validatePiCapabilityResults(VERSION, capabilities);
         return {
+            schema: "pi-engine-conformance-v1",
             packageName: "@earendil-works/pi-coding-agent",
             packageVersion: VERSION,
             ownedUiContractVersion: OWNED_UI_CONTRACT_VERSION,
             serviceDiagnostics: services.diagnostics.length,
             sessionId,
-            commandSurface: ["prompt", "abort", "compact", "setModel", "setThinkingLevel", "subscribe", "dispose"],
+            commandSurface,
+            capabilities,
         };
     }
     finally {
         await rm(root, { recursive: true, force: true });
     }
 }
-//# sourceMappingURL=conformance.js.map
+function requireMethods(target, capabilityName, operations) {
+    const surface = target;
+    for (const operation of operations) {
+        if (typeof surface[operation] !== "function")
+            throw new Error(`${capabilityName}.${operation} is unavailable`);
+    }
+}
+function capability(capabilityName, operations) {
+    return { capability: capabilityName, operations, passed: true };
+}
+export function validatePiCapabilityResults(packageVersion, results) {
+    for (const [capabilityName, requiredOperations] of Object.entries(REQUIRED_PI_CAPABILITY_OPERATIONS)) {
+        const result = results.find(candidate => candidate.capability === capabilityName);
+        if (!result)
+            throw new PiCapabilityCompatibilityError(packageVersion, capabilityName, requiredOperations[0], "capability result is missing");
+        if (!result.passed)
+            throw new PiCapabilityCompatibilityError(packageVersion, capabilityName, requiredOperations[0], "capability reported failure");
+        for (const operation of requiredOperations) {
+            if (!result.operations.includes(operation))
+                throw new PiCapabilityCompatibilityError(packageVersion, capabilityName, operation, "required operation is missing");
+        }
+    }
+}

package/dist/src/foundation/pi-engine-adapter/index.d.ts

@@ -1,4 +1,9 @@
 export * from "./adapter.js";
 export * from "./conformance.js";
+export * from "./runtime-integration.js";
+export * from "./session-integration.js";
+export * from "./model-auth-integration.js";
+export * from "./settings-integration.js";
+export * from "./resource-extension-integration.js";
+export * from "./workflow-controllers.js";
 export * from "./workflows.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/src/foundation/pi-engine-adapter/index.js

@@ -1,4 +1,9 @@
 export * from "./adapter.js";
 export * from "./conformance.js";
+export * from "./runtime-integration.js";
+export * from "./session-integration.js";
+export * from "./model-auth-integration.js";
+export * from "./settings-integration.js";
+export * from "./resource-extension-integration.js";
+export * from "./workflow-controllers.js";
 export * from "./workflows.js";
-//# sourceMappingURL=index.js.map

package/dist/src/foundation/pi-engine-adapter/model-auth-integration.d.ts

@@ -0,0 +1,30 @@
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import type { AgentAuthenticationPort, AgentModelDescriptor, AgentModelPort } from "../agent-engine-contracts/index.js";
+export type PiDocumentedModelRuntime = Pick<ModelRuntime, "getAvailableSnapshot" | "getModel" | "getProvider" | "hasConfiguredAuth" | "refresh" | "logout">;
+export interface PiModelAuthenticationOptions {
+    readonly runtime: PiDocumentedModelRuntime;
+    readonly currentModel: () => AgentModelDescriptor | null;
+    readonly selectModel: (model: ReturnType<PiDocumentedModelRuntime["getModel"]> extends infer T ? Exclude<T, undefined> : never) => Promise<void>;
+    readonly login: (providerId: string, signal: AbortSignal) => Promise<void>;
+    readonly timeoutMs?: number;
+    readonly scopedModelIds?: () => readonly string[] | undefined;
+}
+export declare class PiModelAuthenticationIntegration implements AgentModelPort, AgentAuthenticationPort {
+    #private;
+    private readonly options;
+    readonly capabilities: {
+        selection: boolean;
+        refresh: boolean;
+        scopedCatalog: boolean;
+        login: boolean;
+        logout: boolean;
+    };
+    constructor(options: PiModelAuthenticationOptions);
+    listModels(): Promise<readonly AgentModelDescriptor[]>;
+    currentModel(): Promise<AgentModelDescriptor | null>;
+    selectModel(providerId: string, modelId: string): Promise<void>;
+    refreshModels(): Promise<void>;
+    status(providerId: string): Promise<"authenticated" | "unauthenticated" | "unavailable">;
+    login(providerId: string, signal?: AbortSignal): Promise<void>;
+    logout(providerId: string): Promise<void>;
+}

package/dist/src/foundation/pi-engine-adapter/model-auth-integration.js

@@ -0,0 +1,61 @@
+export class PiModelAuthenticationIntegration {
+    options;
+    capabilities = { selection: true, refresh: true, scopedCatalog: true, login: true, logout: true };
+    #timeoutMs;
+    constructor(options) {
+        this.options = options;
+        this.#timeoutMs = options.timeoutMs ?? 30_000;
+    }
+    async listModels() {
+        const scope = this.options.scopedModelIds?.();
+        const selected = scope ? new Set(scope) : null;
+        return this.options.runtime.getAvailableSnapshot()
+            .filter(model => !selected || selected.has(`${model.provider}/${model.id}`))
+            .map(model => ({
+            providerId: model.provider,
+            modelId: model.id,
+            displayName: model.name,
+            contextWindow: model.contextWindow,
+            thinkingLevels: [],
+        }));
+    }
+    async currentModel() { return this.options.currentModel(); }
+    async selectModel(providerId, modelId) {
+        const model = this.options.runtime.getModel(providerId, modelId);
+        if (!model)
+            throw new Error(`model is unavailable: ${providerId}/${modelId}`);
+        await this.options.selectModel(model);
+    }
+    async refreshModels() {
+        await this.options.runtime.refresh();
+    }
+    async status(providerId) {
+        return this.options.runtime.getProvider(providerId) === undefined
+            ? "unavailable"
+            : this.options.runtime.hasConfiguredAuth(providerId) ? "authenticated" : "unauthenticated";
+    }
+    async login(providerId, signal) {
+        await boundedOperation(inner => this.options.login(providerId, inner), this.#timeoutMs, signal);
+    }
+    async logout(providerId) {
+        await boundedOperation(signal => this.options.runtime.logout(providerId, { signal }), this.#timeoutMs);
+    }
+}
+async function boundedOperation(operation, timeoutMs, outer) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(outer?.reason);
+    outer?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(() => controller.abort(new Error(`model/authentication operation timed out after ${timeoutMs}ms`)), timeoutMs);
+    try {
+        if (outer?.aborted)
+            abort();
+        await Promise.race([
+            operation(controller.signal),
+            new Promise((_, reject) => controller.signal.addEventListener("abort", () => reject(controller.signal.reason ?? new Error("model/authentication operation cancelled")), { once: true })),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+        outer?.removeEventListener("abort", abort);
+    }
+}

package/dist/src/foundation/pi-engine-adapter/public-main-entry.d.ts

@@ -0,0 +1,5 @@
+export interface PublicMainEntryDependencies {
+    readonly main?: (arguments_: string[]) => Promise<void>;
+    readonly stderr?: (message: string) => void;
+}
+export declare function runPublicMainEntry(arguments_: readonly string[], dependencies?: PublicMainEntryDependencies): Promise<number>;

package/dist/src/foundation/pi-engine-adapter/public-main-entry.js

@@ -0,0 +1,18 @@
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { main as runPublicMain } from "@earendil-works/pi-coding-agent";
+export async function runPublicMainEntry(arguments_, dependencies = {}) {
+    try {
+        await (dependencies.main ?? runPublicMain)([...arguments_]);
+        return 0;
+    }
+    catch (error) {
+        const detail = (error instanceof Error ? error.message : String(error)).replace(/[\r\n\t]+/g, " ").trim();
+        const bounded = detail.length > 400 ? `${detail.slice(0, 397)}...` : detail;
+        (dependencies.stderr ?? (message => process.stderr.write(message)))(`Selected Pi startup failed: ${bounded || "unknown error"}\n`);
+        return 1;
+    }
+}
+const isMain = process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain)
+    process.exitCode = await runPublicMainEntry(process.argv.slice(2));

package/dist/src/foundation/pi-engine-adapter/resource-extension-integration.d.ts

@@ -0,0 +1,31 @@
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { AgentExtensionBinding, AgentExtensionFailure, AgentExtensionPort, AgentResourceDescriptor, AgentResourcesPort, AgentSessionMetadata } from "../agent-engine-contracts/index.js";
+export interface PiResourceExtensionOptions {
+    readonly session: AgentSession;
+    readonly bindUi: () => Promise<void>;
+    readonly unbindUi: () => Promise<void>;
+}
+export declare class PiResourceExtensionIntegration implements AgentResourcesPort, AgentExtensionPort {
+    #private;
+    private readonly options;
+    readonly capabilities: {
+        reload: boolean;
+        extensionBinding: boolean;
+        binding: boolean;
+        renderers: boolean;
+    };
+    constructor(options: PiResourceExtensionOptions);
+    discoverResources(): Promise<readonly AgentResourceDescriptor[]>;
+    discoverCommands(): Promise<{
+        name: string;
+        description: string;
+    }[]>;
+    sessionMetadata(): Promise<AgentSessionMetadata>;
+    bind(sessionId: string): Promise<AgentExtensionBinding>;
+    bindExtensions(sessionId: string): Promise<AgentExtensionBinding>;
+    reload(): Promise<void>;
+    resolveMessageRenderer(customType: string): unknown;
+    resolveToolRenderer(toolName: string): unknown;
+    subscribeFailures(listener: (failure: AgentExtensionFailure) => void): () => void;
+    dispose(): Promise<void>;
+}

package/dist/src/foundation/pi-engine-adapter/resource-extension-integration.js

@@ -0,0 +1,80 @@
+export class PiResourceExtensionIntegration {
+    options;
+    capabilities = { reload: true, extensionBinding: true, binding: true, renderers: true };
+    #failures = new Set();
+    #unsubscribeError;
+    #binding;
+    constructor(options) {
+        this.options = options;
+        this.#unsubscribeError = options.session.extensionRunner.onError(error => {
+            const failure = {
+                extensionPath: error.extensionPath || null,
+                operation: error.event || "extension",
+                message: error.error || "unknown extension failure",
+                recoverable: true,
+            };
+            for (const listener of this.#failures)
+                listener(failure);
+        });
+    }
+    async discoverResources() {
+        const loader = this.options.session.resourceLoader;
+        const resources = [];
+        for (const skill of loader.getSkills().skills)
+            resources.push(resource(skill.name, "skill", skill.name, { source: skill.filePath }));
+        for (const prompt of loader.getPrompts().prompts)
+            resources.push(resource(prompt.name, "prompt", prompt.name, { source: prompt.filePath }));
+        for (const theme of loader.getThemes().themes)
+            resources.push(resource(theme.name ?? "theme", "other", theme.name ?? "Theme", { resourceType: "theme" }));
+        for (const file of loader.getAgentsFiles().agentsFiles)
+            resources.push(resource(file.path, "other", file.path, { resourceType: "agent-context" }));
+        for (const command of this.options.session.extensionRunner.getRegisteredCommands())
+            resources.push(resource(command.name, "command", command.name, { invocationName: command.invocationName }));
+        return resources;
+    }
+    async discoverCommands() {
+        return this.options.session.extensionRunner.getRegisteredCommands().map(command => ({
+            name: command.name,
+            description: command.description ?? "",
+        }));
+    }
+    async sessionMetadata() {
+        const manager = this.options.session.sessionManager;
+        return {
+            sessionId: this.options.session.sessionId,
+            sessionName: manager.getSessionName() ?? null,
+            sessionPath: manager.getSessionFile() ?? null,
+            cwd: manager.getCwd(),
+        };
+    }
+    async bind(sessionId) {
+        if (sessionId !== this.options.session.sessionId)
+            throw new Error("extension binding targets a different session");
+        await this.#binding?.dispose();
+        await this.options.bindUi();
+        let disposed = false;
+        const binding = {
+            sessionId,
+            dispose: async () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                if (this.#binding === binding)
+                    this.#binding = undefined;
+                await this.options.unbindUi();
+            },
+        };
+        this.#binding = binding;
+        return binding;
+    }
+    async bindExtensions(sessionId) { return this.bind(sessionId); }
+    async reload() { await this.options.session.reload(); }
+    resolveMessageRenderer(customType) { return this.options.session.extensionRunner.getMessageRenderer(customType); }
+    resolveToolRenderer(toolName) { return this.options.session.extensionRunner.getToolDefinition(toolName); }
+    subscribeFailures(listener) { this.#failures.add(listener); return () => this.#failures.delete(listener); }
+    async dispose() { await this.#binding?.dispose(); this.#unsubscribeError(); this.#failures.clear(); }
+}
+function resource(id, kind, label, metadata) {
+    return { id: normalizeId(id), kind, label, metadata: Object.fromEntries(Object.entries(metadata).filter((entry) => typeof entry[1] === "string")) };
+}
+function normalizeId(value) { return value.replace(/[^A-Za-z0-9._:/-]/g, "-").slice(0, 128) || "resource"; }

package/dist/src/foundation/pi-engine-adapter/runtime-integration.d.ts

@@ -0,0 +1,18 @@
+import { type AgentSession, type AgentSessionRuntime } from "@earendil-works/pi-coding-agent";
+export interface PiRuntimeIntegrationOptions {
+    readonly cwd: string;
+    readonly agentDir: string;
+    readonly sessionDir?: string;
+}
+export type PiSessionReplacement = {
+    readonly kind: "new";
+} | {
+    readonly kind: "resume";
+    readonly sessionPath: string;
+};
+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>;

package/dist/src/foundation/pi-engine-adapter/runtime-integration.js

@@ -0,0 +1,32 @@
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, SessionManager, } from "@earendil-works/pi-coding-agent";
+export async function createPiRuntimeIntegration(options) {
+    const sessionManager = SessionManager.create(options.cwd, options.sessionDir ?? process.env.PI_CODING_AGENT_SESSION_DIR);
+    const createRuntime = async ({ cwd, sessionManager: targetSessionManager, sessionStartEvent, }) => {
+        const services = await createAgentSessionServices({ cwd, agentDir: options.agentDir });
+        const created = await createAgentSessionFromServices({
+            services,
+            sessionManager: targetSessionManager,
+            ...(sessionStartEvent ? { sessionStartEvent } : {}),
+        });
+        return { ...created, services, diagnostics: services.diagnostics };
+    };
+    return createAgentSessionRuntime(createRuntime, {
+        cwd: options.cwd,
+        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/src/foundation/pi-engine-adapter/session-integration.d.ts

@@ -0,0 +1,43 @@
+import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import { type AgentCommandOutcome, type AgentEvent } from "../agent-engine-contracts/index.js";
+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): Promise<void>;
+    followUp(text: string): Promise<void>;
+    abort(): Promise<void>;
+    abortRetry(): void;
+    abortCompaction(): void;
+    compact(customInstructions?: Parameters<AgentSession["compact"]>[0]): Promise<unknown>;
+    executeBash?(command: string, onChunk: unknown, options: {
+        readonly excludeFromContext: boolean;
+    }): Promise<unknown>;
+}
+export type PiSessionCommand = {
+    readonly type: "prompt" | "steer" | "follow-up";
+    readonly text: string;
+} | {
+    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;
+}
+export declare class PiSessionCommandIntegration {
+    #private;
+    private readonly session;
+    constructor(session: PiDocumentedSessionCommands);
+    execute(command: PiSessionCommand): Promise<PiSessionCommandResult>;
+}
+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;

package/dist/src/foundation/pi-engine-adapter/session-integration.js

@@ -0,0 +1,97 @@
+import { AGENT_ENGINE_CONTRACT_VERSION, } from "../agent-engine-contracts/index.js";
+export class PiSessionCommandIntegration {
+    session;
+    #lastPrompt = null;
+    constructor(session) {
+        this.session = session;
+    }
+    async execute(command) {
+        switch (command.type) {
+            case "prompt":
+                this.#lastPrompt = command.text;
+                await this.session.prompt(command.text, this.session.isStreaming ? { streamingBehavior: "followUp" } : undefined);
+                return { outcome: "completed" };
+            case "steer":
+                this.#lastPrompt = command.text;
+                await this.session.steer(command.text);
+                return { outcome: "completed" };
+            case "follow-up":
+                this.#lastPrompt = command.text;
+                await this.session.followUp(command.text);
+                return { outcome: "completed" };
+            case "abort":
+                if (this.session.isRetrying)
+                    this.session.abortRetry();
+                if (this.session.isCompacting)
+                    this.session.abortCompaction();
+                await this.session.abort();
+                return { outcome: "cancelled" };
+            case "retry":
+                if (this.#lastPrompt === null)
+                    return { outcome: "rejected" };
+                await this.session.prompt(this.#lastPrompt, this.session.isStreaming ? { streamingBehavior: "followUp" } : undefined);
+                return { outcome: "completed" };
+            case "compact":
+                return { outcome: "completed", value: await this.session.compact() };
+            case "bash": {
+                if (!this.session.executeBash)
+                    return { outcome: "rejected" };
+                const value = await this.session.executeBash(command.command, command.onChunk, { excludeFromContext: command.excludeFromContext });
+                if (!value || typeof value !== "object")
+                    throw new TypeError("Pi bash result is malformed");
+                const result = value;
+                if (typeof result.cancelled !== "boolean" || (result.exitCode !== undefined && typeof result.exitCode !== "number"))
+                    throw new TypeError("Pi bash result is malformed");
+                return { outcome: result.cancelled ? "cancelled" : result.exitCode === 0 ? "completed" : "failed", value };
+            }
+        }
+    }
+}
+export function subscribeToPiSessionEvents(session, sessionId, emit, malformed) {
+    let sequence = 0;
+    let disposed = false;
+    const unsubscribe = session.subscribe(event => {
+        if (disposed)
+            return;
+        sequence += 1;
+        try {
+            const converted = convertPiSessionEvent(event, sessionId, sequence);
+            if (converted)
+                emit(converted);
+        }
+        catch (error) {
+            malformed(`Pi session event ${sequence} is malformed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+    return { dispose() { if (disposed)
+            return; disposed = true; unsubscribe(); } };
+}
+export function convertPiSessionEvent(event, sessionId, sequence) {
+    const base = { contractVersion: AGENT_ENGINE_CONTRACT_VERSION, sessionId, sequence };
+    switch (event.type) {
+        case "agent_start": return { ...base, type: "lifecycle", lifecycle: "busy", reason: null };
+        case "agent_settled": return { ...base, type: "lifecycle", lifecycle: "ready", reason: null };
+        case "agent_end": return event.willRetry ? null : { ...base, type: "lifecycle", lifecycle: "ready", reason: null };
+        case "message_start":
+        case "message_update":
+        case "message_end":
+            return { ...base, type: "content", content: toAgentMessage(event.message, event.type === "message_end" ? "final" : "streaming", sequence) };
+        default: return null;
+    }
+}
+function toAgentMessage(value, status, sequence) {
+    if (!value || typeof value !== "object")
+        throw new TypeError("message payload is not an object");
+    const message = value;
+    const role = message.role === "user" || message.role === "assistant" || message.role === "tool" || message.role === "system" ? message.role : "assistant";
+    const source = Array.isArray(message.content) ? message.content : [];
+    const text = source.flatMap(part => part && typeof part === "object" && typeof part.text === "string" ? [part.text] : []).join("");
+    return {
+        id: typeof message.id === "string" ? message.id : `message-${sequence}`,
+        role,
+        status,
+        content: text.length > 0
+            ? [{ kind: "text", text }]
+            : [{ kind: "unknown", sourceType: "pi-message", payload: { role: String(message.role ?? "unknown") } }],
+    };
+}

package/dist/src/foundation/pi-engine-adapter/settings-integration.d.ts

@@ -0,0 +1,17 @@
+import type { SettingsManager } from "@earendil-works/pi-coding-agent";
+import type { AgentJsonValue, AgentSettingDescriptor, AgentSettingsPort } from "../agent-engine-contracts/index.js";
+export declare const EXPOSED_SETTING_KEYS: readonly ["autoCompact", "showImages", "imageWidthCells", "autoResizeImages", "blockImages", "enableSkillCommands", "steeringMode", "followUpMode", "transport", "httpIdleTimeoutMs", "thinkingLevel", "theme", "hideThinkingBlock", "mermaidRenderingMode", "showCacheMissNotices", "collapseChangelog", "enableInstallTelemetry", "quietStartup", "defaultProjectTrust", "doubleEscapeAction", "treeFilterMode", "showHardwareCursor", "editorPaddingX", "outputPad", "autocompleteMaxVisible", "clearOnShrink", "showTerminalProgress", "tuiMode", "fullscreenExitOutput", "fullscreenScrollbar", "warnings"];
+export declare class PiSettingsIntegration implements AgentSettingsPort {
+    #private;
+    private readonly settings;
+    readonly capabilities: {
+        write: boolean;
+        flush: boolean;
+    };
+    constructor(settings: SettingsManager);
+    listSettings(): Promise<readonly AgentSettingDescriptor[]>;
+    readSetting(key: string): Promise<AgentJsonValue | undefined>;
+    writeSetting(key: string, value: AgentJsonValue): Promise<void>;
+    writeSettingNow(key: string, value: AgentJsonValue): void;
+    flush(): Promise<void>;
+}