@piagent/platform 1.7.1 → 1.9.0

package/packages/piagent-webui/gateway/gateway-service.ts

@@ -1,3 +1,4 @@
+import { managedProjection } from './managed-projection.ts';
 import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -16,11 +17,14 @@ import {
   writeGatewayDescriptor,
   type GatewayDescriptor
 } from "./profile-state.ts";
-import { buildSessionCatalog } from "./session-catalog.ts";
+import { buildSessionCatalog, projectRefForCwd } from "./session-catalog.ts";
+import { sessionRefForPath } from "../ownership/session-refs.ts";
 import { SessionMetadataStore } from "./session-metadata-store.ts";
 import { GatewayProtocolService } from "./gateway-protocol-service.ts";
 import { SessionLeaseStore } from "./session-lease-store.ts";
 import { SessionRuntimeSupervisor } from "./session-runtime-supervisor.ts";
+import { cachedSessionLister } from "./session-list-cache.ts";
+import { cachedSessionFacts } from "./session-file-facts.ts";
 import { buildSessionLiveState } from "./session-live-state.ts";
 import { SessionCommandStore } from "./session-command-store.ts";
 import { SessionCommandController } from "./session-command-controller.ts";
@@ -30,9 +34,10 @@ import { SessionInspectionRegistry } from "./session-inspection-registry.ts";
 import { SessionAttachmentRegistry } from "./session-attachment-registry.ts";
 import { ProjectRegistry } from "./project-registry.ts";
 import { pickNativeProjectFolders } from "./native-project-picker.ts";
+import { CompanyRelay, type CompanyConnector } from "./company-relay.ts";
 import { ProviderAuthBroker } from "./provider-auth-broker.ts";
 import { McpAuthBroker } from "./mcp-auth-broker.ts";
-import type { ScopedBrokerRouter } from "./session-runtime-factory.ts";
+import type { ScopedBrokerRouter, RuntimeFactory } from "./session-runtime-factory.ts";
 
 function unavailable(reasonCode: string) {
   return { status: "unavailable" as const, version: null, reasonCode };
@@ -44,7 +49,7 @@ function safeModelLabel(value: unknown): string {
   return (redactSensitiveText(String(value ?? "Model")).text.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim() || "Model").slice(0, 120);
 }
 
-function capabilities(gatewayInstanceRef: string, runtimeAvailable = false): PiagentGatewayCapabilityHandshakeV1 {
+function capabilities(gatewayInstanceRef: string, runtimeAvailable = false, managed = false): PiagentGatewayCapabilityHandshakeV1 {
   return {
     schemaVersion: 1,
     version: "piagent-gateway-capabilities-v1",
@@ -61,9 +66,9 @@ function capabilities(gatewayInstanceRef: string, runtimeAvailable = false): Pia
         create: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
         send: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
         abort: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
-        setModel: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
+        setModel: runtimeAvailable && !managed ? available() : unavailable("model-managed-by-studio"),
         setThinking: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
-        setPermission: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
+        setPermission: runtimeAvailable && !managed ? available() : unavailable("permissions-managed-by-studio"),
         rename: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
         pin: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
         archive: runtimeAvailable ? available() : unavailable("session-runtime-not-enabled"),
@@ -77,12 +82,20 @@ function capabilities(gatewayInstanceRef: string, runtimeAvailable = false): Pia
   };
 }
 
+function packageVersion(root: string): string | undefined {
+  try { return String(JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version); } catch { return undefined; }
+}
+
 export async function startPiagentGateway(options: {
   packageRoot: string;
   expectedPiVersion: string;
   agentDir?: string;
   staticRoot?: string;
   scopedBrokerRouter?: ScopedBrokerRouter;
+  managed?: { host: any; models: any; runtimeFactory: RuntimeFactory; project: string | null };
+  // Company sessions relayed into this dashboard (the dashboard entry passes
+  // the Agent Watch binding; omitted: none).
+  company?: CompanyConnector;
 }): Promise<{ descriptor: GatewayDescriptor; wait(): Promise<void>; close(): Promise<void> }> {
   const state = gatewayProfileState(options.agentDir);
   process.env.PI_CODING_AGENT_DIR = state.agentDir;
@@ -99,6 +112,7 @@ export async function startPiagentGateway(options: {
   let runtimes: SessionRuntimeSupervisor | null = null;
   let mcpAuth: McpAuthBroker | null = null;
   let attachments: SessionAttachmentRegistry | null = null;
+  let relay: CompanyRelay | null = null;
   let closing: Promise<void> | null = null;
   let settleWait: (() => void) | null = null;
   const waited = new Promise<void>((resolve) => { settleWait = resolve; });
@@ -107,6 +121,7 @@ export async function startPiagentGateway(options: {
     if (closing) return await closing;
     closing = (async () => {
       removeGatewayDescriptor(state, gatewayInstanceRef);
+      relay?.close();
       await loopback?.close().catch(() => undefined);
       // Staged bytes are private temp files. Closing deletes them rather than
       // leaving a directory per session behind for the TTL sweep that will never
@@ -129,14 +144,26 @@ export async function startPiagentGateway(options: {
         if (!loopback) return { ok: false, error: "gateway-starting" };
         return reply({ launchUrl: loopback.issueLaunchUrl(), gatewayInstanceRef });
       }
+      if (request.action === "project.register" || request.action === "project.paths") {
+        if (!options.managed || !runtimes) return { ok: false, error: "project-control-unavailable" };
+        if (request.action === "project.register") {
+          try { return reply(projects.register(request.cwd)); } catch { return { ok: false, error: "project-import-folder-invalid" }; }
+        }
+        // Registered folders and the folders of existing sessions.
+        return runtimes.listSessions().then((sessions) => {
+          const paths = new Map(projects.list().map((item) => [item.projectRef, projects.resolve(item.projectRef)]));
+          for (const info of sessions) if (typeof info.cwd === "string") paths.set(projectRefForCwd(key, info.cwd), info.cwd);
+          return reply([...paths].filter(([, cwd]) => cwd).map(([projectRef, cwd]) => ({ projectRef, cwd })));
+        }, () => ({ ok: false as const, error: "project-control-unavailable" }));
+      }
       setImmediate(() => { void close(); });
       return reply({ stopping: true, gatewayInstanceRef });
     }
   });
 
   try {
-    const host = await loadPinnedPiHost(options.expectedPiVersion);
-    const inspectionModels = await host.ModelRuntime.create({
+    const host = options.managed?.host ?? await loadPinnedPiHost(options.expectedPiVersion);
+    const inspectionModels = options.managed?.models ?? await host.ModelRuntime.create({
       authPath: path.join(state.agentDir, "auth.json"),
       modelsPath: path.join(state.agentDir, "models.json"),
       allowModelNetwork: false
@@ -145,12 +172,21 @@ export async function startPiagentGateway(options: {
     mcpAuth = new McpAuthBroker(state.agentDir);
     const leases = new SessionLeaseStore(state.root, key);
     const events = new GatewayEventStore();
+    if (options.managed?.project) projects.register(options.managed.project);
     runtimes = new SessionRuntimeSupervisor({
-      gatewayInstanceRef, key, leases, listSessions: () => host.SessionManager.listAll(),
+      gatewayInstanceRef, key, leases, listSessions: cachedSessionLister((dir) => host.SessionManager.listAll(dir), path.join(state.agentDir, 'sessions'), Boolean(options.managed)),
       host, agentDir: state.agentDir, packageRoot: options.packageRoot, modelRuntime: inspectionModels, events,
+      runtimeFactory: options.managed?.runtimeFactory,
+      sessionDirectory: options.managed ? path.join(state.agentDir, 'sessions') : undefined,
       scopedBrokerRouter: options.scopedBrokerRouter,
       resolveProject: (projectRef) => projects.resolve(projectRef)
     });
+    const sessionFacts = (manager: { buildSessionContext(): any; getBranch(): any[] }) => {
+      const context = manager.buildSessionContext();
+      return { model: context.model ? { provider: String(context.model.provider), modelId: String(context.model.modelId) } : null,
+        thinkingLevel: context.thinkingLevel, managed: managedProjection(context, manager.getBranch()) };
+    };
+    const fileFacts = cachedSessionFacts((file) => sessionFacts(host.SessionManager.open(file)));
     const readCatalog = () => buildSessionCatalog({
       gatewayInstanceRef,
       key,
@@ -159,12 +195,15 @@ export async function startPiagentGateway(options: {
       readOwnership: (sessionRef) => runtimes!.ownership(sessionRef),
       readSessionOptions: (info) => {
         try {
-          const context = host.SessionManager.open(info.path).buildSessionContext();
-          const model = context.model ? inspectionModels.getModel(context.model.provider, context.model.modelId) : null;
-          const thinking = ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(String(context.thinkingLevel))
-            ? context.thinkingLevel : "unknown";
-          return { modelLabel: model ? safeModelLabel(model.name ?? model.id ?? context.model?.modelId) : null,
-            thinkingLevel: thinking };
+          // A session running here may not have flushed its model and thinking
+          // entries yet; its live manager has them, the file does not.
+          const live = runtimes!.liveSessionManager(sessionRefForPath(key, info.path));
+          const facts = live ? sessionFacts(live) : fileFacts(info.path);
+          const model = facts.model ? inspectionModels.getModel(facts.model.provider, facts.model.modelId) : null;
+          const thinking = ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(String(facts.thinkingLevel))
+            ? facts.thinkingLevel : "unknown";
+          return { modelLabel: model ? safeModelLabel(model.name ?? model.id ?? facts.model?.modelId) : null,
+            thinkingLevel: thinking, ...facts.managed };
         } catch { return { modelLabel: null, thinkingLevel: "unknown" }; }
       }
     });
@@ -173,7 +212,16 @@ export async function startPiagentGateway(options: {
       if (catalog.state !== "ready" || !session) throw new Error("session-projection-unavailable");
       return { sessionRevision: session.sessionRevision, liveState: session.liveState };
     });
-    const commands = new SessionCommandController({ catalog: readCatalog, runtimes, metadata,
+    relay = options.managed || !options.company ? null : new CompanyRelay({
+      connector: options.company,
+      events, hubProject: (cwd) => projectRefForCwd(key, cwd),
+      folder: async (projectRef) => projects.resolve(projectRef)
+        ?? (await runtimes!.listSessions()).find((info) => projectRefForCwd(key, info.cwd) === projectRef)?.cwd ?? null });
+    // Every revision the browser sees and sends back is the merged one.
+    const hubCatalog = relay ? async () => relay!.merge(await readCatalog()) : readCatalog;
+    const company = (sessionRef: unknown) => !!relay?.owns(sessionRef);
+    const relayPost = (path: string, body: unknown) => relay!.json("POST", path, body);
+    const commands = new SessionCommandController({ catalog: hubCatalog, runtimes, metadata,
       store: new SessionCommandStore(state.root, key), events,
       // Resolved at call time: the attachment registry is built after this
       // controller, because it reads sessions through the inspection registry.
@@ -182,8 +230,9 @@ export async function startPiagentGateway(options: {
         return attachments.reserveForPrompt(sessionRef, refs, messageRequestId, text);
       } });
     const runtimeCommands = new RuntimeCommandController({ catalog: readCatalog, runtimes, events });
-    const protocol = new GatewayProtocolService({ capabilities: () => capabilities(gatewayInstanceRef, true), catalog: readCatalog,
-      events, command: commands });
+    const protocol = new GatewayProtocolService({ capabilities: () => capabilities(gatewayInstanceRef, true, !!options.managed), catalog: hubCatalog,
+      events, command: relay ? { execute: (command) => relay!.handles(command)
+        ? relay!.command(command as Record<string, unknown>, async () => (await hubCatalog()).catalogRevision) : commands.execute(command) } : commands });
     const inspections = new SessionInspectionRegistry({ gatewayInstanceRef, host, key, packageRoot: options.packageRoot, agentDir: state.agentDir,
       models: inspectionModels, projects, mcpAuth, listSessions: () => runtimes!.listSessions(),
       openLiveSession: (sessionRef) => runtimes!.liveSessionManager(sessionRef),
@@ -196,22 +245,51 @@ export async function startPiagentGateway(options: {
     loopback = await startLoopbackServer({
       staticRoot,
       mode: "gateway",
-      readCapabilities: () => capabilities(gatewayInstanceRef, true),
-      readSessionCatalog: readCatalog,
-      readSessionLiveState: () => buildSessionLiveState({ gatewayInstanceRef, eventSequence: events.stateVersion,
-        operations: runtimes!.currentOperations(), settlements: events.recentOperationSettlements() }),
-      readSessionCreationOptions: () => inspections.creationOptions(),
+      readCapabilities: () => capabilities(gatewayInstanceRef, true, !!options.managed),
+      readSessionCatalog: hubCatalog,
+      // Company settlements arrive as re-published events; running company
+      // operations are read from its Gateway.
+      readSessionLiveState: async () => {
+        const companyOperations = relay ? await relay.operations() : [];
+        const live = buildSessionLiveState({ gatewayInstanceRef, eventSequence: events.stateVersion,
+          operations: runtimes!.currentOperations(), settlements: events.recentOperationSettlements() });
+        return companyOperations.length ? { ...live, operations: [...live.operations, ...companyOperations] } : live;
+      },
+      readSessionCreationOptions: async () => {
+        if (!relay) return inspections.creationOptions();
+        // A folder with company conversations is a dashboard project too, so
+        // a new chat there (company or personal) can be started from here.
+        for (const folder of await relay.folders()) { try { projects.register(folder); } catch { /* moved or unreadable */ } }
+        const options = await inspections.creationOptions() as { models: unknown[] };
+        return { ...options, models: [...await relay.models(), ...options.models] };
+      },
+      relaySessionRead: relay ? async (sessionRef, path) => company(sessionRef)
+        ? await relay!.http("GET", `/api/v1/sessions/${encodeURIComponent(sessionRef)}/inspection${path}`) : null : undefined,
       readSessionModel: (sessionRef) => inspections.provider(sessionRef),
       readSessionConnections: (sessionRef) => inspections.connections(sessionRef),
-      executeSessionConnection: (command) => inspections.executeConnectionCommand(command),
-      executeRuntimeCommand: (command) => runtimeCommands.execute(command),
-      executeSessionAttachment: (sessionRef, command) => attachments.execute(sessionRef, command),
-      executeApproval: (approvalRef, decision) => runtimes!.decideApproval(approvalRef, decision),
+      executeSessionConnection: (command) => {
+        if (options.managed) throw new Error('connections-managed-by-studio');
+        return company((command as { sessionRef?: unknown } | null)?.sessionRef) ? relayPost("/api/v1/session-connections", command)
+          : inspections.executeConnectionCommand(command);
+      },
+      executeRuntimeCommand: (command) => company((command as { sessionRef?: unknown } | null)?.sessionRef)
+        ? relayPost("/api/v1/runtime-commands", command) : runtimeCommands.execute(command),
+      executeSessionAttachment: (sessionRef, command) => company(sessionRef)
+        ? relayPost(`/api/v1/sessions/${encodeURIComponent(sessionRef)}/attachments`, command) : attachments.execute(sessionRef, command),
+      // Approval refs carry no session; a company approval is not pending here.
+      executeApproval: async (approvalRef, decision) => {
+        try { return await runtimes!.decideApproval(approvalRef, decision); }
+        catch (error) {
+          if (!relay || (error as Error).message !== "approval-not-pending") throw error;
+          return await relayPost(`/api/v1/approvals/${encodeURIComponent(approvalRef)}/decision`, decision);
+        }
+      },
       readMcpAuthJob: (jobRef) => mcpAuth!.read(jobRef),
       cancelMcpAuthJob: (jobRef) => mcpAuth!.cancel(jobRef),
-      readProviderAuthCatalog: () => providerAuth.catalog(),
+      readProviderAuthCatalog: () => options.managed ? { ...providerAuth.catalog(), providers: [], reasonCode: 'personal-oauth-requires-personal-session' } : providerAuth.catalog(),
       readProviderAuthJob: (jobRef) => providerAuth.read(jobRef),
       executeProviderAuth: (command) => {
+        if (options.managed) throw new Error('personal-oauth-requires-personal-session');
         const action = command && typeof command === "object" && !Array.isArray(command) ? (command as Record<string, unknown>).action : null;
         if (action === "provider-auth.start") return providerAuth.start(command);
         if (action === "provider-auth.respond") return providerAuth.respond(command);
@@ -225,6 +303,7 @@ export async function startPiagentGateway(options: {
         events.publish("catalog.changed", { reasonCode: "project-imported" });
         return { schemaVersion: 1, version: "piagent-project-import-result-v1", importedAt: new Date().toISOString(), project, projects: registered };
       },
+      ...(relay ? { readCompanyStatus: () => relay!.status(), executeCompanyConnect: async () => { await relay!.connect(true); return relay!.status(); } } : {}),
       gatewayProtocol: protocol
     });
     descriptor = {
@@ -234,9 +313,11 @@ export async function startPiagentGateway(options: {
       startedAt: new Date().toISOString(),
       origin: loopback.origin,
       controlSocket: state.controlSocket,
-      profileRef: profileRef(state, key)
+      profileRef: profileRef(state, key),
+      packageVersion: packageVersion(options.packageRoot)
     };
     writeGatewayDescriptor(state, descriptor);
+    relay?.start();
   } catch (error) {
     await close();
     throw error;

package/packages/piagent-webui/gateway/gateway-session-stream.ts

@@ -3,6 +3,7 @@ import { randomBytes } from "node:crypto";
 import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
 import { hasVisibleText } from "../shared/text-visibility.ts";
 import type { TerminalDeliveryReceipt } from "../server/terminal-delivery-receipt.ts";
+import { effectiveStopReason } from "../server/message-stop-reason.ts";
 import { GatewayEventStore, type GatewayTaskStatus } from "./gateway-events.ts";
 import { SessionOperationLifecycle, type SessionOperationObservation,
   type SessionOperationPhase, type SessionOperationRetryPolicyOptions } from "./session-operation-lifecycle.ts";
@@ -103,7 +104,7 @@ function messageText(message: any): string {
     .map((item: any) => item.text).join("\n");
 }
 function assistantSettlement(message: any): Settlement {
-  const stopReason = String(message?.stopReason ?? "");
+  const stopReason = effectiveStopReason(message);
   if (stopReason === "aborted") return { outcome: "aborted", reasonCode: "operation-aborted" };
   if (stopReason === "error") return { outcome: "error", reasonCode: "assistant-response-failed" };
   if (stopReason === "length") return { outcome: "error", reasonCode: "assistant-output-incomplete" };
@@ -159,6 +160,8 @@ export class GatewaySessionStream {
   readonly #commitTerminalDeliveryReceipt: ((message: unknown) => TerminalDeliveryReceipt | undefined) | undefined;
   #terminalDeliveryMessage: unknown;
   #receiptOnly = true;
+  #compactionRef: string | null = null;
+  readonly #capacityRefs = new Map<string, string>();
 
   get runtimeRestartRequired(): boolean { return this.#runtimeRestartRequired; }
   get lifecycleTerminationReasonCode(): string | null { return this.#lifecycleTerminationReasonCode; }
@@ -204,7 +207,17 @@ export class GatewaySessionStream {
   }
 
   observe(event: any): SessionOperationObservation {
+    // A company subagent started or ended while the main agent was quiet: its
+    // count in the catalog row ("Subagent 1/2") changed, and no agent event says so.
+    if (event?.type === "managed_helpers") this.#events.publish("catalog.changed", { reasonCode: "managed-helpers-changed" });
     const wasStarted = this.#lifecycle.started, wasSettled = this.#lifecycle.hostSettled;
+    // Summarising the older part of a long conversation can take a minute,
+    // right before the model is asked or after it answered: shown as a step
+    // of the running turn, not as silence.
+    if (event?.type === "compaction_start" || event?.type === "compaction_end") this.#compaction(event);
+    // A company request waiting in line for a free model account: a step of
+    // the running turn until Studio admits it, it gives up or Stop ends it.
+    if (event?.type === "managed_capacity_wait") this.#capacityWait(event);
     const observation = this.#lifecycle.observe(event);
     if (!observation.accepted) return observation;
     if (event?.type === "agent_start" || event?.message?.role === "assistant" || event?.assistantMessageEvent
@@ -255,6 +268,38 @@ export class GatewaySessionStream {
     return observation;
   }
 
+  #compaction(event: any): void {
+    if (event.type === "compaction_start") {
+      if (this.#compactionRef) return;
+      this.#compactionRef = ref("tool");
+      this.#events.publish("tool.started", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(),
+        toolCallRef: this.#compactionRef, toolLabel: "compaction", fileLabel: null, isError: null, reasonCode: null });
+      return;
+    }
+    if (!this.#compactionRef) return;
+    const failed = typeof event.errorMessage === "string" && event.errorMessage.length > 0;
+    this.#events.publish("tool.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(),
+      toolCallRef: this.#compactionRef, toolLabel: "compaction", fileLabel: null, isError: failed, reasonCode: failed ? "compaction-failed" : null });
+    this.#compactionRef = null;
+  }
+
+  #capacityWait(event: any): void {
+    const id = typeof event.id === "string" ? event.id : null;
+    if (!id) return;
+    if (event.state === "start" && !this.#capacityRefs.has(id)) {
+      const toolCallRef = ref("tool"); this.#capacityRefs.set(id, toolCallRef);
+      this.#events.publish("tool.started", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(),
+        toolCallRef, toolLabel: "capacity-wait", fileLabel: null, isError: null, reasonCode: null });
+      return;
+    }
+    const toolCallRef = this.#capacityRefs.get(id);
+    if (event.state !== "end" || !toolCallRef) return;
+    this.#capacityRefs.delete(id);
+    const failed = event.outcome === "gave-up";
+    this.#events.publish("tool.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(),
+      toolCallRef, toolLabel: "capacity-wait", fileLabel: null, isError: failed, reasonCode: failed ? "capacity-wait-expired" : null });
+  }
+
   #settleActiveTools(reasonCode: string): void {
     for (const [toolCallId, toolCallRef] of this.#toolRefs) {
       this.#events.publish("tool.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(), toolCallRef,
@@ -262,6 +307,11 @@ export class GatewaySessionStream {
         isError: true, reasonCode });
     }
     this.#toolRefs.clear(); this.#toolLabels.clear(); this.#toolFileLabels.clear();
+    for (const toolCallRef of this.#capacityRefs.values()) {
+      this.#events.publish("tool.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(), toolCallRef,
+        toolLabel: "capacity-wait", fileLabel: null, isError: false, reasonCode: null });
+    }
+    this.#capacityRefs.clear();
   }
 
   #flush(final: boolean): void {
@@ -270,7 +320,13 @@ export class GatewaySessionStream {
       return;
     }
     let take = final ? this.#buffer.length : this.#buffer.lastIndexOf("\n") + 1;
-    if (take <= 0 && this.#buffer.length >= 1_024) take = this.#buffer.length;
+    // A long line goes out in pieces cut after a space. Credentials hold no
+    // space, so one still arriving is never sent half-formed (redaction knows
+    // a token only by its whole shape); a blob without any space is sent at 16 KiB.
+    if (take <= 0 && this.#buffer.length >= 1_024) {
+      const space = this.#buffer.search(/\s\S*$/);
+      take = space >= 0 ? space + 1 : this.#buffer.length >= 16_384 ? this.#buffer.length : 0;
+    }
     if (take <= 0) return;
     const candidate = this.#buffer.slice(0, take), privateStart = candidate.search(PRIVATE_BEGIN);
     if (privateStart >= 0 && !PRIVATE_END.test(candidate.slice(privateStart))) {

package/packages/piagent-webui/gateway/managed-gateway.mjs

@@ -0,0 +1,41 @@
+import { managedThinkingLevels } from '../../piagent-core/managed/capabilities.mjs';
+import { ManagedBrokerClient } from '../../piagent-core/managed/broker-client.mjs';
+import { ManagedSession } from '../../piagent-core/managed/session.mjs';
+import fs from 'node:fs';
+
+// Only called by the pinned launcher with Watch's non-secret import manifest.
+// Each web session owns its own broker; no personal auth/model/resource loader.
+export async function startManagedGateway({ config, configPath, cwd, agentDir, packageRoot, registerProject = true }) {
+  // Agent Watch may hold another key of this member since the Gateway
+  // started: a new conversation, or one that enrolls again, uses that key.
+  const slot=()=>{try{const now=JSON.parse(fs.readFileSync(configPath,'utf8'));return /^[a-f0-9]{64}$/.test(now.profile_id)&&now.broker===config.broker?now.profile_id:config.profile_id;}catch{return config.profile_id;}};
+  const newBroker=()=>new ManagedBrokerClient({executable:config.broker,profileID:slot()});
+  // Agent Watch rewrites the binding's revision when the key or its harness
+  // changes; a warm conversation then enrolls again before its next run.
+  const bindingRevision=()=>{try{return String(JSON.parse(fs.readFileSync(configPath,'utf8')).configuration_revision??'')||null;}catch{return null;}};
+  const probeBroker = newBroker();
+  let probe;
+  try {
+    probe = await ManagedSession.create({sdkRoot:config.sdk_root,cwd,origin:config.origin,broker:probeBroker,agentDir,protectedRoots:[configPath,agentDir]});
+    const { startPiagentGateway } = await import('./gateway-service.ts');
+    const { rpcUiContext } = await import('./rpc-ui-context.ts');
+    const { webUiModelRef } = await import('../../piagent-core/runtime/inspection/webui-snapshot.ts');
+    const host=probe.api,models=probe.modelRuntime;
+    const snapshot=models.getAvailableSnapshot.bind(models);
+    models.getAvailableSnapshot=()=>snapshot().map(model=>({...model,managedThinkingLevels:managedThinkingLevels(probe.manifest,models,model)}));
+    const factory=async(info,_instance,manager,initial)=>{
+      if(initial?.modelRef && initial.modelRef!==webUiModelRef('agent_watch_managed','agent-watch-auto')) throw Error('managed-personal-switch-requires-new-session');
+      const broker=newBroker();
+      let runtime;
+      try {
+        runtime=await ManagedSession.create({sdkRoot:config.sdk_root,cwd:info.cwd,origin:config.origin,broker,agentDir,
+          sessionManager:manager??host.SessionManager.open(info.path),protectedRoots:[configPath,agentDir],renewBroker:newBroker,bindingRevision});
+        if(initial) runtime.session.setThinkingLevel(initial.thinkingLevel);
+        await runtime.session.bindExtensions({mode:'rpc',uiContext:rpcUiContext()});
+        return {session:runtime.session,dispose:()=>runtime.dispose()};
+      } catch(error) { if(runtime) await runtime.dispose(); else await broker.dispose(); throw error; }
+    };
+    const gateway=await startPiagentGateway({packageRoot,agentDir,expectedPiVersion:'0.87.1',managed:{host,models,runtimeFactory:factory,project:registerProject?cwd:null}});
+    return gateway;
+  } finally { if(probe) await probe.dispose(); else await probeBroker.dispose(); }
+}

package/packages/piagent-webui/gateway/managed-launch.ts

@@ -0,0 +1,145 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { requestGatewayControl } from "./control-socket.ts";
+import { gatewayProfileState } from "./profile-state.ts";
+import { storedSlot } from "../../piagent-core/managed/store.mjs";
+
+// The personal dashboard shows company sessions but never runs them: it starts
+// the pinned managed entrypoint (its own process and Gateway, `--serve`) the
+// way Agent Watch's launcher does, then relays to it. Grants stay inside that
+// process; this process only reads the public binding.
+export type ManagedLaunchStatus = { schemaVersion: 1; version: "piagent-managed-launch-status-v1"; available: boolean; model: "agent-watch-auto" };
+type Binding = { file: string; profile: string; node: string; entrypoint: string; broker: string; brokerSha256: string };
+
+const CLEAN_ENV = { PATH: "/usr/bin:/bin", LANG: "en_US.UTF-8", TERM: "xterm-256color" };
+const READY = /^Agent Watch Auto: ready$/m;
+const sha256 = (file: string) => createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+const HEX64 = /^[a-f0-9]{64}$/;
+
+const DEFAULT_AGENT_DIR = path.join(os.homedir(), ".pi", "agent");
+
+// The relay and the company Gateway speak one protocol, so they must be the
+// same Piagent release: Agent Watch may still point at another install (nvm,
+// Homebrew…) and a company Gateway started before an update keeps running.
+const versionAt = (file: string): string | null => { try { return String(JSON.parse(fs.readFileSync(file, "utf8")).version); } catch { return null; } };
+const OWN_VERSION = versionAt(fileURLToPath(new URL("../../../package.json", import.meta.url)));
+const sameRelease = (pinned: Binding) => OWN_VERSION === null || versionAt(path.join(path.dirname(path.dirname(pinned.entrypoint)), "package.json")) === OWN_VERSION;
+const current = (health: { packageVersion?: unknown }) => OWN_VERSION === null || health.packageVersion === OWN_VERSION;
+
+// Agent Watch writes the binding into the personal Pi folder it imported into.
+function binding(agentDir: string): Binding | null {
+  const file = path.join(agentDir, "agent-watch-managed.json");
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.size > 16_384) return null;
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    const absolute = (entry: unknown) => typeof entry === "string" && path.isAbsolute(entry);
+    if (value?.schema_version !== 1 || value.model !== "agent-watch-auto" || !HEX64.test(String(value.profile_id))
+      || !absolute(value.node) || !absolute(value.entrypoint) || !absolute(value.broker) || !HEX64.test(String(value.broker_sha256))) return null;
+    return { file, profile: value.profile_id, node: value.node, entrypoint: value.entrypoint, broker: value.broker, brokerSha256: value.broker_sha256 };
+  } catch { return null; }
+}
+
+export function managedLaunchStatus(agentDir = DEFAULT_AGENT_DIR): ManagedLaunchStatus {
+  return { schemaVersion: 1, version: "piagent-managed-launch-status-v1", available: binding(agentDir) !== null, model: "agent-watch-auto" };
+}
+
+// A key's slot points at its member's conversation store once it has been
+// launched (store.mjs); until then the slot's own folder is asked.
+function controlSocket(home: string, profile: string): string {
+  const root = path.join(home, "Library/Application Support/AgentWatch/ManagedSessions");
+  return gatewayProfileState(path.join(root, storedSlot(root, profile) ?? profile)).controlSocket;
+}
+
+// "busy": the Gateway took the connection but has not answered yet. It is
+// alive; starting another beside it would leave two on the same store.
+async function running(socket: string): Promise<{ packageVersion?: unknown } | "busy" | null> {
+  try {
+    const reply = await requestGatewayControl(socket, { action: "health" });
+    return reply.ok ? (reply.value && typeof reply.value === "object" ? reply.value : {}) : null;
+  } catch (error) { return error instanceof Error && error.message === "gateway-control-timeout" ? "busy" : null; }
+}
+
+// Same foreground step as Agent Watch: macOS may ask once to let this build of
+// the broker read its Keychain item. Nothing secret comes back. Exit 67 means
+// the imported key is no longer connected in Agent Watch.
+async function authorize(pinned: Binding): Promise<void> {
+  if (fs.realpathSync(pinned.broker) !== pinned.broker || sha256(pinned.broker) !== pinned.brokerSha256) throw new Error("managed-launch-binding-changed");
+  const code = await new Promise<number | null>((resolve) => {
+    const child = spawn(pinned.broker, ["managed-authorize", "--profile", pinned.profile], { cwd: "/", stdio: "ignore", env: CLEAN_ENV, timeout: 180_000, killSignal: "SIGKILL" });
+    child.once("error", () => resolve(null));
+    child.once("exit", (exit) => resolve(exit));
+  });
+  if (code === 67) throw new Error("managed-profile-disconnected");
+  if (code !== 0) throw new Error("managed-keychain-approval-required");
+}
+
+// The control socket of a running company Gateway, without launching one.
+export async function attachCompanyGateway(agentDir = DEFAULT_AGENT_DIR, home = os.homedir()): Promise<string | null> {
+  const pinned = binding(agentDir);
+  if (!pinned || !sameRelease(pinned)) return null;
+  const socket = controlSocket(home, pinned.profile);
+  const health = await running(socket);
+  return health && health !== "busy" && current(health) ? socket : null;
+}
+
+let inFlight: Promise<string> | null = null;
+
+// Returns the company Gateway's control socket, starting it when needed.
+export function ensureCompanyGateway(agentDir = DEFAULT_AGENT_DIR, home = os.homedir(), timeoutMs = 45_000): Promise<string> {
+  inFlight ??= start(agentDir, home, timeoutMs).finally(() => { inFlight = null; });
+  return inFlight;
+}
+
+async function start(agentDir: string, home: string, timeoutMs: number): Promise<string> {
+  const pinned = binding(agentDir);
+  if (!pinned) throw new Error("managed-config-missing");
+  if (!sameRelease(pinned)) throw new Error("managed-launch-version-mismatch");
+  const socket = controlSocket(home, pinned.profile);
+  let health = await running(socket);
+  for (const started = Date.now(); health === "busy"; health = await running(socket)) {
+    if (Date.now() - started > timeoutMs) throw new Error("managed-launch-busy");
+  }
+  if (health && current(health)) return socket;
+  if (health) {
+    // A company Gateway from before the update: stop it (its transcripts stay
+    // on disk) and start this release.
+    try { await requestGatewayControl(socket, { action: "stop" }); } catch { /* already stopping */ }
+    for (const started = Date.now(); await running(socket);) {
+      if (Date.now() - started > 15_000) throw new Error("managed-launch-stale-runtime");
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+  }
+  await authorize(pinned);
+  // Startup failures are reported on stderr as `Agent Watch: managed-…`; the
+  // log is private and removed once the process is ready or has exited.
+  const directory = path.join(home, "Library/Application Support/AgentWatch/ManagedLaunch");
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 }); fs.chmodSync(directory, 0o700);
+  const log = path.join(directory, `launch-${process.pid}-${Date.now()}.log`);
+  const fd = fs.openSync(log, "wx", 0o600);
+  let exited = false;
+  try {
+    const child = spawn(pinned.node, [pinned.entrypoint, "--config", pinned.file, "--serve"],
+      { cwd: "/", detached: true, stdio: ["ignore", fd, fd], env: CLEAN_ENV });
+    child.once("exit", () => { exited = true; }); child.once("error", () => { exited = true; }); child.unref();
+  } finally { fs.closeSync(fd); }
+  try {
+    for (const started = Date.now(); Date.now() - started < timeoutMs;) {
+      const text = fs.readFileSync(log, "utf8");
+      // The launch may just have pointed this slot at the member's store.
+      if (READY.test(text)) return controlSocket(home, pinned.profile);
+      if (exited) throw new Error(text.match(/Agent Watch: (managed-[a-z:_-]+)\./)?.[1] ?? "managed-launch-failed");
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    throw new Error("managed-launch-timeout");
+  } finally { fs.rmSync(log, { force: true }); }
+}
+
+// The personal dashboard's connector for company sessions (CompanyRelay).
+export function agentWatchCompanyConnector(agentDir = DEFAULT_AGENT_DIR, home = os.homedir()) {
+  return { configured: () => binding(agentDir) !== null, ensure: () => ensureCompanyGateway(agentDir, home), attach: () => attachCompanyGateway(agentDir, home) };
+}

package/packages/piagent-webui/gateway/managed-projection.ts

@@ -0,0 +1,20 @@
+// Public managed state contains no provider/model route or credential.
+const STATUS = ['pending', 'in_progress', 'completed'];
+const OUTCOMES = ['no_change', 'interrupted', 'blocking_open', 'unverified', 'review_unavailable', 'unreviewed', 'clean'];
+export function managedProjection(context: any, entries: any[]) {
+  if (context?.model?.provider !== 'agent_watch_managed') return {};
+  const last = (type: string) => entries.filter(e => e.type === 'custom' && e.customType === type).at(-1)?.data;
+  const counter = last('agent-watch-helpers');
+  const capabilities = last('agent-watch-model')?.managedThinkingLevels;
+  const levels = ['off','minimal','low','medium','high','xhigh','max'];
+  // The agent's checklist (update_plan) and how its last code-changing turn ended.
+  const plan = last('agent-watch-plan')?.plan;
+  const steps = Array.isArray(plan) && plan.length >= 1 && plan.length <= 30 && plan.every((p: any) => typeof p?.step === 'string' && p.step.trim() && STATUS.includes(p.status))
+    ? plan.map((p: any) => ({ step: p.step.trim().slice(0, 200), status: p.status })) : null;
+  const final = entries.filter(e => e.type === 'custom_message' && e.customType === 'agent-watch-process' && e.details?.phase === 'final').at(-1)?.details;
+  const process = final && OUTCOMES.includes(final.outcome) ? { outcome: final.outcome, verified: final.verified === true, reviewed: final.reviewed === true,
+    blockingOpen: Number.isInteger(final.blockingOpen) && final.blockingOpen >= 0 ? Math.min(final.blockingOpen, 1000) : 0, ...(final.planSkipped === true ? { planSkipped: true as const } : {}) } : null;
+  return {modelLabel:'agent-watch-auto', managedHelpers:{active:Number.isInteger(counter?.active) && counter.active>=0 && counter.active<=2 ? counter.active : 0, maximum:2 as const},
+    ...(Array.isArray(capabilities)?{managedThinkingLevels:levels.filter(level=>capabilities.includes(level))}:{}),
+    ...(steps ? {managedPlan:{steps}} : {}), ...(process ? {managedProcess:process} : {})};
+}

package/packages/piagent-webui/gateway/pi-host.ts

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
@@ -27,10 +28,27 @@ export function installedPiHostRoot(): string {
   } catch {
     // The operator installation is normally global.
   }
-  const executable = execFileSync("which", ["pi"], { encoding: "utf8", timeout: 2_000 }).trim();
-  const found = packageRootFrom(fs.realpathSync(executable));
-  if (!found) throw new Error("pi-host-unavailable");
-  return found;
+  try {
+    const executable = execFileSync("which", ["pi"], { encoding: "utf8", timeout: 2_000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+    const found = packageRootFrom(fs.realpathSync(executable));
+    if (found) return found;
+  } catch {
+    // A launcher with a short PATH (Agent Watch, launchd) cannot see `pi`.
+  }
+  // Then the host the installed CLI recorded, and the usual global prefixes.
+  const home = os.homedir(), hostPackage = path.join("lib", "node_modules", "@earendil-works", "pi-coding-agent");
+  let recorded: string | null = null;
+  try {
+    const agentDir = process.env.PI_CODING_AGENT_DIR || path.join(home, ".pi", "agent");
+    recorded = JSON.parse(fs.readFileSync(path.join(agentDir, "piagent-runtime.json"), "utf8")).pi_sdk_root ?? null;
+  } catch { /* no record yet */ }
+  for (const candidate of [recorded, path.join(home, ".pi", "npm-global", hostPackage), path.join(home, ".local", hostPackage),
+    path.join("/opt/homebrew", hostPackage), path.join("/usr/local", hostPackage)]) {
+    if (!candidate) continue;
+    const found = packageRootFrom(path.join(candidate, "package.json"));
+    if (found) return found;
+  }
+  throw new Error("pi-host-unavailable");
 }
 
 export async function loadPinnedPiHost(expectedVersion: string): Promise<any> {