@piagent/platform 1.9.3 → 1.11.0

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

@@ -1,7 +1,8 @@
-import http, { type IncomingMessage, type ServerResponse } from "node:http";
+import http, { type ServerResponse } from "node:http";
 import { randomBytes } from "node:crypto";
 
-import { errorResponse, applySecurityHeaders, jsonResponse } from "./http-security.ts";
+import { errorResponse, applySecurityHeaders, jsonResponse, requestBody } from "./http-security.ts";
+import { routeMemberRequest, type UpdateRoutes } from "./member-routes.ts";
 import { ReadModelNotFound, type WebUiReadModelProvider } from "./read-model-provider.ts";
 import { routeReadOnlyRequest } from "./read-only-router.ts";
 import { SessionAuthority } from "./session-auth.ts";
@@ -32,20 +33,6 @@ export type LoopbackServer = {
   close(): Promise<void>;
 };
 
-function requestBody(request: IncomingMessage, maximumBytes: number): Promise<Buffer> {
-  return new Promise((resolve, reject) => {
-    const chunks: Buffer[] = []; let bytes = 0, failed = false;
-    request.on("data", (chunk: Buffer) => {
-      if (failed) return;
-      bytes += chunk.length;
-      if (bytes > maximumBytes) { failed = true; reject(new Error("body-limit")); }
-      else chunks.push(chunk);
-    });
-    request.on("end", () => { if (!failed) resolve(Buffer.concat(chunks)); });
-    request.on("error", (error) => { if (!failed) reject(error); });
-  });
-}
-
 function serveAsset(response: ServerResponse, asset: StaticAsset): void {
   response.statusCode = 200;
   response.setHeader("Cache-Control", "no-store");
@@ -81,6 +68,9 @@ 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>;
+  updates?: UpdateRoutes;
   bootstrapTtlMs?: number;
   sessionTtlMs?: number;
 }): Promise<LoopbackServer> {
@@ -302,6 +292,9 @@ export async function startLoopbackServer(options: {
       catch { return errorResponse(response, 503, "attachment-runtime-unavailable"); }
     }
 
+    // The main agent's questions to the member, and Piagent's own updates.
+    if (await routeMemberRequest({ request, response, url, origin, requestOrigin, auth, now, consumeControl }, options)) return;
+
     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/member-routes.ts

@@ -0,0 +1,99 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { errorResponse, jsonResponse, requestBody } from "./http-security.ts";
+import type { SessionAuthority } from "./session-auth.ts";
+
+// Requests a member makes beside a conversation: answering the main agent's
+// questions, and keeping Piagent itself up to date. Reads need the browser
+// session; every change also needs this origin, the session's CSRF token and
+// a share of the control rate.
+const MAX_CONTROL_BODY_BYTES = 70_000;
+const CURSOR = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+const QUESTION_PATH = /^\/api\/v1\/sessions\/([^/]+)\/questions(?:\/([^/]+)\/answer)?$/;
+
+export type UpdateRoutes = {
+  // What is installed, what is available, and the last update run.
+  status(): unknown | Promise<unknown>;
+  // Asks the registry now instead of waiting for the next periodic check.
+  check(): unknown | Promise<unknown>;
+  // Starts the update to the version the member saw; refused when it moved.
+  apply(request: unknown): unknown | Promise<unknown>;
+};
+
+type Context = {
+  request: IncomingMessage; response: ServerResponse; url: URL; origin: string; requestOrigin: string | undefined;
+  auth: SessionAuthority; now: number; consumeControl(sessionId: string, now: number): boolean;
+};
+type Options = {
+  readSessionQuestions?: (sessionRef: string) => unknown | Promise<unknown>;
+  answerSessionQuestion?: (sessionRef: string, questionRef: string, answer: unknown) => unknown | Promise<unknown>;
+  updates?: UpdateRoutes;
+};
+
+// The checks every change shares; a refusal is answered here and false returned.
+function authorizeChange(context: Context): boolean {
+  const { request, response, origin, requestOrigin, auth, now, consumeControl } = context;
+  if (requestOrigin !== origin) { errorResponse(response, 403, "origin-required"); return false; }
+  const session = auth.authorizeMutation(request);
+  if (!session) { errorResponse(response, 403, "mutation-authority-rejected"); return false; }
+  if (!consumeControl(session.id, now)) { errorResponse(response, 429, "control-rate-limit"); return false; }
+  if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) { errorResponse(response, 415, "content-type"); return false; }
+  return true;
+}
+
+async function jsonBody(context: Context, code: string): Promise<{ ok: true; value: unknown } | { ok: false }> {
+  try { return { ok: true, value: JSON.parse((await requestBody(context.request, MAX_CONTROL_BODY_BYTES)).toString("utf8")) }; }
+  catch (error) { errorResponse(context.response, (error as Error).message === "body-limit" ? 413 : 400, code); return { ok: false }; }
+}
+
+const UPDATE_STATUS: Record<string, number> = {
+  "update-not-installable": 409, "update-blocked-running": 409, "update-already-running": 409,
+  "update-version-changed": 409, "update-not-available": 409, "update-request-invalid": 400
+};
+
+// True when the request was one of these routes (answered, or refused).
+export async function routeMemberRequest(context: Context, options: Options): Promise<boolean> {
+  const { request, response, url, auth } = context;
+  const question = QUESTION_PATH.exec(url.pathname);
+  if (request.method === "GET" && question && !question[2] && options.readSessionQuestions) {
+    if (!auth.authenticate(request)) { errorResponse(response, 401, "authentication-required"); return true; }
+    const sessionRef = decodeURIComponent(question[1]);
+    if (!CURSOR.test(sessionRef)) { errorResponse(response, 400, "invalid-session-ref"); return true; }
+    try { jsonResponse(response, 200, await options.readSessionQuestions(sessionRef)); }
+    catch { errorResponse(response, 503, "questions-unavailable"); }
+    return true;
+  }
+  if (request.method === "POST" && question && question[2] && options.answerSessionQuestion) {
+    if (!authorizeChange(context)) return true;
+    const sessionRef = decodeURIComponent(question[1]), questionRef = decodeURIComponent(question[2]);
+    if (!CURSOR.test(sessionRef) || !/^question\.[0-9a-f-]{36}$/.test(questionRef)) { errorResponse(response, 400, "invalid-question-ref"); return true; }
+    const body = await jsonBody(context, "invalid-question-answer");
+    if (!body.ok) return true;
+    try { jsonResponse(response, 200, await options.answerSessionQuestion(sessionRef, questionRef, body.value)); }
+    catch (error) {
+      const code = error instanceof Error ? error.message : "questions-unavailable";
+      errorResponse(response, code === "question-not-pending" ? 409 : code === "question-answer-invalid" ? 400 : 503, code);
+    }
+    return true;
+  }
+
+  if (!options.updates || !url.pathname.startsWith("/api/v1/updates")) return false;
+  const updates = options.updates;
+  if (request.method === "GET" && url.pathname === "/api/v1/updates") {
+    if (!auth.authenticate(request)) { errorResponse(response, 401, "authentication-required"); return true; }
+    try { jsonResponse(response, 200, await updates.status()); }
+    catch { errorResponse(response, 503, "update-status-unavailable"); }
+    return true;
+  }
+  const action = request.method === "POST" ? /^\/api\/v1\/updates\/(check|apply)$/.exec(url.pathname)?.[1] : undefined;
+  if (!action) { errorResponse(response, 404, "not-found"); return true; }
+  if (!authorizeChange(context)) return true;
+  const body = await jsonBody(context, "update-request-invalid");
+  if (!body.ok) return true;
+  try { jsonResponse(response, action === "apply" ? 202 : 200, action === "apply" ? await updates.apply(body.value) : await updates.check()); }
+  catch (error) {
+    const code = error instanceof Error ? error.message : "update-unavailable";
+    errorResponse(response, UPDATE_STATUS[code] ?? 503, UPDATE_STATUS[code] ? code : "update-unavailable");
+  }
+  return true;
+}

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" },

package/scripts/dashboard-update-job.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// One update started from the dashboard, run apart from it: the dashboard is
+// restarted at the end, so this process must outlive it. It moves Pi and
+// Piagent to the chosen release with `piagent-update` (Pi first, to the
+// version that release pins), restarts the dashboard on the new code, and
+// leaves the outcome in ~/.pi/piagent-update-job.json for the new dashboard to
+// show. The full output goes to ~/.pi/piagent-update-job.log.
+//
+//   dashboard-update-job.mjs --from 1.10.0 --to 1.11.0
+//     [--updater <script>] [--dashboard <script>] [--home <dir>]   (tests)
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const RELEASE = /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/;
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function option(name, fallback) {
+  const index = process.argv.indexOf(`--${name}`);
+  return index > 0 && process.argv[index + 1] ? process.argv[index + 1] : fallback;
+}
+const from = option("from"), to = option("to");
+const home = path.resolve(option("home", os.homedir()));
+const updater = option("updater", path.join(packageRoot, "scripts", "update-global.mjs"));
+const dashboard = option("dashboard", path.join(packageRoot, "scripts", "piagent-dashboard.mjs"));
+if (!RELEASE.test(from ?? "") || !RELEASE.test(to ?? "")) {
+  process.stderr.write("usage: dashboard-update-job.mjs --from X.Y.Z --to X.Y.Z\n");
+  process.exit(2);
+}
+
+const directory = path.join(home, ".pi"), jobFile = path.join(directory, "piagent-update-job.json");
+fs.mkdirSync(directory, { recursive: true });
+const startedAt = (() => {
+  try { const value = JSON.parse(fs.readFileSync(jobFile, "utf8")); return value?.to === to && Number.isFinite(Date.parse(value.startedAt)) ? value.startedAt : undefined; }
+  catch { return undefined; }
+})() ?? new Date().toISOString();
+function record(fields) {
+  const temporary = `${jobFile}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify({ from, to, startedAt, pid: process.pid, ...fields }, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporary, jobFile);
+}
+const finish = (state, fields = {}) => { record({ state, finishedAt: new Date().toISOString(), ...fields }); process.exit(state === "succeeded" ? 0 : 1); };
+
+record({ state: "running" });
+const log = fs.openSync(path.join(directory, "piagent-update-job.log"), "w", 0o600);
+const env = { ...process.env, PIAGENT_NO_UPDATE_CHECK: "1" };
+fs.writeSync(log, `Piagent update ${from} -> ${to} (${new Date().toISOString()})\n`);
+const update = spawnSync(process.execPath, [updater, "--version", to], { stdio: ["ignore", log, log], env, timeout: 30 * 60 * 1000 });
+if (update.status !== 0) finish("failed", { reason: "update-command-failed" });
+
+let installed;
+try { installed = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version; } catch { installed = undefined; }
+if (installed !== to) finish("failed", { reason: "update-version-mismatch", ...(RELEASE.test(installed ?? "") ? { installed } : {}) });
+
+// Agent Watch pins the company launcher it starts; a release that changed
+// the launcher needs the binding imported again in Agent Watch.
+let bindingChanged = false;
+try {
+  const agentDir = process.env.PI_CODING_AGENT_DIR?.trim() || path.join(home, ".pi", "agent");
+  const binding = JSON.parse(fs.readFileSync(path.join(agentDir, "agent-watch-managed.json"), "utf8"));
+  if (typeof binding?.entrypoint === "string" && typeof binding?.entrypoint_sha256 === "string")
+    bindingChanged = crypto.createHash("sha256").update(fs.readFileSync(binding.entrypoint)).digest("hex") !== binding.entrypoint_sha256;
+} catch { /* no company binding on this machine */ }
+
+// The new dashboard opens in a new browser tab: the old tab's browser session
+// ends with the old dashboard. Its launch link is never written to the log.
+fs.writeSync(log, "\nRestarting the dashboard on the new release\n");
+const restart = spawnSync(process.execPath, [dashboard, "restart", "--json"], { stdio: ["ignore", "ignore", log], env, timeout: 3 * 60 * 1000 });
+finish("succeeded", { installed, ...(bindingChanged ? { bindingChanged } : {}), ...(restart.status === 0 ? {} : { reason: "dashboard-restart-failed" }) });