feat: add authenticated voice pipeline API docs

src/server/sessions/piSessionService.messages.test.ts

@@ -65,6 +65,21 @@ describe("PiSessionService", () => {
       await service.dispose();
     });
 
+    it("forwards Pi's native agent_settled event without inferring it from agent_end", async () => {
+      const { fake, service, events } = messagesService([]);
+      await service.status(sessionRef("session-1"));
+
+      fake.emit({ type: "agent_end" });
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      expect(events.sessionEvents.map(({ event }) => event).filter((event) => event.type === "agent.settled")).toEqual([]);
+
+      fake.emit({ type: "agent_settled" });
+      expect(events.sessionEvents.map(({ event }) => event).filter((event) => event.type === "agent.settled")).toEqual([
+        { type: "agent.settled" },
+      ]);
+      await service.dispose();
+    });
+
     it("annotates the join-time stream snapshot partial with the current thinking level", async () => {
       const streamingMessage = {
         role: "assistant",

src/server/sessions/piSessionService.ts

@@ -3224,6 +3224,9 @@ export class PiSessionService implements SessionRouteService {
       this.publishActivityForEvent(session, event);
       const eventType = getString(event, "type");
       if (eventType === "agent_end") this.abortRunScopedExtensionDialogs(session.sessionId);
+      // Pi itself emits agent_settled only after automatic retries, compaction,
+      // and queued continuations are exhausted. Preserve that native lifecycle
+      // event; never infer it from agent_end or mutable runtime flags.
       if (eventType === "compaction_end") this.scheduleCompactionQueueDrain(session.sessionId);
       if (eventType === "agent_start" || eventType === "agent_end") this.scheduleCompactionQueueDrain(session.sessionId);
       this.publishStatus(session);
@@ -4209,6 +4212,7 @@ function toClientEvent(event: unknown, thinkingLevel?: string): SessionUiEvent {
   }
   if (eventType === "agent_start") return { type: "agent.start" };
   if (eventType === "agent_end") return { type: "agent.end" };
+  if (eventType === "agent_settled") return { type: "agent.settled" };
   if (eventType === "message_end") {
     const message = getProperty(event, "message");
     if (message === undefined) return { type: "message.end" };