@pasko70/pibo 3.0.1 → 3.1.0

package/README.md

@@ -24,6 +24,19 @@ pibo --help
 
 The current package declares Node.js 24+. Some Linux distributions still ship Node 22 through `apt`, so install a recent Node release first when needed. A user-local Node/npm setup through `nvm`, `fnm`, or a user-writable npm prefix works well.
 
+Package installation has no host-level side effects. For a self-hosted server, choose a supported setup profile after installing the CLI:
+
+```bash
+# Recommended complete workstation
+pibo setup plan --profile batteries-included --domain pibo.example.com
+sudo pibo setup install --profile batteries-included --domain pibo.example.com --apply --yes
+
+# Minimal gateway and Chat Web only
+pibo setup plan --profile vanilla --domain pibo.example.com
+```
+
+See [Installation profiles](./docs/project/installation-profiles.md) for components, resource and security costs, staging, upgrades, and rollback.
+
 For a user-local global npm prefix:
 
 ```bash
@@ -67,17 +80,18 @@ A fresh server install usually needs only three decisions:
 2. Install Node.js 24+ for that user or system-wide.
 3. Install Pibo through npm.
 
-Use the setup planner to keep the first run simple:
+Use an installation profile for the normal first run. Batteries Included is recommended; Vanilla is the minimal controlled base:
 
 ```bash
 pibo setup doctor --domain pibo.example.com --expected-ip <server-ip>
-pibo setup user-host --domain pibo.example.com --print-files
-pibo setup user-host --domain pibo.example.com --write-to /tmp/pibo-setup
+pibo setup plan --profile batteries-included --domain pibo.example.com
+pibo setup install --profile batteries-included --domain pibo.example.com --write-to /tmp/pibo-setup
+sudo pibo setup install --profile batteries-included --domain pibo.example.com --apply --yes
 ```
 
-This is the normal user path: one gateway, one `PIBO_HOME`, no required Docker, no dev gateway, and no GitHub App setup. After reviewing staged files, use `--apply --yes` to write the generated systemd/Caddy files.
+The package install remains side-effect free. The explicit setup command records ownership, checks pinned downloads, configures the selected components, and exposes status, upgrade, and uninstall plans. See [Installation profiles](./docs/project/installation-profiles.md).
 
-Developer hosts are opt-in and add production/dev separation plus Docker compute workers:
+Core developers can still use the topology-specific developer-host planner to add production/dev separation plus Docker compute workers:
 
 ```bash
 pibo setup developer-host \
@@ -159,7 +173,7 @@ pibo mcp          # discover and call configured MCP servers
 pibo tools        # install and inspect curated external CLI tools
 pibo pi-packages  # register Pi Coding Agent packages
 pibo debug        # inspect local Pibo data stores
-pibo setup        # plan user-host installs and developer-host upgrades
+pibo setup        # plan and manage supported host installation profiles
 pibo profile      # inspect runtime profiles
 pibo tui          # start the direct Pi TUI
 pibo tui:routed   # start the routed Pibo TUI

package/compute-image/Dockerfile

@@ -0,0 +1,47 @@
+FROM node:24-slim
+
+RUN apt-get update && apt-get install -y \
+    python3 python3-venv python3-dev \
+    build-essential curl git ca-certificates \
+    chromium chromium-driver xvfb xauth x11-xserver-utils \
+    fonts-liberation libappindicator3-1 libasound2 libatk-bridge2.0-0 \
+    libatk1.0-0 libcups2 libdbus-1-3 libdrm2 libgbm1 libgtk-3-0 libnspr4 \
+    libnss3 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 xdg-utils \
+    dbus dbus-x11 \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.local/bin:${PATH}"
+ENV DISPLAY=:99
+ENV PIBO_BROWSER_USE_CHROME=/usr/bin/chromium
+
+# The host stages only the published package archive and this Dockerfile, so an
+# installed package's production node_modules never enters the build context.
+COPY pibo-package.tgz /tmp/pibo-package.tgz
+
+WORKDIR /app
+RUN npm init -y >/dev/null && \
+    npm install --omit=dev --no-audit --no-fund /tmp/pibo-package.tgz && \
+    rm -f /tmp/pibo-package.tgz
+
+RUN mkdir -p /root/.pibo/tools/browser-use/home/bin && \
+    uv venv /root/.pibo/tools/browser-use/.venv --python 3.12 && \
+    uv pip install --python /root/.pibo/tools/browser-use/.venv/bin/python \
+    'browser-use[cli]==0.12.6'
+
+RUN mkdir -p /root/.pibo/tools/agent-browser/home/bin \
+    /root/.pibo/tools/agent-browser/home/profiles \
+    /root/.pibo/tools/agent-browser/node && \
+    npm install --prefix /root/.pibo/tools/agent-browser/node agent-browser@0.27.0
+
+WORKDIR /app/node_modules/@pasko70/pibo
+RUN sed -i 's/\r$//' scripts/*.sh && \
+    chmod +x scripts/*.sh && \
+    scripts/prepare-browser-use-wrapper.sh && \
+    scripts/prepare-agent-browser-wrapper.sh && \
+    mkdir -p /root/.pibo /root/.browser-use /root/.pibo/tools/agent-browser/home
+
+EXPOSE 4788 4789 56663
+
+ENTRYPOINT ["/app/node_modules/@pasko70/pibo/scripts/docker-entrypoint.sh"]
+CMD ["gateway:web"]

package/compute-image/Dockerfile.dockerignore

@@ -0,0 +1,5 @@
+node_modules
+node_modules/**
+.pibo
+.pibo/**
+*.log

package/dist/agent-runtime/context-build.js

@@ -17,6 +17,7 @@ export function profileWithRuntimeInstance(profile, runtimeInstanceId) {
         parentSessionId: profile.parentSessionId,
         model: undefined,
         mainModel: undefined,
+        mainModelFallbacks: [],
         subagentModel: undefined,
         thinkingLevel: profile.thinkingLevel,
         mainThinkingLevel: profile.mainThinkingLevel,
@@ -30,6 +31,7 @@ export function profileWithRuntimeInstance(profile, runtimeInstanceId) {
         mcpServers: profile.mcpServers,
         piPackages: profile.piPackages,
         contextFiles: profile.contextFiles,
+        diagnostics: profile.diagnostics,
         builtinTools: profile.builtinTools,
         builtinToolNames: profile.builtinToolNames,
         autoContextFiles: profile.autoContextFiles,
@@ -229,6 +231,7 @@ export function buildPortableRuntimeContextSnapshot(input) {
         metadata: {
             activeModel: runtimeManifest.effectiveModel,
             mainModel: profile.mainModel,
+            mainModelFallbacks: profile.mainModelFallbacks,
             subagentModel: profile.subagentModel,
             mainThinkingLevel: profile.mainThinkingLevel ?? profile.thinkingLevel,
             subagentThinkingLevel: profile.subagentThinkingLevel ?? profile.thinkingLevel,
@@ -240,6 +243,21 @@ export function buildPortableRuntimeContextSnapshot(input) {
                 ?? input.runtime.capabilities.nativeSubagents.enabledByDefault,
         },
     });
+    for (const [index, diagnostic] of profile.diagnostics.entries()) {
+        addNode({
+            id: `profile-diagnostic-${index}`,
+            kind: "diagnostic",
+            title: diagnostic.code,
+            source: "profile",
+            state: diagnostic.severity === "error" ? "error" : "warning",
+            badges: [diagnostic.severity.toUpperCase(), "PROFILE"],
+            hydratedText: diagnostic.message,
+            metadata: diagnostic.resourceName ? {
+                resourceKind: diagnostic.resourceKind,
+                resourceName: diagnostic.resourceName,
+            } : undefined,
+        });
+    }
     for (const [index, diagnostic] of input.runtime.diagnostics.entries()) {
         addNode({
             id: `runtime-diagnostic-${index}`,
@@ -265,9 +283,11 @@ export function buildPortableRuntimeContextSnapshot(input) {
         });
     }
     const resourceDiagnostics = input.resources?.diagnostics ?? [];
-    const warnings = input.runtime.diagnostics.filter((diagnostic) => diagnostic.severity === "warning").length
+    const warnings = profile.diagnostics.filter((diagnostic) => diagnostic.severity === "warning").length
+        + input.runtime.diagnostics.filter((diagnostic) => diagnostic.severity === "warning").length
         + resourceDiagnostics.filter((diagnostic) => diagnostic.severity === "warning").length;
-    const errors = input.runtime.diagnostics.filter((diagnostic) => diagnostic.severity === "error").length
+    const errors = profile.diagnostics.filter((diagnostic) => diagnostic.severity === "error").length
+        + input.runtime.diagnostics.filter((diagnostic) => diagnostic.severity === "error").length
         + resourceDiagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
     return {
         version: 1,
@@ -287,6 +307,10 @@ export function buildPortableRuntimeContextSnapshot(input) {
         },
         nodes,
         diagnostics: [
+            ...profile.diagnostics.map((diagnostic) => ({
+                type: diagnostic.severity,
+                message: `[${diagnostic.code}] ${diagnostic.message}`,
+            })),
             ...input.runtime.diagnostics.map((diagnostic) => ({ type: diagnostic.severity, message: diagnostic.message })),
             ...resourceDiagnostics.map((diagnostic) => ({ type: diagnostic.severity, message: diagnostic.message })),
         ],

package/dist/agent-runtime/contract.js

@@ -1,46 +1,96 @@
 import { AgentRuntimeContractError } from "./errors.js";
+import { validateAgentRuntimeCapabilities } from "./capabilities.js";
 import { hasPendingNativeSession } from "../sessions/runtime-binding.js";
+const REQUIRED_SESSION_METHODS = ["getBinding", "subscribe", "prompt", "abort", "dispose", "getStatus"];
+const BINDING_STATES = new Set(["unbound", "bound", "missing", "error"]);
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
 export function validateAgentRuntimeSessionContract(session) {
     const errors = [];
-    const capabilities = session.capabilities;
-    const controls = session.controls;
+    if (!isRecord(session))
+        return ["session must be an object"];
+    for (const field of ["adapterId", "runtimeInstanceId", "cwd"]) {
+        if (typeof session[field] !== "string" || !session[field].trim()) {
+            errors.push(`session.${field} must be a non-empty string`);
+        }
+    }
+    for (const method of REQUIRED_SESSION_METHODS) {
+        if (typeof session[method] !== "function")
+            errors.push(`session.${method}() is required`);
+    }
+    let capabilities;
+    if (!isRecord(session.capabilities)) {
+        errors.push("session.capabilities must be an object");
+    }
+    else {
+        const capabilityErrors = validateAgentRuntimeCapabilities(session.capabilities);
+        errors.push(...capabilityErrors.map((error) => `session.capabilities.${error}`));
+        if (capabilityErrors.length === 0)
+            capabilities = session.capabilities;
+    }
+    const controls = isRecord(session.controls) ? session.controls : undefined;
+    if (session.controls !== undefined && !controls)
+        errors.push("session.controls must be an object when provided");
     const requireMethod = (enabled, path, method) => {
         if (enabled && typeof controls?.[method] !== "function") {
             errors.push(`${path} requires controls.${String(method)}()`);
         }
     };
-    if (capabilities.input.steering && typeof session.steer !== "function") {
+    if (capabilities?.input.steering && typeof session.steer !== "function") {
         errors.push("input.steering requires session.steer()");
     }
-    requireMethod(capabilities.lifecycle.listNativeSessions, "lifecycle.listNativeSessions", "listSessions");
-    requireMethod(capabilities.lifecycle.fork, "lifecycle.fork", "forkSession");
-    requireMethod(capabilities.lifecycle.clone, "lifecycle.clone", "cloneSession");
-    requireMethod(capabilities.lifecycle.tree, "lifecycle.tree", "getSessionTree");
-    requireMethod(capabilities.lifecycle.tree, "lifecycle.tree", "navigateSessionTree");
-    requireMethod(capabilities.models.switchInSession, "models.switchInSession", "setModel");
-    requireMethod(capabilities.reasoning.supported, "reasoning.supported", "getReasoning");
-    requireMethod(capabilities.reasoning.supported, "reasoning.supported", "setReasoning");
-    requireMethod(capabilities.approvals.supported, "approvals.supported", "respondToApproval");
-    requireMethod(capabilities.approvals.structuredUserInput, "approvals.structuredUserInput", "respondToUserInput");
-    requireMethod(capabilities.maintenance.compaction, "maintenance.compaction", "compact");
-    const binding = session.getBinding();
-    if (binding.adapterId !== session.adapterId) {
-        errors.push(`binding.adapterId "${binding.adapterId}" does not match session.adapterId "${session.adapterId}"`);
-    }
-    if (binding.runtimeInstanceId !== session.runtimeInstanceId) {
-        errors.push(`binding.runtimeInstanceId "${binding.runtimeInstanceId}" does not match session.runtimeInstanceId "${session.runtimeInstanceId}"`);
-    }
-    if (binding.state === "bound" && !binding.nativeSessionId) {
-        errors.push("a bound session requires binding.nativeSessionId");
-    }
-    if (binding.state === "unbound" && binding.nativeSessionId && !hasPendingNativeSession(binding)) {
-        errors.push("an unbound session must not expose binding.nativeSessionId");
+    if (capabilities) {
+        requireMethod(capabilities.lifecycle.listNativeSessions, "lifecycle.listNativeSessions", "listSessions");
+        requireMethod(capabilities.lifecycle.fork, "lifecycle.fork", "forkSession");
+        requireMethod(capabilities.lifecycle.clone, "lifecycle.clone", "cloneSession");
+        requireMethod(capabilities.lifecycle.tree, "lifecycle.tree", "getSessionTree");
+        requireMethod(capabilities.lifecycle.tree, "lifecycle.tree", "navigateSessionTree");
+        requireMethod(capabilities.models.switchInSession, "models.switchInSession", "setModel");
+        requireMethod(capabilities.reasoning.supported, "reasoning.supported", "getReasoning");
+        requireMethod(capabilities.reasoning.supported, "reasoning.supported", "setReasoning");
+        requireMethod(capabilities.approvals.supported, "approvals.supported", "respondToApproval");
+        requireMethod(capabilities.approvals.structuredUserInput, "approvals.structuredUserInput", "respondToUserInput");
+        requireMethod(capabilities.maintenance.compaction, "maintenance.compaction", "compact");
+    }
+    if (typeof session.getBinding === "function") {
+        try {
+            const binding = session.getBinding();
+            if (!isRecord(binding)) {
+                errors.push("session.getBinding() must return an object");
+            }
+            else {
+                for (const field of ["piboSessionId", "runtimeInstanceId", "adapterId"]) {
+                    if (typeof binding[field] !== "string" || !binding[field].trim()) {
+                        errors.push(`session.getBinding().${field} must be a non-empty string`);
+                    }
+                }
+                if (!BINDING_STATES.has(String(binding.state))) {
+                    errors.push("session.getBinding().state is invalid");
+                }
+                if (binding.adapterId !== session.adapterId) {
+                    errors.push(`binding.adapterId "${String(binding.adapterId)}" does not match session.adapterId "${String(session.adapterId)}"`);
+                }
+                if (binding.runtimeInstanceId !== session.runtimeInstanceId) {
+                    errors.push(`binding.runtimeInstanceId "${String(binding.runtimeInstanceId)}" does not match session.runtimeInstanceId "${String(session.runtimeInstanceId)}"`);
+                }
+                if (binding.state === "bound" && !binding.nativeSessionId) {
+                    errors.push("a bound session requires binding.nativeSessionId");
+                }
+                if (binding.state === "unbound" && binding.nativeSessionId && !hasPendingNativeSession(binding)) {
+                    errors.push("an unbound session must not expose binding.nativeSessionId");
+                }
+            }
+        }
+        catch {
+            errors.push("session.getBinding() must not throw during contract validation");
+        }
     }
     return errors;
 }
-export function assertAgentRuntimeSessionContract(session) {
+export function assertAgentRuntimeSessionContract(session, runtimeInstanceId) {
     const errors = validateAgentRuntimeSessionContract(session);
     if (errors.length > 0) {
-        throw new AgentRuntimeContractError(session.runtimeInstanceId, `Agent runtime session contract failed: ${errors.join("; ")}`);
+        throw new AgentRuntimeContractError(runtimeInstanceId ?? (isRecord(session) && typeof session.runtimeInstanceId === "string" ? session.runtimeInstanceId : "unknown"), `Agent runtime session contract failed: ${errors.join("; ")}`);
     }
 }

package/dist/agent-runtime/portable-history.js

@@ -46,6 +46,9 @@ function boundedIdentifierText(value, fallback, maxLength = 512) {
 function optionalBoundedIdentifierText(value) {
     return value ? boundedIdentifierText(value, "portable-id") : undefined;
 }
+function toolInvocationKey(turnId, toolCallId) {
+    return JSON.stringify([turnId ?? null, toolCallId]);
+}
 function boundedText(value, maxBytes = MAX_ENTRY_BYTES) {
     if (Buffer.byteLength(value, "utf8") <= maxBytes)
         return value;
@@ -274,18 +277,22 @@ export class PiboDataPortableHistoryProvider {
         for (const row of rows) {
             if (!row.tool_call_id)
                 continue;
+            const invocationKey = toolInvocationKey(row.turn_id, row.tool_call_id);
             if (row.type === "tool_call") {
                 const attributes = parseObject(row.attributes_json);
-                const existing = calls.get(row.tool_call_id);
+                const existing = calls.get(invocationKey);
                 if (!existing || attributes.argsComplete === true)
-                    calls.set(row.tool_call_id, row);
+                    calls.set(invocationKey, row);
             }
             else {
-                results.set(row.tool_call_id, row);
+                results.set(invocationKey, row);
             }
         }
         const entries = [];
-        for (const [toolCallId, row] of calls) {
+        for (const row of calls.values()) {
+            const toolCallId = row.tool_call_id;
+            if (!toolCallId)
+                continue;
             const attributes = parseObject(row.attributes_json);
             const portableToolCallId = boundedIdentifierText(toolCallId, `tool-call-${row.stream_id}`);
             const toolName = boundedIdentifierText(typeof attributes.toolName === "string" ? attributes.toolName : row.preview_text ?? "tool", "tool", 256);
@@ -309,7 +316,10 @@ export class PiboDataPortableHistoryProvider {
                 toolName,
             });
         }
-        for (const [toolCallId, row] of results) {
+        for (const row of results.values()) {
+            const toolCallId = row.tool_call_id;
+            if (!toolCallId)
+                continue;
             const attributes = parseObject(row.attributes_json);
             const portableToolCallId = boundedIdentifierText(toolCallId, `tool-call-${row.stream_id}`);
             const toolName = boundedIdentifierText(typeof attributes.toolName === "string" ? attributes.toolName : row.preview_text ?? "tool", "tool", 256);
@@ -374,18 +384,18 @@ function normalizeToolPairs(entries) {
         if (entry.type !== "message")
             continue;
         if (entry.role === "tool" && entry.toolCallId)
-            resultIds.add(entry.toolCallId);
+            resultIds.add(toolInvocationKey(entry.turnId, entry.toolCallId));
         if (!Array.isArray(entry.content))
             continue;
         for (const part of entry.content) {
             if (part.type === "tool_call")
-                callIds.add(part.toolCallId);
+                callIds.add(toolInvocationKey(entry.turnId, part.toolCallId));
         }
     }
     return entries.map((entry) => {
         if (entry.type !== "message")
             return entry;
-        if (entry.role === "tool" && entry.toolCallId && !callIds.has(entry.toolCallId)) {
+        if (entry.role === "tool" && entry.toolCallId && !callIds.has(toolInvocationKey(entry.turnId, entry.toolCallId))) {
             return {
                 ...entry,
                 role: "user",
@@ -402,7 +412,7 @@ function normalizeToolPairs(entries) {
         if (entry.role !== "assistant" || !Array.isArray(entry.content))
             return entry;
         const content = entry.content.map((part) => {
-            if (part.type !== "tool_call" || resultIds.has(part.toolCallId))
+            if (part.type !== "tool_call" || resultIds.has(toolInvocationKey(entry.turnId, part.toolCallId)))
                 return part;
             return {
                 type: "text",

package/dist/agent-runtime/registry.js

@@ -450,10 +450,16 @@ export class AgentRuntimeAdapterRegistry {
         const adapter = this.requireInstance(instanceId);
         const session = await adapter.openSession(input);
         try {
-            assertAgentRuntimeSessionContract(session);
+            assertAgentRuntimeSessionContract(session, instanceId);
         }
         catch (error) {
-            await session.dispose().catch(() => { });
+            try {
+                if (typeof session?.dispose === "function")
+                    await session.dispose();
+            }
+            catch {
+                // Preserve the admission error when best-effort cleanup also fails.
+            }
             throw error;
         }
         return session;

package/dist/agent-runtime/routed-session.js

@@ -1,5 +1,6 @@
 import { PiboSteeringUnavailableError, } from "../core/events.js";
-import { runtimeSessionErrorDetails } from "../core/session-errors.js";
+import { PIBO_PROVIDER_RECOVERY_PROMPT, isPiboProviderFallbackError } from "../core/provider-recovery.js";
+import { normalizeSessionErrorDetails, runtimeSessionErrorDetails } from "../core/session-errors.js";
 import { isPiboThinkingLevel } from "../core/thinking.js";
 import { AgentRuntimeCapabilityUnavailableError } from "./errors.js";
 const RUN_REMINDER_CAPABILITY_TOOLS = new Set([
@@ -13,7 +14,7 @@ const RUN_REMINDER_CAPABILITY_TOOLS = new Set([
 const RUN_REMINDER_MAX_TOOL_EXECUTIONS = 64;
 const RUN_REMINDER_MAX_PROVIDER_ROUNDS = 64;
 const RUN_REMINDER_MAX_ACTIVE_TOKENS = 2_000_000;
-const RUN_REMINDER_MAX_DURATION_MS = 15 * 60 * 1000;
+export const RUN_REMINDER_MAX_DURATION_MS = 15 * 60 * 1000;
 const RUN_REMINDER_MAX_REPEATED_TOOL_CALLS = 12;
 function serializedToolArgs(value) {
     try {
@@ -29,6 +30,23 @@ function errorMessage(error) {
 function promptSource(source) {
     return source === "user" || source === "ui" ? "interactive" : "rpc";
 }
+function sameModel(left, right) {
+    return Boolean(left && right && left.provider === right.provider && left.id === right.id);
+}
+function uniqueModels(models) {
+    const seen = new Set();
+    return models.flatMap((model) => {
+        const provider = model.provider.trim();
+        const id = model.id.trim();
+        if (!provider || !id)
+            return [];
+        const key = `${provider}\u0000${id}`;
+        if (seen.has(key))
+            return [];
+        seen.add(key);
+        return [{ provider, id }];
+    });
+}
 function runtimeCapabilityError(session, capability) {
     return new AgentRuntimeCapabilityUnavailableError(capability, session.runtimeInstanceId, `Runtime instance "${session.runtimeInstanceId}" does not support ${capability}.`);
 }
@@ -120,6 +138,10 @@ export class RuntimeRoutedSession {
     nextThinkingIndex = 0;
     sessionIdentityOperationInFlight = false;
     forkCandidatesRequest;
+    primaryModel;
+    modelFallbacks;
+    suppressProviderFailures = false;
+    pendingProviderFailure;
     unsubscribe;
     constructor(piboSessionId, runtimeSession, emit, pluginRegistry, options = {}) {
         this.piboSessionId = piboSessionId;
@@ -128,6 +150,10 @@ export class RuntimeRoutedSession {
         this.pluginRegistry = pluginRegistry;
         this.options = options;
         this.runtime = runtimeSession.getNativeCompatibilityHandle?.() ?? runtimeSession;
+        this.primaryModel = runtimeSession.getStatus().activeModel
+            ? { ...runtimeSession.getStatus().activeModel }
+            : undefined;
+        this.modelFallbacks = uniqueModels(options.modelFallbacks ?? []);
         this.unsubscribe = runtimeSession.subscribe((event) => this.handleRuntimeEvent(event));
     }
     enqueueMessage(event, onAccepted = () => { }) {
@@ -182,14 +208,20 @@ export class RuntimeRoutedSession {
         this.assertActive();
         if (event.action === "compact")
             return this.enqueueCompactAction(event);
-        const changesSessionIdentity = event.action === "session.fork" || event.action === "session.clone";
-        if (changesSessionIdentity) {
-            this.assertSessionIdentityOperationIdle(event.action === "session.fork" ? "fork" : "clone");
+        const sessionIdentityOperation = event.action === "session.fork"
+            ? "fork"
+            : event.action === "session.clone"
+                ? "clone"
+                : event.action === "session.switch"
+                    ? "switch"
+                    : undefined;
+        if (sessionIdentityOperation) {
+            this.assertSessionIdentityOperationIdle(sessionIdentityOperation);
             this.sessionIdentityOperationInFlight = true;
             this.notifyState();
         }
         try {
-            if (changesSessionIdentity)
+            if (sessionIdentityOperation)
                 await this.options.onBeforeSessionIdentityOperation?.(event);
             const result = await this.runAction(event);
             if (isSessionOperationResult(result))
@@ -205,7 +237,7 @@ export class RuntimeRoutedSession {
             return output;
         }
         finally {
-            if (changesSessionIdentity) {
+            if (sessionIdentityOperation) {
                 this.sessionIdentityOperationInFlight = false;
                 this.notifyState();
                 this.startDrain();
@@ -407,7 +439,9 @@ export class RuntimeRoutedSession {
         const setModel = this.runtimeSession.controls?.setModel;
         if (!setModel)
             throw runtimeCapabilityError(this.runtimeSession, "in-session model switching");
-        return await setModel(model);
+        const selected = await setModel(model);
+        this.primaryModel = { ...selected };
+        return selected;
     }
     setThinkingLevel(level) {
         const setReasoning = this.runtimeSession.controls?.setReasoning;
@@ -642,10 +676,10 @@ export class RuntimeRoutedSession {
                 }));
                 return;
             case "error":
-                this.emitRuntimeError(event.message, event.details);
+                this.handleRuntimeFailure(event.message, event.details);
                 return;
             case "turn_failed":
-                this.emitRuntimeError(event.message, event.details);
+                this.handleRuntimeFailure(event.message, event.details);
                 return;
             case "native_event":
                 this.options.onNativeEventTelemetry?.(this.piboSessionId, event.event, {
@@ -661,6 +695,14 @@ export class RuntimeRoutedSession {
                 return;
         }
     }
+    handleRuntimeFailure(message, details) {
+        const normalized = normalizeSessionErrorDetails(message, details);
+        if (this.suppressProviderFailures && isPiboProviderFallbackError(message, normalized)) {
+            this.pendingProviderFailure = { message, details: normalized };
+            return;
+        }
+        this.emitRuntimeError(message, normalized);
+    }
     emitRuntimeError(message, details) {
         if (this.activeMessageFailed)
             return;
@@ -706,6 +748,71 @@ export class RuntimeRoutedSession {
             this.notifyState();
         }
     }
+    async promptWithModelFallbacks(event, inFlight) {
+        const setModel = this.runtimeSession.controls?.setModel;
+        const fallbackModels = this.modelFallbacks.filter((model) => !sameModel(model, this.primaryModel));
+        if (!setModel || fallbackModels.length === 0) {
+            await this.runtimeSession.prompt({
+                text: event.text,
+                source: promptSource(event.source),
+                capabilityScope: event.capabilityScope,
+            });
+            return;
+        }
+        this.suppressProviderFailures = true;
+        let switchedModel = false;
+        let finalFailure;
+        try {
+            for (let attempt = 0; attempt <= fallbackModels.length; attempt += 1) {
+                if (this.disposed || inFlight.cancelled)
+                    return;
+                if (attempt > 0) {
+                    try {
+                        await setModel(fallbackModels[attempt - 1]);
+                        switchedModel = true;
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                this.pendingProviderFailure = undefined;
+                let promptError;
+                try {
+                    await this.runtimeSession.prompt({
+                        text: attempt === 0 ? event.text : PIBO_PROVIDER_RECOVERY_PROMPT,
+                        source: attempt === 0 ? promptSource(event.source) : "rpc",
+                        capabilityScope: event.capabilityScope,
+                    });
+                }
+                catch (error) {
+                    promptError = error;
+                }
+                if (this.disposed || inFlight.cancelled)
+                    return;
+                const failure = this.pendingProviderFailure;
+                if (!failure) {
+                    if (promptError)
+                        throw promptError;
+                    return;
+                }
+                finalFailure = failure;
+            }
+            if (finalFailure)
+                this.emitRuntimeError(finalFailure.message, finalFailure.details);
+        }
+        finally {
+            this.suppressProviderFailures = false;
+            this.pendingProviderFailure = undefined;
+            if (switchedModel && this.primaryModel && !this.disposed) {
+                try {
+                    await setModel(this.primaryModel);
+                }
+                catch (error) {
+                    console.warn(`Failed to restore primary model for Pibo session "${this.piboSessionId}": ${errorMessage(error)}`);
+                }
+            }
+        }
+    }
     async processQueuedMessage(event) {
         const inFlight = this.beginInFlightMessage(event);
         try {
@@ -743,11 +850,7 @@ export class RuntimeRoutedSession {
             });
             if (inFlight.cancelled)
                 return;
-            await this.runtimeSession.prompt({
-                text: event.text,
-                source: promptSource(event.source),
-                capabilityScope: event.capabilityScope,
-            });
+            await this.promptWithModelFallbacks(event, inFlight);
             if (this.disposed || inFlight.cancelled)
                 return;
             if (!this.activeMessageFailed) {
@@ -776,6 +879,8 @@ export class RuntimeRoutedSession {
             }
         }
         finally {
+            this.suppressProviderFailures = false;
+            this.pendingProviderFailure = undefined;
             this.activeMessage = undefined;
             this.activeMessageFailed = false;
             this.resetContentIndices();