@piagent/platform 1.6.1 → 1.8.0

package/schemas/contract-family-library.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://piagent.dev/schemas/contract-family-library.schema.json",
+  "title": "Declarative reusable contract library",
+  "description": "Bounded data templates, not executable oracle code. A {$parameter: name} node is replaced with one typed binding, never evaluated or recursively interpreted. Runtime additionally checks unique identities, used references and full expanded contract semantics.",
+  "type": "object", "additionalProperties": false, "required": ["schemaVersion", "families"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "families": { "type": "array", "minItems": 1, "maxItems": 32, "items": {
+      "type": "object", "additionalProperties": false,
+      "required": ["id", "version", "domain", "description", "parameters", "template"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9:._-]{0,79}$" },
+        "version": { "type": "integer", "minimum": 1, "maximum": 1000000 },
+        "domain": { "enum": ["pure-function", "temporal-input", "configuration-precedence", "stateful-recovery"] },
+        "description": { "type": "string", "minLength": 1, "maxLength": 2000 },
+        "parameters": { "type": "object", "maxProperties": 32, "propertyNames": { "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" },
+          "additionalProperties": { "enum": ["export", "string", "number", "value"] } },
+        "template": { "type": "object", "additionalProperties": false, "required": ["exportName", "checks"], "properties": {
+          "exportName": { "oneOf": [ { "type": "string", "pattern": "^[a-zA-Z_$][a-zA-Z0-9_$]{0,127}$" }, { "$ref": "#/$defs/reference" } ] },
+          "checks": { "type": "array", "minItems": 1, "maxItems": 256, "items": { "type": "object" } }
+        } }
+      }
+    } }
+  },
+  "$defs": { "reference": { "type": "object", "additionalProperties": false, "required": ["$parameter"],
+    "properties": { "$parameter": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } } } }
+}

package/schemas/contract-selection-recipe.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://piagent.dev/schemas/contract-selection-recipe.schema.json",
+  "title": "Reusable contract selection recipe (not authority or evidence)",
+  "description": "Exact criterion text/obligation matching against a task snapshot. No fuzzy source matching. Parameters substitute complete data nodes; the compiler validates the fully expanded independent plan. Unknown or ambiguous requested selections produce no plan.",
+  "type": "object", "additionalProperties": false,
+  "required": ["schemaVersion", "backend", "selections"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "backend": { "$ref": "approved-host-contracts.schema.json#/$defs/backend" },
+    "selections": { "type": "array", "minItems": 1, "maxItems": 12, "items": {
+      "type": "object", "additionalProperties": false,
+      "required": ["criterion", "family", "parameters", "sourcePath", "maxAttempts"],
+      "properties": {
+        "criterion": { "type": "object", "additionalProperties": false, "required": ["text", "obligation"], "properties": {
+          "text": { "type": "string", "minLength": 1, "maxLength": 4000 },
+          "obligation": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9:._-]{0,79}$" }
+        } },
+        "family": { "type": "object", "additionalProperties": false, "required": ["id", "version"], "properties": {
+          "id": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9:._-]{0,79}$" },
+          "version": { "type": "integer", "minimum": 1, "maximum": 1000000 },
+          "digest": { "$ref": "approved-host-contracts.schema.json#/$defs/hash" }
+        } },
+        "parameters": { "type": "object", "maxProperties": 32 },
+        "sourcePath": { "$ref": "approved-host-contracts.schema.json#/$defs/contracts/items/properties/sourcePath" },
+        "modulePaths": { "$ref": "approved-host-contracts.schema.json#/$defs/contracts/items/properties/modulePaths" },
+        "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 8 }
+      }
+    } }
+  }
+}

package/schemas/failure-evidence.schema.json

@@ -10,11 +10,11 @@
     "parserVersion": { "const": "failure-parser-v1" },
     "exitCode": { "type": "integer", "minimum": 0, "maximum": 255 },
     "signals": { "type": "array", "maxItems": 16, "uniqueItems": true, "items": { "$ref": "#/$defs/reason" } },
-    "structuredEvents": { "type": "array", "maxItems": 16, "uniqueItems": true, "items": { "enum": ["scope-violation", "protected-path", "permission-denied", "policy-block", "provider-network", "environment", "flaky-infrastructure", "stale-verifier", "missing-verifier"] } },
+    "structuredEvents": { "type": "array", "maxItems": 16, "uniqueItems": true, "items": { "enum": ["scope-violation", "protected-path", "permission-denied", "policy-block", "provider-network", "environment", "flaky-infrastructure", "stale-verifier", "missing-verifier", "verification-gap"] } },
     "outputRef": { "$ref": "#/$defs/outputRef" }
   },
   "$defs": {
-    "reason": { "enum": ["exit-zero", "structured-scope", "structured-protected-path", "structured-permission", "structured-policy", "structured-provider", "structured-environment", "structured-flaky-infrastructure", "structured-stale-verifier", "structured-missing-verifier", "typescript-diagnostic", "python-type-diagnostic", "go-compile-diagnostic", "rust-compile-diagnostic", "generic-compile-diagnostic", "test-assertion-diagnostic", "lint-format-diagnostic", "dependency-config-diagnostic", "environment-diagnostic", "provider-rate-limit", "provider-transport", "permission-diagnostic", "policy-diagnostic", "scope-diagnostic", "local-port-conflict", "transient-infrastructure", "unknown-diagnostic"] },
+    "reason": { "enum": ["exit-zero", "structured-scope", "structured-protected-path", "structured-permission", "structured-policy", "structured-provider", "structured-environment", "structured-flaky-infrastructure", "structured-stale-verifier", "structured-missing-verifier", "structured-verification-gap", "typescript-diagnostic", "python-type-diagnostic", "go-compile-diagnostic", "rust-compile-diagnostic", "generic-compile-diagnostic", "test-assertion-diagnostic", "lint-format-diagnostic", "dependency-config-diagnostic", "environment-diagnostic", "provider-rate-limit", "provider-transport", "permission-diagnostic", "policy-diagnostic", "scope-diagnostic", "local-port-conflict", "transient-infrastructure", "unknown-diagnostic"] },
     "outputRef": { "type": "object", "additionalProperties": false, "required": ["sha256", "chars", "truncated", "captureRef"], "properties": { "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "chars": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "truncated": { "type": "boolean" }, "captureRef": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,255}$" } } }
   }
 }

package/schemas/helper-request.schema.json

@@ -1,11 +1,11 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://piagent.io.vn/schemas/helper-request.schema.json",
-  "title": "Piagent HelperRequest v1",
+  "title": "Piagent HelperRequest v2",
   "type": "object",
-  "required": ["schemaVersion", "policyVersion", "role", "objectiveHash", "objectiveText", "taskId", "taskRunId", "sessionHash", "authority", "readScope", "writeScope", "allowedTools", "model", "contextBudget", "ceilings", "outputSchema", "stoppingRule", "approvalRestrictions", "parentAuthorityDigest", "singleWriterOwnership", "deduplicationKey"],
+  "required": ["schemaVersion", "policyVersion", "role", "objectiveHash", "objectiveText", "taskId", "taskRunId", "sessionHash", "authority", "readScope", "writeScope", "allowedTools", "model", "contextBudget", "ceilings", "outputSchema", "stoppingRule", "approvalRestrictions", "parentAuthorityDigest", "singleWriterOwnership", "deduplicationKey", "contextTransfer"],
   "properties": {
-    "schemaVersion": { "const": 1 }, "policyVersion": { "const": "role-policy-v1" },
+    "schemaVersion": { "const": 2 }, "policyVersion": { "const": "role-policy-v1" },
     "role": { "enum": ["retriever", "scout", "planner", "worker", "reviewer", "oracle", "researcher"] },
     "objectiveHash": { "$ref": "#/$defs/hash" }, "objectiveText": { "type": "string", "minLength": 3, "maxLength": 1000 },
     "taskId": { "$ref": "#/$defs/ref" }, "taskRunId": { "$ref": "#/$defs/ref" }, "sessionHash": { "$ref": "#/$defs/hash" },
@@ -13,7 +13,19 @@
     "model": { "anyOf": [{ "type": "null" }, { "type": "object", "required": ["provider", "modelId", "effort", "source"], "properties": { "provider": { "$ref": "#/$defs/text" }, "modelId": { "$ref": "#/$defs/text" }, "effort": { "$ref": "#/$defs/text" }, "source": { "$ref": "#/$defs/text" } }, "additionalProperties": false }] },
     "contextBudget": { "type": "integer", "minimum": 256, "maximum": 100000 }, "ceilings": { "$ref": "#/$defs/ceilings" },
     "outputSchema": { "type": "string", "minLength": 3, "maxLength": 200 }, "stoppingRule": { "type": "string", "minLength": 3, "maxLength": 500 }, "approvalRestrictions": { "$ref": "#/$defs/names" },
-    "parentAuthorityDigest": { "$ref": "#/$defs/hash" }, "singleWriterOwnership": { "type": ["string", "null"], "pattern": "^[a-zA-Z0-9][a-zA-Z0-9:._/-]{0,255}$" }, "deduplicationKey": { "$ref": "#/$defs/hash" }
+    "parentAuthorityDigest": { "$ref": "#/$defs/hash" }, "singleWriterOwnership": { "type": ["string", "null"], "pattern": "^[a-zA-Z0-9][a-zA-Z0-9:._/-]{0,255}$" }, "deduplicationKey": { "$ref": "#/$defs/hash" },
+    "contextTransfer": {
+      "description": "Only a bounded isolated seed is transferred. Runtime validation also recomputes estimatedSeedTokens and requires it not to exceed maxSeedTokens.",
+      "type": "object",
+      "required": ["mode", "inheritParentHistory", "maxSeedTokens", "estimatedSeedTokens"],
+      "properties": {
+        "mode": { "const": "isolated-minimal" },
+        "inheritParentHistory": { "const": false },
+        "maxSeedTokens": { "type": "integer", "minimum": 256, "maximum": 2048 },
+        "estimatedSeedTokens": { "type": "integer", "minimum": 0, "maximum": 2048 }
+      },
+      "additionalProperties": false
+    }
   },
   "additionalProperties": false,
   "$defs": {

package/schemas/host-contract-plan.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://piagent.dev/schemas/host-contract-plan.schema.json",
+  "title": "Operator-reviewed independent verification plan",
+  "description": "Input to piagent approve-verification. Expected results must be reviewed independently of the candidate; this file is not itself authority or evidence.",
+  "oneOf": [
+    {"$ref": "approved-host-contracts.schema.json#/$defs/plan"},
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion","plans"],
+      "properties": {
+        "schemaVersion": {"const": 2},
+        "plans": {"type": "array","minItems": 1,"maxItems": 32,"items": {"$ref": "approved-host-contracts.schema.json#/$defs/plan"}}
+      }
+    },
+    {"allOf": [{"$ref": "approved-host-contracts.schema.json#/$defs/planV2"}, {"not": {"required": ["nativeOnly"]}}]},
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion","plans"],
+      "properties": {"schemaVersion": {"const": 4},"plans": {"type": "array","minItems": 1,"maxItems": 32,"items": {"$ref": "approved-host-contracts.schema.json#/$defs/planV2"}}}
+    }
+  ]
+}

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

@@ -326,6 +326,7 @@
                 "sessionRevision": { "$ref": "common-v1.schema.json#/$defs/revisionToken" },
                 "liveState": { "enum": ["offline", "idle", "running", "paused", "waiting-approval", "uncertain"] },
                 "operationRef": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
+                "messageRequestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
                 "reasonCode": { "$ref": "common-v1.schema.json#/$defs/nullableReasonCode" }
               },
               "allOf": [
@@ -379,6 +380,7 @@
               "properties": {
                 "sessionRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
                 "operationRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+                "messageRequestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
                 "messageRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
                 "messageSequence": { "$ref": "#/$defs/stateVersion" },
                 "delta": { "type": "string", "maxLength": 16384, "pattern": "^[^\\u0000]*$" }
@@ -402,6 +404,7 @@
               "properties": {
                 "sessionRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
                 "operationRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+                "messageRequestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
                 "messageRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
                 "sessionRevision": { "$ref": "common-v1.schema.json#/$defs/revisionToken" },
                 "truncated": { "type": "boolean" }
@@ -414,23 +417,26 @@
     "operationCompletedPayload": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["sessionRef", "operationRef", "messageRef", "sessionRevision", "settlement", "reasonCode"],
+      "required": ["sessionRef", "operationRef", "messageRef", "sessionRevision", "settlement", "taskStatus", "reasonCode"],
       "properties": {
         "sessionRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
         "operationRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "messageRequestId": { "$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" },
+        "taskStatus": { "enum": ["pending", "completed", "refused", "failed", "unknown"] },
         "reasonCode": { "type": "null" }
       }
     },
     "operationIncompletePayload": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["sessionRef", "operationRef", "messageRef", "sessionRevision", "settlement", "reasonCode"],
+      "required": ["sessionRef", "operationRef", "messageRef", "sessionRevision", "settlement", "taskStatus", "reasonCode"],
       "properties": {
         "sessionRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
         "operationRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "messageRequestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
         "messageRef": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
         "sessionRevision": {
           "anyOf": [
@@ -439,6 +445,7 @@
           ]
         },
         "settlement": { "enum": ["blocked", "aborted", "error", "unknown"] },
+        "taskStatus": { "enum": ["pending", "completed", "refused", "failed", "unknown"] },
         "reasonCode": { "$ref": "common-v1.schema.json#/$defs/reasonCode" }
       }
     },
@@ -473,8 +480,15 @@
               "properties": {
                 "sessionRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
                 "operationRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+                "messageRequestId": { "$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]+$" },
+                "fileLabel": {
+                  "type": ["string", "null"],
+                  "minLength": 1,
+                  "maxLength": 160,
+                  "pattern": "^[^/\\\\\\u0000-\\u001F\\u007F]+$"
+                },
                 "isError": { "type": ["boolean", "null"] },
                 "reasonCode": { "$ref": "common-v1.schema.json#/$defs/nullableReasonCode" }
               }

package/schemas/piagent-webui/runtime-command-v1.schema.json

@@ -9,7 +9,7 @@
   "$defs": {
     "action": {
       "enum": [
-        "runtime.status", "runtime.inspector", "runtime.commands", "orchestration.status",
+        "runtime.status", "runtime.inspector", "runtime.commands", "runtime.fast-status", "runtime.fast-on", "runtime.fast-off", "orchestration.status",
         "usage.live", "usage.history", "usage.logs", "usage.efficiency", "usage.preflight",
         "onboarding.status", "onboarding.profile", "onboarding.tech",
         "profile.status", "profile.options", "profile.tech-options", "profile.apply", "profile.auto",
@@ -18,7 +18,29 @@
         "mcp.status", "mcp.doctor", "mcp.detail", "mcp.approve", "mcp.reject", "mcp.reset"
       ]
     },
-    "effect": { "enum": ["read-only", "workspace-write", "model-assisted"] },
+    "effect": { "enum": ["read-only", "workspace-write", "model-assisted", "session-setting"] },
+    "serviceTierReceipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion", "enabled", "mode", "source", "requestedServiceTier", "observedRequestServiceTier",
+        "providerResponseServiceTier", "providerResponseEvidence", "provider", "modelId", "applied", "reasonCode"
+      ],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "enabled": { "type": "boolean" },
+        "mode": { "enum": ["standard", "fast"] },
+        "source": { "enum": ["default", "environment", "session-command", "session-state"] },
+        "requestedServiceTier": { "enum": ["fast", null] },
+        "observedRequestServiceTier": { "enum": ["priority", null] },
+        "providerResponseServiceTier": { "type": "null" },
+        "providerResponseEvidence": { "const": "unavailable-host-api" },
+        "provider": { "type": ["string", "null"], "maxLength": 512, "pattern": "^[^\\u0000]*$" },
+        "modelId": { "type": ["string", "null"], "maxLength": 512, "pattern": "^[^\\u0000]*$" },
+        "applied": { "type": "boolean" },
+        "reasonCode": { "enum": ["fast-mode-disabled", "provider-not-supported", "fast-request-pending", "fast-request-observed"] }
+      }
+    },
     "output": {
       "type": "object",
       "additionalProperties": false,
@@ -27,7 +49,8 @@
         "customType": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9._-]+$" },
         "content": { "type": "string", "maxLength": 12000, "pattern": "^[^\\u0000]*$" },
         "truncated": { "type": "boolean" },
-        "redacted": { "type": "boolean" }
+        "redacted": { "type": "boolean" },
+        "details": { "$ref": "#/$defs/serviceTierReceipt" }
       }
     },
     "command": {

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

@@ -2051,6 +2051,25 @@
         }
       ]
     },
+    "streamActivity": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Content-free observations at the Pi message-update hook, not provider usage or network liveness. Only retained at message settlement; absent for legacy events.",
+      "required": ["schemaVersion", "boundary", "observedUpdates", "textUpdates", "thinkingUpdates", "toolCallUpdates", "otherUpdates", "lastUpdateKind", "lastObservedAt", "countersCapped"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "boundary": { "const": "pi-message-update-hook" },
+        "observedUpdates": { "$ref": "#/$defs/streamActivityCount" },
+        "textUpdates": { "$ref": "#/$defs/streamActivityCount" },
+        "thinkingUpdates": { "$ref": "#/$defs/streamActivityCount" },
+        "toolCallUpdates": { "$ref": "#/$defs/streamActivityCount" },
+        "otherUpdates": { "$ref": "#/$defs/streamActivityCount" },
+        "lastUpdateKind": { "enum": [null, "start", "text_start", "text_delta", "text_end", "thinking_start", "thinking_delta", "thinking_end", "toolcall_start", "toolcall_delta", "toolcall_end", "done", "error", "other"] },
+        "lastObservedAt": { "anyOf": [{ "type": "null" }, { "type": "string", "format": "date-time", "maxLength": 40 }] },
+        "countersCapped": { "type": "boolean" }
+      }
+    },
+    "streamActivityCount": { "type": "integer", "minimum": 0, "maximum": 100000 },
     "messageCompletedPayload": {
       "type": "object",
       "additionalProperties": false,
@@ -2090,6 +2109,9 @@
         },
         "usage": {
           "$ref": "#/$defs/nullableTokenUsage"
+        },
+        "streamActivity": {
+          "$ref": "#/$defs/streamActivity"
         }
       }
     },
@@ -2121,6 +2143,9 @@
         },
         "contentDigest": {
           "$ref": "#/$defs/nullableDigest"
+        },
+        "streamActivity": {
+          "$ref": "#/$defs/streamActivity"
         }
       }
     },
@@ -2973,7 +2998,13 @@
               {
                 "properties": {
                   "isError": { "const": false },
-                  "reasonCode": { "const": "search-target-missing" }
+                  "reasonCode": {
+                    "enum": [
+                      "target-not-found",
+                      "target-is-directory",
+                      "search-target-missing"
+                    ]
+                  }
                 }
               }
             ]

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

@@ -48,6 +48,7 @@
       "properties": {
         "sessionRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
         "operationRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "messageRequestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
         "state": { "enum": ["running", "waiting-approval", "settling"] },
         "abortable": { "type": "boolean" }
       },
@@ -66,6 +67,7 @@
       "properties": {
         "sessionRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
         "operationRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "messageRequestId": { "$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" },

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

@@ -1651,6 +1651,9 @@
         "staged"
       ],
       "properties": {
+        "projectionRevision": {
+          "$ref": "common-v1.schema.json#/$defs/revisionToken"
+        },
         "task": {
           "allOf": [
             { "$ref": "#/$defs/sourceViewSummary" },

package/schemas/piagent-webui/source-change-v1.schema.json

@@ -27,6 +27,7 @@
     "identity": { "$ref": "common-v1.schema.json#/$defs/identity" },
     "view": { "$ref": "#/$defs/view" },
     "viewRevision": { "$ref": "common-v1.schema.json#/$defs/revisionToken" },
+    "snapshotBinding": { "$ref": "#/$defs/snapshotBinding" },
     "bases": {
       "type": "array",
       "minItems": 1,
@@ -174,6 +175,17 @@
     "view": {
       "enum": ["task", "working-tree", "staged"]
     },
+    "snapshotBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sourceProjectionRevision", "taskViewRevision", "workspaceRevision", "indexRevision"],
+      "properties": {
+        "sourceProjectionRevision": { "$ref": "common-v1.schema.json#/$defs/revisionToken" },
+        "taskViewRevision": { "$ref": "common-v1.schema.json#/$defs/nullableRevisionToken" },
+        "workspaceRevision": { "$ref": "common-v1.schema.json#/$defs/nullableRevisionToken" },
+        "indexRevision": { "$ref": "common-v1.schema.json#/$defs/nullableRevisionToken" }
+      }
+    },
     "availability": {
       "type": "object",
       "additionalProperties": false,

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

@@ -183,9 +183,10 @@
       "properties": {
         "messageRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
         "parentMessageRef": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
-        "role": { "enum": ["user", "assistant", "tool-result"] },
+        "role": { "enum": ["user", "assistant", "tool-result", "custom"] },
         "recordedAt": { "$ref": "common-v1.schema.json#/$defs/timestamp" },
         "agentOperationId": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
+        "messageRequestId": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
         "turnIndex": { "$ref": "#/$defs/nullableCount" },
         "content": { "$ref": "#/$defs/content" },
         "attachments": {

package/schemas/public-contracts/codex-mcp-metadata-v1.schema.json

@@ -0,0 +1,206 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://piagent.local/schemas/public-contracts/codex-mcp-metadata-v1.schema.json",
+  "title": "PiAgent Codex MCP Metadata Contract v1",
+  "description": "Untrusted, zero-authority params._meta accepted by the scoped benchmark broker.",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "progressToken": {"$ref": "#/$defs/progressToken"}
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["callId", "threadId", "itemId", "x-codex-turn-metadata"],
+      "properties": {
+        "progressToken": {"$ref": "#/$defs/progressToken"},
+        "callId": {"$ref": "#/$defs/id160"},
+        "threadId": {"$ref": "#/$defs/id160"},
+        "itemId": {"$ref": "#/$defs/id160"},
+        "x-codex-turn-metadata": {"$ref": "#/$defs/turnMetadata"},
+        "codex/sandbox-state-meta": {"$ref": "#/$defs/sandboxState"}
+      }
+    }
+  ],
+  "$defs": {
+    "id160": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160,
+      "pattern": "^[A-Za-z0-9_.:-]+$"
+    },
+    "progressToken": {
+      "oneOf": [
+        {"type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991},
+        {"type": "string", "maxLength": 160}
+      ]
+    },
+    "turnMetadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "session_id",
+        "thread_id",
+        "turn_started_at_unix_ms",
+        "turn_id",
+        "node_repl_disabled",
+        "thread_source",
+        "sandbox",
+        "sandbox_mode",
+        "auto_review_enabled",
+        "node_repl_auto_review_required",
+        "model"
+      ],
+      "properties": {
+        "session_id": {"$ref": "#/$defs/id160"},
+        "thread_id": {"$ref": "#/$defs/id160"},
+        "turn_started_at_unix_ms": {"type": "integer", "minimum": 0, "maximum": 9007199254740991},
+        "turn_id": {"$ref": "#/$defs/id160"},
+        "node_repl_disabled": {"type": "boolean"},
+        "thread_source": {"const": "user"},
+        "sandbox": {"type": "string", "minLength": 1, "maxLength": 80},
+        "sandbox_mode": {"const": "workspace-write"},
+        "auto_review_enabled": {"type": "boolean"},
+        "node_repl_auto_review_required": {"type": "boolean"},
+        "model": {"$ref": "#/$defs/id160"},
+        "reasoning_effort": {
+          "enum": ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"]
+        }
+      }
+    },
+    "sandboxState": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["permissionProfile", "codexLinuxSandboxExe", "sandboxCwd", "useLegacyLandlock"],
+      "properties": {
+        "permissionProfile": {"$ref": "#/$defs/permissionProfile"},
+        "codexLinuxSandboxExe": {
+          "oneOf": [
+            {"type": "null"},
+            {"type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^/"}
+          ]
+        },
+        "sandboxCwd": {"type": "string", "minLength": 6, "maxLength": 2048, "pattern": "^file:"},
+        "useLegacyLandlock": {"type": "boolean"}
+      }
+    },
+    "permissionProfile": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type"],
+          "properties": {"type": {"const": "disabled"}}
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "network"],
+          "properties": {
+            "type": {"const": "external"},
+            "network": {"enum": ["restricted", "enabled"]}
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "file_system", "network"],
+          "properties": {
+            "type": {"const": "managed"},
+            "file_system": {"$ref": "#/$defs/fileSystemPermissions"},
+            "network": {"enum": ["restricted", "enabled"]}
+          }
+        }
+      ]
+    },
+    "fileSystemPermissions": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type"],
+          "properties": {"type": {"const": "unrestricted"}}
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "entries"],
+          "properties": {
+            "type": {"const": "restricted"},
+            "entries": {
+              "type": "array",
+              "maxItems": 64,
+              "items": {"$ref": "#/$defs/fileSystemEntry"}
+            },
+            "glob_scan_max_depth": {"type": "integer", "minimum": 1, "maximum": 64}
+          }
+        }
+      ]
+    },
+    "fileSystemEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "access"],
+      "properties": {
+        "path": {"$ref": "#/$defs/fileSystemPath"},
+        "access": {"enum": ["read", "write", "deny"]},
+        "missing_path_behavior": {"const": "skip"}
+      }
+    },
+    "fileSystemPath": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "path"],
+          "properties": {
+            "type": {"const": "path"},
+            "path": {"type": "string", "minLength": 1, "maxLength": 2048}
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "pattern"],
+          "properties": {
+            "type": {"const": "glob_pattern"},
+            "pattern": {"type": "string", "minLength": 1, "maxLength": 2048}
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "value"],
+          "properties": {
+            "type": {"const": "special"},
+            "value": {"$ref": "#/$defs/specialPath"}
+          }
+        }
+      ]
+    },
+    "specialPath": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind"],
+          "properties": {
+            "kind": {"enum": ["root", "minimal", "tmpdir", "slash_tmp"]}
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind"],
+          "properties": {
+            "kind": {"const": "project_roots"},
+            "subpath": {"type": "string", "minLength": 1, "maxLength": 1024}
+          }
+        }
+      ]
+    }
+  }
+}