workspai 0.47.0 → 0.49.0

package/contracts/published-contract-catalog.v1.json

@@ -75,7 +75,9 @@
         "skillsIndex": "workspace-skills-index.v1",
         "agents": null,
         "explain": "workspace-explain.v1",
-        "intelligenceRun": "workspace-intelligence-run.v1"
+        "intelligenceRun": "workspace-intelligence-run.v1",
+        "evaluationLive": "workspace-intelligence-evaluation.v1",
+        "evaluationLastRun": "workspace-intelligence-evaluation.v1"
       },
       "contractPath": null,
       "publication": "embedded-type",
@@ -169,6 +171,16 @@
           "path": ".workspai/reports/workspace-intelligence-run-last-run.json",
           "schemaVersion": "workspace-intelligence-run.v1",
           "contractPath": "contracts/workspace-intelligence/workspace-intelligence-run.v1.json"
+        },
+        "evaluationLive": {
+          "path": ".workspai/reports/workspace-intelligence-evaluation-live.json",
+          "schemaVersion": "workspace-intelligence-evaluation.v1",
+          "contractPath": "contracts/workspace-intelligence/workspace-intelligence-evaluation.v1.json"
+        },
+        "evaluationLastRun": {
+          "path": ".workspai/reports/workspace-intelligence-evaluation-last-run.json",
+          "schemaVersion": "workspace-intelligence-evaluation.v1",
+          "contractPath": "contracts/workspace-intelligence/workspace-intelligence-evaluation.v1.json"
         }
       }
     },
@@ -222,6 +234,11 @@
       "contractPath": "contracts/workspace-intelligence/workspace-knowledge-graph.v1.json",
       "publication": "json-schema"
     },
+    "workspaceGraphStream": {
+      "schemaVersion": "workspace-graph-stream.v1",
+      "contractPath": "contracts/workspace-intelligence/workspace-graph-stream.v1.json",
+      "publication": "json-schema"
+    },
     "workspaceKnowledgeGraphChangeOverlay": {
       "schemaVersion": "workspace-knowledge-graph-change-overlay.v1",
       "contractPath": "contracts/workspace-intelligence/workspace-knowledge-graph-change-overlay.v1.json",
@@ -237,6 +254,21 @@
       "contractPath": "contracts/workspace-intelligence/workspace-graph-token-efficiency.v1.json",
       "publication": "json-schema"
     },
+    "modelUsageEvent": {
+      "schemaVersion": "model-usage-event.v1",
+      "contractPath": "contracts/workspace-intelligence/model-usage-event.v1.json",
+      "publication": "json-schema"
+    },
+    "workspaceIntelligenceEvaluation": {
+      "schemaVersion": "workspace-intelligence-evaluation.v1",
+      "contractPath": "contracts/workspace-intelligence/workspace-intelligence-evaluation.v1.json",
+      "publication": "json-schema"
+    },
+    "workspaceIntelligenceEvaluationComparison": {
+      "schemaVersion": "workspace-intelligence-evaluation-comparison.v1",
+      "contractPath": "contracts/workspace-intelligence/workspace-intelligence-evaluation-comparison.v1.json",
+      "publication": "json-schema"
+    },
     "workspaceIntelligenceHistory": {
       "schemaVersion": "workspace-intelligence-history.v1",
       "contractPath": "contracts/workspace-intelligence/workspace-intelligence-history.v1.json",

package/contracts/runtime-command-surface.v1.json

@@ -856,6 +856,82 @@
         "--json"
       ]
     },
+    {
+      "invocation": "workspace eval",
+      "summary": "Measure model usage, agent activity, cost provenance, and verified task outcomes without storing prompt or response bodies.",
+      "canonicalArgv": [
+        "workspace",
+        "eval",
+        "status",
+        "--json"
+      ],
+      "input": {
+        "transport": "stdin",
+        "mediaType": "application/json",
+        "required": false,
+        "schemaVersion": "model-usage-event.v1",
+        "contractPath": "contracts/workspace-intelligence/model-usage-event.v1.json"
+      },
+      "output": {
+        "defaultFormat": "human-or-json",
+        "modes": [
+          {
+            "selector": "init <task> [strategy] --json",
+            "format": "json",
+            "mediaType": "application/json"
+          },
+          {
+            "selector": "record --json",
+            "format": "json",
+            "mediaType": "application/json"
+          },
+          {
+            "selector": "status --json",
+            "format": "json",
+            "mediaType": "application/json"
+          },
+          {
+            "selector": "report --json",
+            "format": "json",
+            "mediaType": "application/json"
+          },
+          {
+            "selector": "compare --from <report> --json",
+            "format": "json",
+            "mediaType": "application/json"
+          }
+        ]
+      }
+    },
+    {
+      "invocation": "workspace eval init",
+      "summary": "Initialize one live, versioned Workspace Intelligence evaluation run for a fixed task and retrieval strategy.",
+      "canonicalArgv": [
+        "workspace",
+        "eval",
+        "init"
+      ]
+    },
+    {
+      "invocation": "workspace eval record --json",
+      "summary": "Validate one privacy-bounded usage or outcome event from stdin and append it to the live evaluation artifact.",
+      "canonicalArgv": [
+        "workspace",
+        "eval",
+        "record",
+        "--json"
+      ]
+    },
+    {
+      "invocation": "workspace eval report --json",
+      "summary": "Finalize the live evaluation into an authoritative last-run report for IDE, CI, and comparison consumers.",
+      "canonicalArgv": [
+        "workspace",
+        "eval",
+        "report",
+        "--json"
+      ]
+    },
     {
       "invocation": "workspace explain",
       "summary": "Explain a workspace relationship, project, or blocker from traceable model and evidence references.",
@@ -930,7 +1006,7 @@
     },
     {
       "invocation": "workspace graph",
-      "summary": "Render the current workspace dependency graph in a supported representation.",
+      "summary": "Query or export the evidence-backed workspace graph derived from the canonical model.",
       "canonicalArgv": [
         "workspace",
         "graph",
@@ -960,6 +1036,26 @@
             "format": "json",
             "mediaType": "application/json"
           },
+          {
+            "selector": "entities [kind] --json",
+            "format": "json",
+            "mediaType": "application/json"
+          },
+          {
+            "selector": "evidence <id-or-unique-label> --json",
+            "format": "json",
+            "mediaType": "application/json"
+          },
+          {
+            "selector": "path <from> <to> --json",
+            "format": "json",
+            "mediaType": "application/json"
+          },
+          {
+            "selector": "overlay --from <graph> --json",
+            "format": "json",
+            "mediaType": "application/json"
+          },
           {
             "selector": "dot",
             "format": "raw-text",
@@ -969,6 +1065,21 @@
             "selector": "mermaid",
             "format": "raw-text",
             "mediaType": "text/vnd.mermaid"
+          },
+          {
+            "selector": "jsonld",
+            "format": "raw-text",
+            "mediaType": "application/ld+json"
+          },
+          {
+            "selector": "graphml",
+            "format": "raw-text",
+            "mediaType": "application/graphml+xml"
+          },
+          {
+            "selector": "gexf",
+            "format": "raw-text",
+            "mediaType": "application/gexf+xml"
           }
         ]
       }
@@ -1155,8 +1266,24 @@
       "summary": "Observe relevant workspace changes and publish versioned watch events.",
       "canonicalArgv": [
         "workspace",
-        "watch"
-      ]
+        "watch",
+        "--json"
+      ],
+      "output": {
+        "defaultFormat": "human-or-json",
+        "modes": [
+          {
+            "selector": "--json",
+            "format": "json",
+            "mediaType": "application/x-ndjson"
+          },
+          {
+            "selector": "--graph-stream --json",
+            "format": "json",
+            "mediaType": "application/x-ndjson"
+          }
+        ]
+      }
     },
     {
       "invocation": "workspace why",
@@ -1402,6 +1529,37 @@
         ]
       ]
     },
+    {
+      "artifactPath": ".workspai/reports/workspace-intelligence-evaluation-live.json",
+      "schemaVersion": "workspace-intelligence-evaluation.v1",
+      "contractPath": "contracts/workspace-intelligence/workspace-intelligence-evaluation.v1.json",
+      "producerCommands": [
+        [
+          "workspace",
+          "eval",
+          "init"
+        ],
+        [
+          "workspace",
+          "eval",
+          "record",
+          "--json"
+        ]
+      ]
+    },
+    {
+      "artifactPath": ".workspai/reports/workspace-intelligence-evaluation-last-run.json",
+      "schemaVersion": "workspace-intelligence-evaluation.v1",
+      "contractPath": "contracts/workspace-intelligence/workspace-intelligence-evaluation.v1.json",
+      "producerCommands": [
+        [
+          "workspace",
+          "eval",
+          "report",
+          "--json"
+        ]
+      ]
+    },
     {
       "artifactPath": ".workspai/workspace.contract.json",
       "schemaVersion": 1,
@@ -1668,6 +1826,7 @@
     "why",
     "trace",
     "feedback",
+    "eval",
     "mcp",
     "policy",
     "contract",
@@ -1696,6 +1855,7 @@
     "why",
     "trace",
     "feedback",
+    "eval",
     "mcp"
   ],
   "workspaceIntelligenceRootCommands": [

package/contracts/workspace-intelligence/model-usage-event.v1.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/model-usage-event.v1.json",
+  "title": "Workspai Model and Agent Usage Event",
+  "description": "A privacy-bounded usage observation. Prompt and response bodies are deliberately excluded; consumers may provide hashes instead.",
+  "type": "object",
+  "required": ["schemaVersion", "eventId", "recordedAt", "kind"],
+  "properties": {
+    "schemaVersion": { "const": "model-usage-event.v1" },
+    "eventId": { "type": "string", "minLength": 1 },
+    "recordedAt": { "type": "string", "format": "date-time" },
+    "kind": { "enum": ["model-call", "tool-call", "outcome", "milestone"] },
+    "stage": { "type": "string", "minLength": 1 },
+    "modelCall": {
+      "type": "object",
+      "required": ["provider", "model", "source", "inputTokens", "outputTokens", "cachedInputTokens", "reasoningTokens", "latencyMs"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "model": { "type": "string", "minLength": 1 },
+        "source": { "enum": ["provider-reported", "tokenizer-counted", "estimated", "unavailable"] },
+        "tokenizer": { "type": "string", "minLength": 1 },
+        "inputTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "outputTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "cachedInputTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "reasoningTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "latencyMs": { "type": ["number", "null"], "minimum": 0 },
+        "promptHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "responseHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "cost": {
+          "type": "object",
+          "required": ["amount", "currency", "source"],
+          "properties": {
+            "amount": { "type": "number", "minimum": 0 },
+            "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+            "source": { "enum": ["provider-reported", "catalog-estimated"] }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "toolCall": {
+      "type": "object",
+      "required": ["tool", "result", "changedSource", "durationMs"],
+      "properties": {
+        "tool": { "type": "string", "minLength": 1 },
+        "result": { "enum": ["passed", "failed", "blocked", "skipped"] },
+        "changedSource": { "type": "boolean" },
+        "durationMs": { "type": ["number", "null"], "minimum": 0 },
+        "artifact": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "outcome": {
+      "type": "object",
+      "required": ["status", "verified", "blockersResolved"],
+      "properties": {
+        "status": { "enum": ["passed", "failed", "blocked", "unknown"] },
+        "verified": { "type": "boolean" },
+        "blockersResolved": { "type": "integer", "minimum": 0 },
+        "summary": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "milestone": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "detail": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "allOf": [
+    { "if": { "properties": { "kind": { "const": "model-call" } } }, "then": { "properties": { "modelCall": {} }, "required": ["modelCall"] } },
+    { "if": { "properties": { "kind": { "const": "tool-call" } } }, "then": { "properties": { "toolCall": {} }, "required": ["toolCall"] } },
+    { "if": { "properties": { "kind": { "const": "outcome" } } }, "then": { "properties": { "outcome": {} }, "required": ["outcome"] } },
+    { "if": { "properties": { "kind": { "const": "milestone" } } }, "then": { "properties": { "milestone": {} }, "required": ["milestone"] } }
+  ],
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/workspace-graph-stream.v1.json

@@ -0,0 +1,262 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/workspace-graph-stream.v1.json",
+  "title": "Workspai Workspace Graph Stream",
+  "description": "Transport-neutral, revision-safe events for hydrating and incrementally updating a Workspace Knowledge Graph consumer.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "type",
+    "workspaceId",
+    "sessionId",
+    "generation",
+    "revision",
+    "modelHash",
+    "graphHash",
+    "generatedAt",
+    "causationId",
+    "correlationId",
+    "payload"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "workspace-graph-stream.v1" },
+    "type": {
+      "enum": [
+        "graph.snapshot",
+        "graph.delta",
+        "graph.provider-progress",
+        "graph.quality-changed",
+        "graph.proof-invalidated",
+        "graph.resync-required",
+        "graph.paused",
+        "graph.complete",
+        "graph.heartbeat",
+        "graph.error"
+      ]
+    },
+    "workspaceId": { "type": "string", "minLength": 1 },
+    "sessionId": { "type": "string", "minLength": 1 },
+    "generation": { "type": "integer", "minimum": 0 },
+    "baseRevision": { "type": "integer", "minimum": 0 },
+    "baseModelHash": { "$ref": "#/$defs/hash" },
+    "baseGraphHash": { "$ref": "#/$defs/hash" },
+    "revision": { "type": "integer", "minimum": 0 },
+    "modelHash": { "$ref": "#/$defs/hash" },
+    "graphHash": { "$ref": "#/$defs/hash" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "causationId": { "type": "string", "minLength": 1 },
+    "correlationId": { "type": "string", "minLength": 1 },
+    "payload": { "type": "object" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "type": { "const": "graph.snapshot" } } },
+      "then": {
+        "properties": {
+          "payload": { "$ref": "#/$defs/snapshotPayload" },
+          "baseRevision": false,
+          "baseModelHash": false,
+          "baseGraphHash": false
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "graph.delta" } } },
+      "then": {
+        "required": ["baseRevision", "baseModelHash", "baseGraphHash"],
+        "properties": { "payload": { "$ref": "#/$defs/deltaPayload" } }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "graph.provider-progress" } } },
+      "then": { "properties": { "payload": { "$ref": "#/$defs/providerProgressPayload" } } }
+    },
+    {
+      "if": { "properties": { "type": { "const": "graph.quality-changed" } } },
+      "then": { "properties": { "payload": { "$ref": "#/$defs/qualityPayload" } } }
+    },
+    {
+      "if": { "properties": { "type": { "const": "graph.proof-invalidated" } } },
+      "then": { "properties": { "payload": { "$ref": "#/$defs/proofInvalidatedPayload" } } }
+    },
+    {
+      "if": { "properties": { "type": { "const": "graph.resync-required" } } },
+      "then": { "properties": { "payload": { "$ref": "#/$defs/resyncPayload" } } }
+    },
+    {
+      "if": {
+        "properties": {
+          "type": { "enum": ["graph.paused", "graph.complete", "graph.heartbeat"] }
+        }
+      },
+      "then": { "properties": { "payload": { "$ref": "#/$defs/controlPayload" } } }
+    },
+    {
+      "if": { "properties": { "type": { "const": "graph.error" } } },
+      "then": { "properties": { "payload": { "$ref": "#/$defs/errorPayload" } } }
+    }
+  ],
+  "$defs": {
+    "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "id": { "type": "string", "minLength": 1 },
+    "snapshotPayload": {
+      "type": "object",
+      "required": ["graph"],
+      "properties": {
+        "graph": { "$ref": "workspace-knowledge-graph.v1.json" },
+        "reason": { "enum": ["initial", "refresh", "recovery", "schema-transition"] }
+      },
+      "additionalProperties": false
+    },
+    "deltaPayload": {
+      "type": "object",
+      "required": [
+        "entitiesAdded",
+        "entitiesUpdated",
+        "entitiesRemoved",
+        "relationsAdded",
+        "relationsUpdated",
+        "relationsRemoved",
+        "proofsAdded",
+        "proofsUpdated",
+        "proofsRemoved",
+        "providersUpdated",
+        "diagnostics"
+      ],
+      "properties": {
+        "entitiesAdded": {
+          "type": "array",
+          "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/entities/items" }
+        },
+        "entitiesUpdated": {
+          "type": "array",
+          "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/entities/items" }
+        },
+        "entitiesRemoved": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/id" },
+          "uniqueItems": true
+        },
+        "relationsAdded": {
+          "type": "array",
+          "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/relations/items" }
+        },
+        "relationsUpdated": {
+          "type": "array",
+          "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/relations/items" }
+        },
+        "relationsRemoved": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/id" },
+          "uniqueItems": true
+        },
+        "proofsAdded": {
+          "type": "array",
+          "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/proofs/items" }
+        },
+        "proofsUpdated": {
+          "type": "array",
+          "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/proofs/items" }
+        },
+        "proofsRemoved": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/id" },
+          "uniqueItems": true
+        },
+        "providersUpdated": {
+          "type": "array",
+          "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/providers/items" }
+        },
+        "quality": {
+          "oneOf": [
+            { "type": "null" },
+            { "$ref": "workspace-knowledge-graph.v1.json#/properties/quality" }
+          ]
+        },
+        "diagnostics": {
+          "type": "array",
+          "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/diagnostics/items" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "providerProgressPayload": {
+      "type": "object",
+      "required": ["providerId", "status"],
+      "properties": {
+        "providerId": { "$ref": "#/$defs/id" },
+        "status": { "enum": ["queued", "running", "passed", "partial", "skipped", "failed"] },
+        "completed": { "type": "integer", "minimum": 0 },
+        "total": { "type": "integer", "minimum": 0 },
+        "message": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "qualityPayload": {
+      "type": "object",
+      "required": ["quality"],
+      "properties": {
+        "quality": { "$ref": "workspace-knowledge-graph.v1.json#/properties/quality" },
+        "diagnostics": {
+          "type": "array",
+          "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/diagnostics/items" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "proofInvalidatedPayload": {
+      "type": "object",
+      "required": ["proofIds", "reason"],
+      "properties": {
+        "proofIds": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/id" },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "reason": { "type": "string", "minLength": 1 },
+        "entityIds": { "type": "array", "items": { "$ref": "#/$defs/id" }, "uniqueItems": true },
+        "relationIds": { "type": "array", "items": { "$ref": "#/$defs/id" }, "uniqueItems": true }
+      },
+      "additionalProperties": false
+    },
+    "resyncPayload": {
+      "type": "object",
+      "required": ["reason"],
+      "properties": {
+        "reason": {
+          "enum": [
+            "revision-gap",
+            "identity-mismatch",
+            "generation-regression",
+            "schema-unsupported",
+            "hash-discontinuity",
+            "validation-failed",
+            "queue-overflow"
+          ]
+        },
+        "expectedRevision": { "type": "integer", "minimum": 0 },
+        "receivedBaseRevision": { "type": "integer", "minimum": 0 },
+        "message": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "controlPayload": {
+      "type": "object",
+      "properties": { "reason": { "type": "string" }, "message": { "type": "string" } },
+      "additionalProperties": false
+    },
+    "errorPayload": {
+      "type": "object",
+      "required": ["code", "message", "recoverable"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "recoverable": { "type": "boolean" },
+        "providerId": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}