@timurproko/a1 0.1.0 → 0.1.1-dev.10

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,55 @@
+import type { SettingsManager } from "@earendil-works/pi-coding-agent";
+import type { AgentJsonValue, AgentSettingDescriptor, AgentSettingsPort } from "../agent-engine-contracts/index.js";
+/**
+ * Values only the running engine knows: the themes installed on this machine and
+ * the thinking levels this session supports. The boundary asks for them as it is
+ * read, so no layer above has to know they are not fixed.
+ */
+export interface PiSettingsProviders {
+    readonly themes?: () => readonly string[];
+    readonly thinkingLevels?: () => readonly string[];
+}
+/**
+ * The engine stores a theme as one string with two forms: a theme's name, or a
+ * `light/dark` pair meaning "follow the terminal". That grammar is the engine's,
+ * so it is parsed and composed here and reaches the surfaces above as ordinary
+ * settings — a theme entry that offers `automatic`, and, while automatic, one
+ * entry per terminal appearance.
+ */
+export declare const AUTOMATIC_THEME = "automatic";
+interface AutomaticTheme {
+    readonly light: string;
+    readonly dark: string;
+}
+/** A stored theme is automatic when it names one theme per terminal appearance. */
+export declare function parseAutomaticTheme(stored: string): AutomaticTheme | null;
+/**
+ * The settings A1 exposes: the ones the engine presents. Kept as the engine's
+ * own inventory rather than a list beside it, so a setting it adds or renames
+ * shows up as a named test failure instead of quietly going missing.
+ */
+export declare const EXPOSED_SETTING_KEYS: readonly string[];
+/**
+ * What has drifted between the settings the engine presents and the settings A1
+ * maps to its API: the ones A1 has not caught up with, and the ones it kept
+ * after the engine dropped them. Either is a build failure with a name in it.
+ */
+export declare function settingsInventoryDrift(presented: readonly string[], mapped: readonly string[]): {
+    readonly unmapped: readonly string[];
+    readonly stale: readonly string[];
+};
+export declare class PiSettingsIntegration implements AgentSettingsPort {
+    #private;
+    private readonly settings;
+    readonly capabilities: {
+        write: boolean;
+        flush: boolean;
+    };
+    constructor(settings: SettingsManager, providers?: PiSettingsProviders);
+    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>;
+}
+export {};

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

@@ -0,0 +1,233 @@
+import piSettingsMetadata from "./pi-settings-metadata.json" with { type: "json" };
+/**
+ * The engine stores a theme as one string with two forms: a theme's name, or a
+ * `light/dark` pair meaning "follow the terminal". That grammar is the engine's,
+ * so it is parsed and composed here and reaches the surfaces above as ordinary
+ * settings — a theme entry that offers `automatic`, and, while automatic, one
+ * entry per terminal appearance.
+ */
+export const AUTOMATIC_THEME = "automatic";
+/** The themes an automatic setting names for each terminal appearance. */
+const LIGHT_APPEARANCE_THEME = "light";
+const DARK_APPEARANCE_THEME = "dark";
+const THEME_KEY = "theme";
+const THINKING_KEY = "thinkingLevel";
+/** A stored theme is automatic when it names one theme per terminal appearance. */
+export function parseAutomaticTheme(stored) {
+    const at = stored.indexOf("/");
+    if (at < 0 || stored.indexOf("/", at + 1) >= 0)
+        return null;
+    const light = stored.slice(0, at).trim();
+    const dark = stored.slice(at + 1).trim();
+    return light.length > 0 && dark.length > 0 ? { light, dark } : null;
+}
+/**
+ * How the engine presents these settings — wording, order, and the flags a
+ * dialog-backed setting offers — generated from its own source by
+ * `npm run update:pi-settings-metadata` and verified by a governance test, so a
+ * Pi upgrade cannot silently reword or reorder what A1 shows.
+ */
+const PRESENTATION = piSettingsMetadata;
+/**
+ * The settings A1 exposes: the ones the engine presents. Kept as the engine's
+ * own inventory rather than a list beside it, so a setting it adds or renames
+ * shows up as a named test failure instead of quietly going missing.
+ */
+export const EXPOSED_SETTING_KEYS = PRESENTATION.presented;
+/**
+ * What has drifted between the settings the engine presents and the settings A1
+ * maps to its API: the ones A1 has not caught up with, and the ones it kept
+ * after the engine dropped them. Either is a build failure with a name in it.
+ */
+export function settingsInventoryDrift(presented, mapped) {
+    const has = new Set(mapped);
+    const engine = new Set(presented);
+    return {
+        unmapped: presented.filter(key => !has.has(key)),
+        stale: mapped.filter(key => !engine.has(key)),
+    };
+}
+/** What the engine offers for a setting, as the strings it words them with. */
+function offered(key) {
+    return PRESENTATION.settings[key]?.values ?? [];
+}
+/**
+ * The same, read as the numbers a numeric setting stores. Only for a setting
+ * whose list is its whole domain: where the engine offers a few numbers but
+ * accepts any within a range, the range governs and the list is only shortcuts.
+ */
+function offeredNumbers(key) {
+    return offered(key).map(value => Number.parseInt(value, 10)).filter(value => Number.isSafeInteger(value));
+}
+export class PiSettingsIntegration {
+    settings;
+    capabilities = { write: true, flush: true };
+    #operations;
+    #providers;
+    constructor(settings, providers = {}) {
+        this.settings = settings;
+        this.#providers = providers;
+        this.#operations = new Map(operations(settings).map(operation => [operation.descriptor.key, operation]));
+        if (this.#operations.size !== EXPOSED_SETTING_KEYS.length || EXPOSED_SETTING_KEYS.some(key => !this.#operations.has(key))) {
+            throw new Error("Pi settings integration does not cover every A1-exposed setting");
+        }
+    }
+    async listSettings() {
+        const rank = (key) => {
+            const at = PRESENTATION.order.indexOf(key);
+            return at < 0 ? PRESENTATION.order.length : at;
+        };
+        const listed = [...this.#operations.values()]
+            .map(operation => {
+            const key = operation.descriptor.key;
+            const wording = PRESENTATION.settings[key];
+            const flags = PRESENTATION.dialogs[key];
+            const bounds = PRESENTATION.bounds[key];
+            return {
+                ...operation.descriptor,
+                ...(bounds === undefined ? {} : bounds),
+                ...(wording === undefined ? {} : { label: wording.label, description: wording.description }),
+                ...(flags === undefined ? {} : { flags }),
+            };
+        })
+            .map(descriptor => this.#resolved(descriptor))
+            .sort((left, right) => rank(left.key) - rank(right.key));
+        // Following the terminal is one choice on the theme itself, not two further
+        // settings: the pair behind it is the engine's grammar, not a reader's task.
+        return listed;
+    }
+    /** Overlays the values a setting can only offer once something is running. */
+    #resolved(descriptor) {
+        if (descriptor.key === THEME_KEY) {
+            const themes = this.#themes();
+            if (themes.length === 0)
+                return descriptor;
+            return { ...descriptor, valueType: "enum", writable: true, resolvedWhenRead: true, choices: [AUTOMATIC_THEME, ...themes] };
+        }
+        if (descriptor.key === THINKING_KEY) {
+            const levels = this.#providers.thinkingLevels?.() ?? [];
+            if (levels.length === 0)
+                return descriptor;
+            return { ...descriptor, resolvedWhenRead: true, choices: [...levels] };
+        }
+        return descriptor;
+    }
+    #themes() {
+        return this.#providers.themes?.() ?? [];
+    }
+    #storedTheme() {
+        const stored = this.#operations.get(THEME_KEY)?.read();
+        return typeof stored === "string" ? stored : "";
+    }
+    async readSetting(key) {
+        if (key === THEME_KEY) {
+            const pair = parseAutomaticTheme(this.#storedTheme());
+            return pair === null ? this.#operations.get(key)?.read() : AUTOMATIC_THEME;
+        }
+        return this.#operations.get(key)?.read();
+    }
+    async writeSetting(key, value) { this.writeSettingNow(key, value); }
+    writeSettingNow(key, value) {
+        if (typeof value === "string" && key === THEME_KEY) {
+            this.#writeTheme(value);
+            return;
+        }
+        const operation = this.#operations.get(key);
+        if (!operation)
+            throw new Error(`setting is unavailable: ${key}`);
+        operation.write(value);
+    }
+    /**
+     * Writes the theme in the engine's own grammar. Following the terminal is
+     * stored as the pair the engine reads for it, made of the themes named for
+     * each appearance when they are installed; where they are not, the theme
+     * already in use stands for both, so the setting still round-trips.
+     */
+    #writeTheme(value) {
+        const theme = this.#operations.get(THEME_KEY);
+        if (!theme)
+            throw new Error(`setting is unavailable: ${THEME_KEY}`);
+        if (value !== AUTOMATIC_THEME) {
+            theme.write(value);
+            return;
+        }
+        if (parseAutomaticTheme(this.#storedTheme()) !== null)
+            return;
+        const installed = this.#themes();
+        const current = this.#storedTheme();
+        const light = installed.includes(LIGHT_APPEARANCE_THEME) ? LIGHT_APPEARANCE_THEME : current;
+        const dark = installed.includes(DARK_APPEARANCE_THEME) ? DARK_APPEARANCE_THEME : current;
+        theme.write(`${light}/${dark}`);
+    }
+    async flush() { await this.settings.flush(); }
+}
+function operations(settings) {
+    return [
+        bool("autoCompact", () => settings.getCompactionEnabled(), value => settings.setCompactionEnabled(value)),
+        bool("showImages", () => settings.getShowImages(), value => settings.setShowImages(value)),
+        numberSetting("imageWidthCells", () => settings.getImageWidthCells(), value => settings.setImageWidthCells(value), 1),
+        bool("autoResizeImages", () => settings.getImageAutoResize(), value => settings.setImageAutoResize(value)),
+        bool("blockImages", () => settings.getBlockImages(), value => settings.setBlockImages(value)),
+        bool("enableSkillCommands", () => settings.getEnableSkillCommands(), value => settings.setEnableSkillCommands(value)),
+        choice("steeringMode", offered("steeringMode"), () => settings.getSteeringMode(), value => settings.setSteeringMode(value)),
+        choice("followUpMode", offered("followUpMode"), () => settings.getFollowUpMode(), value => settings.setFollowUpMode(value)),
+        choice("transport", offered("transport"), () => settings.getTransport(), value => settings.setTransport(value)),
+        numberSetting("httpIdleTimeoutMs", () => settings.getHttpIdleTimeoutMs(), value => settings.setHttpIdleTimeoutMs(value), 0),
+        // The engine reads these from the running session rather than declaring them,
+        // so they arrive through the runtime provider rather than from its source.
+        choice("thinkingLevel", ["off", "minimal", "low", "medium", "high", "xhigh"], () => settings.getDefaultThinkingLevel() ?? "medium", value => settings.setDefaultThinkingLevel(value)),
+        // The raw setting, not the resolved theme: the engine hides the automatic
+        // pair behind getTheme, and the pair is the thing A1 presents parts of.
+        stringSetting("theme", () => settings.getThemeSetting() ?? "default", value => settings.setTheme(value)),
+        bool("hideThinkingBlock", () => settings.getHideThinkingBlock(), value => settings.setHideThinkingBlock(value)),
+        choice("mermaidRenderingMode", offered("mermaidRenderingMode"), () => settings.getMermaidRenderingMode(), value => settings.setMermaidRenderingMode(value)),
+        bool("showCacheMissNotices", () => settings.getShowCacheMissNotices(), value => settings.setShowCacheMissNotices(value)),
+        bool("collapseChangelog", () => settings.getCollapseChangelog(), value => settings.setCollapseChangelog(value)),
+        bool("enableInstallTelemetry", () => settings.getEnableInstallTelemetry(), value => settings.setEnableInstallTelemetry(value)),
+        bool("quietStartup", () => settings.getQuietStartup(), value => settings.setQuietStartup(value)),
+        choice("defaultProjectTrust", offered("defaultProjectTrust"), () => settings.getDefaultProjectTrust(), value => settings.setDefaultProjectTrust(value)),
+        choice("doubleEscapeAction", offered("doubleEscapeAction"), () => settings.getDoubleEscapeAction(), value => settings.setDoubleEscapeAction(value)),
+        choice("treeFilterMode", offered("treeFilterMode"), () => settings.getTreeFilterMode(), value => settings.setTreeFilterMode(value)),
+        bool("showHardwareCursor", () => settings.getShowHardwareCursor(), value => settings.setShowHardwareCursor(value)),
+        numberSetting("editorPaddingX", () => settings.getEditorPaddingX(), value => settings.setEditorPaddingX(value), 0),
+        choice("outputPad", offeredNumbers("outputPad"), () => settings.getOutputPad(), value => settings.setOutputPad(value)),
+        numberSetting("autocompleteMaxVisible", () => settings.getAutocompleteMaxVisible(), value => settings.setAutocompleteMaxVisible(value), 1),
+        bool("clearOnShrink", () => settings.getClearOnShrink(), value => settings.setClearOnShrink(value)),
+        bool("showTerminalProgress", () => settings.getShowTerminalProgress(), value => settings.setShowTerminalProgress(value)),
+        choice("tuiMode", offered("tuiMode"), () => settings.getTuiMode(), value => settings.setTuiMode(value)),
+        choice("fullscreenExitOutput", offered("fullscreenExitOutput"), () => settings.getFullscreenExitOutput(), value => settings.setFullscreenExitOutput(value)),
+        choice("fullscreenScrollbar", offered("fullscreenScrollbar"), () => settings.getFullscreenScrollbar(), value => settings.setFullscreenScrollbar(value)),
+        jsonObject("warnings", () => settings.getWarnings(), value => settings.setWarnings(value)),
+    ];
+}
+function bool(key, read, write) {
+    return { descriptor: { key, valueType: "boolean", writable: true }, read, write(value) { if (typeof value !== "boolean")
+            invalid(key); write(value); } };
+}
+function numberSetting(key, read, write, minimum) {
+    const declared = PRESENTATION.bounds[key];
+    const low = declared?.minimum ?? minimum;
+    const high = declared?.maximum;
+    return {
+        descriptor: { key, valueType: "number", writable: true },
+        read,
+        write(value) {
+            if (typeof value !== "number" || !Number.isSafeInteger(value) || value < low || (high !== undefined && value > high))
+                invalid(key);
+            write(value);
+        },
+    };
+}
+function stringSetting(key, read, write) {
+    return { descriptor: { key, valueType: "string", writable: true }, read, write(value) { if (typeof value !== "string" || value.length === 0)
+            invalid(key); write(value); } };
+}
+function jsonObject(key, read, write) {
+    return { descriptor: { key, valueType: "json", writable: true }, read: () => Object.fromEntries(Object.entries(read()).filter((entry) => typeof entry[1] === "boolean")), write(value) { if (!value || typeof value !== "object" || Array.isArray(value))
+            invalid(key); write(value); } };
+}
+function choice(key, choices, read, write) {
+    return { descriptor: { key, valueType: "enum", writable: true, choices }, read, write(value) { if (!choices.includes(value))
+            invalid(key); write(value); } };
+}
+function invalid(key) { throw new TypeError(`setting value is invalid: ${key}`); }

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

@@ -0,0 +1,20 @@
+import type { AgentJsonValue, AgentWorkflowDescriptor, AgentWorkflowPort } from "../agent-engine-contracts/index.js";
+import { type PiWorkflowRoute } from "./workflows.js";
+export type WorkflowCapability = "prompt" | "abort" | "compact" | "bash" | "models.read" | "models.write" | "auth.login" | "auth.logout" | "settings.read" | "settings.write" | "resources.read" | "resources.reload" | "session.read" | "session.new" | "session.resume" | "session.fork" | "session.tree" | "session.import" | "clipboard.write" | "export.write" | "share.write" | "process.quit" | "diagnostics.read";
+export interface WorkflowControllerResult {
+    readonly outcome: "completed" | "cancelled" | "failed";
+    readonly message: string;
+    readonly value?: AgentJsonValue;
+}
+export declare class PiWorkflowControllerPort implements AgentWorkflowPort {
+    #private;
+    private readonly execute;
+    readonly capabilities: {
+        execute: boolean;
+    };
+    constructor(available: readonly WorkflowCapability[], execute: (workflowId: PiWorkflowRoute, input: AgentJsonValue, signal?: AbortSignal) => Promise<WorkflowControllerResult>);
+    listWorkflows(): Promise<readonly AgentWorkflowDescriptor[]>;
+    executeWorkflow(workflowId: string, input: AgentJsonValue, signal?: AbortSignal): Promise<AgentJsonValue>;
+}
+export declare const PI_BUILTIN_WORKFLOW_ROUTES: readonly ("name" | "share" | "model" | "login" | "logout" | "settings" | "reload" | "compact" | "new" | "resume" | "scoped-models" | "export" | "import" | "copy" | "session" | "changelog" | "hotkeys" | "fork" | "clone" | "tree" | "trust" | "quit" | "debug" | "arminsayshi" | "dementedelves")[];
+export declare const PI_WORKFLOW_CAPABILITIES: readonly WorkflowCapability[];

package/dist/src/foundation/pi-engine-adapter/workflow-controllers.js

@@ -0,0 +1,48 @@
+import { PINNED_PI_HIDDEN_COMMAND_NAMES, PINNED_PI_WORKFLOW_COMMAND_NAMES } from "./workflows.js";
+const DEFINITIONS = [
+    define("settings", "settings.read", "settings.write"), define("model", "models.read", "models.write"),
+    define("scoped-models", "models.read", "models.write"), define("export", "export.write"), define("import", "session.import"),
+    define("share", "share.write"), define("copy", "clipboard.write"), define("name", "session.read"), define("session", "session.read"),
+    define("changelog", "resources.read"), define("hotkeys", "resources.read"), define("fork", "session.fork"), define("clone", "session.fork"),
+    define("tree", "session.tree"), define("trust", "settings.write"), define("login", "auth.login"), define("logout", "auth.logout"),
+    define("new", "session.new"), define("compact", "compact"), define("resume", "session.resume"), define("reload", "resources.reload"),
+    define("quit", "process.quit"), define("debug", "diagnostics.read"), define("arminsayshi", "resources.read"), define("dementedelves", "resources.read"),
+];
+export class PiWorkflowControllerPort {
+    execute;
+    capabilities = { execute: true };
+    #available;
+    constructor(available, execute) {
+        this.execute = execute;
+        this.#available = new Set(available);
+    }
+    async listWorkflows() {
+        return DEFINITIONS.map(definition => ({ id: definition.id, label: definition.id, requiredCommands: definition.required }));
+    }
+    async executeWorkflow(workflowId, input, signal) {
+        const definition = DEFINITIONS.find(value => value.id === workflowId);
+        if (!definition)
+            return failure(`workflow is unavailable: ${workflowId}`);
+        const missing = definition.required.filter(capability => !this.#available.has(capability));
+        if (missing.length > 0)
+            return failure(`${workflowId} requires unavailable capabilities: ${missing.join(", ")}`);
+        if (signal?.aborted)
+            return { outcome: "cancelled", message: "workflow cancelled" };
+        try {
+            const result = await this.execute(definition.id, input, signal);
+            return { ...result, message: bounded(result.message) };
+        }
+        catch (error) {
+            return failure(`${workflowId} failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+export const PI_BUILTIN_WORKFLOW_ROUTES = Object.freeze([...PINNED_PI_WORKFLOW_COMMAND_NAMES, ...PINNED_PI_HIDDEN_COMMAND_NAMES]);
+export const PI_WORKFLOW_CAPABILITIES = Object.freeze([
+    "prompt", "abort", "compact", "bash", "models.read", "models.write", "auth.login", "auth.logout", "settings.read", "settings.write",
+    "resources.read", "resources.reload", "session.read", "session.new", "session.resume", "session.fork", "session.tree", "session.import",
+    "clipboard.write", "export.write", "share.write", "process.quit", "diagnostics.read",
+]);
+function define(id, ...required) { return { id, required }; }
+function failure(message) { return { outcome: "failed", message: bounded(message) }; }
+function bounded(message) { return message.length <= 512 ? message : `${message.slice(0, 509)}...`; }

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

@@ -48,6 +48,15 @@ export interface PiWorkflowOption {
     readonly label: string;
     readonly description?: string;
 }
+export interface PiAuthenticationProviderStatus {
+    readonly type: "oauth" | "api_key";
+    readonly source?: string;
+}
+export interface PiAuthenticationProviderOption extends PiWorkflowOption {
+    readonly providerId: string;
+    readonly authType: "oauth" | "api_key";
+    readonly status?: PiAuthenticationProviderStatus;
+}
 export interface PiWorkflowRequest {
     readonly command: PiWorkflowRoute;
     readonly argument: string;
@@ -162,4 +171,3 @@ export interface PiBashWorkflowResult {
     readonly truncated: boolean;
     readonly excludeFromContext: boolean;
 }
-//# sourceMappingURL=workflows.d.ts.map