@kontourai/flow-agents 3.12.1 → 4.1.0

package/dist/codex/schemas/grounded-execution-narrative.schema.json

@@ -0,0 +1,292 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/grounded-execution-narrative.schema.json",
+  "title": "Flow Agents Grounded Execution Narrative",
+  "$comment": "compiler_sha256 identifies the built envelope module bytes and is therefore build-dependent.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "narrative_id",
+    "provenance",
+    "capture_completeness",
+    "sections",
+    "correlation",
+    "conclusions",
+    "coverage",
+    "unavailable_sources"
+  ],
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "source_id": {
+      "type": "string",
+      "pattern": "^fa1:(telemetry|cmdlog|agent-event|delegation|trust-claim|trust-evidence|flow-state|flow-report|flow-transition|surface-explanation|transcript|file):(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+(?:/(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+)*:(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+(?:/(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+)*(?:#(?:0|[1-9][0-9]*))?$"
+    },
+    "source_refs": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 1,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/source_id" }
+    },
+    "capture_completeness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["channels", "known_gaps"],
+      "properties": {
+        "channels": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "enum": ["active", "inactive", "unknown"]
+          }
+        },
+        "known_gaps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["class", "ref"],
+            "properties": {
+              "class": {
+                "type": "string",
+                "enum": [
+                  "mcp_non_native_tools",
+                  "actor_attribution_conflation",
+                  "cross_session_event_contamination"
+                ]
+              },
+              "ref": { "type": "string", "minLength": 1 },
+              "note": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "flow_section": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["authority", "kind", "source_refs", "sha256", "embedded_bytes"],
+      "properties": {
+        "authority": { "const": "flow" },
+        "kind": { "const": "flow-process-projection" },
+        "source_refs": { "$ref": "#/$defs/source_refs" },
+        "sha256": { "$ref": "#/$defs/sha256" },
+        "embedded_bytes": { "type": "string", "minLength": 1 }
+      }
+    },
+    "surface_section": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["authority", "kind", "source_refs", "sha256", "embedded_bytes"],
+      "properties": {
+        "authority": { "const": "surface" },
+        "kind": { "const": "claim-explanation" },
+        "source_refs": { "$ref": "#/$defs/source_refs" },
+        "sha256": { "$ref": "#/$defs/sha256" },
+        "embedded_bytes": { "type": "string", "minLength": 1 }
+      }
+    },
+    "runtime_section": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["authority", "kind", "sha256", "embedded"],
+      "properties": {
+        "authority": { "const": "flow-agents" },
+        "kind": { "const": "runtime-projection" },
+        "sha256": { "$ref": "#/$defs/sha256" },
+        "embedded": { "type": "object" }
+      }
+    },
+    "correlation_rule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version", "inputs"],
+      "properties": {
+        "id": { "const": "flow-turn-correlation/v1" },
+        "version": { "const": "v1" },
+        "inputs": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/source_id" }
+        }
+      }
+    },
+    "flow_transition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "from", "to", "source_refs", "rule"],
+      "properties": {
+        "kind": { "const": "flow-transition" },
+        "from": { "type": "string", "minLength": 1 },
+        "to": { "type": "string", "minLength": 1 },
+        "at": { "type": "string", "format": "date-time" },
+        "source_refs": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/source_id" }
+        },
+        "rule": { "$ref": "#/$defs/correlation_rule" }
+      }
+    },
+    "unplaced_flow_transition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "from", "to", "source_refs", "rule", "reason"],
+      "properties": {
+        "kind": { "const": "flow-transition" },
+        "from": { "type": "string", "minLength": 1 },
+        "to": { "type": "string", "minLength": 1 },
+        "at": { "type": "string", "minLength": 1 },
+        "source_refs": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/source_id" }
+        },
+        "rule": { "$ref": "#/$defs/correlation_rule" },
+        "reason": { "type": "string", "enum": ["ambiguous_window", "no_timestamp", "no_timezone", "no_turns"] }
+      }
+    },
+    "flow_gate_conclusion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["proposition", "grounding"],
+      "properties": {
+        "proposition": { "type": "string", "minLength": 1 },
+        "grounding": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "source_ref", "pointer"],
+          "properties": {
+            "kind": { "const": "flow_gate_derivation" },
+            "source_ref": { "$ref": "#/$defs/source_id" },
+            "pointer": { "type": "string", "pattern": "^/gate_summaries/(?:0|[1-9][0-9]*)$" }
+          }
+        }
+      }
+    },
+    "surface_conclusion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["proposition", "grounding"],
+      "properties": {
+        "proposition": { "type": "string", "minLength": 1 },
+        "grounding": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "source_ref"],
+          "properties": {
+            "kind": { "const": "surface_explanation" },
+            "source_ref": { "$ref": "#/$defs/source_id" }
+          }
+        }
+      }
+    }
+  },
+  "properties": {
+    "schema_version": { "const": "grounded-execution-narrative/v1" },
+    "narrative_id": { "type": "string", "minLength": 1 },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "compiler",
+        "compiled_at",
+        "manifest_sha256",
+        "schema_sha256",
+        "config_sha256",
+        "compiler_sha256"
+      ],
+      "properties": {
+        "compiler": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["name", "version"],
+          "properties": {
+            "name": { "const": "flow-agents-narrative-composer" },
+            "version": { "type": "string", "minLength": 1 }
+          }
+        },
+        "compiled_at": { "type": "string", "format": "date-time" },
+        "manifest_sha256": { "$ref": "#/$defs/sha256" },
+        "schema_sha256": { "$ref": "#/$defs/sha256" },
+        "config_sha256": { "$ref": "#/$defs/sha256" },
+        "compiler_sha256": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "capture_completeness": { "$ref": "#/$defs/capture_completeness" },
+    "sections": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "anyOf": [
+          { "$ref": "#/$defs/flow_section" },
+          { "$ref": "#/$defs/surface_section" },
+          { "$ref": "#/$defs/runtime_section" }
+        ]
+      }
+    },
+    "correlation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["turns", "unplaced"],
+      "properties": {
+        "turns": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["turn_ordinal", "placed"],
+            "properties": {
+              "turn_ordinal": { "type": "integer", "minimum": -1 },
+              "placed": { "type": "array", "items": { "$ref": "#/$defs/flow_transition" } }
+            }
+          }
+        },
+        "unplaced": { "type": "array", "items": { "$ref": "#/$defs/unplaced_flow_transition" } }
+      }
+    },
+    "conclusions": {
+      "type": "array",
+      "items": {
+        "anyOf": [
+          { "$ref": "#/$defs/flow_gate_conclusion" },
+          { "$ref": "#/$defs/surface_conclusion" }
+        ]
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sources", "embedded", "unavailable"],
+      "properties": {
+        "sources": { "type": "integer", "minimum": 0 },
+        "embedded": { "type": "integer", "minimum": 0 },
+        "unavailable": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "unavailable_sources": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["source_ref", "reason"],
+        "properties": {
+          "source_ref": { "$ref": "#/$defs/source_id" },
+          "reason": {
+            "type": "string",
+            "enum": ["expired", "redacted", "unauthorized", "not_captured", "corrupt"]
+          }
+        }
+      }
+    }
+  }
+}

package/dist/codex/schemas/narrative-eval-result.schema.json

@@ -0,0 +1,205 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/narrative-eval-result.schema.json",
+  "title": "Flow Agents Narrative Eval Result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "work_item",
+    "measurement_note",
+    "results",
+    "metrics",
+    "uncertainty",
+    "capability_parity",
+    "known_gaps"
+  ],
+  "$defs": {
+    "verdict": {
+      "type": "string",
+      "enum": ["accept", "reject", "known_gap"]
+    },
+    "rate": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "metric_uncertainty": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sample_n", "range", "basis"],
+      "properties": {
+        "sample_n": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "range": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": {
+            "type": "number"
+          }
+        },
+        "basis": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "raw_source_link": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source_id", "manifest_path"],
+      "properties": {
+        "source_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "manifest_path": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "result": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "case_class", "expected", "actual", "pass", "raw_source_links"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "case_class": {
+          "type": "string",
+          "minLength": 1
+        },
+        "expected": {
+          "$ref": "#/$defs/verdict"
+        },
+        "actual": {
+          "$ref": "#/$defs/verdict"
+        },
+        "pass": {
+          "type": "boolean"
+        },
+        "raw_source_links": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/raw_source_link"
+          }
+        }
+      }
+    }
+  },
+  "properties": {
+    "schema_version": {
+      "const": "narrative-eval-result/v1"
+    },
+    "work_item": {
+      "type": "string",
+      "minLength": 1
+    },
+    "measurement_note": {
+      "type": "string",
+      "minLength": 1
+    },
+    "results": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/result"
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "unsupported_claim_rate",
+        "citation_precision",
+        "citation_recall",
+        "citation_resolvability",
+        "material_claim_coverage",
+        "omission_rate_by_class",
+        "epistemic_classification_accuracy"
+      ],
+      "properties": {
+        "unsupported_claim_rate": {
+          "$ref": "#/$defs/rate"
+        },
+        "citation_precision": {
+          "$ref": "#/$defs/rate"
+        },
+        "citation_recall": {
+          "$ref": "#/$defs/rate"
+        },
+        "citation_resolvability": {
+          "$ref": "#/$defs/rate"
+        },
+        "material_claim_coverage": {
+          "$ref": "#/$defs/rate"
+        },
+        "omission_rate_by_class": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/rate"
+          }
+        },
+        "epistemic_classification_accuracy": {
+          "$ref": "#/$defs/rate"
+        }
+      }
+    },
+    "uncertainty": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/metric_uncertainty"
+      }
+    },
+    "capability_parity": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["runtime", "capability", "declared_status"],
+        "properties": {
+          "runtime": {
+            "type": "string",
+            "minLength": 1
+          },
+          "capability": {
+            "type": "string",
+            "minLength": 1
+          },
+          "declared_status": {
+            "type": "string",
+            "enum": ["supported", "partial", "unsupported"]
+          }
+        }
+      }
+    },
+    "known_gaps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "detail"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "minLength": 1
+          },
+          "detail": {
+            "type": "string",
+            "minLength": 1
+          },
+          "ref": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  }
+}

package/dist/codex/schemas/narrative-runtime-projection.schema.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/narrative-runtime-projection.schema.json",
+  "title": "Flow Agents Grounded Runtime Projection",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "narrative_id", "provenance", "capture_completeness", "turns", "document_statements", "coverage"],
+  "$defs": {
+    "source_id": {
+      "type": "string",
+      "pattern": "^fa1:(telemetry|cmdlog|agent-event|delegation|trust-claim|trust-evidence|flow-state|flow-report|flow-transition|surface-explanation|transcript|file):(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+(?:/(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+)*:(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+(?:/(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+)*(?:#(?:0|[1-9][0-9]*))?$"
+    },
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "known_gap": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["class", "ref"],
+      "properties": {
+        "class": { "type": "string", "enum": ["mcp_non_native_tools", "actor_attribution_conflation", "cross_session_event_contamination"] },
+        "ref": { "type": "string", "minLength": 1 },
+        "note": { "type": "string", "minLength": 1 }
+      }
+    },
+    "capture_completeness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["channels", "known_gaps"],
+      "properties": {
+        "channels": { "type": "object", "additionalProperties": { "type": "string", "enum": ["active", "inactive", "unknown"] } },
+        "known_gaps": { "type": "array", "items": { "$ref": "#/$defs/known_gap" } }
+      }
+    },
+    "rule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version", "inputs"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "inputs": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/source_id" } }
+      }
+    },
+    "statement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "class", "proposition", "source_refs"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[0-9a-f]{16}$" },
+        "class": { "type": "string", "enum": ["observed", "deterministic_derived"] },
+        "proposition": { "type": "string", "minLength": 1 },
+        "source_refs": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/source_id" } },
+        "turn_ref": { "type": "integer", "minimum": -1 },
+        "actor": { "type": "string", "minLength": 1 },
+        "rule": { "$ref": "#/$defs/rule" }
+      },
+      "oneOf": [
+        {
+          "properties": { "class": { "const": "observed" } },
+          "required": ["class"],
+          "not": { "required": ["rule"] }
+        },
+        {
+          "properties": { "class": { "const": "deterministic_derived" } },
+          "required": ["class", "rule"]
+        }
+      ]
+    },
+    "turn": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ordinal", "sessionId", "boundary", "known_gap_refs", "statements"],
+      "properties": {
+        "ordinal": { "type": "integer", "minimum": -1 },
+        "sessionId": { "type": "string", "minLength": 1 },
+        "turnId": { "type": "string", "minLength": 1 },
+        "boundary": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["derived"],
+          "properties": {
+            "derived": { "type": "boolean" },
+            "rule_id": { "type": "string", "const": "turn-spine/v1" }
+          }
+        },
+        "purpose": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["step", "gate"],
+          "properties": {
+            "step": { "type": "string", "minLength": 1 },
+            "gate": { "type": "string", "minLength": 1 }
+          }
+        },
+        "known_gap_refs": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "statements": { "type": "array", "items": { "$ref": "#/$defs/statement" } }
+      }
+    }
+  },
+  "properties": {
+    "schema_version": { "type": "string", "const": "grounded-runtime-projection/v1" },
+    "narrative_id": { "type": "string", "minLength": 1 },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["projector", "projected_at", "manifest_sha256"],
+      "properties": {
+        "projector": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["name", "version"],
+          "properties": {
+            "name": { "type": "string", "minLength": 1 },
+            "version": { "type": "string", "minLength": 1 }
+          }
+        },
+        "projected_at": { "type": "string", "format": "date-time" },
+        "manifest_sha256": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "capture_completeness": { "$ref": "#/$defs/capture_completeness" },
+    "turns": { "type": "array", "items": { "$ref": "#/$defs/turn" } },
+    "document_statements": { "type": "array", "items": { "$ref": "#/$defs/statement" } },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sources", "cited", "unavailable"],
+      "properties": {
+        "sources": { "type": "integer", "minimum": 0 },
+        "cited": { "type": "integer", "minimum": 0 },
+        "unavailable": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}