@piagent/platform 1.9.3 → 1.10.0

package/packages/piagent-webui/dist/client/index.html

@@ -7,8 +7,8 @@
     <meta name="csp-nonce" content="__PIAGENT_CSP_NONCE__" />
     <meta name="piagent-webui-mode" content="__PIAGENT_WEBUI_MODE__" />
     <title>Piagent WebUI</title>
-    <script type="module" crossorigin src="/assets/index-Cv5u0MN8.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-DgSmcnP8.css">
+    <script type="module" crossorigin src="/assets/index-yg9s8sA_.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-Z91z6SlN.css">
   </head>
   <body>
     <div id="root"></div>

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

@@ -276,6 +276,13 @@ export async function startPiagentGateway(options: {
         ? 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),
+      // The main agent's questions to the member, read and answered where the
+      // conversation runs (the company Gateway for a company conversation).
+      readSessionQuestions: (sessionRef) => company(sessionRef)
+        ? relay!.json("GET", `/api/v1/sessions/${encodeURIComponent(sessionRef)}/questions`) : runtimes!.questions(sessionRef),
+      answerSessionQuestion: (sessionRef, questionRef, answer) => company(sessionRef)
+        ? relayPost(`/api/v1/sessions/${encodeURIComponent(sessionRef)}/questions/${encodeURIComponent(questionRef)}/answer`, answer)
+        : runtimes!.answerQuestion(sessionRef, questionRef, answer),
       // Approval refs carry no session; a company approval is not pending here.
       executeApproval: async (approvalRef, decision) => {
         try { return await runtimes!.decideApproval(approvalRef, decision); }

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

@@ -1,6 +1,6 @@
 // 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'];
+const OUTCOMES = ['no_change', 'interrupted', 'disputed', '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;

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

@@ -0,0 +1,15 @@
+import { memberQuestions } from "../../piagent-core/managed/member-questions.mjs";
+
+// The main agent's questions to the member of a conversation this Gateway
+// runs: the conversation's runtime is where they are answered, and a question
+// waiting for its answer keeps the running turn alive (`progress`).
+export function bindSessionQuestions(sessionId: string, progress: () => void): () => void {
+  return memberQuestions.bindSurface(sessionId, progress);
+}
+export function sessionQuestions(sessionId: string | null): { questions: ReturnType<typeof memberQuestions.pending> } {
+  return { questions: sessionId ? memberQuestions.pending(sessionId) : [] };
+}
+export function answerSessionQuestion(sessionId: string | null, questionRef: string, answer: unknown): unknown {
+  if (!sessionId) throw new Error("question-not-pending");
+  return memberQuestions.answer(sessionId, questionRef, answer);
+}

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

@@ -6,6 +6,7 @@ import { activeSessionTask } from "../../piagent-core/extensions/task-state.js";
 import { createSessionOperationSettlement } from "./session-operation-settlement.ts";
 import { inspectTaskControlState } from "../../piagent-core/runtime/inspection/task-control-journal.ts";
 import { piApprovalBroker, type ApprovalBrokerEvent } from "../../piagent-core/runtime/inspection/approval-broker.ts";
+import { answerSessionQuestion, bindSessionQuestions, sessionQuestions } from "./session-questions.ts";
 import { isUserConversationSession, projectRefForCwd, sessionRefForPath, type SessionOwnerProjection, type PiSessionInfo } from "./session-catalog.ts";
 import { SessionLeaseStore, type SessionLeaseSnapshot } from "./session-lease-store.ts";
 import { GatewayEventStore } from "./gateway-events.ts";
@@ -311,8 +312,10 @@ export class SessionRuntimeSupervisor {
   }
   #bindApproval(sessionRef: string, active: ActiveRuntime): void {
     const authority = () => sessionApprovalAuthority(this.#key, sessionRef, active);
-    active.unbindApproval = piApprovalBroker.bind({ cwd: active.info.cwd, rawSessionId: active.info.id,
-      runtimeInstanceId: active.lease.runtimeInstanceRef!, authority });
+    // The main agent's questions to the member are answered here too (session-questions.ts).
+    const unbindQuestions = bindSessionQuestions(active.info.id, () => active.watchdog?.progress()), unbindApproval = piApprovalBroker.bind({
+      cwd: active.info.cwd, rawSessionId: active.info.id, runtimeInstanceId: active.lease.runtimeInstanceRef!, authority });
+    active.unbindApproval = () => { unbindQuestions(); unbindApproval(); };
     active.unsubscribeApproval = piApprovalBroker.subscribe(active.info.cwd, active.info.id, (event: ApprovalBrokerEvent) => {
       active.watchdog?.progress();
       const projection = piApprovalBroker.projection(active.info.cwd, active.info.id);
@@ -388,6 +391,8 @@ export class SessionRuntimeSupervisor {
     const active = this.#active.get(sessionRef);
     return active ? piApprovalBroker.detail(active.info.cwd, active.info.id, approvalRef) : null;
   }
+  questions(sessionRef: string) { return sessionQuestions(this.#active.get(sessionRef)?.info.id ?? null); }
+  answerQuestion(sessionRef: string, questionRef: string, answer: unknown): unknown { return answerSessionQuestion(this.#active.get(sessionRef)?.info.id ?? null, questionRef, answer); }
   async decideApproval(approvalRef: string, decision: unknown): Promise<unknown> {
     for (const active of this.#active.values()) {
       if (piApprovalBroker.detail(active.info.cwd, active.info.id, approvalRef)) {

package/packages/piagent-webui/server/loopback-server.ts

@@ -81,6 +81,8 @@ export async function startLoopbackServer(options: {
   executeControl?: (command: unknown) => unknown | Promise<unknown>;
   executeAttachment?: (command: unknown) => unknown | Promise<unknown>;
   executeApproval?: (approvalRef: string, decision: unknown) => unknown | Promise<unknown>;
+  readSessionQuestions?: (sessionRef: string) => unknown | Promise<unknown>;
+  answerSessionQuestion?: (sessionRef: string, questionRef: string, answer: unknown) => unknown | Promise<unknown>;
   bootstrapTtlMs?: number;
   sessionTtlMs?: number;
 }): Promise<LoopbackServer> {
@@ -302,6 +304,33 @@ export async function startLoopbackServer(options: {
       catch { return errorResponse(response, 503, "attachment-runtime-unavailable"); }
     }
 
+    // The main agent's questions to the member of a conversation, and the answer.
+    const questionPath = /^\/api\/v1\/sessions\/([^/]+)\/questions(?:\/([^/]+)\/answer)?$/.exec(url.pathname);
+    if (request.method === "GET" && questionPath && !questionPath[2] && options.readSessionQuestions) {
+      if (!auth.authenticate(request)) return errorResponse(response, 401, "authentication-required");
+      const sessionRef = decodeURIComponent(questionPath[1]);
+      if (!CURSOR.test(sessionRef)) return errorResponse(response, 400, "invalid-session-ref");
+      try { return jsonResponse(response, 200, await options.readSessionQuestions(sessionRef)); }
+      catch { return errorResponse(response, 503, "questions-unavailable"); }
+    }
+    if (request.method === "POST" && questionPath && questionPath[2] && options.answerSessionQuestion) {
+      if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
+      const mutationSession = auth.authorizeMutation(request);
+      if (!mutationSession) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!consumeControl(mutationSession.id, now)) return errorResponse(response, 429, "control-rate-limit");
+      if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
+      const sessionRef = decodeURIComponent(questionPath[1]), questionRef = decodeURIComponent(questionPath[2]);
+      if (!CURSOR.test(sessionRef) || !/^question\.[0-9a-f-]{36}$/.test(questionRef)) return errorResponse(response, 400, "invalid-question-ref");
+      let answer: unknown;
+      try { answer = JSON.parse((await requestBody(request, MAX_CONTROL_BODY_BYTES)).toString("utf8")); }
+      catch (error) { return errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-question-answer"); }
+      try { return jsonResponse(response, 200, await options.answerSessionQuestion(sessionRef, questionRef, answer)); }
+      catch (error) {
+        const code = error instanceof Error ? error.message : "questions-unavailable";
+        return errorResponse(response, code === "question-not-pending" ? 409 : code === "question-answer-invalid" ? 400 : 503, code);
+      }
+    }
+
     if (request.method === "POST" && url.pathname.startsWith("/api/v1/approvals/") && url.pathname.endsWith("/decision") && options.executeApproval) {
       if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
       const mutationSession = auth.authorizeMutation(request);

package/packages/piagent-webui/server/transcript-projection.ts

@@ -35,8 +35,10 @@ type TranscriptItem = { messageRef: string; parentMessageRef: string | null; rol
   toolCalls: Array<{ toolCallRef: string; toolName: string; state: "requested" | "completed" | "failed" | "unknown";
     summary?: ToolSummary; change?: ToolChange; result?: ToolResult }>; usage?: TurnUsage; model?: string; process?: HarnessProcess };
 type HarnessFinding = { severity: "blocking" | "major" | "minor"; file: string; line: number | null; issue: string };
-type HarnessProcess = { phase: "plan" | "verify" | "review" | "final"; outcome?: string; loop?: number; maxLoops?: number; verified?: boolean; reviewed?: boolean;
-  blockingOpen?: number; planOpen?: number; planSkipped?: true; verifyPolicy?: string; reviewPolicy?: string; reviewUnavailable?: string; findings?: HarnessFinding[] };
+type HarnessIssue = { kind: "wrong_premise" | "conflicts_with_request" | "ambiguous" | "out_of_scope"; detail: string };
+type HarnessProcess = { phase: "plan" | "verify" | "review" | "final" | "objection" | "answer" | "claims" | "rejudge" | "dispute"; outcome?: string; loop?: number; maxLoops?: number;
+  verified?: boolean; reviewed?: boolean; blockingOpen?: number; planOpen?: number; planSkipped?: true; verifyPolicy?: string; reviewPolicy?: string; reviewUnavailable?: string;
+  findings?: HarnessFinding[]; role?: "scout" | "research" | "verify" | "review"; by?: "main" | "harness"; disputes?: number; unchanged?: true; issues?: HarnessIssue[]; claims?: { claim: string }[] };
 export type TranscriptDocument = { schemaVersion: 1; version: "piagent-webui-transcript-v1"; generatedAt: string; identity: TranscriptIdentity;
   revision: TranscriptRevision; eventCursor: string; state: "ready" | "unavailable"; items: TranscriptItem[];
   page: { beforeCursor: string | null; nextBeforeCursor: string | null; hasOlder: boolean; limit: number; truncated: boolean }; reasonCode: string | null };
@@ -163,10 +165,13 @@ function toolCalls(message: any, sessionRef: string, role: TranscriptItem["role"
 }
 // The harness's process notes ("agent-watch-process"): what it asked of the
 // agent before a code-changing turn ended, and how that turn ended.
-const PROCESS_OUTCOMES = ["no_change", "interrupted", "blocking_open", "unverified", "review_unavailable", "unreviewed", "clean"];
+const PROCESS_OUTCOMES = ["no_change", "interrupted", "disputed", "blocking_open", "unverified", "review_unavailable", "unreviewed", "clean"];
+// A helper's objection to its brief, a failed claim, a disagreement handed to the member.
+const PROCESS_PHASES = ["plan", "verify", "review", "final", "objection", "answer", "claims", "rejudge", "dispute"];
+const ISSUE_KINDS = ["wrong_premise", "conflicts_with_request", "ambiguous", "out_of_scope"], HELPER_ROLES = ["scout", "research", "verify", "review"];
 const POLICY_MODES = ["off", "suggest", "require"];
 function harnessProcess(details: any): HarnessProcess | null {
-  if (!["plan", "verify", "review", "final"].includes(details?.phase)) return null;
+  if (!PROCESS_PHASES.includes(details?.phase)) return null;
   const loop = (n: unknown): n is number => Number.isInteger(n) && (n as number) >= 0 && (n as number) <= 3;
   const out: HarnessProcess = { phase: details.phase };
   if (PROCESS_OUTCOMES.includes(details.outcome)) out.outcome = details.outcome;
@@ -184,6 +189,14 @@ function harnessProcess(details: any): HarnessProcess | null {
     .filter((f: any) => ["blocking", "major", "minor"].includes(f?.severity) && typeof f.issue === "string" && f.issue.trim()).slice(0, 10)
     .map((f: any) => ({ severity: f.severity, file: safeText(String(f.file ?? "")).full.slice(0, 300), line: Number.isSafeInteger(f.line) && f.line > 0 ? f.line : null,
       issue: safeText(f.issue).full.slice(0, 500) }));
+  if (HELPER_ROLES.includes(details.role)) out.role = details.role;
+  if (["main", "harness"].includes(details.by)) out.by = details.by;
+  if (Number.isInteger(details.disputes) && details.disputes >= 1) out.disputes = Math.min(details.disputes, 1000);
+  if (details.unchanged === true) out.unchanged = true;
+  if (Array.isArray(details.issues)) out.issues = details.issues.filter((i: any) => ISSUE_KINDS.includes(i?.kind) && typeof i.detail === "string" && i.detail.trim()).slice(0, 10)
+    .map((i: any) => ({ kind: i.kind, detail: safeText(i.detail).full.slice(0, 400) }));
+  if (Array.isArray(details.claims)) out.claims = details.claims.filter((c: any) => typeof c?.claim === "string" && c.claim.trim()).slice(0, 10)
+    .map((c: any) => ({ claim: safeText(c.claim).full.slice(0, 500) }));
   return out;
 }
 function role(message: any): TranscriptItem["role"] | null {

package/schemas/piagent-webui/session-catalog-v1.schema.json

@@ -97,7 +97,7 @@
           "steps": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "required": ["step", "status"], "properties": {
             "step": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "enum": ["pending", "in_progress", "completed"] } } } } } },
         "managedProcess": { "type": "object", "additionalProperties": false, "required": ["outcome", "verified", "reviewed", "blockingOpen"], "properties": {
-          "outcome": { "enum": ["no_change", "interrupted", "blocking_open", "unverified", "review_unavailable", "unreviewed", "clean"] },
+          "outcome": { "enum": ["no_change", "interrupted", "disputed", "blocking_open", "unverified", "review_unavailable", "unreviewed", "clean"] },
           "verified": { "type": "boolean" }, "reviewed": { "type": "boolean" }, "blockingOpen": { "type": "integer", "minimum": 0, "maximum": 1000 }, "planSkipped": { "const": true } } },
         "modelLabel": { "$ref": "common-v1.schema.json#/$defs/nullableDisplayText" },
         "thinkingLevel": { "enum": ["off", "minimal", "low", "medium", "high", "xhigh", "max", "unknown"] },

package/schemas/piagent-webui/transcript-v1.schema.json

@@ -157,8 +157,35 @@
       "additionalProperties": false,
       "required": ["phase"],
       "properties": {
-        "phase": { "enum": ["plan", "verify", "review", "final"] },
-        "outcome": { "enum": ["no_change", "interrupted", "blocking_open", "unverified", "review_unavailable", "unreviewed", "clean"] },
+        "phase": { "enum": ["plan", "verify", "review", "final", "objection", "answer", "claims", "rejudge", "dispute"] },
+        "outcome": { "enum": ["no_change", "interrupted", "disputed", "blocking_open", "unverified", "review_unavailable", "unreviewed", "clean"] },
+        "role": { "enum": ["scout", "research", "verify", "review"] },
+        "by": { "enum": ["main", "harness"] },
+        "disputes": { "type": "integer", "minimum": 1, "maximum": 1000 },
+        "unchanged": { "const": true },
+        "issues": {
+          "type": "array",
+          "maxItems": 10,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "detail"],
+            "properties": {
+              "kind": { "enum": ["wrong_premise", "conflicts_with_request", "ambiguous", "out_of_scope"] },
+              "detail": { "type": "string", "maxLength": 400 }
+            }
+          }
+        },
+        "claims": {
+          "type": "array",
+          "maxItems": 10,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["claim"],
+            "properties": { "claim": { "type": "string", "maxLength": 500 } }
+          }
+        },
         "loop": { "type": "integer", "minimum": 0, "maximum": 3 },
         "maxLoops": { "type": "integer", "minimum": 0, "maximum": 3 },
         "verified": { "type": "boolean" },