docs: clarify Pi-compatible agent profiles

src/shared/apiTypes.ts

@@ -6,6 +6,7 @@ export const PI_WEB_CAPABILITIES = {
   sessionsBulkMutations: "sessions.bulkMutations",
   sessionsCleanup: "sessions.cleanup",
   sessionsReload: "sessions.reload",
+  sessionsClearQueue: "sessions.clearQueue",
   sessionsPersistedState: "sessions.persistedState",
   promptAttachments: "prompt.attachments",
   workspaceFileSuggestions: "workspace.fileSuggestions",
@@ -67,9 +68,9 @@ export interface PiWebUploadsConfig {
 }
 
 export interface PiWebAgentConfig {
-  /** Agent CLI command used for diagnostics and package-managed updates. */
+  /** Pi-compatible companion CLI used for diagnostics and safe package-managed updates. */
   command?: string;
-  /** Agent config/state directory containing auth.json, models.json, settings.json, and sessions/. */
+  /** Pi-compatible profile directory containing auth.json, models.json, settings.json, and sessions/. */
   dir?: string;
 }
 
@@ -94,7 +95,7 @@ export interface PiWebConfigValues {
    * while the capability stabilizes. Requires spawnSessions to be enabled.
    */
   subsessions?: boolean;
-  /** Agent runtime command/state used by PI WEB and the session daemon (Pi by default). */
+  /** Desired Pi-compatible agent profile and companion CLI (Pi by default). */
   agent?: PiWebAgentConfig;
 }
 

src/shared/capabilities.test.ts

@@ -30,6 +30,26 @@ describe("PI WEB capabilities", () => {
     })).toContain(PI_WEB_CAPABILITIES.sessionsPersistedState);
   });
 
+  it("requires web and session daemon support for server-side queue clearing", () => {
+    const clearQueue = PI_WEB_CAPABILITIES.sessionsClearQueue;
+    expect(WEB_RUNTIME_CAPABILITIES).toContain(clearQueue);
+    expect(SESSIOND_RUNTIME_CAPABILITIES).toContain(clearQueue);
+    expect(parseKnownPiWebCapabilities([clearQueue, "future.capability"])).toEqual([clearQueue]);
+
+    expect(effectivePiWebCapabilities({
+      web: { available: true, capabilities: [clearQueue] },
+      sessiond: { available: true, capabilities: [] },
+    })).not.toContain(clearQueue);
+    expect(effectivePiWebCapabilities({
+      web: { available: true, capabilities: [] },
+      sessiond: { available: true, capabilities: [clearQueue] },
+    })).not.toContain(clearQueue);
+    expect(effectivePiWebCapabilities({
+      web: { available: true, capabilities: [clearQueue] },
+      sessiond: { available: true, capabilities: [clearQueue] },
+    })).toContain(clearQueue);
+  });
+
   it("keeps only known string capabilities when parsing runtime data", () => {
     expect(parseKnownPiWebCapabilities([PI_WEB_CAPABILITIES.piPackagesManage, PI_WEB_CAPABILITIES.selectedMachineSettings, "future.capability"])).toEqual([PI_WEB_CAPABILITIES.piPackagesManage, PI_WEB_CAPABILITIES.selectedMachineSettings]);
     expect(parseKnownPiWebCapabilities([PI_WEB_CAPABILITIES.piPackagesManage, 1])).toBeUndefined();

src/shared/capabilities.ts

@@ -11,6 +11,7 @@ export const WEB_RUNTIME_CAPABILITIES = [
   PI_WEB_CAPABILITIES.sessionsBulkMutations,
   PI_WEB_CAPABILITIES.sessionsCleanup,
   PI_WEB_CAPABILITIES.sessionsReload,
+  PI_WEB_CAPABILITIES.sessionsClearQueue,
   PI_WEB_CAPABILITIES.sessionsPersistedState,
   PI_WEB_CAPABILITIES.promptAttachments,
   PI_WEB_CAPABILITIES.workspaceFileSuggestions,
@@ -24,6 +25,7 @@ export const SESSIOND_RUNTIME_CAPABILITIES = [
   PI_WEB_CAPABILITIES.sessionsBulkMutations,
   PI_WEB_CAPABILITIES.sessionsCleanup,
   PI_WEB_CAPABILITIES.sessionsReload,
+  PI_WEB_CAPABILITIES.sessionsClearQueue,
   PI_WEB_CAPABILITIES.sessionsPersistedState,
   PI_WEB_CAPABILITIES.promptAttachments,
 ] as const satisfies readonly PiWebCapability[];
@@ -33,6 +35,7 @@ const EFFECTIVE_CAPABILITY_REQUIREMENTS = {
   [PI_WEB_CAPABILITIES.sessionsBulkMutations]: ["web", "sessiond"],
   [PI_WEB_CAPABILITIES.sessionsCleanup]: ["web", "sessiond"],
   [PI_WEB_CAPABILITIES.sessionsReload]: ["web", "sessiond"],
+  [PI_WEB_CAPABILITIES.sessionsClearQueue]: ["web", "sessiond"],
   [PI_WEB_CAPABILITIES.sessionsPersistedState]: ["web", "sessiond"],
   [PI_WEB_CAPABILITIES.promptAttachments]: ["web", "sessiond"],
   [PI_WEB_CAPABILITIES.workspaceFileSuggestions]: ["web"],

src/shared/federatedRoutes.ts

@@ -59,6 +59,7 @@ export const FEDERATED_HTTP_ROUTES = [
   { method: "POST", path: "/sessions/:sessionId/thinking-level/cycle" },
   { method: "GET", path: "/sessions/:sessionId/commands" },
   { method: "POST", path: "/sessions/:sessionId/prompt" },
+  { method: "POST", path: "/sessions/:sessionId/queue/clear" },
   { method: "POST", path: "/sessions/:sessionId/attachments" },
   { method: "POST", path: "/sessions/:sessionId/shell" },
   { method: "POST", path: "/sessions/:sessionId/commands/run" },