@pasko70/pibo 1.16.5 → 2.0.0

package/dist/core/session-router.js

@@ -1,8 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { InitialSessionContext, } from "./profiles.js";
 import { createDefaultPiboPluginRegistry, createPiboProfileFromRegistryOrDefault, resolvePiboProfileNameFromRegistryOrDefault, selectDefaultPiboProfileName } from "../plugins/builtin.js";
-import { createPiboRuntime } from "./runtime.js";
-import { RoutedSession } from "./routed-session.js";
+import { RuntimeRoutedSession as RoutedSession, } from "../agent-runtime/routed-session.js";
 import { runtimeSessionErrorDetails } from "./session-errors.js";
 import { createSubagentToolName } from "../subagents/tool.js";
 import { PiboRunRegistry } from "../runs/registry.js";
@@ -11,6 +10,9 @@ import { PiboRunResourceLimitError } from "../runs/resource-isolation.js";
 import { createPiboSignalRegistry } from "../signals/registry.js";
 import { createDefaultPiboReliabilityStore } from "../reliability/store.js";
 import { InMemoryPiboSessionStore, } from "../sessions/store.js";
+import { createLegacyPiRuntimeSessionBinding, RuntimeSessionBindingConflictError, } from "../sessions/runtime-binding.js";
+import { AgentRuntimeBindingMissingError, AgentRuntimeUnavailableError } from "../agent-runtime/errors.js";
+import { validateAgentRuntimeProfileCapabilities } from "../agent-runtime/profile-validation.js";
 import { getDefaultPiboWorkspace } from "./workspace.js";
 import { loadPiboModelDefaults, selectRequestedFastMode } from "./model-defaults.js";
 import { loadPiboUserSettings } from "./user-settings.js";
@@ -22,8 +24,12 @@ import { withWorkflowSessionKind } from "../sessions/workflow-session-kind.js";
 import { PiboRuntimeTelemetryRecorder } from "./runtime-telemetry.js";
 import { createPiboProviderTelemetryExtension } from "./provider-telemetry.js";
 import { AsyncTelemetryWriter } from "../data/telemetry-writer.js";
+import { createPiboToolPayloadWriter } from "../tools/payload-writer.js";
+import { PiboPortableToolService, } from "../tools/session-service.js";
+import { PiboRuntimeResourceService, } from "../agent-runtime/resource-service.js";
 const DEFAULT_SUBAGENT_REPLY_TIMEOUT_MS = 10 * 60 * 1000;
 const DEFAULT_SUBAGENT_MAX_DEPTH = 3;
+const MAX_SUBAGENT_THREAD_KEY_BYTES = 512;
 const DEFAULT_ROUTED_SESSION_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 const DEFAULT_ROUTED_SESSION_DISPOSE_TIMEOUT_MS = 30 * 1000;
 export const LOOP_RUNTIME_RETRY_DEFAULTS = {
@@ -47,11 +53,27 @@ export function resolvePiboSessionInitialFastMode(session) {
 function hasReachedSubagentMaxDepth(subagent, depth) {
     return depth >= (subagent.maxDepth ?? DEFAULT_SUBAGENT_MAX_DEPTH);
 }
-function profileForSession(baseProfile, piSessionId, parentPiSessionId, subagentDepth) {
+function resolveSubagentThreadKey(threadKey) {
+    const normalized = threadKey?.trim();
+    if (!normalized)
+        return randomUUID();
+    if (Buffer.byteLength(normalized, "utf8") > MAX_SUBAGENT_THREAD_KEY_BYTES) {
+        throw new Error(`Subagent thread key exceeds ${MAX_SUBAGENT_THREAD_KEY_BYTES} bytes.`);
+    }
+    return normalized;
+}
+function subagentAbortError() {
+    const error = new Error("Subagent request was aborted.");
+    error.name = "AbortError";
+    return error;
+}
+function profileForSession(baseProfile, runtimeInstanceId, nativeSessionId, parentNativeSessionId, subagentDepth) {
     const options = {
         profileName: baseProfile.profileName,
-        sessionId: piSessionId,
-        parentSessionId: parentPiSessionId,
+        runtimeInstanceId,
+        runtimeOptions: baseProfile.runtimeOptions,
+        sessionId: nativeSessionId,
+        parentSessionId: parentNativeSessionId,
         model: baseProfile.model,
         mainModel: baseProfile.mainModel,
         subagentModel: baseProfile.subagentModel,
@@ -131,13 +153,32 @@ function isTerminalRunStatus(status) {
 function asJsonObject(value) {
     return value ?? {};
 }
-function shouldResetSessionAfterAction(action) {
-    return action === "login.complete" || action === "login.apikey" || action === "logout";
+function shouldResetSessionAfterAction(action, output) {
+    if (action === "login.apikey" || action === "logout")
+        return true;
+    if (action !== "login.complete")
+        return false;
+    const result = output?.type === "execution_result" && output.result && typeof output.result === "object" && !Array.isArray(output.result)
+        ? output.result
+        : undefined;
+    return result?.state !== "pending";
 }
 function piboRoomIdFromMetadata(metadata) {
     const value = metadata?.chatRoomId;
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
+function runtimeBindingsEqual(left, right) {
+    return left.piboSessionId === right.piboSessionId
+        && left.runtimeInstanceId === right.runtimeInstanceId
+        && left.adapterId === right.adapterId
+        && left.nativeSessionId === right.nativeSessionId
+        && left.state === right.state
+        && left.protocol === right.protocol
+        && left.protocolVersion === right.protocolVersion
+        && left.adapterVersion === right.adapterVersion
+        && JSON.stringify(left.locator ?? null) === JSON.stringify(right.locator ?? null)
+        && JSON.stringify(left.metadata ?? {}) === JSON.stringify(right.metadata ?? {});
+}
 class PiboSessionDisposalTimeoutError extends Error {
     piboSessionId;
     timeoutMs;
@@ -151,6 +192,9 @@ class PiboSessionDisposalTimeoutError extends Error {
 function telemetryStoreFromSessionStore(store) {
     return store.getTelemetryStore?.();
 }
+function payloadStoreFromSessionStore(store) {
+    return store.getPayloadStore?.();
+}
 function providerEventTelemetryModeFromEnv(env = process.env) {
     const value = env.PIBO_TELEMETRY_PROVIDER_EVENTS?.trim().toLowerCase();
     return value === "1" || value === "true" || value === "detailed" ? "detailed" : "aggregate";
@@ -164,6 +208,12 @@ export class PiboSessionRouter {
     gatewayWorkAdmission = new GatewayWorkAdmissionController();
     signalRegistry;
     runtimeRegistry;
+    portableToolService;
+    portableToolSessions = new Map();
+    runtimeResourceService;
+    runtimeResourceSessions = new Map();
+    runtimeAuthFingerprints = new Map();
+    activeSubagentChildren = new Map();
     scheduledRunReminders = new Map();
     runReminderGenerations = new Map();
     quiescingSessions = new Set();
@@ -173,6 +223,7 @@ export class PiboSessionRouter {
     routedSessionDisposeTimeoutMs;
     baseProfile;
     pluginRegistry;
+    compatibilityRuntimeRegistry;
     sessionStore;
     reliabilityStore;
     telemetryStore;
@@ -183,6 +234,9 @@ export class PiboSessionRouter {
     constructor(options = {}) {
         this.options = options;
         this.pluginRegistry = options.pluginRegistry ?? createDefaultPiboPluginRegistry();
+        // Historical custom registries supplied only actions/profiles while runtime creation was implicit.
+        // Preserve that composition contract during the adapter migration without branching on adapter ids.
+        this.compatibilityRuntimeRegistry = options.pluginRegistry ? createDefaultPiboPluginRegistry() : undefined;
         this.sessionStore = options.sessionStore ?? new InMemoryPiboSessionStore();
         this.telemetryStore = options.telemetryStore ?? telemetryStoreFromSessionStore(this.sessionStore);
         this.telemetryWriter = this.telemetryStore ? new AsyncTelemetryWriter(this.telemetryStore) : undefined;
@@ -207,6 +261,11 @@ export class PiboSessionRouter {
         this.reliabilityStore = options.reliabilityStore ?? (options.persistSession === false ? undefined : createDefaultPiboReliabilityStore());
         this.signalRegistry = options.signalRegistry ?? createPiboSignalRegistry();
         this.runtimeRegistry = new RuntimeSessionRegistry({ cwd: options.cwd ?? getDefaultPiboWorkspace() });
+        const payloadStore = payloadStoreFromSessionStore(this.sessionStore);
+        this.portableToolService = new PiboPortableToolService({
+            ...(payloadStore ? { payloadWriter: createPiboToolPayloadWriter(payloadStore) } : {}),
+        });
+        this.runtimeResourceService = options.runtimeResourceService ?? new PiboRuntimeResourceService();
         this.runRegistry = new PiboRunRegistry({ store: this.reliabilityStore });
         this.runRegistry.subscribe((event) => this.projectRunRegistryEvent(event));
         const recoveredRuntimeState = options.recoverInterruptedRuntimeState
@@ -299,13 +358,23 @@ export class PiboSessionRouter {
                 teardownCompleted = true;
                 return output;
             }
+            const childAbort = event.action === "abort"
+                ? this.abortActiveSubagentSessions(event.piboSessionId)
+                : undefined;
             const output = await session.executeAction(event);
+            await childAbort;
             if (event.action === "kill" || event.action === "kill_all") {
                 await this.disposeSessionSubtree(event.piboSessionId, `${event.action} action`, { cancelRuns: event.action === "kill_all" });
                 teardownCompleted = true;
             }
-            else if (shouldResetSessionAfterAction(event.action)) {
-                await this.resetCachedSession(event.piboSessionId, "provider auth changed");
+            else if (shouldResetSessionAfterAction(event.action, output)) {
+                const runtimeInstanceId = this.getSessionRuntimeBinding(event.piboSessionId)?.runtimeInstanceId;
+                if (runtimeInstanceId) {
+                    await this.resetCachedRuntimeAuthSessions(runtimeInstanceId, "runtime provider auth changed");
+                }
+                else {
+                    await this.resetCachedSession(event.piboSessionId, "runtime provider auth changed");
+                }
             }
             return output;
         }
@@ -333,6 +402,9 @@ export class PiboSessionRouter {
             this.scheduleIdleSessionEvictionIfIdle(event.piboSessionId);
         }
     }
+    async disposeSession(piboSessionId, reason = "session deleted") {
+        await this.disposeSessionSubtree(piboSessionId, reason, { cancelRuns: true });
+    }
     async killSession(piboSessionId, options) {
         const rootSession = this.sessions.get(piboSessionId);
         if (!rootSession)
@@ -388,6 +460,15 @@ export class PiboSessionRouter {
         finally {
             if (timeout)
                 clearTimeout(timeout);
+            const portableTools = this.portableToolSessions.get(piboSessionId);
+            portableTools?.dispose();
+            if (this.portableToolSessions.get(piboSessionId) === portableTools)
+                this.portableToolSessions.delete(piboSessionId);
+            const resources = this.runtimeResourceSessions.get(piboSessionId);
+            if (resources)
+                await resources.dispose();
+            if (this.runtimeResourceSessions.get(piboSessionId) === resources)
+                this.runtimeResourceSessions.delete(piboSessionId);
         }
     }
     async disposeSessionSubtree(piboSessionId, reason, options) {
@@ -480,13 +561,105 @@ export class PiboSessionRouter {
     getPiboSessionIds() {
         return [...this.sessions.keys()];
     }
+    async getAgentRuntimeAuthStatus(runtimeInstanceId) {
+        const registry = this.resolveAgentRuntimeRegistry(runtimeInstanceId);
+        const statuses = await registry.getAgentRuntimeAuthStatus(runtimeInstanceId);
+        const fingerprint = statuses
+            .map((status) => `${status.id}:${status.configured}:${status.details?.accountType ?? ""}:${status.details?.planType ?? ""}`)
+            .sort()
+            .join("|");
+        const previous = this.runtimeAuthFingerprints.get(runtimeInstanceId);
+        this.runtimeAuthFingerprints.set(runtimeInstanceId, fingerprint);
+        if (previous !== undefined && previous !== fingerprint) {
+            await this.resetCachedRuntimeAuthSessions(runtimeInstanceId, "runtime provider auth changed");
+        }
+        return statuses;
+    }
+    async startAgentRuntimeAuth(runtimeInstanceId, input) {
+        const registry = this.resolveAgentRuntimeRegistry(runtimeInstanceId);
+        const result = await registry.startAgentRuntimeAuth(runtimeInstanceId, input);
+        if (result.state !== "pending") {
+            await this.resetCachedRuntimeAuthSessions(runtimeInstanceId, "runtime provider auth changed");
+        }
+        return result;
+    }
+    async completeAgentRuntimeAuth(runtimeInstanceId, input) {
+        const registry = this.resolveAgentRuntimeRegistry(runtimeInstanceId);
+        const result = await registry.completeAgentRuntimeAuth(runtimeInstanceId, input);
+        if (result.state !== "pending") {
+            await this.resetCachedRuntimeAuthSessions(runtimeInstanceId, "runtime provider auth changed");
+        }
+        return result;
+    }
+    async cancelAgentRuntimeAuth(runtimeInstanceId, input) {
+        return await this.resolveAgentRuntimeRegistry(runtimeInstanceId)
+            .cancelAgentRuntimeAuth(runtimeInstanceId, input);
+    }
+    async logoutAgentRuntimeAuth(runtimeInstanceId, input) {
+        const result = await this.resolveAgentRuntimeRegistry(runtimeInstanceId)
+            .logoutAgentRuntimeAuth(runtimeInstanceId, input);
+        await this.resetCachedRuntimeAuthSessions(runtimeInstanceId, "runtime provider auth changed");
+        return result;
+    }
+    getSessionRuntimeBinding(piboSessionId) {
+        const session = this.sessionStore.get(piboSessionId);
+        return session ? structuredClone(this.resolveSessionRuntimeBinding(session)) : undefined;
+    }
+    async rebindSessionRuntime(piboSessionId, input) {
+        const session = this.sessionStore.get(piboSessionId);
+        if (!session)
+            throw new Error(`Unknown Pibo session "${piboSessionId}".`);
+        const current = this.resolveSessionRuntimeBinding(session);
+        const currentRevision = current.revision ?? 1;
+        if (currentRevision !== input.expectedRevision) {
+            throw new RuntimeSessionBindingConflictError(piboSessionId, input.expectedRevision, currentRevision);
+        }
+        const liveStatus = this.sessions.get(piboSessionId)?.getStatus();
+        if (liveStatus && (liveStatus.processing || liveStatus.streaming || liveStatus.queuedMessages > 0)) {
+            throw new Error("A runtime binding can only be repaired or rebound while the session is idle.");
+        }
+        if (this.sessions.has(piboSessionId) || this.pendingSessions.has(piboSessionId)) {
+            await this.resetCachedSession(piboSessionId, "runtime binding rebind");
+        }
+        const registry = this.resolveAgentRuntimeRegistry(input.runtimeInstanceId);
+        const adapter = registry.requireAgentRuntimeAdapter(input.runtimeInstanceId);
+        const requestedState = input.state ?? (input.nativeSessionId ? "bound" : "unbound");
+        let next = {
+            piboSessionId,
+            runtimeInstanceId: input.runtimeInstanceId,
+            adapterId: adapter.descriptor.id,
+            nativeSessionId: input.nativeSessionId,
+            state: requestedState,
+            protocol: adapter.descriptor.protocol?.name,
+            protocolVersion: current.runtimeInstanceId === input.runtimeInstanceId ? current.protocolVersion : undefined,
+            locator: input.locator,
+            metadata: {},
+        };
+        if (next.state === "bound" && adapter.resolveBinding) {
+            next = await adapter.resolveBinding({
+                binding: next,
+                workspace: session.workspace ?? this.options.cwd ?? getDefaultPiboWorkspace(),
+            });
+        }
+        const mode = (current.state === "missing" || current.state === "error")
+            && current.runtimeInstanceId === next.runtimeInstanceId
+            && current.adapterId === next.adapterId
+            ? "repair"
+            : "rebind";
+        const persisted = this.persistSessionRuntimeBinding(session, next, {
+            expectedRevision: input.expectedRevision,
+            mode,
+        });
+        return structuredClone(persisted);
+    }
     getSessionRuntimeStatus(piboSessionId) {
-        return this.sessions.get(piboSessionId)?.getStatus();
+        const status = this.sessions.get(piboSessionId)?.getStatus();
+        return status ? this.withPersistedRuntimeBinding(status) : undefined;
     }
     async getSessionStatusSnapshot(piboSessionId) {
         const session = await this.getOrCreateSession(piboSessionId);
         try {
-            return await session.getStatusSnapshot();
+            return this.withPersistedRuntimeBinding(await session.getStatusSnapshot());
         }
         finally {
             this.scheduleIdleSessionEvictionIfIdle(piboSessionId);
@@ -517,7 +690,7 @@ export class PiboSessionRouter {
         });
     }
     listSessionRuntimeStatuses() {
-        return [...this.sessions.values()].map((session) => session.getStatus());
+        return [...this.sessions.values()].map((session) => this.withPersistedRuntimeBinding(session.getStatus()));
     }
     listRuns(options = {}) {
         return this.runRegistry.listAll(options);
@@ -543,12 +716,42 @@ export class PiboSessionRouter {
     subscribeSignalStatuses(listener) {
         return this.signalRegistry.subscribeAll(listener);
     }
-    async emitMessageAndWaitForReply(event, timeoutMs = 120000) {
+    async emitMessageAndWaitForReply(event, timeoutMs = 120000, signal) {
         const eventWithId = { ...event, id: event.id ?? randomUUID() };
         return await new Promise((resolve, reject) => {
             let settled = false;
+            let messageDispatched = false;
             let lastAssistantMessage;
             let timeout;
+            const abortChild = () => {
+                if (!messageDispatched)
+                    return;
+                void this.emit({
+                    type: "execution",
+                    piboSessionId: eventWithId.piboSessionId,
+                    action: "abort",
+                    id: randomUUID(),
+                }).catch(() => { });
+            };
+            const finish = (result) => {
+                if (settled)
+                    return false;
+                settled = true;
+                if (timeout)
+                    clearTimeout(timeout);
+                signal?.removeEventListener("abort", onAbort);
+                unsubscribe();
+                if (result instanceof Error)
+                    reject(result);
+                else
+                    resolve(result);
+                return true;
+            };
+            const onAbort = () => {
+                if (!finish(subagentAbortError()))
+                    return;
+                abortChild();
+            };
             const unsubscribe = this.subscribe((output) => {
                 if (output.piboSessionId !== eventWithId.piboSessionId ||
                     !("eventId" in output) ||
@@ -565,34 +768,18 @@ export class PiboSessionRouter {
                     finish(new Error(output.error));
                 }
             });
-            const finish = (result) => {
-                if (settled)
-                    return;
-                settled = true;
-                if (timeout)
-                    clearTimeout(timeout);
-                unsubscribe();
-                if (result instanceof Error) {
-                    reject(result);
-                }
-                else {
-                    resolve(result);
-                }
-            };
+            if (signal?.aborted) {
+                onAbort();
+                return;
+            }
+            signal?.addEventListener("abort", onAbort, { once: true });
             timeout = setTimeout(() => {
-                if (settled)
-                    return;
-                settled = true;
-                unsubscribe();
                 const timeoutError = new Error(`Timed out waiting for assistant reply from Pibo session "${eventWithId.piboSessionId}"`);
-                reject(timeoutError);
-                void this.emit({
-                    type: "execution",
-                    piboSessionId: eventWithId.piboSessionId,
-                    action: "abort",
-                    id: randomUUID(),
-                }).catch(() => { });
+                if (!finish(timeoutError))
+                    return;
+                abortChild();
             }, timeoutMs);
+            messageDispatched = true;
             this.emit(eventWithId).catch(finish);
         });
     }
@@ -629,7 +816,18 @@ export class PiboSessionRouter {
                 throw new AggregateError(failures, "Failed to dispose all Pibo sessions");
         }
         finally {
+            const authDisposals = await Promise.allSettled([
+                this.pluginRegistry.disposeAgentRuntimeAuth(),
+                ...(this.compatibilityRuntimeRegistry ? [this.compatibilityRuntimeRegistry.disposeAgentRuntimeAuth()] : []),
+            ]);
+            await this.portableToolService.dispose();
+            await this.runtimeResourceService.dispose();
+            this.runtimeResourceSessions.clear();
+            this.activeSubagentChildren.clear();
             await this.telemetryWriter?.dispose();
+            const authFailures = authDisposals.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+            if (authFailures.length > 0)
+                throw new AggregateError(authFailures, "Failed to dispose runtime authentication controllers.");
         }
     }
     clearIdleSessionTimer(piboSessionId) {
@@ -707,55 +905,317 @@ export class PiboSessionRouter {
         let session;
         this.signalRegistry.project({ type: "session_created", session: piboSession });
         const profile = createPiboProfileFromRegistryOrDefault(this.pluginRegistry, piboSession.profile);
-        const parentPiSessionId = piboSession.parentId
-            ? this.resolvePiboSession(piboSession.parentId).piSessionId
+        let binding = this.resolveSessionRuntimeBinding(piboSession);
+        const parent = piboSession.parentId ? this.resolvePiboSession(piboSession.parentId) : undefined;
+        const parentBinding = parent ? this.resolveSessionRuntimeBinding(parent) : undefined;
+        const parentModelScopeId = parent ? parentBinding?.nativeSessionId ?? parent.id : undefined;
+        const runtimeParentNativeSessionId = parentBinding
+            && parentBinding.runtimeInstanceId === binding.runtimeInstanceId
+            && parentBinding.adapterId === binding.adapterId
+            ? parentBinding.nativeSessionId
             : undefined;
         const modelDefaults = this.resolveModelDefaults();
-        const activeModel = this.ensureSessionActiveModel(piboSession, profile, parentPiSessionId, modelDefaults);
+        const activeModel = this.ensureSessionActiveModel(piboSession, profile, parentModelScopeId, modelDefaults);
         const initialThinkingLevel = resolvePiboSessionInitialThinkingLevel(piboSession);
-        const sessionProfile = profileForSession(profile, piboSession.piSessionId, parentPiSessionId, this.getSubagentDepth(piboSession.id));
+        const sessionProfile = profileForSession(profile, binding.runtimeInstanceId, binding.nativeSessionId, runtimeParentNativeSessionId, this.getSubagentDepth(piboSession.id));
         const userSettings = loadPiboUserSettings();
         const telemetryExtension = this.telemetryStore
             ? createPiboProviderTelemetryExtension({ store: this.telemetryStore, writer: this.telemetryWriter, session: piboSession, model: activeModel })
             : undefined;
-        const runtime = await createPiboRuntime({
-            cwd: piboSession.workspace ?? this.options.cwd,
-            persistSession: this.options.persistSession,
-            thinkingLevel: initialThinkingLevel ?? this.options.thinkingLevel,
-            retryDefaults: resolvePiboSessionRetryDefaults(piboSession.kind, this.options.retryDefaults),
+        const runtimeRegistry = this.resolveAgentRuntimeRegistry(binding.runtimeInstanceId);
+        const runtimeAdapter = runtimeRegistry.requireAgentRuntimeAdapter(binding.runtimeInstanceId);
+        if (runtimeAdapter.descriptor.id !== binding.adapterId) {
+            throw new AgentRuntimeUnavailableError(binding.runtimeInstanceId, `Runtime binding for Pibo session "${piboSession.id}" expects adapter "${binding.adapterId}", but instance "${binding.runtimeInstanceId}" uses "${runtimeAdapter.descriptor.id}".`);
+        }
+        const workspace = piboSession.workspace ?? this.options.cwd ?? getDefaultPiboWorkspace();
+        if (binding.state === "bound" && runtimeAdapter.resolveBinding) {
+            const resolved = await runtimeAdapter.resolveBinding({ binding, workspace });
+            if (!runtimeBindingsEqual(binding, resolved)) {
+                binding = this.persistSessionRuntimeBinding(piboSession, resolved, {
+                    expectedRevision: binding.revision,
+                });
+            }
+        }
+        this.assertOpenableRuntimeBinding(binding);
+        const profileDiagnostics = [
+            ...validateAgentRuntimeProfileCapabilities(sessionProfile, runtimeAdapter.descriptor.capabilities),
+            ...runtimeAdapter.validateProfile({
+                profile: sessionProfile,
+                workspace,
+            }),
+        ];
+        const invalidProfile = profileDiagnostics.find((diagnostic) => diagnostic.severity === "error");
+        if (invalidProfile) {
+            throw new Error(`Runtime profile validation failed: ${invalidProfile.message}`);
+        }
+        const initialFastMode = resolvePiboSessionInitialFastMode(piboSession) ?? selectRequestedFastMode(sessionProfile, modelDefaults) ?? false;
+        const subagentRunner = this.createSubagentRunner(piboSession.id);
+        const runToolController = this.createRunToolController(piboSession.id);
+        const codeRuntimeToolController = this.runtimeRegistry.createController(piboSession.id);
+        const sessionGeneration = randomUUID();
+        const previousResources = this.runtimeResourceSessions.get(piboSession.id);
+        if (previousResources)
+            await previousResources.dispose();
+        this.portableToolSessions.get(piboSession.id)?.dispose();
+        const portableTools = this.portableToolService.createSession({
+            piboSessionId: piboSession.id,
+            piboRoomId: piboRoomIdFromMetadata(piboSession.metadata),
+            runtimeInstanceId: binding.runtimeInstanceId,
+            adapterId: binding.adapterId,
+            sessionGeneration,
             profile: sessionProfile,
-            extensionFactories: [
-                ...(telemetryExtension ? [telemetryExtension] : []),
-                ...(this.options.extensionFactories ?? []),
-            ],
-            subagentRunner: this.createSubagentRunner(piboSession.id),
-            runToolController: this.createRunToolController(piboSession.id),
-            runtimeToolController: this.runtimeRegistry.createController(piboSession.id),
-            modelDefaults,
-            activeModel,
-            sessionContext: {
+            cwd: workspace,
+            getActiveMessage: () => session?.getActiveMessage(),
+            subagentRunner,
+            runToolController,
+            runtimeToolController: codeRuntimeToolController,
+        });
+        this.portableToolSessions.set(piboSession.id, portableTools);
+        let resources;
+        try {
+            resources = await this.runtimeResourceService.createSession({
                 piboSessionId: piboSession.id,
                 piboRoomId: piboRoomIdFromMetadata(piboSession.metadata),
+                runtimeInstanceId: binding.runtimeInstanceId,
+                adapterId: binding.adapterId,
+                sessionGeneration,
+                profile: sessionProfile,
+                cwd: workspace,
                 timezone: userSettings.timezone,
-                getActiveMessage: () => session?.getActiveMessage(),
+                capabilities: runtimeAdapter.descriptor.capabilities,
+            });
+            this.runtimeResourceSessions.set(piboSession.id, resources);
+        }
+        catch (error) {
+            portableTools.dispose();
+            if (this.portableToolSessions.get(piboSession.id) === portableTools)
+                this.portableToolSessions.delete(piboSession.id);
+            throw error;
+        }
+        let runtimeSession;
+        try {
+            runtimeSession = await runtimeRegistry.openAgentRuntimeSession(binding.runtimeInstanceId, {
+                piboSession: { ...piboSession, runtimeBinding: binding },
+                profile: sessionProfile,
+                binding,
+                workspace,
+                activeModel,
+                productContext: {
+                    piboSessionId: piboSession.id,
+                    piboRoomId: piboRoomIdFromMetadata(piboSession.metadata),
+                    timezone: userSettings.timezone,
+                    getActiveMessage: () => session?.getActiveMessage(),
+                },
+                services: {
+                    subagentRunner,
+                    runToolController,
+                    codeRuntimeToolController,
+                    portableTools,
+                    resources,
+                    compatibility: {
+                        persistSession: this.options.persistSession,
+                        thinkingLevel: initialThinkingLevel ?? this.options.thinkingLevel,
+                        retryDefaults: resolvePiboSessionRetryDefaults(piboSession.kind, this.options.retryDefaults),
+                        extensionFactories: [
+                            ...(telemetryExtension ? [telemetryExtension] : []),
+                            ...(this.options.extensionFactories ?? []),
+                        ],
+                        modelDefaults,
+                        initialFastMode,
+                    },
+                },
+            });
+        }
+        catch (error) {
+            portableTools.dispose();
+            if (this.portableToolSessions.get(piboSession.id) === portableTools)
+                this.portableToolSessions.delete(piboSession.id);
+            await resources.dispose();
+            if (this.runtimeResourceSessions.get(piboSession.id) === resources)
+                this.runtimeResourceSessions.delete(piboSession.id);
+            if (error instanceof AgentRuntimeBindingMissingError && binding.state === "bound") {
+                this.persistSessionRuntimeBinding(piboSession, {
+                    ...binding,
+                    state: "missing",
+                    metadata: {
+                        ...(binding.metadata ?? {}),
+                        diagnosticCode: "runtime_binding_missing",
+                        diagnosticMessage: "The bound native session is no longer available in the configured runtime instance.",
+                    },
+                }, {
+                    expectedRevision: binding.revision,
+                });
+            }
+            throw error;
+        }
+        try {
+            const openedBinding = runtimeSession.getBinding();
+            if (openedBinding.runtimeInstanceId !== binding.runtimeInstanceId || openedBinding.adapterId !== binding.adapterId) {
+                throw new AgentRuntimeUnavailableError(binding.runtimeInstanceId, `Runtime instance "${binding.runtimeInstanceId}" opened an inconsistent binding for Pibo session "${piboSession.id}".`);
+            }
+            if (!runtimeBindingsEqual(binding, openedBinding)) {
+                binding = this.persistSessionRuntimeBinding(piboSession, openedBinding, {
+                    expectedRevision: binding.revision,
+                });
+            }
+        }
+        catch (error) {
+            await runtimeSession.dispose().catch(() => { });
+            portableTools.dispose();
+            if (this.portableToolSessions.get(piboSession.id) === portableTools)
+                this.portableToolSessions.delete(piboSession.id);
+            await resources.dispose();
+            if (this.runtimeResourceSessions.get(piboSession.id) === resources)
+                this.runtimeResourceSessions.delete(piboSession.id);
+            throw error;
+        }
+        session = new RoutedSession(piboSession.id, runtimeSession, this.emitOutput, this.pluginRegistry, {
+            forwardLegacyPiEvents: this.options.forwardPiEvents ?? false,
+            onNativeEventTelemetry: this.telemetryRecorder
+                ? (id, event, context) => this.telemetryRecorder?.recordPiEvent(id, event, {
+                    session: this.sessionStore.get(id),
+                    status: context.status,
+                    activeEventId: context.activeEventId,
+                })
+                : undefined,
+            onSessionOperation: (result, event) => this.handleSessionOperation(result, event),
+            onKillChildren: (id, opts) => this.killChildSessions(id, opts),
+            onStateChange: (state) => {
+                this.signalRegistry.project({
+                    type: "session_processing_changed",
+                    piboSessionId: piboSession.id,
+                    processing: state.processing,
+                    queuedMessages: state.queuedMessages,
+                });
+                if (!state.processing && state.queuedMessages === 0 && !state.disposed) {
+                    this.syncLiveSessionRuntimeBinding(piboSession.id, runtimeSession);
+                }
+                if (state.disposed || state.processing || state.queuedMessages > 0)
+                    this.clearIdleSessionTimer(piboSession.id);
+                else
+                    this.scheduleIdleSessionEvictionIfIdle(piboSession.id);
+            },
+            onMessagesInterrupted: (messages, reason) => this.telemetryRecorder?.recordMessagesInterrupted(messages, {
+                session: this.sessionStore.get(piboSession.id),
+                status: this.sessions.get(piboSession.id)?.getStatus(),
+            }, reason),
+            messagePreflight: this.options.messagePreflight,
+            getRuntimeAuthStatus: () => runtimeRegistry.getAgentRuntimeAuthStatus(binding.runtimeInstanceId),
+            startRuntimeAuth: async (input) => {
+                const { runtimeInstanceId: _runtimeInstanceId, ...result } = await runtimeRegistry.startAgentRuntimeAuth(binding.runtimeInstanceId, input);
+                return result;
+            },
+            completeRuntimeAuth: async (input) => {
+                const { runtimeInstanceId: _runtimeInstanceId, ...result } = await runtimeRegistry.completeAgentRuntimeAuth(binding.runtimeInstanceId, input);
+                return result;
+            },
+            cancelRuntimeAuth: async (input) => {
+                const { runtimeInstanceId: _runtimeInstanceId, ...result } = await runtimeRegistry.cancelAgentRuntimeAuth(binding.runtimeInstanceId, input);
+                return result;
+            },
+            logoutRuntimeAuth: async (input) => {
+                const { runtimeInstanceId: _runtimeInstanceId, ...result } = await runtimeRegistry.logoutAgentRuntimeAuth(binding.runtimeInstanceId, input);
+                return result;
             },
         });
-        const initialFastMode = resolvePiboSessionInitialFastMode(piboSession) ?? selectRequestedFastMode(sessionProfile, modelDefaults) ?? false;
-        session = new RoutedSession(piboSession.id, runtime, this.emitOutput, this.pluginRegistry, this.options.forwardPiEvents ?? false, this.telemetryRecorder
-            ? (id, event, context) => this.telemetryRecorder?.recordPiEvent(id, event, { session: this.sessionStore.get(id), status: context.status, activeEventId: context.activeEventId })
-            : undefined, initialFastMode, (result, event) => this.handleSessionOperation(result, event), (id, opts) => this.killChildSessions(id, opts), (state) => {
-            this.signalRegistry.project({ type: "session_processing_changed", piboSessionId: piboSession.id, processing: state.processing, queuedMessages: state.queuedMessages });
-            if (state.disposed || state.processing || state.queuedMessages > 0)
-                this.clearIdleSessionTimer(piboSession.id);
-            else
-                this.scheduleIdleSessionEvictionIfIdle(piboSession.id);
-        }, (messages, reason) => this.telemetryRecorder?.recordMessagesInterrupted(messages, {
-            session: this.sessionStore.get(piboSession.id),
-            status: this.sessions.get(piboSession.id)?.getStatus(),
-        }, reason), this.options.messagePreflight);
         this.sessions.set(piboSession.id, session);
         return session;
     }
+    resolveAgentRuntimeRegistry(instanceId) {
+        if (this.pluginRegistry.getAgentRuntimeAdapter(instanceId))
+            return this.pluginRegistry;
+        if (this.compatibilityRuntimeRegistry?.getAgentRuntimeAdapter(instanceId))
+            return this.compatibilityRuntimeRegistry;
+        throw new Error(`Unknown agent runtime instance "${instanceId}".`);
+    }
+    resolveSessionRuntimeBinding(session) {
+        return this.sessionStore.getRuntimeBinding?.(session.id)
+            ?? session.runtimeBinding
+            ?? createLegacyPiRuntimeSessionBinding(session.id, session.piSessionId, session.createdAt);
+    }
+    withPersistedRuntimeBinding(status) {
+        const session = this.sessionStore.get(status.piboSessionId);
+        if (!session)
+            return status;
+        const binding = this.resolveSessionRuntimeBinding(session);
+        return {
+            ...status,
+            runtimeBinding: {
+                runtimeInstanceId: binding.runtimeInstanceId,
+                adapterId: binding.adapterId,
+                nativeSessionId: binding.nativeSessionId,
+                state: binding.state,
+                protocol: binding.protocol,
+                protocolVersion: binding.protocolVersion,
+                adapterVersion: binding.adapterVersion,
+                revision: binding.revision,
+            },
+        };
+    }
+    persistSessionRuntimeBinding(session, binding, options = {}) {
+        const current = this.resolveSessionRuntimeBinding(session);
+        const normalized = { ...structuredClone(binding), piboSessionId: session.id };
+        if (runtimeBindingsEqual(current, normalized))
+            return current;
+        const persisted = this.sessionStore.updateRuntimeBinding?.(session.id, normalized, options);
+        if (persisted) {
+            const updatedSession = this.sessionStore.get(session.id);
+            if (updatedSession)
+                this.signalRegistry.project({ type: "session_created", session: updatedSession });
+            return persisted;
+        }
+        const now = new Date().toISOString();
+        if (normalized.adapterId === "pi" && normalized.nativeSessionId !== session.piSessionId) {
+            this.sessionStore.update(session.id, { piSessionId: normalized.nativeSessionId ?? "" });
+        }
+        const updatedSession = this.sessionStore.get(session.id);
+        if (updatedSession)
+            this.signalRegistry.project({ type: "session_created", session: updatedSession });
+        return {
+            ...normalized,
+            revision: (current.revision ?? 1) + 1,
+            createdAt: current.createdAt ?? session.createdAt,
+            updatedAt: now,
+        };
+    }
+    syncLiveSessionRuntimeBinding(piboSessionId, runtimeSession) {
+        const session = this.sessionStore.get(piboSessionId);
+        if (!session)
+            return;
+        try {
+            this.persistSessionRuntimeBinding(session, runtimeSession.getBinding());
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.emitOutput({
+                type: "session_error",
+                piboSessionId,
+                error: `Failed to persist the live runtime binding: ${message}`,
+                errorDetails: runtimeSessionErrorDetails(message),
+            });
+        }
+    }
+    assertOpenableRuntimeBinding(binding) {
+        if (binding.state === "missing") {
+            throw new AgentRuntimeBindingMissingError(binding.piboSessionId, binding.runtimeInstanceId, binding.nativeSessionId);
+        }
+        if (binding.state === "error") {
+            const diagnostic = typeof binding.metadata?.diagnosticMessage === "string"
+                ? binding.metadata.diagnosticMessage
+                : "The persisted runtime binding is in an error state.";
+            throw new AgentRuntimeUnavailableError(binding.runtimeInstanceId, `Runtime binding for Pibo session "${binding.piboSessionId}" cannot be opened: ${diagnostic}`);
+        }
+    }
+    createRuntimeBindingInput(profile) {
+        const registry = this.resolveAgentRuntimeRegistry(profile.runtimeInstanceId);
+        const adapter = registry.requireAgentRuntimeAdapter(profile.runtimeInstanceId);
+        return {
+            runtimeInstanceId: profile.runtimeInstanceId,
+            adapterId: adapter.descriptor.id,
+            state: "unbound",
+            protocol: adapter.descriptor.protocol?.name,
+        };
+    }
     ensureSessionActiveModel(piboSession, profile, parentPiSessionId, modelDefaults) {
         const activeModel = resolvePiboSessionActiveModel({
             profile,
@@ -778,19 +1238,33 @@ export class PiboSessionRouter {
     async handleSessionOperation(result, event) {
         if (result.cancelled)
             return;
+        const source = this.resolvePiboSession(event.piboSessionId);
+        const previousBinding = this.resolveSessionRuntimeBinding(source);
+        const liveBinding = this.sessions.get(event.piboSessionId)?.getRuntimeBinding();
+        const currentBinding = {
+            ...previousBinding,
+            ...liveBinding,
+            piboSessionId: source.id,
+            nativeSessionId: result.current.piSessionId,
+            state: "bound",
+            locator: result.current.sessionFile
+                ? { kind: "local-file", value: result.current.sessionFile }
+                : liveBinding?.locator ?? previousBinding.locator,
+        };
         if (event.action === "session.fork" || event.action === "session.clone") {
             const action = event.action;
-            const created = this.createDerivedSession(result, action);
+            const created = this.createDerivedSession(result, action, currentBinding);
             result.piboSessionId = created.id;
             await this.resetCachedSession(event.piboSessionId);
             return;
         }
-        this.sessionStore.update(event.piboSessionId, {
-            piSessionId: result.current.piSessionId,
-            workspace: result.current.cwd,
+        this.persistSessionRuntimeBinding(source, currentBinding, {
+            expectedRevision: previousBinding.revision,
+            mode: "rebind",
         });
+        this.sessionStore.update(event.piboSessionId, { workspace: result.current.cwd });
     }
-    createDerivedSession(result, action) {
+    createDerivedSession(result, action, currentBinding) {
         const source = this.resolvePiboSession(result.piboSessionId);
         return this.sessionStore.create({
             channel: source.channel,
@@ -798,17 +1272,54 @@ export class PiboSessionRouter {
             profile: source.profile,
             parentId: source.kind === "subagent" ? source.parentId : undefined,
             originId: source.id,
-            piSessionId: result.current.piSessionId,
+            runtimeBinding: {
+                runtimeInstanceId: currentBinding.runtimeInstanceId,
+                adapterId: currentBinding.adapterId,
+                nativeSessionId: currentBinding.nativeSessionId ?? result.current.piSessionId,
+                state: "bound",
+                protocol: currentBinding.protocol,
+                protocolVersion: currentBinding.protocolVersion,
+                adapterVersion: currentBinding.adapterVersion,
+                locator: currentBinding.locator,
+                metadata: currentBinding.metadata,
+            },
             workspace: result.current.cwd,
             title: source.title,
             activeModel: source.activeModel,
             metadata: {
                 ...asJsonObject(source.metadata),
                 originAction: action,
-                originPiSessionId: result.previous.piSessionId,
+                originRuntimeNativeSessionId: result.previous.piSessionId,
+                ...(currentBinding.adapterId === "pi" ? { originPiSessionId: result.previous.piSessionId } : {}),
             },
         });
     }
+    runtimeAuthAffectedInstanceIds(runtimeInstanceId) {
+        const registry = this.resolveAgentRuntimeRegistry(runtimeInstanceId);
+        const target = registry.requireAgentRuntimeAdapter(runtimeInstanceId);
+        if (target.descriptor.capabilities.auth.credentialScope === "runtime-instance")
+            return [runtimeInstanceId];
+        return registry.getAgentRuntimeInstanceIds().filter((candidateId) => {
+            const candidate = registry.getAgentRuntimeAdapter(candidateId);
+            return candidate?.descriptor.id === target.descriptor.id
+                && candidate.descriptor.capabilities.auth.credentialScope === "adapter-shared";
+        });
+    }
+    async resetCachedRuntimeAuthSessions(runtimeInstanceId, reason) {
+        const affectedInstanceIds = new Set(this.runtimeAuthAffectedInstanceIds(runtimeInstanceId));
+        for (const affectedInstanceId of affectedInstanceIds)
+            this.runtimeAuthFingerprints.delete(affectedInstanceId);
+        const ids = [...new Set([...this.sessions.keys(), ...this.pendingSessions.keys()])]
+            .filter((piboSessionId) => {
+            const boundRuntimeInstanceId = this.getSessionRuntimeBinding(piboSessionId)?.runtimeInstanceId;
+            return boundRuntimeInstanceId !== undefined && affectedInstanceIds.has(boundRuntimeInstanceId);
+        });
+        const results = await Promise.allSettled(ids.map(async (piboSessionId) => await this.resetCachedSession(piboSessionId, reason)));
+        const failures = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+        if (failures.length > 0) {
+            throw new AggregateError(failures, `Failed to reset cached sessions affected by runtime auth target "${runtimeInstanceId}".`);
+        }
+    }
     async resetCachedSession(piboSessionId, reason) {
         const existingDisposal = this.disposingSessions.get(piboSessionId);
         if (existingDisposal)
@@ -860,14 +1371,50 @@ export class PiboSessionRouter {
             channel: "pibo.runtime",
             kind: "runtime",
             profile: this.baseProfile.profileName,
+            runtimeBinding: this.createRuntimeBindingInput(this.baseProfile),
             workspace: this.options.cwd ?? getDefaultPiboWorkspace(),
         });
         this.signalRegistry.project({ type: "session_created", session: created });
         return created;
     }
+    trackActiveSubagent(parentPiboSessionId, childPiboSessionId) {
+        let children = this.activeSubagentChildren.get(parentPiboSessionId);
+        if (!children) {
+            children = new Map();
+            this.activeSubagentChildren.set(parentPiboSessionId, children);
+        }
+        children.set(childPiboSessionId, (children.get(childPiboSessionId) ?? 0) + 1);
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            const current = this.activeSubagentChildren.get(parentPiboSessionId);
+            if (!current)
+                return;
+            const remaining = (current.get(childPiboSessionId) ?? 1) - 1;
+            if (remaining > 0)
+                current.set(childPiboSessionId, remaining);
+            else
+                current.delete(childPiboSessionId);
+            if (current.size === 0)
+                this.activeSubagentChildren.delete(parentPiboSessionId);
+        };
+    }
+    async abortActiveSubagentSessions(parentPiboSessionId) {
+        const childIds = [...(this.activeSubagentChildren.get(parentPiboSessionId)?.keys() ?? [])];
+        if (childIds.length === 0)
+            return;
+        await Promise.allSettled(childIds.map(async (childPiboSessionId) => await this.emit({
+            type: "execution",
+            piboSessionId: childPiboSessionId,
+            action: "abort",
+            id: randomUUID(),
+        })));
+    }
     createSubagentRunner(parentPiboSessionId) {
         return {
-            runSubagent: async ({ subagent, message, threadKey, toolCallId }) => {
+            runSubagent: async ({ subagent, message, threadKey, toolCallId, signal }) => {
                 this.assertSubagentDepth(parentPiboSessionId, subagent);
                 const child = this.resolveSubagentSession(parentPiboSessionId, subagent, threadKey);
                 const toolName = createSubagentToolName(subagent.name);
@@ -887,8 +1434,14 @@ export class PiboSessionRouter {
                     childPiboSessionId: child.id,
                     threadKey: typeof child.metadata?.threadKey === "string" ? child.metadata.threadKey : undefined,
                 });
-                const reply = await this.emitMessageAndWaitForReply(event, subagent.timeoutMs ?? DEFAULT_SUBAGENT_REPLY_TIMEOUT_MS);
-                return { piboSessionId: child.id, eventId: event.id, reply };
+                const untrack = this.trackActiveSubagent(parentPiboSessionId, child.id);
+                try {
+                    const reply = await this.emitMessageAndWaitForReply(event, subagent.timeoutMs ?? DEFAULT_SUBAGENT_REPLY_TIMEOUT_MS, signal);
+                    return { piboSessionId: child.id, eventId: event.id, reply };
+                }
+                finally {
+                    untrack();
+                }
             },
         };
     }
@@ -987,7 +1540,7 @@ export class PiboSessionRouter {
     resolveSubagentSession(parentPiboSessionId, subagent, threadKey) {
         const targetProfile = resolvePiboProfileNameFromRegistryOrDefault(this.pluginRegistry, subagent.targetProfile);
         const parent = this.resolvePiboSession(parentPiboSessionId);
-        const resolvedThreadKey = threadKey?.trim() ? threadKey.trim() : randomUUID();
+        const resolvedThreadKey = resolveSubagentThreadKey(threadKey);
         const baseMetadata = {
             subagentName: subagent.name,
             subagentToolName: createSubagentToolName(subagent.name),
@@ -1027,6 +1580,7 @@ export class PiboSessionRouter {
             kind: "subagent",
             profile: targetProfile,
             parentId: parent.id,
+            runtimeBinding: this.createRuntimeBindingInput(childProfile),
             workspace: parent.workspace,
             metadata,
         });
@@ -1034,7 +1588,7 @@ export class PiboSessionRouter {
         const activeModel = resolvePiboSessionActiveModel({
             profile: childProfile,
             piboSession: childSession,
-            parentPiSessionId: parent.piSessionId,
+            parentPiSessionId: this.resolveSessionRuntimeBinding(parent).nativeSessionId ?? parent.id,
             modelDefaults: this.resolveModelDefaults(),
         });
         return activeModel ? this.sessionStore.update(childSession.id, { activeModel }) ?? childSession : childSession;