@piagent/platform 1.6.1 → 1.7.1

package/packages/piagent-webui/gateway/session-inspection-registry.ts

@@ -108,11 +108,13 @@ export class SessionInspectionRegistry {
   readonly #models?: ModelRuntime;
   readonly #projects?: ProjectSource;
   readonly #mcpAuth?: McpAuthBroker;
+  readonly #operationLiveness: ((sessionRef: string) => "idle" | "running" | "unknown") | null;
   readonly #providers = new Map<string, { modifiedAt: string; provider: CoreInspectionProvider }>();
 
   constructor(options: { gatewayInstanceRef: string; host: PiHost; key: Buffer; packageRoot: string; agentDir?: string; models?: ModelRuntime; projects?: ProjectSource;
     mcpAuth?: McpAuthBroker; listSessions?: () => Promise<PiSessionInfo[]>;
-    openLiveSession?: (sessionRef: string) => ReturnType<PiHost["SessionManager"]["open"]> | null }) {
+    openLiveSession?: (sessionRef: string) => ReturnType<PiHost["SessionManager"]["open"]> | null;
+    operationLiveness?: (sessionRef: string) => "idle" | "running" | "unknown" }) {
     this.#gatewayInstanceRef = options.gatewayInstanceRef;
     this.#host = options.host;
     this.#listSessions = options.listSessions ?? (() => options.host.SessionManager.listAll());
@@ -123,6 +125,7 @@ export class SessionInspectionRegistry {
     this.#models = options.models;
     this.#projects = options.projects;
     this.#mcpAuth = options.mcpAuth;
+    this.#operationLiveness = options.operationLiveness ?? null;
   }
 
   #connectionRef(server: { scope: string; origin: string; name: string }): string {
@@ -255,7 +258,12 @@ export class SessionInspectionRegistry {
       eventStore,
       task: () => safeRead(() => activeSessionTask(info.cwd, info.id), undefined),
       activityEvents: () => safeRead(() => readContextTelemetry(info.cwd, { limit: 5_000 }), []),
-      sessionEntries: () => entries,
+      // A provider can outlive the turn that created it (notably while a new
+      // session has not reached the host index yet). Read the branch at request
+      // time so transcript/activity projection cannot freeze at the pre-turn
+      // snapshot while the live manager continues appending entries.
+      sessionEntries: () => safeRead(() => manager.getBranch(), []),
+      sessionFile: () => info.path,
       protectedPaths: () => runtimeProtectedPaths(this.#packageRoot, info.cwd),
       // The document workspace lists the project plus whatever the operator
       // granted in the profile. Without this it silently shows the project only,
@@ -269,6 +277,7 @@ export class SessionInspectionRegistry {
       contextUsage: () => contextUsage,
       model: () => model,
       thinkingLevel: () => context.thinkingLevel,
+      operationLiveness: () => this.#operationLiveness?.(sessionRef) ?? "unknown",
       approvalProjection: () => piApprovalBroker.projection(info.cwd, info.id),
       approvalDetail: (approvalRef) => piApprovalBroker.detail(info.cwd, info.id, approvalRef)
     });

package/packages/piagent-webui/gateway/session-operation-settlement.ts

@@ -0,0 +1,28 @@
+import { settleIndependentWebUiOperation } from "../../piagent-core/extensions/acceptance-independent-registry.js";
+import type { activeSessionTask } from "../../piagent-core/extensions/task-state.js";
+import type { GatewaySessionStream } from "./gateway-session-stream.ts";
+import type { ScopedBrokerRouter } from "./session-runtime-factory.ts";
+
+type SettlementInput = { sessionId: string; operationRef: string; messageRequestId: string | null;
+  manager: any; stream: Pick<GatewaySessionStream, "markBlocked" | "markError"> };
+
+export function createSessionOperationSettlement(options: {
+  scopedBrokerRouter?: ScopedBrokerRouter;
+  compositeSettlementEvidence?(): unknown | Promise<unknown>;
+}) {
+  const router = options.scopedBrokerRouter;
+  const evidence = options.compositeSettlementEvidence ?? (router ? () => router.settlementEvidence()
+    : () => { throw new Error("composite-settlement-evidence-unavailable"); });
+  return async (cwd: string, task: ReturnType<typeof activeSessionTask>, input: SettlementInput) => {
+    const { sessionId, operationRef, messageRequestId, manager, stream } = input;
+    const settlement = await settleIndependentWebUiOperation(cwd, task,
+      { operationRef, messageRequestId, manager, evidence });
+    if (settlement.status === "blocked") stream.markBlocked("composite-settlement-blocked");
+    if (settlement.status === "not-applicable" && task?.trace?.outcome === "completed"
+      && router?.discardUnusedSettlement && messageRequestId) {
+      try { router.discardUnusedSettlement({ sessionId, operationRef, messageRequestId }); }
+      catch { stream.markError("scoped-operation-retirement-failed"); }
+    }
+    return settlement;
+  };
+}

package/packages/piagent-webui/gateway/session-prompt-dispatch.ts

@@ -0,0 +1,37 @@
+import { GatewaySessionStream } from "./gateway-session-stream.ts";
+import { waitForOperationStart } from "./session-operation-start.ts";
+
+export type LaunchedSessionPrompt = {
+  started: Promise<void>;
+  completion: Promise<void>;
+};
+export type SessionSendResult = { resultCode: "started" | "queued" | "steered"; operationRef: string;
+  dispatch?: () => void; cancel?: () => boolean };
+
+/**
+ * Launches host prompt work on the next event-loop turn. Gateway command
+ * admission can therefore persist and return its exact operation receipt
+ * before expensive synchronous Pi hooks begin, while direct runtime callers
+ * can still await the observed agent start through `started`.
+ */
+export function launchSessionPrompt(options: {
+  stream: GatewaySessionStream;
+  invoke(): Promise<void> | void;
+  finish(): Promise<void>;
+  canInvoke(): boolean;
+}): LaunchedSessionPrompt {
+  const prompt = new Promise<void>((resolve, reject) => {
+    setImmediate(() => {
+      if (!options.canInvoke()) { reject(new Error("session-operation-cancelled-before-dispatch")); return; }
+      try { Promise.resolve(options.invoke()).then(resolve, reject); }
+      catch (error) { reject(error); }
+    });
+  });
+  const observed = waitForOperationStart(options.stream, prompt);
+  const lifecycle = observed.then(async (mode) => {
+    if (mode === "deferred") await options.stream.settled();
+    else await Promise.race([options.stream.settled(), prompt]);
+  });
+  const completion = lifecycle.then(options.finish, () => { options.stream.markError(); return options.finish(); });
+  return { started: observed.then(() => undefined), completion };
+}

package/packages/piagent-webui/gateway/session-runtime-close.ts

@@ -0,0 +1,36 @@
+import { boundedResult } from "./session-operation-watchdog.ts";
+
+type ClosingRuntime = {
+  operationRef: string | null;
+  settling: boolean;
+  completion: Promise<void> | null;
+  stream: { markError(reasonCode: string): void } | null;
+};
+
+/** Drain ordinary settlement, then revoke authority for work that cannot finish. */
+export async function closeSessionRuntimes<T extends ClosingRuntime>(options: {
+  opening: ReadonlyMap<string, Promise<unknown>>;
+  active: ReadonlyMap<string, T>;
+  terminationTimeoutMs: number;
+  abort(sessionRef: string, operationRef: string): Promise<void>;
+  release(sessionRef: string): Promise<unknown>;
+  quarantine(sessionRef: string, operationRef: string, active: T, reasonCode: string): Promise<void>;
+}): Promise<void> {
+  await Promise.allSettled([...options.opening.values()]);
+  await Promise.allSettled([...options.active.entries()].filter(([, active]) => active.operationRef)
+    .map(([sessionRef, active]) => options.abort(sessionRef, active.operationRef!)));
+  await Promise.allSettled([...options.active.entries()].map(async ([sessionRef, active]) => {
+    // Normal settlement owns its completion promise and cannot be aborted.
+    if (active.settling && active.completion) {
+      await boundedResult(active.completion, options.terminationTimeoutMs);
+    }
+    if (options.active.get(sessionRef) !== active) return;
+    if (active.operationRef && active.stream) {
+      const reasonCode = "session-runtime-shutdown-incomplete";
+      active.stream.markError(reasonCode);
+      await options.quarantine(sessionRef, active.operationRef, active, reasonCode);
+      return;
+    }
+    await options.release(sessionRef);
+  }));
+}

package/packages/piagent-webui/gateway/session-runtime-factory.ts

@@ -1,32 +1,189 @@
 import path from "node:path";
+import fs from "node:fs";
+import { createHash, createPrivateKey, sign, verify, createPublicKey } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 
+import { webUiModelRef } from "../../piagent-core/runtime/inspection/webui-snapshot.ts";
+import { createHostWireSession } from "../../piagent-core/runtime/session/runtime-state.ts";
+import { appendJsonlBounded } from "../../piagent-core/extensions/state-retention.js";
 import type { PiSessionInfo } from "./session-catalog.ts";
 import { preferAuthoritativePiagentGuard } from "./extension-authority.ts";
 import { rpcUiContext } from "./rpc-ui-context.ts";
 
-export type RuntimeHandle = { dispose(): Promise<void>; session?: any };
+export type WireOperation = { operationRef: string; messageRequestId: string | null; inputText: string };
+export type RuntimeHandle = { dispose(): Promise<void>; session?: any;
+  beginWireOperation?(identity: WireOperation): (reason: string) => void };
+export type InitialSessionOptions = { modelRef: string | null; thinkingLevel: string };
 export type RuntimeFactory = (info: PiSessionInfo, runtimeInstanceRef: string,
-  sessionManager?: any) => Promise<RuntimeHandle>;
+  sessionManager?: any, initialOptions?: InitialSessionOptions) => Promise<RuntimeHandle>;
+export type ScopedBrokerRouter = { toolNames: readonly string[]; extensionFactory: (pi: any) => void;
+  beginOperation(identity: WireOperation & { sessionId: string }): (reason: string) => void;
+  settlementEvidence(): unknown; assertProviderDispatchReady(): true;
+  discardUnusedSettlement?(identity: { sessionId: string; operationRef: string; messageRequestId: string }): void;
+  takeFatalProviderBoundaryError(): Error | null;
+  assertOwnership(resourceLoader: any): unknown; dispose(): Promise<void> };
+const MAX_WIRE_JOURNAL_BYTES = 64 * 1024 * 1024;
+
+function privateWireFile(file: string, cwd: string, maximum: number, sync = false) {
+  const root = fs.realpathSync(cwd), absolute = path.resolve(file), parent = path.dirname(absolute);
+  if (!path.isAbsolute(file) || absolute !== fs.realpathSync(absolute) || absolute === root
+    || absolute.startsWith(`${root}${path.sep}`)) throw new Error("provider-wire-private-path-invalid");
+  const directory = fs.lstatSync(parent);
+  if (!directory.isDirectory() || directory.uid !== process.getuid?.() || (directory.mode & 0o777) !== 0o700)
+    throw new Error("provider-wire-private-directory-invalid");
+  const fd = fs.openSync(absolute, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  try {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || stat.nlink !== 1 || stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o600 || stat.size > maximum)
+      throw new Error("provider-wire-private-file-invalid");
+    const data = fs.readFileSync(fd);
+    if (data.length !== stat.size || data.length > maximum) throw new Error("provider-wire-private-file-changed");
+    if (sync) fs.fsyncSync(fd);
+    return { absolute, data, dev: stat.dev, ino: stat.ino };
+  } finally { fs.closeSync(fd); }
+}
+
+function wireConfiguration(options: { wireManifest?: unknown; signReceipt?: (material: string) => string; wireReceiptsPath?: string }, cwd: string) {
+  const manifestPath = process.env.PIAGENT_WIRE_MANIFEST_PATH, expectedHash = process.env.PIAGENT_WIRE_MANIFEST_SHA256;
+  const keyPath = process.env.PIAGENT_WIRE_SIGNING_KEY_PATH;
+  const receiptsPath = options.wireReceiptsPath ?? process.env.PIAGENT_WIRE_RECEIPTS_PATH;
+  let manifest = options.wireManifest, signer = options.signReceipt;
+  if (manifest === undefined && !manifestPath && !expectedHash && !keyPath && !receiptsPath) return null;
+  if (manifest === undefined) {
+    if (!manifestPath || !/^[a-f0-9]{64}$/.test(expectedHash ?? "")) throw new Error("provider-wire-manifest-pin-missing");
+    const source = privateWireFile(manifestPath, cwd, 4 * 1024 * 1024).data;
+    if (createHash("sha256").update(source).digest("hex") !== expectedHash) throw new Error("provider-wire-manifest-pin-mismatch");
+    manifest = JSON.parse(source.toString("utf8"));
+  }
+  if (!signer) {
+    if (!keyPath) throw new Error("provider-wire-signer-missing");
+    const key = createPrivateKey(privateWireFile(keyPath, cwd, 16 * 1024).data);
+    if (key.asymmetricKeyType !== "ed25519") throw new Error("provider-wire-signer-invalid");
+    signer = (material: string) => sign(null, Buffer.from(material), key).toString("base64");
+  }
+  if (!receiptsPath) throw new Error("provider-wire-receipts-path-missing");
+  const publicKey = createPublicKey({ key: Buffer.from((manifest as any)?.receiptPublicKey ?? "", "base64"), type: "spki", format: "der" });
+  let previous = privateWireFile(receiptsPath, cwd, MAX_WIRE_JOURNAL_BYTES);
+  let sequence = 0, previousReceiptHash: string | null = null;
+  if (previous.data.length) throw new Error("provider-wire-journal-replay-required");
+  return { manifest, signReceipt: signer, record: async (receipt: unknown) => {
+    const envelope = receipt as { material: string; signature: string };
+    if (typeof envelope?.material !== "string" || typeof envelope.signature !== "string"
+      || !verify(null, Buffer.from(envelope.material), publicKey, Buffer.from(envelope.signature, "base64")))
+      throw new Error("provider-wire-receipt-signature-invalid");
+    const material = JSON.parse(envelope.material);
+    if (material.sequence !== sequence + 1 || material.previousReceiptHash !== previousReceiptHash)
+      throw new Error("provider-wire-receipt-chain-invalid");
+    const current = privateWireFile(receiptsPath, cwd, MAX_WIRE_JOURNAL_BYTES), line = Buffer.from(`${JSON.stringify(receipt)}\n`);
+    if (current.dev !== previous.dev || current.ino !== previous.ino || !current.data.equals(previous.data)
+      || current.data.length + line.length > MAX_WIRE_JOURNAL_BYTES || fs.existsSync(`${current.absolute}.1`))
+      throw new Error("provider-wire-journal-continuity-lost");
+    if (!isDeepStrictEqual(appendJsonlBounded(current.absolute, receipt, { maxBytes: MAX_WIRE_JOURNAL_BYTES, mode: 0o600 }), receipt))
+      throw new Error("provider-wire-receipt-truncated");
+    const persisted = privateWireFile(receiptsPath, cwd, MAX_WIRE_JOURNAL_BYTES, true);
+    if (persisted.dev !== current.dev || persisted.ino !== current.ino || !persisted.data.equals(Buffer.concat([current.data, line])))
+      throw new Error("provider-wire-receipt-not-persisted");
+    previous = persisted; sequence = material.sequence;
+    previousReceiptHash = createHash("sha256").update(JSON.stringify(receipt)).digest("hex");
+  } };
+}
 
 export function createProductionRuntimeFactory(options: {
   host: any;
   agentDir: string;
   packageRoot: string;
   modelRuntime?: any;
+  wireManifest?: unknown;
+  signReceipt?: (material: string) => string;
+  wireReceiptsPath?: string;
+  scopedBrokerRouter?: ScopedBrokerRouter;
 }): RuntimeFactory {
-  return async (info, _runtimeInstanceRef, sessionManager) => {
+  return async (info, runtimeInstanceRef, sessionManager, initialOptions) => {
+    const wireConfig = wireConfiguration(options, info.cwd);
+    let pendingInitialOptions = initialOptions;
+    let wire: ReturnType<typeof createHostWireSession> | null = null;
+    const retireWire = () => { wire?.dispose(); wire = null; };
     const guard = path.join(options.packageRoot, "packages", "piagent-core", "extensions", "piagent-guard.ts");
     const createRuntime = async ({ cwd, agentDir, sessionManager, sessionStartEvent }: any) => {
+      const requested = pendingInitialOptions;
+      pendingInitialOptions = undefined;
+      let modelRuntime = options.modelRuntime;
+      if (options.scopedBrokerRouter) {
+        const streamSimple = modelRuntime?.streamSimple;
+        if (typeof streamSimple !== "function") throw new Error("session-scoped-provider-boundary-unavailable");
+        const guarded = Object.create(modelRuntime);
+        Object.defineProperty(guarded, "streamSimple", { enumerable: true,
+          value(...args: unknown[]) {
+            options.scopedBrokerRouter!.assertProviderDispatchReady();
+            return Reflect.apply(streamSimple, modelRuntime, args);
+          } });
+        modelRuntime = guarded;
+      }
       const services = await options.host.createAgentSessionServices({
-        cwd, agentDir, modelRuntime: options.modelRuntime,
+        cwd, agentDir, modelRuntime,
         resourceLoaderOptions: {
           additionalExtensionPaths: [guard],
-          extensionsOverride: preferAuthoritativePiagentGuard(guard)
+          extensionsOverride: preferAuthoritativePiagentGuard(guard),
+          ...(options.scopedBrokerRouter ? { noExtensions: true, noSkills: true, noPromptTemplates: true,
+            noThemes: true, noContextFiles: true,
+            extensionFactories: [options.scopedBrokerRouter.extensionFactory] } : {})
         }
       });
       const extensionErrors = services.resourceLoader.getExtensions().errors;
       if (extensionErrors.length) throw new Error("session-runtime-extension-load-failed");
-      const created = await options.host.createAgentSessionFromServices({ services, sessionManager, sessionStartEvent });
+      options.scopedBrokerRouter?.assertOwnership(services.resourceLoader);
+      const models = requested?.modelRef ? services.modelRuntime?.getAvailableSnapshot?.() ?? [] : [];
+      const model = requested?.modelRef ? models.find((value: any) => webUiModelRef(String(value.provider ?? ""),
+        String(value.id ?? value.modelId ?? "")) === requested.modelRef) : undefined;
+      if (requested?.modelRef && !model) throw new Error("session-model-unavailable");
+      const created = await options.host.createAgentSessionFromServices({ services, sessionManager, sessionStartEvent,
+        ...(model ? { model } : {}), ...(requested ? { thinkingLevel: requested.thinkingLevel } : {}),
+        ...(options.scopedBrokerRouter ? { noTools: "all", tools: [...options.scopedBrokerRouter.toolNames] } : {}) });
+      if (options.scopedBrokerRouter && JSON.stringify(created.session.getActiveToolNames?.())
+        !== JSON.stringify(options.scopedBrokerRouter.toolNames)) throw new Error("session-scoped-tool-surface-mismatch");
+      if (options.scopedBrokerRouter) {
+        const agent = created.session?.agent, sdkPayload = agent?.onPayload;
+        if (typeof sdkPayload !== "function") throw new Error("session-scoped-provider-boundary-unavailable");
+        agent.onPayload = async (raw: unknown, model: { provider: string; id: string }) => {
+          await options.scopedBrokerRouter!.assertProviderDispatchReady();
+          return await sdkPayload(raw, model);
+        };
+      }
+      if (wireConfig) {
+        const session = created.session, agent = session.agent, sdkPayload = agent?.onPayload;
+        if (typeof sdkPayload !== "function") throw new Error("provider-wire-final-callback-unavailable");
+        let hookErrors = 0, disposed = false;
+        const installWire = () => {
+          retireWire();
+          wire = createHostWireSession({ cwd, sessionId: sessionManager.getSessionId(), runtimeInstanceRef,
+            manifest: wireConfig.manifest as Record<string, any>, signReceipt: wireConfig.signReceipt, record: wireConfig.record });
+          return wire;
+        };
+        let ownedWire = installWire();
+        agent.onPayload = async (raw: unknown, model: { provider: string; id: string }) => {
+          const current = ownedWire;
+          if (disposed || wire !== current) throw new Error("provider-wire-session-stale");
+          const transformed = await sdkPayload(raw, model);
+          const payload = structuredClone(transformed === undefined ? raw : transformed);
+          if (disposed || wire !== current) throw new Error("provider-wire-session-stale");
+          await current.validatePayload({ payload, model, hookErrors });
+          if (disposed || wire !== current) throw new Error("provider-wire-session-stale");
+          return payload;
+        };
+        const bindExtensions = session.bindExtensions.bind(session);
+        session.bindExtensions = (bindings: any) => bindExtensions({ ...bindings, onError: (error: any) => {
+          hookErrors++; bindings.onError?.(error);
+        } });
+        const reload = session.reload.bind(session), dispose = session.dispose.bind(session);
+        session.reload = async (...args: unknown[]) => {
+          if (disposed || wire !== ownedWire) throw new Error("provider-wire-session-stale");
+          retireWire();
+          hookErrors = 0;
+          await reload(...args);
+          ownedWire = installWire();
+        };
+        session.dispose = () => { disposed = true; ownedWire.dispose(); if (wire === ownedWire) wire = null; return dispose(); };
+      }
       return { ...created, services, diagnostics: services.diagnostics };
     };
     const manager = sessionManager ?? options.host.SessionManager.open(info.path);
@@ -38,6 +195,26 @@ export function createProductionRuntimeFactory(options: {
     });
     const bind = async (session: any) => session.bindExtensions({ mode: "rpc", uiContext: rpcUiContext() });
     runtime.setRebindSession(bind);
+    if (wireConfig) runtime.setBeforeSessionInvalidate?.(retireWire);
+    if (wireConfig || options.scopedBrokerRouter) {
+      runtime.beginWireOperation = (identity: WireOperation) => {
+        const finishers: Array<(reason: string) => void> = [];
+        try {
+          if (options.scopedBrokerRouter) finishers.push(options.scopedBrokerRouter.beginOperation({
+            ...identity, sessionId: manager.getSessionId() }));
+          if (wireConfig) {
+        if (!wire) throw new Error("provider-wire-session-unavailable");
+        if (!identity.messageRequestId) throw new Error("provider-wire-operation-identity-missing");
+        const current = wire, cancel = current.beginOperation({ ...identity, messageRequestId: identity.messageRequestId });
+            finishers.push((reason: string) => { try { cancel(reason); } catch { current.dispose(); } });
+          }
+        } catch (error) { for (const finish of finishers.reverse()) try { finish("operation-start-failed"); } catch {}
+          throw error; }
+        return (reason: string) => { for (const finish of finishers) finish(reason); };
+      };
+      const dispose = runtime.dispose.bind(runtime);
+      runtime.dispose = async () => { retireWire(); await options.scopedBrokerRouter?.dispose(); await dispose(); };
+    }
     try { await bind(runtime.session); }
     catch (error) { await runtime.dispose().catch(() => undefined); throw error; }
     return runtime;

package/packages/piagent-webui/gateway/session-runtime-ownership.ts

@@ -0,0 +1,48 @@
+import { createHmac } from "node:crypto";
+import type { SessionOwnerProjection } from "./session-catalog.ts";
+import type { SessionLeaseSnapshot } from "./session-lease-store.ts";
+
+type ActiveOwnership = {
+  lease: SessionLeaseSnapshot;
+  operationRef: string | null;
+  approvalWaiting: boolean;
+};
+
+export function projectSessionRuntimeOwnership(options: {
+  lease: SessionLeaseSnapshot;
+  active?: ActiveOwnership;
+  gatewayInstanceRef: string;
+  key: Buffer;
+}): SessionOwnerProjection {
+  const { lease, active, gatewayInstanceRef, key } = options;
+  if (lease.state === "released") return {
+    state: "offline", liveState: "offline", composerAvailable: true, needsAttention: false,
+    owner: { kind: "none", ownerEpoch: null, gatewayInstanceRef: null, runtimeInstanceRef: null, continuity: "released" },
+    reasonCode: null
+  };
+  if (lease.state === "gateway-owned" && active && active.lease.ownerEpoch === lease.ownerEpoch
+    && lease.gatewayInstanceRef === gatewayInstanceRef && active.lease.runtimeInstanceRef === lease.runtimeInstanceRef) return {
+    state: "gateway-owned", liveState: active.approvalWaiting ? "waiting-approval" : active.operationRef ? "running" : "idle",
+    composerAvailable: true, needsAttention: active.approvalWaiting,
+    owner: { kind: "gateway", ownerEpoch: lease.ownerEpoch!, gatewayInstanceRef: lease.gatewayInstanceRef!,
+      runtimeInstanceRef: lease.runtimeInstanceRef!, continuity: "exact" }, reasonCode: null
+  };
+  if (lease.state === "unavailable") return {
+    state: "recovery-required", liveState: "uncertain", composerAvailable: false, needsAttention: true,
+    owner: { kind: "none", ownerEpoch: null, gatewayInstanceRef: null, runtimeInstanceRef: null, continuity: "unknown" },
+    reasonCode: lease.reasonCode ?? "session-lease-unavailable"
+  };
+  if (lease.state === "terminal-owned") return {
+    state: "terminal-owned", liveState: "uncertain", composerAvailable: false, needsAttention: false,
+    owner: { kind: "terminal", ownerEpoch: lease.ownerEpoch!,
+      gatewayInstanceRef: `terminal_${createHmac("sha256", key).update(lease.gatewayInstanceRef!).digest("base64url").slice(0, 43)}`,
+      runtimeInstanceRef: lease.runtimeInstanceRef!, continuity: "exact" },
+    reasonCode: "terminal-owner-active"
+  };
+  return {
+    state: "recovery-required", liveState: "uncertain", composerAvailable: false, needsAttention: true,
+    owner: { kind: "gateway", ownerEpoch: lease.ownerEpoch!, gatewayInstanceRef: lease.gatewayInstanceRef!,
+      runtimeInstanceRef: lease.runtimeInstanceRef!, continuity: "uncertain" },
+    reasonCode: lease.reasonCode ?? "session-owner-continuity-unknown"
+  };
+}

package/packages/piagent-webui/gateway/session-runtime-state.ts

@@ -0,0 +1,24 @@
+import type { PiSessionInfo } from "./session-catalog.ts";
+import type { GatewaySessionStream } from "./gateway-session-stream.ts";
+import type { SessionLeaseSnapshot } from "./session-lease-store.ts";
+import type { SessionOperationWatchdog } from "./session-operation-watchdog.ts";
+import type { RuntimeHandle } from "./session-runtime-factory.ts";
+
+export type ActiveRuntime = {
+  runtime: RuntimeHandle;
+  lease: SessionLeaseSnapshot;
+  info: PiSessionInfo;
+  operationRef: string | null;
+  messageRequestId: string | null;
+  cancelWire: ((reason: string) => void) | null;
+  stream: GatewaySessionStream | null;
+  unsubscribe: (() => void) | null;
+  completion: Promise<void> | null;
+  settling: boolean;
+  approvalWaiting: boolean;
+  unbindApproval: (() => void) | null;
+  unsubscribeApproval: (() => void) | null;
+  sessionManager: any | null;
+  watchdog: SessionOperationWatchdog | null;
+  lastSessionRevision: string | null;
+};