@rivus/agent 0.14.4 → 0.15.0

package/examples/pi-feishu-deployment.bootstrap.ts

@@ -1,10 +1,13 @@
-import { mkdir, readFile } from "node:fs/promises";
+import { createPiManagedSessionContext } from "../src/adapters/pi/model-management/pi-managed-session-context.js";
+import { ensurePiModel } from "../src/adapters/pi/model-management/pi-model-resolution.js";
+import { openPiModelManagementDeployment } from "../src/bootstrap/deployment/model-management/pi-model-management-deployment.js";
+import { mkdir, readFile, stat } from "node:fs/promises";
 import { createHash, randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { join, relative } from "node:path";
 import { Effect } from "effect";
 import * as Lark from "@larksuiteoapi/node-sdk";
-import { createAgentSession, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import {
   createAgentsMdInstructionsProvider,
   createAgentHarness,
@@ -29,6 +32,7 @@ import {
   createHumanInteractionEndpointRegistry,
   createHumanInteractionService,
   createHumanInteractionToolApprovalGateway,
+  createHumanInteractionModelChangeApproval,
   createJsonFetchRequest,
   createJsonFileFeishuCardTargetRegistry,
   createJsonlAgentEventLog,
@@ -70,6 +74,8 @@ import {
   type FeishuBackgroundSessionDelivery,
   type FeishuWebSocketClient,
   type RivusDaemonConfig,
+  type RivusDaemonEnv,
+  type RivusEndpointDeployment,
   type RivusDeploymentBackgroundSession,
   type RivusDeploymentBootstrapContext,
   type RivusThinkingLevel
@@ -94,9 +100,17 @@ const THINKING_LEVELS = new Set<RivusThinkingLevel>(["off", "minimal", "low", "m
 
 export async function createRivusDeploymentAdapters(context: RivusDeploymentBootstrapContext) {
   await mkdir(PI_AGENT_DIR, { recursive: true });
-  const piOptions = await createPiSessionOptions(context);
+  const hasManagedState = await stat(join(STATE_DIR, "model-management", "model-state.json")).then(
+    () => true,
+    (error: NodeJS.ErrnoException) => {
+      if (error.code === "ENOENT") return false;
+      throw error;
+    }
+  );
+  const deferModel = context.env.RIVUS_MODEL_MANAGEMENT_ENABLED?.trim() === "true" || hasManagedState;
+  const piOptions = await createPiSessionOptions(context, deferModel);
   const telemetryConfig = resolveLangfuseTelemetryConfig(context.env);
-  const telemetry = telemetryConfig ? createLangfuseAgentTelemetry(telemetryConfig) : undefined;
+  let telemetry: ReturnType<typeof createLangfuseAgentTelemetry> | undefined;
   const memory = await openJsonlAgentMemoryService({
     filePath: join(STATE_DIR, "memory", "agent-memory.jsonl")
   });
@@ -109,477 +123,526 @@ export async function createRivusDeploymentAdapters(context: RivusDeploymentBoot
     });
   const interactionRegistry = createHumanInteractionEndpointRegistry();
   const manifest = await loadRivusDeploymentManifest(context.manifestPath);
-  const backgroundSessionsConfig = manifest.backgroundSessions;
-  const sessionRepository = backgroundSessionsConfig?.enabled
-    ? await openJsonlBackgroundSessionRepository({
-        filePath: join(STATE_DIR, "background-sessions", "sessions.jsonl")
-      })
-    : undefined;
-  const sessionDeliveries = backgroundSessionsConfig?.enabled
-    ? await openJsonlBackgroundSessionDeliveryStore({
-        filePath: join(STATE_DIR, "background-sessions", "deliveries.jsonl")
-      })
-    : undefined;
-  const deliveryClients = new Map<string, FeishuBackgroundSessionDelivery>();
-  const backgroundService = backgroundSessionsConfig?.enabled
-    ? createBackgroundSessionService({
+  const defaultEndpoint = manifest.endpoints.find((endpoint) => endpoint.id === manifest.defaultEndpointId)!;
+  const management = await openPiModelManagementDeployment({
+    agentId: manifest.defaultAgentId,
+    approval: createHumanInteractionModelChangeApproval({
+      endpointId: manifest.defaultEndpointId,
+      registry: interactionRegistry
+    }),
+    agentCount: manifest.agents.length,
+    endpointId: manifest.defaultEndpointId,
+    env: context.env,
+    environmentOverrides: context.environmentOverrides ?? process.env,
+    ...(context.envFilePath ? { envFilePath: context.envFilePath } : {}),
+    modelAuthPath: PI_AUTH_FILE,
+    modelCatalogPath: PI_MODELS_FILE,
+    modelRuntime: piOptions.modelRuntime!,
+    reply: (messageId, text) => {
+      const config = createEndpointConfig(defaultEndpoint, manifest.defaultAgentId, context.env);
+      return createConfiguredFeishuTextReplySender({ config, client: createOpenApiClient(config) }).reply(
+        messageId,
+        text
+      );
+    },
+    stateDirectory: STATE_DIR,
+    thinkingLevel: piOptions.thinkingLevel ?? "medium"
+  });
+  try {
+    telemetry = telemetryConfig ? createLangfuseAgentTelemetry(telemetryConfig) : undefined;
+    if (management && !management.enabled) {
+      piOptions.model = await ensurePiModel({
+        modelRuntime: piOptions.modelRuntime!,
+        modelsPath: PI_MODELS_FILE,
+        target: management.model
+      });
+    }
+    if (management?.enabled && management.recoveryRequired) {
+      console.error("Model management requires recovery; business Runs are paused. Query rivus model status --json.");
+    }
+    if (management?.enabled && management.skillInstallation.status === "conflict") {
+      console.error("The runtime-management Skill has local edits; its installed instructions were preserved.");
+    }
+    const backgroundSessionsConfig = manifest.backgroundSessions;
+    const sessionRepository = backgroundSessionsConfig?.enabled
+      ? await openJsonlBackgroundSessionRepository({
+          filePath: join(STATE_DIR, "background-sessions", "sessions.jsonl")
+        })
+      : undefined;
+    const sessionDeliveries = backgroundSessionsConfig?.enabled
+      ? await openJsonlBackgroundSessionDeliveryStore({
+          filePath: join(STATE_DIR, "background-sessions", "deliveries.jsonl")
+        })
+      : undefined;
+    const deliveryClients = new Map<string, FeishuBackgroundSessionDelivery>();
+    const backgroundService = backgroundSessionsConfig?.enabled
+      ? createBackgroundSessionService({
+          clock: { now: () => new Date().toISOString() },
+          deliveries: sessionDeliveries!,
+          repository: sessionRepository!
+        })
+      : undefined;
+    const createBackgroundSessionAdapter = (
+      input: CreateRivusDeploymentBackgroundSessionInput
+    ): RivusDeploymentBackgroundSession => {
+      const resolveDeliverySender = async (endpointId: string): Promise<FeishuBackgroundSessionDelivery> => {
+        const existing = deliveryClients.get(endpointId);
+        if (existing) return existing;
+        const endpoint = manifest.endpoints.find(({ id }) => id === endpointId);
+        if (!endpoint) throw new Error(`background session delivery endpoint not found: ${endpointId}`);
+        const config = createEndpointConfig(endpoint, endpoint.agentId, context.env);
+        const sender = createConfiguredFeishuBackgroundSessionDelivery({
+          client: createOpenApiClient(config),
+          config
+        });
+        deliveryClients.set(endpointId, sender);
+        return sender;
+      };
+      const supervisor = createBackgroundSessionSupervisor({
         clock: { now: () => new Date().toISOString() },
+        config: {
+          intervalMs: resolveBackgroundSessionSupervisorIntervalMs(input.config.leaseMs),
+          leaseMs: input.config.leaseMs,
+          leaseRenewalIntervalMs: input.config.leaseRenewalIntervalMs,
+          maxConcurrentSessions: input.config.maxConcurrentSessions,
+          maxConsecutiveFailures: input.config.maxConsecutiveFailures,
+          retryBackoffMs: input.config.retryBackoffMs,
+          sessionLifetimeMs: input.config.sessionLifetimeMs
+        },
         deliveries: sessionDeliveries!,
-        repository: sessionRepository!
-      })
-    : undefined;
-  const createBackgroundSessionAdapter = (
-    input: CreateRivusDeploymentBackgroundSessionInput
-  ): RivusDeploymentBackgroundSession => {
-    const resolveDeliverySender = async (endpointId: string): Promise<FeishuBackgroundSessionDelivery> => {
-      const existing = deliveryClients.get(endpointId);
-      if (existing) return existing;
-      const endpoint = manifest.endpoints.find(({ id }) => id === endpointId);
-      if (!endpoint) throw new Error(`background session delivery endpoint not found: ${endpointId}`);
-      const credentials = resolveFeishuEndpointCredentials(endpoint.credentialRef, context.env);
-      const config: RivusDaemonConfig = {
-        agentId: endpoint.agentId,
-        feishu: {
-          ...credentials,
-          baseUrl: endpoint.baseUrl,
-          cardStreamLeaseMs: endpoint.cardStreamLeaseMs,
-          streamMinIntervalMs: endpoint.streamMinIntervalMs
+        deliver: async (delivery) => {
+          const session = await sessionRepository!.get(delivery.sessionId);
+          if (!session) throw new Error(`background session not found for delivery: ${delivery.sessionId}`);
+          if (!session.origin.conversationId) {
+            throw new Error(`background session has no delivery conversation: ${delivery.sessionId}`);
+          }
+          const sender = await resolveDeliverySender(session.origin.endpointId);
+          return sender.deliver({
+            chatId: resolveFeishuDeliveryChatId(session.origin.conversationId),
+            deliveryId: delivery.deliveryId,
+            displayName: session.displayName,
+            kind: delivery.kind,
+            sessionId: session.sessionId,
+            text: delivery.text
+          });
         },
-        pi: {}
-      };
-      const sender = createConfiguredFeishuBackgroundSessionDelivery({
-        client: createOpenApiClient(config),
-        config
+        onError: (error) => {
+          console.error("Background session supervisor failed", error);
+        },
+        repository: sessionRepository!,
+        runStep: async ({ session, signal, wakeText }) => {
+          let runId: string | undefined;
+          const invocation = {
+            allowedActorOpenIds: session.origin.allowedActorOpenIds,
+            ...(session.origin.conversationId ? { conversationId: session.origin.conversationId } : {}),
+            endpointId: session.origin.endpointId,
+            kind: "background-session" as const,
+            ...(session.origin.memory ? { memory: session.origin.memory } : {}),
+            sessionId: session.sessionId,
+            sourceMessageId: createBackgroundSessionStepSourceMessageId(session.sessionId, session.stepCount + 1),
+            tenantKey: session.origin.tenantKey
+          };
+          const abortPromise = new Promise<never>((_resolve, reject) => {
+            signal.addEventListener(
+              "abort",
+              () => {
+                if (runId) {
+                  void input.cancel({
+                    agentId: session.authority.agentId,
+                    reason: "background session step aborted",
+                    runId,
+                    sessionKey: session.authority.sessionKey
+                  });
+                }
+                reject(new Error("background session step aborted"));
+              },
+              { once: true }
+            );
+          });
+          const runPromise = input
+            .run({
+              agentId: session.authority.agentId,
+              invocation,
+              onUpdate: (update) => {
+                if (update.event.type === "agent_run_accepted" && !runId) {
+                  runId = update.event.runId;
+                }
+              },
+              sessionKey: session.authority.sessionKey,
+              text: wakeText
+            })
+            .then((result) => readStepRunResult(result));
+          return Promise.race([runPromise, abortPromise]);
+        },
+        sleep
       });
-      deliveryClients.set(endpointId, sender);
-      return sender;
+      let running = false;
+      return {
+        running: () => running,
+        status: () => supervisor.status(),
+        start: async () => {
+          await Effect.runPromise(supervisor.recover());
+          await Effect.runPromise(supervisor.start());
+          running = true;
+        },
+        stop: async () => {
+          await Effect.runPromise(supervisor.stop());
+          running = false;
+        }
+      };
     };
-    const supervisor = createBackgroundSessionSupervisor({
-      clock: { now: () => new Date().toISOString() },
-      config: {
-        intervalMs: resolveBackgroundSessionSupervisorIntervalMs(input.config.leaseMs),
-        leaseMs: input.config.leaseMs,
-        leaseRenewalIntervalMs: input.config.leaseRenewalIntervalMs,
-        maxConcurrentSessions: input.config.maxConcurrentSessions,
-        maxConsecutiveFailures: input.config.maxConsecutiveFailures,
-        retryBackoffMs: input.config.retryBackoffMs,
-        sessionLifetimeMs: input.config.sessionLifetimeMs
+    return {
+      dispose: async () => {
+        if (management?.enabled) await management.close();
+        await telemetry?.shutdown();
       },
-      deliveries: sessionDeliveries!,
-      deliver: async (delivery) => {
-        const session = await sessionRepository!.get(delivery.sessionId);
-        if (!session) throw new Error(`background session not found for delivery: ${delivery.sessionId}`);
-        if (!session.origin.conversationId) {
-          throw new Error(`background session has no delivery conversation: ${delivery.sessionId}`);
-        }
-        const sender = await resolveDeliverySender(session.origin.endpointId);
-        return sender.deliver({
-          chatId: resolveFeishuDeliveryChatId(session.origin.conversationId),
-          deliveryId: delivery.deliveryId,
-          displayName: session.displayName,
-          kind: delivery.kind,
-          sessionId: session.sessionId,
-          text: delivery.text
+      createRecoveryControl: () =>
+        openJsonlRecoveryControl({
+          endpointsDirectory: join(STATE_DIR, "endpoints"),
+          instancesDirectory: join(STATE_DIR, "instances")
+        }),
+      createBackgroundSession: backgroundSessionsConfig?.enabled
+        ? (input: CreateRivusDeploymentBackgroundSessionInput) => createBackgroundSessionAdapter(input)
+        : undefined,
+      createAutomation: async (input: CreateRivusDeploymentAutomationInput) => {
+        const config = createEndpointConfig(input.deliveryEndpoint, input.definition.agentId, context.env);
+        const openApiClient = createOpenApiClient(config);
+        const sender = createConfiguredFeishuAutomationCardSender({
+          client: openApiClient,
+          config
         });
-      },
-      onError: (error) => {
-        console.error("Background session supervisor failed", error);
-      },
-      repository: sessionRepository!,
-      runStep: async ({ session, signal, wakeText }) => {
-        let runId: string | undefined;
-        const invocation = {
-          allowedActorOpenIds: session.origin.allowedActorOpenIds,
-          ...(session.origin.conversationId ? { conversationId: session.origin.conversationId } : {}),
-          endpointId: session.origin.endpointId,
-          kind: "background-session" as const,
-          ...(session.origin.memory ? { memory: session.origin.memory } : {}),
-          sessionId: session.sessionId,
-          sourceMessageId: createBackgroundSessionStepSourceMessageId(session.sessionId, session.stepCount + 1),
-          tenantKey: session.origin.tenantKey
-        };
-        const abortPromise = new Promise<never>((_resolve, reject) => {
-          signal.addEventListener(
-            "abort",
-            () => {
-              if (runId) {
-                void input.cancel({
-                  agentId: session.authority.agentId,
-                  reason: "background session step aborted",
-                  runId,
-                  sessionKey: session.authority.sessionKey
-                });
-              }
-              reject(new Error("background session step aborted"));
-            },
-            { once: true }
-          );
+        const repository = await openJsonAutomationTickRepository({
+          filePath: join(
+            STATE_DIR,
+            "automations",
+            createHash("sha256").update(input.automationId).digest("hex").slice(0, 16),
+            "ticks.json"
+          )
         });
-        const runPromise = input
-          .run({
-            agentId: session.authority.agentId,
-            invocation,
-            onUpdate: (update) => {
-              if (update.event.type === "agent_run_accepted" && !runId) {
-                runId = update.event.runId;
-              }
+        const target = resolveAutomationTarget(input.definition.delivery.targetRef, context.env);
+        const automation = createScheduledAutomation({
+          automationId: input.automationId,
+          binding: {
+            agentId: input.definition.agentId,
+            bindingId: input.automationId,
+            delivery: {
+              endpointId: input.definition.delivery.endpointId,
+              targetKey: createHash("sha256").update(target).digest("hex"),
+              targetType: input.definition.delivery.targetType
             },
-            sessionKey: session.authority.sessionKey,
-            text: wakeText
-          })
-          .then((result) => readStepRunResult(result));
-        return Promise.race([runPromise, abortPromise]);
-      },
-      sleep
-    });
-    let running = false;
-    return {
-      running: () => running,
-      status: () => supervisor.status(),
-      start: async () => {
-        await Effect.runPromise(supervisor.recover());
-        await Effect.runPromise(supervisor.start());
-        running = true;
-      },
-      stop: async () => {
-        await Effect.runPromise(supervisor.stop());
-        running = false;
-      }
-    };
-  };
-  return {
-    dispose: () => telemetry?.shutdown(),
-    createRecoveryControl: () =>
-      openJsonlRecoveryControl({
-        endpointsDirectory: join(STATE_DIR, "endpoints"),
-        instancesDirectory: join(STATE_DIR, "instances")
-      }),
-    createBackgroundSession: backgroundSessionsConfig?.enabled
-      ? (input: CreateRivusDeploymentBackgroundSessionInput) => createBackgroundSessionAdapter(input)
-      : undefined,
-    createAutomation: async (input: CreateRivusDeploymentAutomationInput) => {
-      const credentials = resolveFeishuEndpointCredentials(input.deliveryEndpoint.credentialRef, context.env);
-      const config: RivusDaemonConfig = {
-        agentId: input.definition.agentId,
-        feishu: {
-          ...credentials,
-          baseUrl: input.deliveryEndpoint.baseUrl,
-          cardStreamLeaseMs: input.deliveryEndpoint.cardStreamLeaseMs,
-          streamMinIntervalMs: input.deliveryEndpoint.streamMinIntervalMs
-        },
-        pi: {}
-      };
-      const openApiClient = createOpenApiClient(config);
-      const sender = createConfiguredFeishuAutomationCardSender({
-        client: openApiClient,
-        config
-      });
-      const repository = await openJsonAutomationTickRepository({
-        filePath: join(
-          STATE_DIR,
-          "automations",
-          createHash("sha256").update(input.automationId).digest("hex").slice(0, 16),
-          "ticks.json"
-        )
-      });
-      const target = resolveAutomationTarget(input.definition.delivery.targetRef, context.env);
-      const automation = createScheduledAutomation({
-        automationId: input.automationId,
-        binding: {
-          agentId: input.definition.agentId,
-          bindingId: input.automationId,
-          delivery: {
-            endpointId: input.definition.delivery.endpointId,
-            targetKey: createHash("sha256").update(target).digest("hex"),
-            targetType: input.definition.delivery.targetType
+            schedule: input.definition.schedule,
+            servicePrincipalId: `automation:${input.automationId}`,
+            skillGrantRevision: input.definition.runtimeDefinition.skillGrantSet.revision,
+            skillIds: input.definition.template.requestedSkillIds,
+            templateId: input.definition.templateId,
+            timeZone: input.definition.timeZone,
+            toolIds: input.definition.template.requestedToolIds
           },
-          schedule: input.definition.schedule,
-          servicePrincipalId: `automation:${input.automationId}`,
-          skillGrantRevision: input.definition.runtimeDefinition.skillGrantSet.revision,
-          skillIds: input.definition.template.requestedSkillIds,
-          templateId: input.definition.templateId,
-          timeZone: input.definition.timeZone,
-          toolIds: input.definition.template.requestedToolIds
-        },
-        createInput: input.definition.template.createInput,
-        deliver: ({ body, idempotencyKey, presentation }) =>
-          Effect.runPromise(
-            sender.send({
-              idempotencyKey,
-              receiveId: target,
-              receiveIdType: input.definition.delivery.targetType,
-              markdown: body,
-              ...(presentation === undefined ? {} : { presentation })
-            })
-          ),
-        onError: () => {
-          console.error(`Scheduled Automation ${input.automationId} failed; it will retry`);
-        },
-        repository,
-        run: async (runInput) => {
-          const result = readAutomationRunResult(await input.run(runInput));
-          const projected =
-            result.body === undefined
-              ? undefined
-              : input.definition.template.createPresentation?.({
-                  occurrence: runInput.occurrence,
-                  text: result.body
-                });
-          const presentation = projected ? readAutomationPresentation(projected) : undefined;
-          return { ...result, ...(presentation === undefined ? {} : { presentation }) };
-        }
-      });
-      return automation;
-    },
-    createEndpoint: async (input: CreateRivusDeploymentEndpointInput) => {
-      const credentials = resolveFeishuEndpointCredentials(input.definition.credentialRef, context.env);
-      const botOpenId = await resolveFeishuBotOpenId(credentials, input.definition.baseUrl);
-      const endpointState = join(STATE_DIR, "endpoints", input.endpointId);
-      const cardTargets = createJsonFileFeishuCardTargetRegistry({
-        filePath: join(endpointState, "feishu-card-targets.json")
-      });
-      const cardLedger = await openJsonlFeishuCardDeliveryLedger({
-        filePath: join(endpointState, "feishu-card-delivery.jsonl")
-      });
-      const inbox = await openJsonlFeishuInboxRepository({ filePath: join(endpointState, "feishu-inbox.jsonl") });
-      const sessionStore = await openJsonFeishuSessionStore({
-        filePath: join(endpointState, "feishu-session-store.json")
-      });
-      const config: RivusDaemonConfig = {
-        agentId: input.agentId,
-        feishu: {
-          ...credentials,
+          createInput: input.definition.template.createInput,
+          deliver: ({ body, idempotencyKey, presentation }) =>
+            Effect.runPromise(
+              sender.send({
+                idempotencyKey,
+                receiveId: target,
+                receiveIdType: input.definition.delivery.targetType,
+                markdown: body,
+                ...(presentation === undefined ? {} : { presentation })
+              })
+            ),
+          onError: () => {
+            console.error(`Scheduled Automation ${input.automationId} failed; it will retry`);
+          },
+          repository,
+          run: async (runInput) => {
+            const result = readAutomationRunResult(await input.run(runInput));
+            const projected =
+              result.body === undefined
+                ? undefined
+                : input.definition.template.createPresentation?.({
+                    occurrence: runInput.occurrence,
+                    text: result.body
+                  });
+            const presentation = projected ? readAutomationPresentation(projected) : undefined;
+            return { ...result, ...(presentation === undefined ? {} : { presentation }) };
+          }
+        });
+        return automation;
+      },
+      createEndpoint: async (input: CreateRivusDeploymentEndpointInput) => {
+        const credentials = resolveFeishuEndpointCredentials(input.definition.credentialRef, context.env);
+        const botOpenId = await resolveFeishuBotOpenId(credentials, input.definition.baseUrl);
+        const endpointState = join(STATE_DIR, "endpoints", input.endpointId);
+        const cardTargets = createJsonFileFeishuCardTargetRegistry({
+          filePath: join(endpointState, "feishu-card-targets.json")
+        });
+        const cardLedger = await openJsonlFeishuCardDeliveryLedger({
+          filePath: join(endpointState, "feishu-card-delivery.jsonl")
+        });
+        const inbox = await openJsonlFeishuInboxRepository({ filePath: join(endpointState, "feishu-inbox.jsonl") });
+        const sessionStore = await openJsonFeishuSessionStore({
+          filePath: join(endpointState, "feishu-session-store.json")
+        });
+        const config = createEndpointConfig(input.definition, input.agentId, context.env);
+        const openApiClient = createOpenApiClient(config);
+        const promptContext = createFeishuTopicContextResolver({
           baseUrl: input.definition.baseUrl,
-          cardStreamLeaseMs: input.definition.cardStreamLeaseMs,
-          streamMinIntervalMs: input.definition.streamMinIntervalMs
-        },
-        pi: {}
-      };
-      const openApiClient = createOpenApiClient(config);
-      const promptContext = createFeishuTopicContextResolver({
-        baseUrl: input.definition.baseUrl,
-        client: openApiClient
-      });
-      const cotPublisher = input.definition.experimental?.cotMessages
-        ? createFeishuCotPublisher({
-            baseUrl: resolveExperimentalCotBaseUrl(context.env),
+          client: openApiClient
+        });
+        const cotPublisher = input.definition.experimental?.cotMessages
+          ? createFeishuCotPublisher({
+              baseUrl: resolveExperimentalCotBaseUrl(context.env),
+              client: openApiClient,
+              minIntervalMs: input.definition.streamMinIntervalMs
+            })
+          : undefined;
+        const interactions = createHumanInteractionService({
+          clock: { now: () => new Date().toISOString() },
+          presenter: createConfiguredFeishuHumanInteractionPresenter({
             client: openApiClient,
-            minIntervalMs: input.definition.streamMinIntervalMs
+            config
+          }),
+          repository: createJsonlHumanInteractionRepository({
+            filePath: join(endpointState, "human-interactions.jsonl")
           })
-        : undefined;
-      const interactions = createHumanInteractionService({
-        clock: { now: () => new Date().toISOString() },
-        presenter: createConfiguredFeishuHumanInteractionPresenter({
+        });
+        const cardRollover = createConfiguredFeishuCardRolloverRuntime({
+          agentName: input.agentId,
+          cardTargets,
           client: openApiClient,
-          config
-        }),
-        repository: createJsonlHumanInteractionRepository({
-          filePath: join(endpointState, "human-interactions.jsonl")
-        })
-      });
-      const cardRollover = createConfiguredFeishuCardRolloverRuntime({
-        agentName: input.agentId,
-        cardTargets,
-        client: openApiClient,
-        clock: createSystemClock(),
-        config,
-        ledger: cardLedger,
-        onError: (error) => {
-          console.error(`Feishu card rollover failed for endpoint ${input.endpointId}`, error);
-        },
-        ...(input.definition.progressDisplay === undefined
-          ? {}
-          : { progressDisplay: input.definition.progressDisplay }),
-        sleep,
-        title: input.agentId
-      });
-      const publisher = cardRollover.rollover;
-      const endpointEvents = createJsonlAgentEventLog({
-        filePath: join(STATE_DIR, "instances", input.instanceId, "agent-events.jsonl")
-      });
-      const endpointInitialEvents = await Effect.runPromise(endpointEvents.readAll());
-      await Effect.runPromise(
-        createFeishuCardDeliveryReconciler({
-          events: endpointInitialEvents,
+          clock: createSystemClock(),
+          config,
           ledger: cardLedger,
-          publish: (action) => publisher.publish(action)
-        }).reconcile()
-      );
-      const replies = createConfiguredFeishuTextReplySender({
-        client: openApiClient,
-        config
-      });
-      const prepareCardTarget = (run: FeishuAgentRunPreparation) => cardRollover.prepareRun(run);
-      const endpoint = createFeishuDeploymentEndpoint({
-        agentId: input.agentId,
-        botOpenId,
-        cardRollover: cardRollover.transport,
-        finalizeRun: (runId) => cardRollover.rollover.releaseRun(runId),
-        cancel: input.cancel,
-        endpointId: input.endpointId,
-        eventDispatcher: createLazyFeishuWebSocketEventDispatcher(() => new Lark.EventDispatcher({})),
-        groupPolicy: input.definition.groupPolicy,
-        handle: input.handle,
-        inboxRepository: inbox,
-        initialEvents: endpointInitialEvents,
-        interactions,
-        maxPendingMessages: 100,
-        memoryTenantId,
-        ...(input.projectSpaceId ? { projectSpaceId: input.projectSpaceId } : {}),
-        onCapacityExceeded: (payload) =>
-          replies.reply(payload.event.message.message_id, "Rivus is busy. Please retry in a moment."),
-        prepareRun: createFeishuPresentationPreparation({
-          ...(cotPublisher ? { cotPublisher } : {}),
-          prepareCardTarget,
-          reportCotError: (operation, error) => reportCotError(input.endpointId, operation, error)
-        }),
-        promptContext,
-        publish: (action) => publisher.publish(action),
-        reply: (messageId, text) => replies.reply(messageId, text),
-        sessionStore,
-        ...(input.steer ? { steer: input.steer } : {}),
-        ...(cotPublisher
-          ? {
-              publishRunUpdate: (update) =>
-                cotPublisher
-                  .publish(update)
-                  .pipe(Effect.catchAll((error) => reportCotError(input.endpointId, "update", error)))
-            }
-          : {}),
-        sessionNamespace: input.definition.sessionNamespace,
-        sleep,
-        websocketClient: createLazyFeishuWebSocketClient(credentials, input.definition.baseUrl),
-        workerConcurrency: 4
-      });
-      interactionRegistry.register(input.endpointId, interactions);
-      return endpoint;
-    },
-    createRuntime: async (input: CreateRivusDeploymentRuntimeInput) => {
-      const instanceState = join(STATE_DIR, "instances", input.instanceId);
-      await mkdir(instanceState, { recursive: true });
-      const eventLog = createJsonlAgentEventLog({ filePath: join(instanceState, "agent-events.jsonl") });
-      const initialEvents = await Effect.runPromise(eventLog.readAll());
-      const broker = createToolBroker({
-        approvals: createRoutedHumanInteractionToolApprovalService(interactionRegistry),
-        catalog: input.catalog,
-        hostTools: [
-          ...(input.definition.memory.tool ? [createRivusMemoryToolDescriptor({ memory })] : []),
-          ...(backgroundService
-            ? [
-                ...createBackgroundSessionHostTools({
-                  createSessionId: () => `bg-${randomUUID()}`,
-                  definition: input.definition,
-                  service: backgroundService
-                })
-              ]
-            : [])
-        ],
-        operations: await openJsonlToolOperationLedger({ filePath: join(instanceState, "tool-operations.jsonl") }),
-        policy: { current: async () => ({ epoch: 1, revokedToolIds: [] }) }
-      });
-      const resolveToolName = createPiToolNameResolver(input.definition.tools);
-      const skillRuntime = createPiSkillRuntime(input.definition.skills);
-      const workingDirectory = input.projectSpace?.workingDirectory ?? process.cwd();
-      const workspaceRoot = input.projectSpace?.root ?? process.cwd();
-      const workspaceInstructions = await createAgentsMdInstructionsProvider().resolve({
-        maxBytes: 64 * 1024,
-        workingDirectory: relative(workspaceRoot, workingDirectory) || ".",
-        workspaceRoot: await createWorkspaceRootHandle(workspaceRoot)
-      });
-      const prepareProjectMemory =
-        input.projectSpace && input.definition.memory.scopes.includes("project")
-          ? createProjectMemoryPromptPreparer({
+          onError: (error) => {
+            console.error(`Feishu card rollover failed for endpoint ${input.endpointId}`, error);
+          },
+          ...(input.definition.progressDisplay === undefined
+            ? {}
+            : { progressDisplay: input.definition.progressDisplay }),
+          sleep,
+          title: input.agentId
+        });
+        const publisher = cardRollover.rollover;
+        const endpointEvents = createJsonlAgentEventLog({
+          filePath: join(STATE_DIR, "instances", input.instanceId, "agent-events.jsonl")
+        });
+        const endpointInitialEvents = await Effect.runPromise(endpointEvents.readAll());
+        await Effect.runPromise(
+          createFeishuCardDeliveryReconciler({
+            events: endpointInitialEvents,
+            ledger: cardLedger,
+            publish: (action) => publisher.publish(action)
+          }).reconcile()
+        );
+        const replies = createConfiguredFeishuTextReplySender({
+          client: openApiClient,
+          config
+        });
+        const prepareCardTarget = (run: FeishuAgentRunPreparation) => cardRollover.prepareRun(run);
+        const endpoint = createFeishuDeploymentEndpoint({
+          agentId: input.agentId,
+          botOpenId,
+          cardRollover: cardRollover.transport,
+          finalizeRun: (runId) => cardRollover.rollover.releaseRun(runId),
+          cancel: input.cancel,
+          endpointId: input.endpointId,
+          eventDispatcher: createLazyFeishuWebSocketEventDispatcher(() => new Lark.EventDispatcher({})),
+          groupPolicy: input.definition.groupPolicy,
+          handle: input.handle,
+          inboxRepository: inbox,
+          initialEvents: endpointInitialEvents,
+          interactions,
+          maxPendingMessages: 100,
+          memoryTenantId,
+          ...(input.projectSpaceId ? { projectSpaceId: input.projectSpaceId } : {}),
+          onCapacityExceeded: (payload) =>
+            replies.reply(payload.event.message.message_id, "Rivus is busy. Please retry in a moment."),
+          prepareRun: createFeishuPresentationPreparation({
+            ...(cotPublisher ? { cotPublisher } : {}),
+            prepareCardTarget,
+            reportCotError: (operation, error) => reportCotError(input.endpointId, operation, error)
+          }),
+          promptContext,
+          publish: (action) => publisher.publish(action),
+          reply: (messageId, text) => replies.reply(messageId, text),
+          sessionStore,
+          ...(input.steer ? { steer: input.steer } : {}),
+          ...(cotPublisher
+            ? {
+                publishRunUpdate: (update) =>
+                  cotPublisher
+                    .publish(update)
+                    .pipe(Effect.catchAll((error) => reportCotError(input.endpointId, "update", error)))
+              }
+            : {}),
+          sessionNamespace: input.definition.sessionNamespace,
+          sleep,
+          websocketClient: createLazyFeishuWebSocketClient(credentials, input.definition.baseUrl),
+          workerConcurrency: 4
+        });
+        interactionRegistry.register(input.endpointId, interactions);
+        return endpoint;
+      },
+      createRuntime: async (input: CreateRivusDeploymentRuntimeInput) => {
+        const instanceState = join(STATE_DIR, "instances", input.instanceId);
+        await mkdir(instanceState, { recursive: true });
+        const eventLog = createJsonlAgentEventLog({ filePath: join(instanceState, "agent-events.jsonl") });
+        const initialEvents = await Effect.runPromise(eventLog.readAll());
+        const broker = createToolBroker({
+          approvals: createRoutedHumanInteractionToolApprovalService(interactionRegistry),
+          catalog: input.catalog,
+          hostTools: [
+            ...(input.definition.memory.tool ? [createRivusMemoryToolDescriptor({ memory })] : []),
+            ...(backgroundService
+              ? [
+                  ...createBackgroundSessionHostTools({
+                    createSessionId: () => `bg-${randomUUID()}`,
+                    definition: input.definition,
+                    service: backgroundService
+                  })
+                ]
+              : [])
+          ],
+          operations: await openJsonlToolOperationLedger({ filePath: join(instanceState, "tool-operations.jsonl") }),
+          policy: { current: async () => ({ epoch: 1, revokedToolIds: [] }) }
+        });
+        const resolveToolName = createPiToolNameResolver(input.definition.tools);
+        const skillRuntime = createPiSkillRuntime(input.definition.skills);
+        const workingDirectory = input.projectSpace?.workingDirectory ?? process.cwd();
+        const runContexts = management?.enabled
+          ? management.createRunContexts({
               agentId: input.agentId,
-              memory,
-              projectId: input.projectSpace.id
+              instanceId: input.instanceId,
+              toolGrantSet: input.definition.toolGrantSet
             })
           : undefined;
-      const sessionRegistry = createPiSessionRegistry({
-        createSession: async (firstInput) => {
-          let activeInput = firstInput;
-          const resources = await createPiSessionResources({
-            agentDir: PI_AGENT_DIR,
-            appendSystemPromptOverride: () =>
-              [workspaceInstructions.content, skillRuntime.prompt].filter((content) => content.length > 0),
-            cwd: workingDirectory,
-            homeDirectory: homedir(),
-            ...(input.projectSpace ? { projectSkillPaths: input.projectSpace.skillPaths } : {}),
-            systemPromptOverride: () => input.definition.systemPrompt
-          });
-          const customTools = [
-            ...createPiSkillReadTools({
+        const workspaceRoot = input.projectSpace?.root ?? process.cwd();
+        const workspaceInstructions = await createAgentsMdInstructionsProvider().resolve({
+          maxBytes: 64 * 1024,
+          workingDirectory: relative(workspaceRoot, workingDirectory) || ".",
+          workspaceRoot: await createWorkspaceRootHandle(workspaceRoot)
+        });
+        const prepareProjectMemory =
+          input.projectSpace && input.definition.memory.scopes.includes("project")
+            ? createProjectMemoryPromptPreparer({
+                agentId: input.agentId,
+                memory,
+                projectId: input.projectSpace.id
+              })
+            : undefined;
+        const sessionRegistry = createPiSessionRegistry({
+          createSession: async (firstInput) => {
+            let activeInput = firstInput;
+            const managedContext =
+              management?.enabled && runContexts && input.definition.runtimeToolGrantSet.toolIds.includes("bash")
+                ? createPiManagedSessionContext({
+                    binDirectory: management.binDirectory,
+                    contexts: runContexts.registry,
+                    cwd: workingDirectory,
+                    nodeExecutable: process.execPath,
+                    socketPath: management.socketPath
+                  })
+                : undefined;
+            const resources = await createPiSessionResources({
+              agentDir: PI_AGENT_DIR,
+              appendSystemPromptOverride: () =>
+                [workspaceInstructions.content, skillRuntime.prompt].filter((content) => content.length > 0),
               cwd: workingDirectory,
-              runtimeToolIds: input.definition.runtimeToolGrantSet.toolIds,
-              skillPaths: resources.skillNames.size > 0 ? resources.skillPaths : []
-            }),
-            ...createPiToolProxyDefinitions({
-              agentId: input.agentId,
-              approvals: createHumanInteractionToolApprovalGateway({ registry: interactionRegistry }),
-              broker,
-              getActiveInput: () => activeInput,
-              instanceId: input.instanceId,
-              memoryScopes: input.definition.memory.scopes,
-              toolGrantSet: input.definition.toolGrantSet,
-              tools: input.definition.tools
-            }),
-            ...(skillRuntime.tool ? [skillRuntime.tool] : [])
-          ];
-          const activeToolNames = resolvePiSessionToolNames(input.definition.runtimeToolGrantSet.toolIds, customTools);
-          const result = await createAgentSession(
-            resources.withSessionOptions({
-              ...piOptions,
-              customTools,
-              excludeTools: [],
-              sessionManager: SessionManager.create(workingDirectory, join(instanceState, "sessions")),
-              tools: [...activeToolNames]
-            })
-          );
-          return {
-            activate: (loopInput) => {
-              activeInput = loopInput;
-            },
-            dispose: () => result.session.dispose(),
-            preparePrompt: async (loopInput) => {
-              validatePiSkillCommand(loopInput.text, resources.skillNames);
-              return prepareProjectMemory ? prepareProjectMemory(loopInput) : loopInput.text;
-            },
-            resolveToolName,
-            session: result.session
-          };
-        }
-      });
-      const loop = createPiAgentLoop({
-        disposeSessionAfterRun: false,
-        ...(telemetry ? { modelContentObserver: telemetry.modelContentObserver } : {}),
-        resolveSession: (loopInput) => sessionRegistry.resolve(loopInput)
-      });
-      const scheduler = createSessionScheduler({
-        createRuntime: (sessionKey) =>
-          createAgentHarnessPooledRuntime(
-            createAgentHarness({
-              clock: createSystemClock(),
-              eventSinks: telemetry ? [eventLog, telemetry.sink] : [eventLog],
-              initialEvents: eventsForSession(initialEvents, sessionKey),
-              loop,
-              runIds: createUuidRunIds(),
-              ...(input.binding.kind === "background-session" && backgroundSessionsConfig
-                ? { runTimeoutMs: backgroundSessionsConfig.stepTimeoutMs }
-                : {})
-            })
-          ),
-        maxConcurrentSessions:
-          input.binding.kind === "background-session" ? (backgroundSessionsConfig?.maxConcurrentSessions ?? 4) : 4,
-        maxQueuedRuns: 32
-      });
-      return {
-        ...scheduler,
-        dispose: async () => {
-          await scheduler.dispose?.();
-          await sessionRegistry.disposeAll();
-        }
-      };
-    }
-  };
+              homeDirectory: homedir(),
+              ...(input.projectSpace ? { projectSkillPaths: input.projectSpace.skillPaths } : {}),
+              systemPromptOverride: () => input.definition.systemPrompt
+            });
+            const customTools = [
+              ...(managedContext ? [managedContext.tool] : []),
+              ...createPiSkillReadTools({
+                cwd: workingDirectory,
+                runtimeToolIds: input.definition.runtimeToolGrantSet.toolIds,
+                skillPaths: resources.skillNames.size > 0 ? resources.skillPaths : []
+              }),
+              ...createPiToolProxyDefinitions({
+                agentId: input.agentId,
+                approvals: createHumanInteractionToolApprovalGateway({ registry: interactionRegistry }),
+                broker,
+                getActiveInput: () => activeInput,
+                instanceId: input.instanceId,
+                memoryScopes: input.definition.memory.scopes,
+                toolGrantSet: input.definition.toolGrantSet,
+                tools: input.definition.tools
+              }),
+              ...(skillRuntime.tool ? [skillRuntime.tool] : [])
+            ];
+            const nativeToolIds = managedContext
+              ? input.definition.runtimeToolGrantSet.toolIds.filter((toolId) => toolId !== "bash")
+              : input.definition.runtimeToolGrantSet.toolIds;
+            const activeToolNames = resolvePiSessionToolNames(nativeToolIds, customTools);
+            const result = await createAgentSession(
+              resources.withSessionOptions({
+                ...piOptions,
+                ...(management?.enabled ? management.runtime.getSessionOptions() : {}),
+                customTools,
+                excludeTools: [],
+                sessionManager: SessionManager.create(workingDirectory, join(instanceState, "sessions")),
+                tools: [...activeToolNames]
+              })
+            );
+            return {
+              activate: (loopInput) => {
+                activeInput = loopInput;
+                managedContext?.activate(loopInput);
+              },
+              deactivate: () => managedContext?.deactivate(),
+              dispose: () => result.session.dispose(),
+              preparePrompt: async (loopInput) => {
+                validatePiSkillCommand(loopInput.text, resources.skillNames);
+                return prepareProjectMemory ? prepareProjectMemory(loopInput) : loopInput.text;
+              },
+              resolveToolName,
+              refreshResources: () => resources.refresh(),
+              session: result.session
+            };
+          }
+        });
+        const unregisterModels = management?.enabled
+          ? management.runtime.registerSessionRegistry(sessionRegistry)
+          : undefined;
+        const loop = createPiAgentLoop({
+          disposeSessionAfterRun: false,
+          ...(management?.enabled ? { runBoundary: management.boundary } : {}),
+          ...(telemetry ? { modelContentObserver: telemetry.modelContentObserver } : {}),
+          resolveSession: (loopInput) => sessionRegistry.resolve(loopInput)
+        });
+        const scheduler = createSessionScheduler({
+          createRuntime: (sessionKey) =>
+            createAgentHarnessPooledRuntime(
+              createAgentHarness({
+                clock: createSystemClock(),
+                eventSinks: telemetry ? [eventLog, telemetry.sink] : [eventLog],
+                initialEvents: eventsForSession(initialEvents, sessionKey),
+                loop,
+                runIds: createUuidRunIds(),
+                ...(input.binding.kind === "background-session" && backgroundSessionsConfig
+                  ? { runTimeoutMs: backgroundSessionsConfig.stepTimeoutMs }
+                  : {})
+              })
+            ),
+          maxConcurrentSessions:
+            input.binding.kind === "background-session" ? (backgroundSessionsConfig?.maxConcurrentSessions ?? 4) : 4,
+          maxQueuedRuns: 32
+        });
+        return {
+          ...scheduler,
+          dispose: async () => {
+            await scheduler.dispose?.();
+            await sessionRegistry.disposeAll();
+            unregisterModels?.();
+            runContexts?.unregister();
+          }
+        };
+      }
+    };
+  } catch (error) {
+    await Promise.allSettled([management?.enabled ? management.close() : Promise.resolve(), telemetry?.shutdown()]);
+    throw error;
+  }
 }
 
 function eventsForSession<T extends { readonly runId: string; readonly sessionKey?: string }>(
@@ -719,7 +782,10 @@ async function resolveFeishuBotOpenId(
   return openId;
 }
 
-async function createPiSessionOptions(context: RivusDeploymentBootstrapContext): Promise<PiSessionOptions> {
+async function createPiSessionOptions(
+  context: RivusDeploymentBootstrapContext,
+  deferModel = false
+): Promise<PiSessionOptions> {
   const modelReference = optional(context.env.PI_MODEL);
   const configuredModel = modelReference ? parseModelReference(modelReference) : undefined;
   const provider = configuredModel?.provider;
@@ -728,16 +794,28 @@ async function createPiSessionOptions(context: RivusDeploymentBootstrapContext):
   if ((apiKey || baseUrl) && !provider) {
     throw new Error("PI_API_KEY and PI_BASE_URL require PI_MODEL in provider/model form");
   }
-  if (baseUrl) await writeProviderBaseUrlOverride(provider!, baseUrl);
+  if (baseUrl && !deferModel) await writeProviderBaseUrlOverride(provider!, baseUrl);
   const modelRuntime = await ModelRuntime.create({
     allowModelNetwork: false,
     authPath: PI_AUTH_FILE,
-    modelsPath: baseUrl ? PI_MODELS_FILE : null
+    modelsPath: baseUrl || deferModel ? PI_MODELS_FILE : null
   });
   if (apiKey) await modelRuntime.setRuntimeApiKey(provider!, apiKey);
-  const model = configuredModel ? modelRuntime.getModel(configuredModel.provider, configuredModel.modelId) : undefined;
-  if (modelReference && !model) throw new Error(`PI_MODEL ${modelReference} was not found in the Pi model runtime`);
-  const thinkingLevel = readThinkingLevel(context.env.PI_THINKING_LEVEL);
+  const model =
+    configuredModel && !deferModel
+      ? modelRuntime.getModel(configuredModel.provider, configuredModel.modelId)
+      : undefined;
+  if (modelReference && !model && !deferModel)
+    throw new Error(`PI_MODEL ${modelReference} was not found in the Pi model runtime`);
+  const settings = deferModel
+    ? SettingsManager.create(process.cwd(), PI_AGENT_DIR, { projectTrusted: false })
+    : undefined;
+  const thinkingLevel =
+    readThinkingLevel(context.env.PI_THINKING_LEVEL) ??
+    (configuredModel
+      ? settings?.getModelThinkingLevel(configuredModel.provider, configuredModel.modelId)
+      : undefined) ??
+    settings?.getDefaultThinkingLevel();
   return {
     cwd: process.cwd(),
     modelRuntime,
@@ -746,6 +824,23 @@ async function createPiSessionOptions(context: RivusDeploymentBootstrapContext):
   };
 }
 
+function createEndpointConfig(
+  definition: RivusEndpointDeployment,
+  agentId: string,
+  env: RivusDaemonEnv
+): RivusDaemonConfig {
+  return {
+    agentId,
+    feishu: {
+      ...resolveFeishuEndpointCredentials(definition.credentialRef, env),
+      baseUrl: definition.baseUrl,
+      cardStreamLeaseMs: definition.cardStreamLeaseMs,
+      streamMinIntervalMs: definition.streamMinIntervalMs
+    },
+    pi: {}
+  };
+}
+
 async function resolvePiApiKey(env: Readonly<Record<string, string | undefined>>): Promise<string | undefined> {
   const inline = optional(env.PI_API_KEY);
   const filePath = optional(env.PI_API_KEY_FILE);