@percepteye/agent-flywheel 0.1.0

package/schema/flywheel-1.json

@@ -0,0 +1,432 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.percepteye.ai/flywheel/1.json",
+  "title": "PerceptEye Flywheel contract, version 1",
+  "description": "The wire contract between a customer-run agent and the PerceptEye control plane. THIS FILE IS THE AUTHORITY. Server implementations pin against the published schema; the schema is never generated from a server type. The Python types in src/agent_flywheel/contract.py are hand-written to match this file, not generated from it, and the test suite asserts the two agree.",
+  "x-contract-version": "flywheel/1",
+  "$defs": {
+    "ToolCallRecord": {
+      "type": "object",
+      "description": "One tool call the agent executed. FLYWHEEL-AUTHORED.",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "outcome",
+        "status_code"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "arguments": {
+          "type": "object"
+        },
+        "outcome": {
+          "description": "REQUIRED, no default. 'unknown' is a first-class, legal value and is the honest answer whenever the framework did not expose a real verdict \u2014 for example a LangChain tool with handle_tool_error=True, which catches its own exception and returns a string that reads like a normal result. 'unknown' must NEVER be rounded up to 'ok'. Maps server-side to a tri-state: ok->true, failed->false, unknown->null, on which outcome-dependent verifiers correctly abstain.",
+          "enum": [
+            "ok",
+            "failed",
+            "unknown"
+          ]
+        },
+        "status_code": {
+          "description": "REQUIRED KEY, nullable value. The HTTP status observed on the wire, or null. MUST be null when outcome is 'unknown': a status may confirm or contradict an observed outcome, it may never manufacture one. Sending outcome='unknown' alongside status_code=200 is the exact shape that scores a failed call as a landed mutation.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 100,
+          "maximum": 599
+        },
+        "output": {
+          "description": "Tool result. Scrubbed of machine-readable status when outcome is 'unknown'."
+        },
+        "error": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "error_class": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "latency_ms": {
+          "type": [
+            "number",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "agent_name": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Which agent in a multi-agent system made this call. null means unattributed, which is NOT a claim that one agent made everything."
+        },
+        "tool_call_id": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The id the MODEL assigned to this call (LangChain ToolMessage.tool_call_id, ADK function_call_id, OpenAI tool_calls[].id). The join key for attributing a call to the completion that emitted it: the same id reappears on the role='tool' message of the agent's NEXT request, so attribution needs no clocks and survives concurrent tools. null/absent means the framework exposed no id -- the call still counts, it just cannot be placed more precisely than 'somewhere in this rollout'."
+        },
+        "entity_ids": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          },
+          "propertyNames": {
+            "enum": [
+              "id",
+              "key",
+              "uuid",
+              "sid",
+              "gid"
+            ]
+          },
+          "description": "Identity the write produced, filed under the field it came from. Present so the entity can be found again later without retaining the response body. High-entropy fields only: a low-entropy value a different entity shares by coincidence identifies the wrong resource. Absent or empty means no identity evidence, which is an abstention and never a failure."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "outcome": {
+                "const": "unknown"
+              }
+            },
+            "required": [
+              "outcome"
+            ]
+          },
+          "then": {
+            "properties": {
+              "status_code": {
+                "type": "null"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "ProductionTurn": {
+      "type": "object",
+      "description": "One customer production turn captured by attach(). Turn-native evidence, not a training row. task_id is caller-authored correlation evidence only and grants no training eligibility.",
+      "additionalProperties": false,
+      "required": [
+        "turn_id",
+        "input_text",
+        "final_text",
+        "tool_calls",
+        "tool_calls_omitted_count"
+      ],
+      "properties": {
+        "turn_id": {
+          "description": "Exact caller turn id. In addition to the shared production identifier grammar, it is one storage-safe path segment: slash, backslash, and the dot segments . and .. are forbidden.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "pattern": "^(?!\\.{1,2}$)(?!\\s)(?!.*\\s$)(?!.*[\\\\/])[^\\u0000-\\u001F\\u007F-\\u009F]+$"
+        },
+        "task_id": {
+          "description": "Optional opaque task/case/work-item identifier supplied by the customer. It is an exact correlation candidate for control-plane validation, never a success label, hint, policy identity, or permission to train.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001F\\u007F-\\u009F]+$"
+        },
+        "conversation_id": {
+          "description": "Optional opaque correlation id using the shared production identifier grammar: no leading/trailing whitespace or C0/C1 control characters.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001F\\u007F-\\u009F]+$"
+        },
+        "turn_index": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "input_text": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "final_text": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "tool_calls": {
+          "description": "null means not reported; [] means observed zero calls.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/$defs/ToolCallRecord"
+          }
+        },
+        "tool_calls_omitted_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "agent_fingerprint": {
+          "type": "object"
+        },
+        "occurred_at": {
+          "description": "Optional RFC 3339 time at which the customer agent produced the turn. Receipt and retention clocks remain control-plane authored.",
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "ProductionTurnBatch": {
+      "type": "object",
+      "description": "The body sent to POST /turns.",
+      "additionalProperties": false,
+      "required": [
+        "agent_id",
+        "turns"
+      ],
+      "properties": {
+        "agent_id": {
+          "description": "Opaque customer agent id using the shared production identifier grammar. Because it is also a URL path segment, slash, backslash, and the dot segments . and .. are forbidden; remaining transport characters are percent-encoded.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "pattern": "^(?!\\.{1,2}$)(?!\\s)(?!.*\\s$)(?!.*[\\\\/])[^\\u0000-\\u001F\\u007F-\\u009F]+$"
+        },
+        "turns": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "$ref": "#/$defs/ProductionTurn"
+          }
+        }
+      }
+    },
+    "Exclusion": {
+      "type": "object",
+      "description": "The flywheel's typed 'do not train on this' signal. Distinct from a low reward: a substrate fault is not a policy failure.",
+      "additionalProperties": false,
+      "required": [
+        "reason"
+      ],
+      "properties": {
+        "reason": {
+          "enum": [
+            "flywheel_crash",
+            "substrate_unavailable",
+            "credential_expired",
+            "deadline_exceeded",
+            "entrypoint_error",
+            "agent_exit_nonzero",
+            "cancelled",
+            "capacity"
+          ]
+        },
+        "detail": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "RolloutRequest": {
+      "type": "object",
+      "description": "PERCEPTEYE-AUTHORED. Handed to the agent for one rollout. Note there is deliberately NO 'environment' key: the only configuration channel into the agent is subprocess environment at spawn. A previous SDK wrote server-supplied values into the RUNNING process's os.environ, which was both dangerous and useless (the LLM client had already read its base_url at construction).",
+      "additionalProperties": false,
+      "required": [
+        "rollout_id",
+        "turn_input",
+        "llm_url",
+        "api_key",
+        "artifacts_dir",
+        "deadline_ts"
+      ],
+      "properties": {
+        "rollout_id": {
+          "description": "Minted by the control plane BEFORE the agent runs anything. This is the attribution unit; it is never a per-process session id.",
+          "type": "string",
+          "minLength": 1
+        },
+        "turn_input": {
+          "type": "string"
+        },
+        "llm_url": {
+          "description": "Per-rollout, unguessable, single-use, expiring. A shared or process-global URL is not an acceptable fallback: it destroys per-rollout attribution and collides across concurrent rollouts.",
+          "type": "string",
+          "format": "uri"
+        },
+        "api_key": {
+          "type": "string",
+          "minLength": 1
+        },
+        "artifacts_dir": {
+          "type": "string"
+        },
+        "deadline_ts": {
+          "description": "Authoritative. The flywheel computes its timeout from this, never from a local environment variable.",
+          "type": "number"
+        },
+        "lease_token": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "lease_expires_ts": {
+          "description": "Absolute epoch seconds at which the lease the server GRANTED expires, as of this claim. Not the work deadline: deadline_ts is the rollout's budget and does not move. The flywheel reads this ONCE, at claim, and paces its heartbeats at a third of the remaining grant for the life of the rollout; it does not re-read a renewed expiry, because heartbeat responses are not parsed and RolloutRequest is frozen. Absent means the server does not report what it granted, and the client falls back to the lease it requested -- which is wrong whenever the server clamped that request down.",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "metadata": {
+          "type": "object"
+        }
+      }
+    },
+    "RolloutOutput": {
+      "type": "object",
+      "description": "FLYWHEEL-AUTHORED. Every field a customer-run flywheel may assert, and the complete set: the SDK is semi-trusted, so anything PerceptEye authors during scoring or training is absent by construction here and rejected at intake if present. The properties below are the whole allowed vocabulary -- additionalProperties is false, so what is permitted is stated positively rather than by listing what is not.",
+      "additionalProperties": false,
+      "required": [
+        "final_text"
+      ],
+      "properties": {
+        "final_text": {
+          "type": "string"
+        },
+        "tool_calls": {
+          "description": "null means NOT REPORTED. [] means OBSERVED ZERO CALLS -- a positive assertion. These are different and the wire keeps them different; the default is null so an agent that reports nothing never accidentally asserts zero. If any executed call cannot be classified, either emit it with outcome='unknown' or set this to null for the WHOLE rollout -- never a partial list, because a truncated list is indistinguishable from a short one and corrupts every set-reasoning verifier.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/$defs/ToolCallRecord"
+          }
+        },
+        "tool_calls_omitted_count": {
+          "description": "Executed calls deliberately not reported. Non-zero forbids training grade.",
+          "type": "integer",
+          "minimum": 0,
+          "default": 0
+        },
+        "llm_call_count": {
+          "description": "Completions the agent believes it issued. Reconciled against the gateway's own count; a mismatch means traffic escaped our wire and the rollout cannot be treated as on-policy.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "artifacts": {
+          "description": "name -> artifact record. A string value is the file's sha256 digest (or a named skip marker such as 'skipped:too_large:N'). An object value additionally INLINES the body of a small UTF-8 file -- for coding/REPL flywheels the files are the deliverable, and a grader that can verify a digest but never read the file proves integrity while grading nothing. Inline bodies are capped per file and per report; binary or over-cap files keep the string form.",
+          "type": "object",
+          "additionalProperties": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "sha256",
+                  "size_bytes",
+                  "content"
+                ],
+                "properties": {
+                  "sha256": {
+                    "type": "string",
+                    "minLength": 64,
+                    "maxLength": 64
+                  },
+                  "size_bytes": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "content": {
+                    "type": "string"
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "reward": {
+          "description": "ADVISORY ONLY. Recorded on the rollout row. PerceptEye's compiled suite remains the scored suite; this scalar never reaches the dataset emitters in v1.",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "success": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "exclusion": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/Exclusion"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "events": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        },
+        "timing": {
+          "type": "object"
+        },
+        "agent_fingerprint": {
+          "description": "ATTESTATION, not an authenticated identity. The customer-declared half of the scaffold identity (SDK version, flywheel version, declared memory/skills/subagent digests). The server-derived half -- rendered-prompt sha, tool-schema digest, sampling params, tokenizer -- is computed at the gateway from the observed wire and is never accepted from here. The two are recorded separately and never conflated.",
+          "type": [
+            "object",
+            "null"
+          ]
+        }
+      }
+    },
+    "ClaimResponse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "rollouts",
+        "poll_after_ms"
+      ],
+      "properties": {
+        "rollouts": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/RolloutRequest"
+          }
+        },
+        "poll_after_ms": {
+          "description": "Server-directed backoff. An empty claim returns 200 with an empty list and this hint -- never a bare 204, which carries no backoff information and forces the client to invent its own.",
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}