@piagent/platform 1.5.5 → 1.6.1

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

@@ -1,11 +1,13 @@
 import { createHash } from "node:crypto";
 
 import { redactSensitiveText } from "../../piagent-core/extensions/redaction-core.js";
+import { hasVisibleText } from "../shared/text-visibility.ts";
 
 const MAX_ENTRIES = 50_000;
 const MAX_ITEMS = 200;
 const MAX_TEXT = 16_384;
-const ANSI = /\u001b(?:[@-_]|\[[0-?]*[ -/]*[@-~])/g;
+const ANSI = /\u001b(?:\[[0-?]*[ -/]*[@-~]|[@-_])/g;
+const COMPLETION_GATE = /^\[Piagent completion gate: (CONTINUING|NOT APPROVED)\]/i;
 
 type TranscriptIdentity = { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string | null; taskRunId: string | null;
   agentOperationId: null; toolCallId: null };
@@ -30,6 +32,7 @@ export type TranscriptProjectionInput = {
   beforeCursor?: string | null;
   limit?: number;
   generatedAt?: string;
+  taskOutcome?: string | null;
 };
 
 function hash(value: string): string { return createHash("sha256").update(value).digest("hex"); }
@@ -87,6 +90,21 @@ function assistantFailureReason(message: any): string | null {
   if (/(?:network|fetch failed|econn|timed? ?out|unavailable)/.test(detail)) return "provider-unavailable";
   return "provider-response-failed";
 }
+function assistantUnavailableReason(message: any, text: string, projectedToolCalls: TranscriptItem["toolCalls"]): string | null {
+  if (message?.role !== "assistant") return null;
+  const stopReason = String(message?.stopReason ?? "");
+  if (stopReason === "error") return assistantFailureReason(message) ?? "provider-response-failed";
+  if (stopReason === "aborted") return "assistant-message-aborted";
+  if (stopReason === "length") return "assistant-output-incomplete";
+  const gate = COMPLETION_GATE.exec(text.trimStart());
+  if (gate) return gate[1]?.toUpperCase() === "CONTINUING"
+    ? "assistant-completion-continuing" : "assistant-completion-not-approved";
+  if (projectedToolCalls.length > 0 || ["toolUse", "pending", "deferred"].includes(stopReason)) return "assistant-intermediate-output";
+  if (!stopReason) return "assistant-settlement-unknown";
+  if (stopReason && stopReason !== "stop") return "assistant-settlement-unknown";
+  if (!hasVisibleText(text)) return "assistant-message-empty";
+  return null;
+}
 function safeText(value: string): { full: string; preview: string; redacted: boolean; truncated: boolean } {
   const clean = value.replace(ANSI, "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ");
   const redaction = redactSensitiveText(clean);
@@ -129,18 +147,102 @@ function item(entry: any, identity: TranscriptIdentity): TranscriptItem | null {
   const itemRole = role(entry.message), recordedAt = timestamp(entry.timestamp ?? entry.message.timestamp);
   if (!itemRole || !recordedAt || typeof entry.id !== "string" || entry.id.length === 0) return null;
   const userProjection = userMessageProjection(entry.message);
+  const projectedToolCalls = toolCalls(entry.message, identity.sessionRef, itemRole);
   const content = itemRole === "tool-result" ? unavailableContent("tool-output-in-activity-preview") : (() => {
     const projected = safeText(itemRole === "user" ? userProjection.text : messageText(entry.message));
-    const failureReason = projected.full.length === 0 ? assistantFailureReason(entry.message) : null;
-    if (failureReason) return unavailableContent(failureReason);
+    const unavailableReason = assistantUnavailableReason(entry.message, projected.full, projectedToolCalls);
+    if (unavailableReason) return unavailableContent(unavailableReason);
     return { state: projected.redacted ? "redacted" as const : "available" as const, text: projected.preview,
       textChars: Math.min(1_000_000_000, projected.full.length), digest: `sha256:${hash(projected.full)}`, truncated: projected.truncated,
       redacted: projected.redacted, imageCount: imageCount(entry.message), reasonCode: projected.redacted ? "sensitive-values-redacted" as const : null };
   })();
   return { messageRef: opaque("message", [identity.sessionRef, entry.id]), parentMessageRef: null, role: itemRole, recordedAt,
     agentOperationId: null, turnIndex: null, content, ...(userProjection.attachments.length ? { attachments: userProjection.attachments } : {}),
-    toolCalls: toolCalls(entry.message, identity.sessionRef, itemRole) };
+    toolCalls: projectedToolCalls };
+}
+
+type ProjectedTranscriptItem = { entry: any; item: TranscriptItem; cursor: string };
+
+function linkTranscriptTurns(values: ProjectedTranscriptItem[]): ProjectedTranscriptItem[] {
+  let userMessageRef: string | null = null;
+  const toolCallOwners = new Map<string, string>();
+  return values.map((value) => {
+    let parentMessageRef: string | null = null;
+    if (value.item.role === "user") userMessageRef = value.item.messageRef;
+    else if (value.item.role === "tool-result") {
+      parentMessageRef = toolCallOwners.get(value.item.toolCalls[0]?.toolCallRef ?? "") ?? userMessageRef;
+    } else parentMessageRef = userMessageRef;
+    const linked = { ...value, item: { ...value.item, parentMessageRef } };
+    if (linked.item.role === "assistant") {
+      for (const toolCall of linked.item.toolCalls) toolCallOwners.set(toolCall.toolCallRef, linked.item.messageRef);
+    }
+    return linked;
+  });
+}
+
+function suppressOpenTaskHandoff(values: ProjectedTranscriptItem[], taskOutcome: string | null | undefined): ProjectedTranscriptItem[] {
+  if (taskOutcome !== "pending") return values;
+  let latestUser = -1;
+  for (let index = values.length - 1; index >= 0; index -= 1) {
+    if (values[index]?.item.role === "user") { latestUser = index; break; }
+  }
+  if (latestUser < 0) return values;
+  return values.map((value, index) => {
+    if (index <= latestUser || value.item.role !== "assistant" || value.item.toolCalls.length > 0
+      || !["available", "redacted"].includes(value.item.content.state)) return value;
+    return { ...value, item: { ...value.item, content: unavailableContent("assistant-task-pending") } };
+  });
+}
+
+function durableAssistant(item: TranscriptItem): boolean {
+  return item.role === "assistant" && item.toolCalls.length === 0
+    && (item.content.state === "available" || item.content.state === "redacted")
+    && hasVisibleText(item.content.text ?? "");
+}
+
+function compactOversizedTurn(
+  values: ProjectedTranscriptItem[], start: number, end: number, limit: number
+): ProjectedTranscriptItem[] {
+  if (limit === 1) return [values[start]!];
+  const selected = new Set<number>([start]);
+  for (let index = end - 1; index > start; index -= 1) {
+    if (durableAssistant(values[index]!.item)) { selected.add(index); break; }
+  }
+  for (let index = end - 1; index > start && selected.size < limit; index -= 1) selected.add(index);
+  return [...selected].sort((left, right) => left - right).map((index) => values[index]!);
+}
+
+function boundedTurnPage(
+  values: ProjectedTranscriptItem[], end: number, limit: number
+): { selected: ProjectedTranscriptItem[]; start: number; compacted: boolean } {
+  if (end <= 0) return { selected: [], start: 0, compacted: false };
+  const users: number[] = [];
+  for (let index = 0; index < end; index += 1) if (values[index]?.item.role === "user") users.push(index);
+  if (users.length === 0) {
+    const start = Math.max(0, end - limit);
+    return { selected: values.slice(start, end), start, compacted: false };
+  }
+
+  const selected: ProjectedTranscriptItem[] = [];
+  let remaining = limit, turnEnd = end, start = end;
+  for (let userIndex = users.length - 1; userIndex >= 0 && remaining > 0; userIndex -= 1) {
+    const turnStart = users[userIndex]!;
+    const turnSize = turnEnd - turnStart;
+    if (turnSize > remaining) {
+      if (selected.length === 0) {
+        const compacted = compactOversizedTurn(values, turnStart, turnEnd, remaining);
+        return { selected: compacted, start: turnStart, compacted: true };
+      }
+      break;
+    }
+    selected.unshift(...values.slice(turnStart, turnEnd));
+    start = turnStart;
+    remaining -= turnSize;
+    turnEnd = turnStart;
+  }
+  return { selected, start, compacted: false };
 }
+
 function unavailable(input: TranscriptProjectionInput, reasonCode: string, limit: number): TranscriptDocument {
   return { schemaVersion: 1, version: "piagent-webui-transcript-v1", generatedAt: input.generatedAt ?? new Date().toISOString(),
     identity: structuredClone(input.identity), revision: structuredClone(input.revision), eventCursor: input.eventCursor,
@@ -150,17 +252,19 @@ function unavailable(input: TranscriptProjectionInput, reasonCode: string, limit
 export function projectTranscript(input: TranscriptProjectionInput): TranscriptDocument {
   const limit = Math.max(1, Math.min(MAX_ITEMS, Number.isInteger(input.limit) ? Number(input.limit) : 50));
   if (!Array.isArray(input.entries) || input.entries.length > MAX_ENTRIES) return unavailable(input, "transcript-history-unavailable", limit);
-  const projected = input.entries.map((entry) => ({ entry, item: item(entry, input.identity) })).filter((value): value is { entry: any; item: TranscriptItem } => Boolean(value.item));
-  const cursors = projected.map(({ entry }) => opaque("transcript", [input.identity.sessionRef, entry.id]));
+  const projected = suppressOpenTaskHandoff(linkTranscriptTurns(input.entries.map((entry) => ({ entry, item: item(entry, input.identity),
+    cursor: opaque("transcript", [input.identity.sessionRef, (entry as any)?.id]) }))
+    .filter((value): value is ProjectedTranscriptItem => Boolean(value.item))), input.taskOutcome);
+  const cursors = projected.map((value) => value.cursor);
   let end = projected.length;
   if (input.beforeCursor) {
     const cursorIndex = cursors.indexOf(input.beforeCursor);
     if (cursorIndex < 0) return unavailable(input, "transcript-cursor-gap", limit);
     end = cursorIndex;
   }
-  const start = Math.max(0, end - limit), selected = projected.slice(start, end).map((value) => value.item), hasOlder = start > 0;
+  const page = boundedTurnPage(projected, end, limit), selected = page.selected.map((value) => value.item), hasOlder = page.start > 0;
   return { schemaVersion: 1, version: "piagent-webui-transcript-v1", generatedAt: input.generatedAt ?? new Date().toISOString(),
     identity: structuredClone(input.identity), revision: structuredClone(input.revision), eventCursor: input.eventCursor,
-    state: "ready", items: selected, page: { beforeCursor: input.beforeCursor ?? null, nextBeforeCursor: hasOlder ? cursors[start] : null,
-      hasOlder, limit, truncated: projected.length !== input.entries.filter((entry: any) => entry?.type === "message").length }, reasonCode: null };
+    state: "ready", items: selected, page: { beforeCursor: input.beforeCursor ?? null, nextBeforeCursor: hasOlder ? cursors[page.start] : null,
+      hasOlder, limit, truncated: page.compacted || projected.length !== input.entries.filter((entry: any) => entry?.type === "message").length }, reasonCode: null };
 }

package/packages/piagent-webui/shared/text-visibility.ts

@@ -0,0 +1,10 @@
+// Classification only: callers keep the original Unicode text unchanged.
+// A response needs at least one rendering code point; whitespace, controls and
+// Unicode default-ignorables alone cannot form a visible assistant answer.
+const NON_RENDERING_CODE_POINT = /^(?:\p{White_Space}|\p{Cc}|\p{Default_Ignorable_Code_Point})$/u;
+const ANSI_ESCAPE = /\u001b(?:\[[0-?]*[ -/]*[@-~]|[@-_])/g;
+
+export function hasVisibleText(value: string): boolean {
+  for (const codePoint of value.replace(ANSI_ESCAPE, "")) if (!NON_RENDERING_CODE_POINT.test(codePoint)) return true;
+  return false;
+}

package/schemas/codex-relative-efficiency-v1.schema.json

@@ -0,0 +1,155 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Vt-mmm/piagent/schemas/codex-relative-efficiency-v1.schema.json",
+  "title": "Piagent Codex-relative efficiency evidence v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "policy", "required", "claim", "billedOrSubscriptionCost", "costBoundary", "checks", "failures", "passed", "families", "totalTokenTraffic", "apiEquivalentCost", "subagents"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "policy": { "$ref": "#/$defs/policy" },
+    "required": { "type": "boolean" },
+    "claim": { "type": "string", "minLength": 1 },
+    "billedOrSubscriptionCost": { "const": false },
+    "costBoundary": { "type": "string", "minLength": 1 },
+    "checks": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "type": "boolean" }
+    },
+    "failures": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+    "passed": { "type": "boolean" },
+    "families": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/family" } },
+    "totalTokenTraffic": { "$ref": "#/$defs/aggregateTokens" },
+    "apiEquivalentCost": { "$ref": "#/$defs/aggregateCost" },
+    "subagents": { "$ref": "#/$defs/subagents" }
+  },
+  "$defs": {
+    "nullableNonNegativeNumber": { "type": ["number", "null"], "minimum": 0 },
+    "nullablePositiveNumber": { "type": ["number", "null"], "exclusiveMinimum": 0 },
+    "confidence": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": ["lower", "upper", "sampleUnit", "scenarioCount"],
+      "properties": {
+        "lower": { "type": "number", "exclusiveMinimum": 0 },
+        "upper": { "type": "number", "exclusiveMinimum": 0 },
+        "sampleUnit": { "const": "scenario-family" },
+        "scenarioCount": { "type": "integer", "minimum": 2 }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "id", "baselineSurface", "candidateSurface", "estimand", "outcomeConditioning", "attemptPolicy", "maximumTotalTokenTrafficRatio", "maximumTotalTokenTrafficRatioUpper95", "maximumApiEquivalentCostRatio", "maximumApiEquivalentCostRatioUpper95", "maximumSubagentSessionsPerAttempt", "maximumSubagentTrafficShare"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "id": { "const": "codex-relative-efficiency-v1" },
+        "baselineSurface": { "const": "codex-cli" },
+        "candidateSurface": { "const": "piagent" },
+        "estimand": { "const": "fixed-workload-family-geometric-mean" },
+        "outcomeConditioning": { "const": "none" },
+        "attemptPolicy": { "const": "accepted-plus-exact-provider-started-failed-attempts" },
+        "maximumTotalTokenTrafficRatio": { "type": "number", "exclusiveMinimum": 0, "maximum": 0.7 },
+        "maximumTotalTokenTrafficRatioUpper95": { "type": "number", "exclusiveMinimum": 0, "maximum": 0.7 },
+        "maximumApiEquivalentCostRatio": { "type": "number", "exclusiveMinimum": 0, "maximum": 0.7 },
+        "maximumApiEquivalentCostRatioUpper95": { "type": "number", "exclusiveMinimum": 0, "maximum": 0.7 },
+        "maximumSubagentSessionsPerAttempt": { "type": "integer", "minimum": 0, "maximum": 1 },
+        "maximumSubagentTrafficShare": { "type": "number", "minimum": 0, "maximum": 0.05 }
+      }
+    },
+    "family": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scenarioId", "expectedAttempts", "pairedAttempts", "exact", "issues", "baselineTokenTraffic", "candidateTokenTraffic", "totalTokenTrafficRatio", "baselineApiEquivalentCostUsd", "candidateApiEquivalentCostUsd", "apiEquivalentCostRatio", "candidateSubagentSessions", "candidateSubagentTraffic", "maximumSubagentSessionsPerAttempt", "candidateAttempts", "subagentEvidenceComplete"],
+      "properties": {
+        "scenarioId": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+        "expectedAttempts": { "type": ["integer", "null"], "minimum": 1 },
+        "pairedAttempts": { "type": "integer", "minimum": 0 },
+        "exact": { "type": "boolean" },
+        "issues": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "baselineTokenTraffic": { "type": "number", "minimum": 0 },
+        "candidateTokenTraffic": { "type": "number", "minimum": 0 },
+        "totalTokenTrafficRatio": { "$ref": "#/$defs/nullablePositiveNumber" },
+        "baselineApiEquivalentCostUsd": { "type": "number", "minimum": 0 },
+        "candidateApiEquivalentCostUsd": { "type": "number", "minimum": 0 },
+        "apiEquivalentCostRatio": { "$ref": "#/$defs/nullablePositiveNumber" },
+        "candidateSubagentSessions": { "type": "integer", "minimum": 0 },
+        "candidateSubagentTraffic": { "type": "integer", "minimum": 0 },
+        "maximumSubagentSessionsPerAttempt": { "type": "integer", "minimum": 0 },
+        "candidateAttempts": { "type": "integer", "minimum": 0 },
+        "subagentEvidenceComplete": { "type": "boolean" }
+      }
+    },
+    "aggregateBase": {
+      "type": "object",
+      "required": ["complete", "expectedScenarioFamilies", "completeScenarioFamilies", "ratio", "ratioConfidence95", "ratioConfidence95Raw", "aggregateRatio", "deltaPercent"],
+      "properties": {
+        "complete": { "type": "boolean" },
+        "expectedScenarioFamilies": { "type": "integer", "minimum": 1 },
+        "completeScenarioFamilies": { "type": "integer", "minimum": 0 },
+        "ratio": { "$ref": "#/$defs/nullablePositiveNumber" },
+        "ratioConfidence95": { "$ref": "#/$defs/confidence" },
+        "ratioConfidence95Raw": { "$ref": "#/$defs/confidence" },
+        "aggregateRatio": { "$ref": "#/$defs/nullableNonNegativeNumber" },
+        "deltaPercent": { "type": ["number", "null"] }
+      }
+    },
+    "aggregateTokens": {
+      "allOf": [
+        { "$ref": "#/$defs/aggregateBase" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["complete", "expectedScenarioFamilies", "completeScenarioFamilies", "ratio", "ratioConfidence95", "ratioConfidence95Raw", "aggregateBaselineTokens", "aggregateCandidateTokens", "aggregateRatio", "deltaPercent"],
+          "properties": {
+            "complete": true,
+            "expectedScenarioFamilies": true,
+            "completeScenarioFamilies": true,
+            "ratio": true,
+            "ratioConfidence95": true,
+            "ratioConfidence95Raw": true,
+            "aggregateRatio": true,
+            "deltaPercent": true,
+            "aggregateBaselineTokens": { "type": "number", "minimum": 0 },
+            "aggregateCandidateTokens": { "type": "number", "minimum": 0 }
+          }
+        }
+      ]
+    },
+    "aggregateCost": {
+      "allOf": [
+        { "$ref": "#/$defs/aggregateBase" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["complete", "expectedScenarioFamilies", "completeScenarioFamilies", "ratio", "ratioConfidence95", "ratioConfidence95Raw", "aggregateBaselineUsd", "aggregateCandidateUsd", "aggregateRatio", "deltaPercent"],
+          "properties": {
+            "complete": true,
+            "expectedScenarioFamilies": true,
+            "completeScenarioFamilies": true,
+            "ratio": true,
+            "ratioConfidence95": true,
+            "ratioConfidence95Raw": true,
+            "aggregateRatio": true,
+            "deltaPercent": true,
+            "aggregateBaselineUsd": { "type": "number", "minimum": 0 },
+            "aggregateCandidateUsd": { "type": "number", "minimum": 0 }
+          }
+        }
+      ]
+    },
+    "subagents": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["candidateAttempts", "sessions", "tokenTraffic", "trafficShare", "maximumObservedSessionsPerAttempt"],
+      "properties": {
+        "candidateAttempts": { "type": "integer", "minimum": 0 },
+        "sessions": { "type": "integer", "minimum": 0 },
+        "tokenTraffic": { "type": "integer", "minimum": 0 },
+        "trafficShare": { "$ref": "#/$defs/nullableNonNegativeNumber" },
+        "maximumObservedSessionsPerAttempt": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

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

@@ -218,6 +218,15 @@
       "supported": true,
       "current": true
     },
+    {
+      "name": "session-live-state-v1",
+      "file": "session-live-state-v1.schema.json",
+      "id": "https://piagent.io.vn/schemas/piagent-webui/session-live-state-v1.schema.json",
+      "documentVersion": 1,
+      "role": "read-model",
+      "supported": true,
+      "current": true
+    },
     {
       "name": "session-command-v1",
       "file": "session-command-v1.schema.json",

package/schemas/piagent-webui/gateway-protocol-v1.schema.json

@@ -269,7 +269,7 @@
         "sequence": { "$ref": "#/$defs/stateVersion" },
         "stateVersion": { "$ref": "#/$defs/stateVersion" },
         "generatedAt": { "$ref": "common-v1.schema.json#/$defs/timestamp" },
-        "kind": { "enum": ["catalog.changed", "session.changed", "runtime.changed", "resync.required", "message.delta", "message.completed", "tool.started", "tool.completed"] },
+        "kind": { "enum": ["catalog.changed", "session.changed", "runtime.changed", "resync.required", "message.delta", "message.completed", "operation.settled", "tool.started", "tool.completed"] },
         "payload": { "type": "object" }
       }
     },
@@ -411,6 +411,54 @@
         }
       ]
     },
+    "operationCompletedPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sessionRef", "operationRef", "messageRef", "sessionRevision", "settlement", "reasonCode"],
+      "properties": {
+        "sessionRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "operationRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "messageRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "sessionRevision": { "$ref": "common-v1.schema.json#/$defs/revisionToken" },
+        "settlement": { "const": "completed" },
+        "reasonCode": { "type": "null" }
+      }
+    },
+    "operationIncompletePayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sessionRef", "operationRef", "messageRef", "sessionRevision", "settlement", "reasonCode"],
+      "properties": {
+        "sessionRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "operationRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "messageRef": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
+        "sessionRevision": {
+          "anyOf": [
+            { "$ref": "common-v1.schema.json#/$defs/revisionToken" },
+            { "type": "null" }
+          ]
+        },
+        "settlement": { "enum": ["blocked", "aborted", "error", "unknown"] },
+        "reasonCode": { "$ref": "common-v1.schema.json#/$defs/reasonCode" }
+      }
+    },
+    "operationSettledEvent": {
+      "allOf": [
+        { "$ref": "#/$defs/eventBase" },
+        {
+          "type": "object",
+          "properties": {
+            "kind": { "const": "operation.settled" },
+            "payload": {
+              "oneOf": [
+                { "$ref": "#/$defs/operationCompletedPayload" },
+                { "$ref": "#/$defs/operationIncompletePayload" }
+              ]
+            }
+          }
+        }
+      ]
+    },
     "toolEvent": {
       "allOf": [
         { "$ref": "#/$defs/eventBase" },
@@ -421,13 +469,14 @@
             "payload": {
               "type": "object",
               "additionalProperties": false,
-              "required": ["sessionRef", "operationRef", "toolCallRef", "toolLabel", "isError"],
+              "required": ["sessionRef", "operationRef", "toolCallRef", "toolLabel", "isError", "reasonCode"],
               "properties": {
                 "sessionRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
                 "operationRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
                 "toolCallRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
                 "toolLabel": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[^\\u0000-\\u001F\\u007F]+$" },
-                "isError": { "type": ["boolean", "null"] }
+                "isError": { "type": ["boolean", "null"] },
+                "reasonCode": { "$ref": "common-v1.schema.json#/$defs/nullableReasonCode" }
               }
             }
           },
@@ -449,6 +498,7 @@
         { "$ref": "#/$defs/resyncRequiredEvent" },
         { "$ref": "#/$defs/messageDeltaEvent" },
         { "$ref": "#/$defs/messageCompletedEvent" },
+        { "$ref": "#/$defs/operationSettledEvent" },
         { "$ref": "#/$defs/toolEvent" }
       ]
     }

package/schemas/piagent-webui/runtime-event-v2.schema.json

@@ -2962,11 +2962,21 @@
           },
           "then": {
             "type": "object",
-            "properties": {
-              "isError": { "const": false },
-              "exitCode": { "anyOf": [{ "const": 0 }, { "type": "null" }] },
-              "reasonCode": { "type": "null" }
-            }
+            "oneOf": [
+              {
+                "properties": {
+                  "isError": { "const": false },
+                  "exitCode": { "anyOf": [{ "const": 0 }, { "type": "null" }] },
+                  "reasonCode": { "type": "null" }
+                }
+              },
+              {
+                "properties": {
+                  "isError": { "const": false },
+                  "reasonCode": { "const": "search-target-missing" }
+                }
+              }
+            ]
           }
         },
         {

package/schemas/piagent-webui/session-live-state-v1.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://piagent.io.vn/schemas/piagent-webui/session-live-state-v1.schema.json",
+  "title": "Piagent WebUI canonical volatile session operation state v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "version", "generatedAt", "gatewayInstanceRef", "eventSequence", "state", "operations", "settlements", "reasonCode"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "version": { "const": "piagent-session-live-state-v1" },
+    "generatedAt": { "$ref": "common-v1.schema.json#/$defs/timestamp" },
+    "gatewayInstanceRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+    "eventSequence": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+    "state": { "enum": ["ready", "unavailable"] },
+    "operations": {
+      "type": "array",
+      "maxItems": 100,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/currentOperation" }
+    },
+    "settlements": {
+      "description": "Bounded, Gateway-epoch-local non-success terminal operation outcomes retained for Activity reconciliation.",
+      "type": "array",
+      "maxItems": 100,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/terminalSettlement" }
+    },
+    "reasonCode": { "$ref": "common-v1.schema.json#/$defs/nullableReasonCode" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "state": { "const": "ready" } }, "required": ["state"] },
+      "then": { "properties": { "reasonCode": { "type": "null" } } },
+      "else": {
+        "properties": {
+          "operations": { "type": "array", "maxItems": 0 },
+          "settlements": { "type": "array", "maxItems": 0 },
+          "reasonCode": { "$ref": "common-v1.schema.json#/$defs/reasonCode" }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "currentOperation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sessionRef", "operationRef", "state", "abortable"],
+      "properties": {
+        "sessionRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "operationRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "state": { "enum": ["running", "waiting-approval", "settling"] },
+        "abortable": { "type": "boolean" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "state": { "const": "settling" } }, "required": ["state"] },
+          "then": { "properties": { "abortable": { "const": false } } },
+          "else": { "properties": { "abortable": { "const": true } } }
+        }
+      ]
+    },
+    "terminalSettlement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sessionRef", "operationRef", "settlement", "reasonCode", "settledAt", "sequence"],
+      "properties": {
+        "sessionRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "operationRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "settlement": { "enum": ["blocked", "aborted", "error", "unknown"] },
+        "reasonCode": { "$ref": "common-v1.schema.json#/$defs/reasonCode" },
+        "settledAt": { "$ref": "common-v1.schema.json#/$defs/timestamp" },
+        "sequence": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }
+      }
+    }
+  }
+}

package/schemas/piagent-webui/subagent-tree-v1.schema.json

@@ -4,7 +4,7 @@
   "title": "Piagent WebUI bounded subagent ownership tree v1",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schemaVersion", "version", "generatedAt", "identity", "runRef", "state", "treeRevision", "evidenceState", "orchestration", "parent", "children", "writer", "nestedLineage", "summary", "warnings", "health"],
+  "required": ["schemaVersion", "version", "generatedAt", "identity", "runRef", "state", "treeRevision", "evidenceState", "orchestration", "delegation", "parent", "children", "writer", "nestedLineage", "summary", "warnings", "health"],
   "properties": {
     "schemaVersion": { "const": 1 },
     "version": { "const": "piagent-webui-subagent-tree-v1" },
@@ -15,6 +15,7 @@
     "treeRevision": { "$ref": "common-v1.schema.json#/$defs/nullableRevisionToken" },
     "evidenceState": { "enum": ["complete", "partial", "aggregate-only", "missing", "unknown"] },
     "orchestration": { "$ref": "#/$defs/orchestration" },
+    "delegation": { "$ref": "#/$defs/delegation" },
     "parent": { "anyOf": [{ "$ref": "#/$defs/parent" }, { "type": "null" }] },
     "children": { "type": "array", "maxItems": 64, "items": { "$ref": "#/$defs/child" } },
     "writer": { "$ref": "#/$defs/writer" },
@@ -51,6 +52,15 @@
       "mode": { "enum": ["solo-first", "bounded-subagents", "parallel-readonly", "unknown"] },
       "subagents": { "enum": ["not-used", "optional", "used", "unknown"] }
     } },
+    "delegation": { "type": "object", "additionalProperties": false, "required": ["action", "reasonCodes", "projectedNetSavingsRatio", "minimumRequiredNetSavingsRatio", "budget"], "properties": {
+      "action": { "enum": ["dispatch", "skip", "unknown"] },
+      "reasonCodes": { "type": "array", "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z0-9_.:-]+$" } },
+      "projectedNetSavingsRatio": { "type": ["number", "null"], "minimum": -10, "maximum": 1 },
+      "minimumRequiredNetSavingsRatio": { "const": 0.3 },
+      "budget": { "type": "object", "additionalProperties": false, "required": ["maxConcurrent", "maxTotal", "maxRetries", "maxWriters"], "properties": {
+        "maxConcurrent": { "const": 1 }, "maxTotal": { "const": 1 }, "maxRetries": { "const": 0 }, "maxWriters": { "const": 0 }
+      } }
+    } },
     "parent": { "type": "object", "additionalProperties": false, "required": ["nodeRef", "lifecycleState", "budgetTerminal", "mergeOwner"], "properties": {
       "nodeRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" }, "lifecycleState": { "enum": ["active", "terminal", "unknown"] },
       "budgetTerminal": { "type": ["boolean", "null"] }, "mergeOwner": { "const": "parent" }

package/schemas/project-profile.schema.json

@@ -382,7 +382,7 @@
         "maxConcurrentSubagents": {
           "type": "integer",
           "minimum": 0,
-          "maximum": 6
+          "maximum": 1
         },
         "defaultReviewLenses": {
           "type": "array",