From c8a3b8422e11287b1810d3c460f5bb3bae4e9d62 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Fri, 3 Apr 2026 15:54:28 -0400 Subject: [PATCH 01/16] Add core agent-plane execution decision schema --- schemas/ExecutionDecision.json | 87 ++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 schemas/ExecutionDecision.json diff --git a/schemas/ExecutionDecision.json b/schemas/ExecutionDecision.json new file mode 100644 index 0000000..9df827f --- /dev/null +++ b/schemas/ExecutionDecision.json @@ -0,0 +1,87 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/ExecutionDecision.json", + "title": "ExecutionDecision", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "sessionRef", + "decision", + "reason", + "issuedAt", + "decisionHash" + ], + "properties": { + "id": { + "type": "string", + "pattern": "^urn:srcos:exec-decision:" + }, + "type": { + "const": "ExecutionDecision" + }, + "specVersion": { + "type": "string" + }, + "sessionRef": { + "type": "string", + "pattern": "^urn:srcos:session:" + }, + "toolRequestRef": { + "type": [ + "string", + "null" + ], + "pattern": "^urn:srcos:tool:" + }, + "decision": { + "enum": [ + "allow", + "deny", + "ask", + "defer", + "rewrite" + ] + }, + "reason": { + "type": "string" + }, + "updatedInput": { + "type": [ + "object", + "null" + ], + "additionalProperties": true + }, + "policyRef": { + "type": [ + "string", + "null" + ], + "pattern": "^urn:srcos:policy:" + }, + "obligations": { + "type": "array", + "items": { + "type": "string" + } + }, + "issuedAt": { + "type": "string", + "format": "date-time" + }, + "expiresAt": { + "type": [ + "string", + "null" + ], + "format": "date-time" + }, + "decisionHash": { + "type": "string", + "pattern": "^sha256:" + } + } +} From 9a58a6496c10120e090ed71047804b11a2f7ec60 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Fri, 3 Apr 2026 15:55:14 -0400 Subject: [PATCH 02/16] Add core agent-plane session schema --- schemas/AgentSession.json | 157 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 schemas/AgentSession.json diff --git a/schemas/AgentSession.json b/schemas/AgentSession.json new file mode 100644 index 0000000..d9ddf72 --- /dev/null +++ b/schemas/AgentSession.json @@ -0,0 +1,157 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/AgentSession.json", + "title": "AgentSession", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "role", + "status", + "mode", + "workspaceRef", + "substrate", + "surface", + "skillRefs", + "memoryRefs", + "decisionRefs", + "time" + ], + "properties": { + "id": { + "type": "string", + "pattern": "^urn:srcos:session:" + }, + "type": { + "const": "AgentSession" + }, + "specVersion": { + "type": "string" + }, + "parentSessionRef": { + "type": [ + "string", + "null" + ], + "pattern": "^urn:srcos:session:" + }, + "role": { + "enum": [ + "main", + "explorer", + "planner", + "executor", + "reviewer", + "auditor", + "reverser", + "custom" + ] + }, + "status": { + "enum": [ + "created", + "waiting", + "running", + "paused", + "completed", + "failed", + "canceled", + "merged", + "reversed" + ] + }, + "mode": { + "enum": [ + "plan", + "ask", + "execute", + "review" + ] + }, + "workspaceRef": { + "type": "string" + }, + "worktreeRef": { + "type": [ + "string", + "null" + ] + }, + "substrate": { + "enum": [ + "local", + "remote-local", + "cloud", + "background", + "event-pushed", + "ci" + ] + }, + "surface": { + "$ref": "ExecutionSurface.json" + }, + "provider": { + "type": [ + "string", + "null" + ] + }, + "skillRefs": { + "type": "array", + "items": { + "type": "string", + "pattern": "^urn:srcos:skill:" + } + }, + "memoryRefs": { + "type": "array", + "items": { + "type": "string", + "pattern": "^urn:srcos:memory:" + } + }, + "transcriptRef": { + "type": [ + "string", + "null" + ], + "pattern": "^urn:srcos:transcript:" + }, + "decisionRefs": { + "type": "array", + "items": { + "type": "string", + "pattern": "^urn:srcos:exec-decision:" + } + }, + "telemetryRefs": { + "type": "array", + "items": { + "type": "string", + "pattern": "^urn:srcos:telemetry:" + } + }, + "time": { + "type": "object", + "additionalProperties": false, + "required": [ + "startedAt" + ], + "properties": { + "startedAt": { + "type": "string", + "format": "date-time" + }, + "endedAt": { + "type": [ + "string", + "null" + ], + "format": "date-time" + } + } + } + } +} From 18b17cf0d352b732f1720e57607b3d37d29aed46 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Fri, 3 Apr 2026 15:55:45 -0400 Subject: [PATCH 03/16] Add core agent-plane execution surface schema --- schemas/ExecutionSurface.json | 77 +++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 schemas/ExecutionSurface.json diff --git a/schemas/ExecutionSurface.json b/schemas/ExecutionSurface.json new file mode 100644 index 0000000..cfe2242 --- /dev/null +++ b/schemas/ExecutionSurface.json @@ -0,0 +1,77 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/ExecutionSurface.json", + "title": "ExecutionSurface", + "type": "object", + "additionalProperties": false, + "required": [ + "pty", + "workdir", + "background", + "reviewOnly", + "worktreeStrategy", + "sandboxMode", + "networkMode", + "egressAllowlist", + "elevated" + ], + "properties": { + "pty": { + "type": "boolean" + }, + "workdir": { + "type": "string" + }, + "background": { + "type": "boolean" + }, + "reviewOnly": { + "type": "boolean" + }, + "worktreeStrategy": { + "enum": [ + "none", + "existing", + "create-temp", + "named" + ] + }, + "sandboxMode": { + "enum": [ + "none", + "user", + "container", + "vm", + "browser-sandbox" + ] + }, + "networkMode": { + "enum": [ + "none", + "allowlist", + "full" + ] + }, + "egressAllowlist": { + "type": "array", + "items": { + "type": "string" + } + }, + "elevated": { + "type": "boolean" + }, + "protectedPaths": { + "type": "array", + "items": { + "type": "string" + } + }, + "approvalProfile": { + "type": [ + "string", + "null" + ] + } + } +} From 4f72ce63a6338e2c2a4e57e5804a2208f16c8b43 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Fri, 3 Apr 2026 15:56:09 -0400 Subject: [PATCH 04/16] Add core agent-plane skill manifest schema --- schemas/SkillManifest.json | 125 +++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 schemas/SkillManifest.json diff --git a/schemas/SkillManifest.json b/schemas/SkillManifest.json new file mode 100644 index 0000000..cee0455 --- /dev/null +++ b/schemas/SkillManifest.json @@ -0,0 +1,125 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/SkillManifest.json", + "title": "SkillManifest", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "name", + "version", + "entryDoc", + "description", + "activationRules", + "requires", + "policyBindings", + "artifactOutputs", + "reviewMode", + "allowShellExecution" + ], + "properties": { + "id": { + "type": "string", + "pattern": "^urn:srcos:skill:" + }, + "type": { + "const": "SkillManifest" + }, + "specVersion": { + "type": "string" + }, + "name": { + "type": "string" + }, + "version": { + "type": "string" + }, + "entryDoc": { + "type": "string" + }, + "description": { + "type": "string" + }, + "activationRules": { + "type": "object", + "additionalProperties": false, + "properties": { + "commands": { + "type": "array", + "items": { + "type": "string" + } + }, + "filePatterns": { + "type": "array", + "items": { + "type": "string" + } + }, + "intentTags": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "requires": { + "type": "object", + "additionalProperties": false, + "properties": { + "binaries": { + "type": "array", + "items": { + "type": "string" + } + }, + "anyBins": { + "type": "array", + "items": { + "type": "string" + } + }, + "tools": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "executionSurfaceRef": { + "type": [ + "string", + "null" + ], + "pattern": "^urn:srcos:surface:" + }, + "policyBindings": { + "type": "array", + "items": { + "type": "string" + } + }, + "artifactOutputs": { + "type": "array", + "items": { + "type": "string" + } + }, + "reviewMode": { + "type": "boolean" + }, + "allowShellExecution": { + "type": "boolean" + }, + "protectedPaths": { + "type": "array", + "items": { + "type": "string" + } + } + } +} From 04ba49d5efe36b796906a96432f2d3619e6d92e0 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Fri, 3 Apr 2026 16:12:43 -0400 Subject: [PATCH 05/16] Add core agent-plane memory entry schema --- schemas/MemoryEntry.json | 115 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 schemas/MemoryEntry.json diff --git a/schemas/MemoryEntry.json b/schemas/MemoryEntry.json new file mode 100644 index 0000000..8001cda --- /dev/null +++ b/schemas/MemoryEntry.json @@ -0,0 +1,115 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/MemoryEntry.json", + "title": "MemoryEntry", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "kind", + "namespace", + "key", + "payloadRef", + "citationRefs", + "scope", + "freshness" + ], + "properties": { + "id": { + "type": "string", + "pattern": "^urn:srcos:memory:" + }, + "type": { + "const": "MemoryEntry" + }, + "specVersion": { + "type": "string" + }, + "kind": { + "enum": [ + "rule", + "learned", + "recap" + ] + }, + "namespace": { + "type": "string" + }, + "key": { + "type": "string" + }, + "payloadRef": { + "type": "string" + }, + "authoritativeRef": { + "type": [ + "string", + "null" + ] + }, + "citationRefs": { + "type": "array", + "items": { + "type": "string" + } + }, + "scope": { + "type": "object", + "additionalProperties": false, + "required": [ + "workspace", + "pathPrefixes" + ], + "properties": { + "workspace": { + "type": [ + "string", + "null" + ] + }, + "pathPrefixes": { + "type": "array", + "items": { + "type": "string" + } + }, + "sessionRef": { + "type": [ + "string", + "null" + ], + "pattern": "^urn:srcos:session:" + } + } + }, + "freshness": { + "type": "object", + "additionalProperties": false, + "required": [ + "learnedAt" + ], + "properties": { + "learnedAt": { + "type": "string", + "format": "date-time" + }, + "reviewedAt": { + "type": [ + "string", + "null" + ], + "format": "date-time" + }, + "ttl": { + "type": [ + "integer", + "null" + ], + "minimum": 0 + } + } + } + } +} From fc045fd58012cbb0b4d3b388e7386980b3065add Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Fri, 3 Apr 2026 16:14:44 -0400 Subject: [PATCH 06/16] Add core agent-plane session receipt schema --- schemas/SessionReceipt.json | 66 +++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 schemas/SessionReceipt.json diff --git a/schemas/SessionReceipt.json b/schemas/SessionReceipt.json new file mode 100644 index 0000000..31685ab --- /dev/null +++ b/schemas/SessionReceipt.json @@ -0,0 +1,66 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/SessionReceipt.json", + "title": "SessionReceipt", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "sessionRef", + "status", + "artifactRefs", + "decisionRefs", + "gateResults", + "capturedAt" + ], + "properties": { + "id": { + "type": "string", + "pattern": "^urn:srcos:receipt:session:" + }, + "type": { + "const": "SessionReceipt" + }, + "specVersion": { + "type": "string" + }, + "sessionRef": { + "type": "string", + "pattern": "^urn:srcos:session:" + }, + "status": { + "enum": [ + "success", + "failure", + "paused", + "deferred", + "canceled" + ] + }, + "artifactRefs": { + "type": "array", + "items": { + "type": "string" + } + }, + "decisionRefs": { + "type": "array", + "items": { + "type": "string", + "pattern": "^urn:srcos:exec-decision:" + } + }, + "gateResults": { + "type": "array", + "items": { + "type": "string" + } + }, + "capturedAt": { + "type": "string", + "format": "date-time" + } + } +} From fad0bd4f350eca0a276176b6596b955668070143 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sat, 4 Apr 2026 03:06:54 -0400 Subject: [PATCH 07/16] Add agent-plane OpenAPI patch fragment --- openapi.agent-plane.patch.yaml | 56 ++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 openapi.agent-plane.patch.yaml diff --git a/openapi.agent-plane.patch.yaml b/openapi.agent-plane.patch.yaml new file mode 100644 index 0000000..b4cdf8c --- /dev/null +++ b/openapi.agent-plane.patch.yaml @@ -0,0 +1,56 @@ +# additive OpenAPI patch fragment for the core agent-plane schema family +paths: + /v2/sessions: + post: + operationId: upsertAgentSession + requestBody: + required: true + content: + application/json: + schema: { $ref: './schemas/AgentSession.json' } + responses: + '200': { description: ok } + /v2/execution/decide: + post: + operationId: decideExecution + requestBody: + required: true + content: + application/json: + schema: { $ref: './schemas/ExecutionDecision.json' } + responses: + '200': + description: execution decision + content: + application/json: + schema: { $ref: './schemas/ExecutionDecision.json' } + /v2/skills: + post: + operationId: upsertSkillManifest + requestBody: + required: true + content: + application/json: + schema: { $ref: './schemas/SkillManifest.json' } + responses: + '200': { description: ok } + /v2/memory: + post: + operationId: upsertMemoryEntry + requestBody: + required: true + content: + application/json: + schema: { $ref: './schemas/MemoryEntry.json' } + responses: + '200': { description: ok } + /v2/receipts/session: + post: + operationId: recordSessionReceipt + requestBody: + required: true + content: + application/json: + schema: { $ref: './schemas/SessionReceipt.json' } + responses: + '200': { description: ok } From ece9aacd5c2543c720b37c5acf77aabcca563d33 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sat, 4 Apr 2026 03:12:20 -0400 Subject: [PATCH 08/16] Add agent-plane AsyncAPI patch fragment --- asyncapi.agent-plane.patch.yaml | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 asyncapi.agent-plane.patch.yaml diff --git a/asyncapi.agent-plane.patch.yaml b/asyncapi.agent-plane.patch.yaml new file mode 100644 index 0000000..8e7f200 --- /dev/null +++ b/asyncapi.agent-plane.patch.yaml @@ -0,0 +1,27 @@ +# additive AsyncAPI patch fragment for the core agent-plane schema family +channels: + srcos.v2.session.events: + publish: + message: + name: SessionEvent + payload: { $ref: './schemas/EventEnvelope.json' } + srcos.v2.execution.events: + publish: + message: + name: ExecutionEvent + payload: { $ref: './schemas/EventEnvelope.json' } + srcos.v2.skill.events: + publish: + message: + name: SkillEvent + payload: { $ref: './schemas/EventEnvelope.json' } + srcos.v2.memory.events: + publish: + message: + name: MemoryEvent + payload: { $ref: './schemas/EventEnvelope.json' } + srcos.v2.receipt.events: + publish: + message: + name: ReceiptEvent + payload: { $ref: './schemas/EventEnvelope.json' } From a6cdd725d576bdf17635824c6cf0ae28cc459e77 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sat, 4 Apr 2026 04:01:17 -0400 Subject: [PATCH 09/16] Add session review schema for reflective continuity --- schemas/SessionReview.json | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 schemas/SessionReview.json diff --git a/schemas/SessionReview.json b/schemas/SessionReview.json new file mode 100644 index 0000000..dbd93f0 --- /dev/null +++ b/schemas/SessionReview.json @@ -0,0 +1,26 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/SessionReview.json", + "title": "SessionReview", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "sessionRef", + "summaryRef", + "learnedMemoryRefs", + "reviewedAt" + ], + "properties": { + "id": {"type": "string", "pattern": "^urn:srcos:session-review:"}, + "type": {"const": "SessionReview"}, + "specVersion": {"type": "string"}, + "sessionRef": {"type": "string", "pattern": "^urn:srcos:session:"}, + "summaryRef": {"type": "string"}, + "learnedMemoryRefs": {"type": "array", "items": {"type": "string", "pattern": "^urn:srcos:memory:"}}, + "followupRefs": {"type": "array", "items": {"type": "string"}}, + "reviewedAt": {"type": "string", "format": "date-time"} + } +} From f98d97927a353a27b07c8ffb9cb635eabfb7760d Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sat, 4 Apr 2026 04:03:58 -0400 Subject: [PATCH 10/16] Add experiment flag schema for rollout state --- schemas/ExperimentFlag.json | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 schemas/ExperimentFlag.json diff --git a/schemas/ExperimentFlag.json b/schemas/ExperimentFlag.json new file mode 100644 index 0000000..b20b8c2 --- /dev/null +++ b/schemas/ExperimentFlag.json @@ -0,0 +1,18 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/ExperimentFlag.json", + "title": "ExperimentFlag", + "type": "object", + "additionalProperties": false, + "required": ["id","type","specVersion","name","state"], + "properties": { + "id": {"type": "string", "pattern": "^urn:srcos:flag:"}, + "type": {"const": "ExperimentFlag"}, + "specVersion": {"type": "string"}, + "name": {"type": "string"}, + "state": {"enum": ["off","shadow","internal","beta","on","retired"]}, + "owner": {"type": ["string","null"]}, + "description": {"type": ["string","null"]}, + "killSwitch": {"type": "boolean"} + } +} From 255ba4b458e213b0a10779397dc41bc48de36cfd Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sat, 4 Apr 2026 04:09:27 -0400 Subject: [PATCH 11/16] Add rollout policy schema for controlled feature exposure --- schemas/RolloutPolicy.json | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 schemas/RolloutPolicy.json diff --git a/schemas/RolloutPolicy.json b/schemas/RolloutPolicy.json new file mode 100644 index 0000000..3353c05 --- /dev/null +++ b/schemas/RolloutPolicy.json @@ -0,0 +1,28 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/RolloutPolicy.json", + "title": "RolloutPolicy", + "type": "object", + "additionalProperties": false, + "required": ["id","type","specVersion","flagRef","rules"], + "properties": { + "id": {"type": "string", "pattern": "^urn:srcos:rollout:"}, + "type": {"const": "RolloutPolicy"}, + "specVersion": {"type": "string"}, + "flagRef": {"type": "string", "pattern": "^urn:srcos:flag:"}, + "rules": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["audience","state"], + "properties": { + "audience": {"type": "string"}, + "state": {"enum": ["off","shadow","internal","beta","on"]}, + "percentage": {"type": ["number","null"], "minimum": 0, "maximum": 100} + } + } + }, + "notes": {"type": ["string","null"]} + } +} From 4817114b2c2ee2dc9e1170ba2e60225aef9f3641 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sat, 4 Apr 2026 04:14:45 -0400 Subject: [PATCH 12/16] Add telemetry event schema scaffold --- schemas/TelemetryEvent.json | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 schemas/TelemetryEvent.json diff --git a/schemas/TelemetryEvent.json b/schemas/TelemetryEvent.json new file mode 100644 index 0000000..af10c58 --- /dev/null +++ b/schemas/TelemetryEvent.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/TelemetryEvent.json", + "title": "TelemetryEvent", + "type": "object", + "additionalProperties": false, + "required": ["id","type","specVersion","sessionRef","eventType","capturedAt"], + "properties": { + "id": {"type": "string", "pattern": "^urn:srcos:telemetry:"}, + "type": {"const": "TelemetryEvent"}, + "specVersion": {"type": "string"}, + "sessionRef": {"type": "string", "pattern": "^urn:srcos:session:"}, + "eventType": {"type": "string"}, + "severity": {"enum": ["debug","info","warn","error"]}, + "capturedAt": {"type": "string", "format": "date-time"} + } +} From c72156182933df96fb6e62f20a62b10d952fd281 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sat, 4 Apr 2026 04:18:02 -0400 Subject: [PATCH 13/16] Add frustration signal schema scaffold --- schemas/FrustrationSignal.json | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 schemas/FrustrationSignal.json diff --git a/schemas/FrustrationSignal.json b/schemas/FrustrationSignal.json new file mode 100644 index 0000000..9e92b23 --- /dev/null +++ b/schemas/FrustrationSignal.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/FrustrationSignal.json", + "title": "FrustrationSignal", + "type": "object", + "additionalProperties": false, + "required": ["id","type","specVersion","sessionRef","signal","capturedAt"], + "properties": { + "id": {"type": "string", "pattern": "^urn:srcos:frustration:"}, + "type": {"const": "FrustrationSignal"}, + "specVersion": {"type": "string"}, + "sessionRef": {"type": "string", "pattern": "^urn:srcos:session:"}, + "signal": {"enum": ["strong-negative-language","cancel","repeated-failure","tool-loop","user-interrupt"]}, + "count": {"type": ["integer","null"], "minimum": 0}, + "capturedAt": {"type": "string", "format": "date-time"} + } +} From 1b292d78e24b06594c25fc0f1f5e45998a46e179 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sat, 4 Apr 2026 04:24:39 -0400 Subject: [PATCH 14/16] Add release receipt schema for publish verification --- schemas/ReleaseReceipt.json | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 schemas/ReleaseReceipt.json diff --git a/schemas/ReleaseReceipt.json b/schemas/ReleaseReceipt.json new file mode 100644 index 0000000..93d6d97 --- /dev/null +++ b/schemas/ReleaseReceipt.json @@ -0,0 +1,19 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/ReleaseReceipt.json", + "title": "ReleaseReceipt", + "type": "object", + "additionalProperties": false, + "required": ["id","type","specVersion","releaseTarget","verifiedAt","status"], + "properties": { + "id": {"type": "string", "pattern": "^urn:srcos:release-receipt:"}, + "type": {"const": "ReleaseReceipt"}, + "specVersion": {"type": "string"}, + "releaseTarget": {"type": "string"}, + "sourceRef": {"type": ["string","null"]}, + "artifactHashes": {"type": "array", "items": {"type": "string"}}, + "checks": {"type": "array", "items": {"type": "string"}}, + "status": {"enum": ["verified","failed","partial"]}, + "verifiedAt": {"type": "string", "format": "date-time"} + } +} From 8e8bc4607b0b61f0d30cfb40839102271234df19 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sun, 5 Apr 2026 14:09:35 -0400 Subject: [PATCH 15/16] Update README.md with comprehensive agent-plane schema documentation --- schemas/README.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 schemas/README.md diff --git a/schemas/README.md b/schemas/README.md new file mode 100644 index 0000000..32f9acd --- /dev/null +++ b/schemas/README.md @@ -0,0 +1,39 @@ +# Agent-Plane Schema Documentation + +## Overview +This document provides comprehensive details about the Agent-Plane schemas, including usage examples, URN patterns, spec metadata explanation, and validation instructions. + +## Usage Examples +### Example 1: Basic Usage +```json +{ + "exampleKey": "exampleValue" +} +``` + +### Example 2: Advanced Usage +```json +{ + "advancedKey": [{ + "nestedKey": "nestedValue" + }] +} +``` + +## URN Patterns +The URN patterns for the agent-plane schemas follow the structure: `urn:example::`. +- **Example:** `urn:sourceos:agent:12345` + +## Spec Metadata Explanation +- **version:** The version of the schema being used. +- **description:** A brief overview of the schema. + +## Validation Instructions +To validate the agent-plane schema, use the following command: +```bash +jsonschema -i example.json schema.json +``` +Make sure to replace `example.json` with your JSON data file and `schema.json` with your schema file. + +## Conclusion +This documentation serves as a reference for working with Agent-Plane schemas. For further details, please refer to the additional resources provided in the repository. \ No newline at end of file From 38e2a06d5523d05c103a01074f1a896c8492358b Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sun, 5 Apr 2026 14:32:29 -0400 Subject: [PATCH 16/16] Comprehensive agent-plane schema documentation push to the repository. --- schemas/README.md | 86 +++++++++++++++++++++++++++++++++++------------ 1 file changed, 64 insertions(+), 22 deletions(-) diff --git a/schemas/README.md b/schemas/README.md index 32f9acd..4e72b03 100644 --- a/schemas/README.md +++ b/schemas/README.md @@ -1,39 +1,81 @@ -# Agent-Plane Schema Documentation +# Agent Plane Schema Documentation ## Overview -This document provides comprehensive details about the Agent-Plane schemas, including usage examples, URN patterns, spec metadata explanation, and validation instructions. +This document provides comprehensive documentation on the Agent Plane schemas, including URN patterns, specification metadata explanation, and usage examples for key entities such as ExecutionDecision, AgentSession, and SessionReceipt. + +## Schema Families Table +| Schema Family | Description | +|-----------------------|-------------------------------------------| +| ExecutionDecision | Represents the decision made by the agent. | +| AgentSession | Represents a session of an agent. | +| SessionReceipt | Represents a receipt for a session. | + +## URN Patterns +### ExecutionDecision URN +- **Pattern**: `urn:sourceos:execution:decision:` + +### AgentSession URN +- **Pattern**: `urn:sourceos:agent:session:` + +### SessionReceipt URN +- **Pattern**: `urn:sourceos:receipt:` + +## Schema Metadata Explanation +Each schema includes metadata that describes its purpose, version, and last updated information. + +- **Version**: Indicates the version of the schema. +- **Last Updated**: Date when the schema was last modified. ## Usage Examples -### Example 1: Basic Usage +### ExecutionDecision Example ```json { - "exampleKey": "exampleValue" + "id": "urn:sourceos:execution:decision:12345", + "metadata": { + "version": "1.0", + "lastUpdated": "2026-04-05" + }, + "decision": "approve" } ``` -### Example 2: Advanced Usage +### AgentSession Example ```json { - "advancedKey": [{ - "nestedKey": "nestedValue" - }] + "id": "urn:sourceos:agent:session:12345", + "metadata": { + "version": "1.0", + "lastUpdated": "2026-04-05" + }, + "status": "active" } ``` -## URN Patterns -The URN patterns for the agent-plane schemas follow the structure: `urn:example::`. -- **Example:** `urn:sourceos:agent:12345` - -## Spec Metadata Explanation -- **version:** The version of the schema being used. -- **description:** A brief overview of the schema. +### SessionReceipt Example +```json +{ + "id": "urn:sourceos:receipt:12345", + "metadata": { + "version": "1.0", + "lastUpdated": "2026-04-05" + }, + "result": "success" +} +``` ## Validation Instructions -To validate the agent-plane schema, use the following command: -```bash -jsonschema -i example.json schema.json -``` -Make sure to replace `example.json` with your JSON data file and `schema.json` with your schema file. +Schema validation must be performed against the JSON Schema specification outlined in the [official documentation](https://json-schema.org/). + +## Versioning Discipline +Follow semantic versioning for all schema updates: +- Major version when incompatible API changes are made, +- Minor version when functionality is added in a backward-compatible manner, +- Patch version when backward-compatible bug fixes are introduced. + +## Current Status +All schemas are currently under active development. All feedback is welcomed. -## Conclusion -This documentation serves as a reference for working with Agent-Plane schemas. For further details, please refer to the additional resources provided in the repository. \ No newline at end of file +## References +- [JSON Schema Official Website](https://json-schema.org/) +- SourceOS Documentation +- API Reference links \ No newline at end of file