monarchic-agent-protocol 0.1.15 → 0.1.17
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +374 -51
- data/schemas/v1/agent_role.json +4 -1
- data/schemas/v1/artifact.json +18 -0
- data/schemas/v1/dataset_ref.json +2 -13
- data/schemas/v1/eval_result.json +1 -5
- data/schemas/v1/event.json +15 -42
- data/schemas/v1/execution_receipt.json +69 -0
- data/schemas/v1/experiment_spec.json +3 -16
- data/schemas/v1/failure_class.json +46 -0
- data/schemas/v1/failure_detail.json +33 -0
- data/schemas/v1/gate_result.json +16 -16
- data/schemas/v1/google.protobuf.Struct.schema.json +7 -0
- data/schemas/v1/monarchic.agent_protocol.v1.DatasetRef.schema.json +9 -0
- data/schemas/v1/monarchic.agent_protocol.v1.EvalResult.schema.json +9 -0
- data/schemas/v1/monarchic.agent_protocol.v1.ExperimentSpec.schema.json +9 -0
- data/schemas/v1/monarchic.agent_protocol.v1.ObjectiveSpec.schema.json +9 -0
- data/schemas/v1/monarchic.agent_protocol.v1.RunContext.schema.json +9 -0
- data/schemas/v1/monarchic_agent_protocol.proto +1205 -16
- data/schemas/v1/objective_spec.json +4 -15
- data/schemas/v1/plan.json +55 -0
- data/schemas/v1/plan_provenance.json +25 -0
- data/schemas/v1/plan_status.json +17 -0
- data/schemas/v1/plan_step.json +31 -0
- data/schemas/v1/provenance.json +1 -8
- data/schemas/v1/role_provenance.json +22 -0
- data/schemas/v1/schema.json +54 -6
- data/schemas/v1/task.json +42 -27
- data/src/ruby/monarchic_agent_protocol_pb.rb +116 -2
- metadata +16 -3
- data/schemas/v1/delivery_contract.json +0 -78
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: e70cc011515a1d46f8b369074834a2abc5ee0d30f928636b333d78e1bcbda9af
|
|
4
|
+
data.tar.gz: 39007a55b96bd1273f66c377063c0a3adba90acff4044be335a8dd2dbcbcb041
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 74384051cc3abf842ec9725ce9cc4842a84481c26ddf4247f423d620ec3a5ff87a36d8721525f839745f188d5f4d236596d42055689acc27ccd478bd86b3328e
|
|
7
|
+
data.tar.gz: 408137845db2c3e52def8b77a0c6c33fb80d7da283cd1c44c816f35fd862bff5ed427831873ed7aebe97db6366b2530d2c90848c132e5aad8400c91a224a53e3
|
data/README.md
CHANGED
|
@@ -32,6 +32,7 @@ Install the published package for your language, then use the generated bindings
|
|
|
32
32
|
|
|
33
33
|
- Rust: `examples/rust/task.rs`
|
|
34
34
|
- TypeScript: `examples/ts/task.ts`
|
|
35
|
+
- JSON (non-protobuf): `examples/json/objective_spec.minimal.json`
|
|
35
36
|
- Protobuf C++: `examples/proto/cpp/task.cpp`
|
|
36
37
|
- Protobuf Java: `examples/proto/java/TaskExample.java`
|
|
37
38
|
- Protobuf Kotlin: `examples/proto/kotlin/TaskExample.kt`
|
|
@@ -42,11 +43,106 @@ Install the published package for your language, then use the generated bindings
|
|
|
42
43
|
- Protobuf Dart: `examples/proto/dart/task.dart`
|
|
43
44
|
- Protobuf Rust: `examples/proto/rust/task.rs`
|
|
44
45
|
|
|
46
|
+
### Non-protobuf language support
|
|
47
|
+
|
|
48
|
+
For languages that do not use protobuf bindings, exchange protocol objects as JSON and validate payloads against the versioned schemas before handoff.
|
|
49
|
+
|
|
50
|
+
- Canonical JSON example for non-protobuf consumers: `examples/json/objective_spec.minimal.json`
|
|
51
|
+
- Validate a typed payload against a specific schema: `bash scripts/validate-protocol-json.sh schemas/v1/objective_spec.json schemas/fixtures/valid/objective_spec.minimal.json`
|
|
52
|
+
- Validate the canonical non-protobuf JSON example: `bash scripts/validate-protocol-json.sh schemas/v1/objective_spec.json examples/json/objective_spec.minimal.json`
|
|
53
|
+
|
|
54
|
+
Project-state contract fixtures used by the shell verification suite live under `fixtures/project-state/`, not the repo root.
|
|
55
|
+
|
|
45
56
|
### Versioning
|
|
46
57
|
|
|
47
58
|
- Protocol versions live under `schemas/v1/`.
|
|
48
59
|
- Each v1 object requires `version: "v1"`.
|
|
49
60
|
- New versions must be added under a new directory (e.g. `schemas/v2/`) without changing existing v1 files.
|
|
61
|
+
- The package/crate transition operator runbook lives at
|
|
62
|
+
[`docs/protocol-release-transition-runbook.md`](docs/protocol-release-transition-runbook.md).
|
|
63
|
+
|
|
64
|
+
### Client boundary contracts
|
|
65
|
+
|
|
66
|
+
The Rust crate also exposes a frozen client-boundary surface under `monarchic_agent_protocol::client_boundary`.
|
|
67
|
+
|
|
68
|
+
Frozen v1 client-boundary types:
|
|
69
|
+
|
|
70
|
+
- `Intent`
|
|
71
|
+
- `Plan`
|
|
72
|
+
- `PlanStep`
|
|
73
|
+
- `ExecutionReceipt`
|
|
74
|
+
- `VerificationReceipt`
|
|
75
|
+
- `PublicationAction`
|
|
76
|
+
- `ModerationDecision`
|
|
77
|
+
- `ReviewDecision`
|
|
78
|
+
- `RerunScope`
|
|
79
|
+
- `BlockedOutcome`
|
|
80
|
+
- `ArtifactDescriptor`
|
|
81
|
+
|
|
82
|
+
Canonical JSON fixtures for these contracts live under `fixtures/client_boundary/v1/`.
|
|
83
|
+
The protocol-owned MAP operation handoff bundle for downstream client snapshots
|
|
84
|
+
also lives there as `map_operation_bundle.v1.json`.
|
|
85
|
+
Legacy runtime compatibility fixtures live under `fixtures/client_boundary/v0/`.
|
|
86
|
+
|
|
87
|
+
### Durable authority contracts
|
|
88
|
+
|
|
89
|
+
The Rust crate also exposes a frozen durable-authority surface under `monarchic_agent_protocol::durable_authority`.
|
|
90
|
+
|
|
91
|
+
Frozen v1 durable-authority types:
|
|
92
|
+
|
|
93
|
+
- `FencingToken`
|
|
94
|
+
- `Lease`
|
|
95
|
+
- `RunLifecycleState`
|
|
96
|
+
- `StepLifecycleState`
|
|
97
|
+
- `LeaseRejectionReason`
|
|
98
|
+
- `RecoveryEvent`
|
|
99
|
+
- `ManualOverrideRecord`
|
|
100
|
+
|
|
101
|
+
Canonical JSON fixtures for these contracts live under `fixtures/durable_authority/v1/`.
|
|
102
|
+
|
|
103
|
+
### Service boundary contracts
|
|
104
|
+
|
|
105
|
+
The Rust crate also exposes a frozen service-boundary surface under `monarchic_agent_protocol::service_boundary`.
|
|
106
|
+
|
|
107
|
+
Frozen v1 service-boundary types:
|
|
108
|
+
|
|
109
|
+
- `PrincipalRef`
|
|
110
|
+
- `TenantRef`
|
|
111
|
+
- `AuthContext`
|
|
112
|
+
- `UsageRecord`
|
|
113
|
+
- `AuditExportManifest`
|
|
114
|
+
- `ControlPlaneQueueJob`
|
|
115
|
+
- `ControlPlaneDispatchRequest`
|
|
116
|
+
|
|
117
|
+
The queue job contract uses the explicit wire marker
|
|
118
|
+
`monarchic.control-plane.queue-job.v1` because it is consumed across the API,
|
|
119
|
+
control-plane queue, and worker boundary. Canonical JSON fixtures for
|
|
120
|
+
service-boundary contracts live under `fixtures/service_boundary/v1/`.
|
|
121
|
+
The cross-service protocol ownership boundary is documented in
|
|
122
|
+
[`docs/service-boundary-architecture.md`](docs/service-boundary-architecture.md).
|
|
123
|
+
|
|
124
|
+
## Lean4 Formalization
|
|
125
|
+
|
|
126
|
+
A Lean4 proof model now lives under `formal/lean/`.
|
|
127
|
+
|
|
128
|
+
It currently formalizes a bounded set of invariants derived from real downstream usage in this workspace:
|
|
129
|
+
|
|
130
|
+
- client-boundary id safety heuristics
|
|
131
|
+
- role normalization aliases
|
|
132
|
+
- verification receipt status consistency
|
|
133
|
+
- terminal lifecycle sink behavior
|
|
134
|
+
- plan dependency grounding
|
|
135
|
+
- protobuf message well-formedness and cross-message integrity
|
|
136
|
+
- protobuf lifecycle transitions and bounded lease control-plane safety
|
|
137
|
+
- protobuf request/report admissibility and fencing-token monotonicity
|
|
138
|
+
- bounded protobuf control-plane trace safety and authority preservation
|
|
139
|
+
- inductive consistency preservation over protobuf control-plane event traces
|
|
140
|
+
- continuous active-authority traces preserve the bound `(run_id, step_id, task_id)` scope
|
|
141
|
+
- active traces exclude competing authorities for the same `(run_id, step_id)` scope
|
|
142
|
+
- a checked protobuf coverage manifest makes the currently formalized subset explicit relative to the full `.proto` surface
|
|
143
|
+
- the schema-side Lean coverage manifest is generated from `schemas/v1/monarchic_agent_protocol.proto` and validated in CI
|
|
144
|
+
|
|
145
|
+
See `docs/lean4-formal-verification.md` for scope and usage.
|
|
50
146
|
|
|
51
147
|
### Schema summary
|
|
52
148
|
|
|
@@ -58,9 +154,16 @@ Schema files live under `schemas/v1/`:
|
|
|
58
154
|
- `schemas/v1/artifact.json`
|
|
59
155
|
- `schemas/v1/event.json`
|
|
60
156
|
- `schemas/v1/gate_result.json`
|
|
157
|
+
- `schemas/v1/failure_class.json`
|
|
158
|
+
- `schemas/v1/plan_status.json`
|
|
159
|
+
- `schemas/v1/failure_detail.json`
|
|
160
|
+
- `schemas/v1/role_provenance.json`
|
|
161
|
+
- `schemas/v1/plan_provenance.json`
|
|
162
|
+
- `schemas/v1/plan_step.json`
|
|
163
|
+
- `schemas/v1/plan.json`
|
|
164
|
+
- `schemas/v1/execution_receipt.json`
|
|
61
165
|
- `schemas/v1/run_context.json`
|
|
62
166
|
- `schemas/v1/run_outcome.json`
|
|
63
|
-
- `schemas/v1/delivery_contract.json`
|
|
64
167
|
- `schemas/v1/agent_role.json`
|
|
65
168
|
- `schemas/v1/dataset_ref.json`
|
|
66
169
|
- `schemas/v1/experiment_spec.json`
|
|
@@ -80,12 +183,69 @@ All schemas allow additional properties for forward compatibility.
|
|
|
80
183
|
- `schemas/v1/artifact.json`
|
|
81
184
|
- `schemas/v1/event.json`
|
|
82
185
|
- `schemas/v1/gate_result.json`
|
|
186
|
+
- `schemas/v1/failure_class.json`
|
|
187
|
+
- `schemas/v1/plan_status.json`
|
|
188
|
+
- `schemas/v1/failure_detail.json`
|
|
189
|
+
- `schemas/v1/role_provenance.json`
|
|
190
|
+
- `schemas/v1/plan_provenance.json`
|
|
191
|
+
- `schemas/v1/plan_step.json`
|
|
192
|
+
- `schemas/v1/plan.json`
|
|
193
|
+
- `schemas/v1/execution_receipt.json`
|
|
83
194
|
- `schemas/v1/run_context.json`
|
|
84
|
-
- `schemas/v1/
|
|
195
|
+
- `schemas/v1/dataset_ref.json`
|
|
196
|
+
- `schemas/v1/experiment_spec.json`
|
|
197
|
+
- `schemas/v1/objective_spec.json`
|
|
198
|
+
- `schemas/v1/eval_result.json`
|
|
199
|
+
- `schemas/v1/provenance.json`
|
|
85
200
|
|
|
86
201
|
`schemas/v1/agent_role.json` is a shared schema used by `task.json`.
|
|
87
|
-
`schemas/v1/
|
|
88
|
-
|
|
202
|
+
`schemas/v1/failure_class.json` is a shared schema used by `event.json` and `gate_result.json`.
|
|
203
|
+
|
|
204
|
+
### TaskMessage and TaskMessageAck
|
|
205
|
+
|
|
206
|
+
These types define the shared contract for orchestrator-mediated runner
|
|
207
|
+
communication.
|
|
208
|
+
|
|
209
|
+
They are intended for:
|
|
210
|
+
|
|
211
|
+
- durable handoff messages between active tasks
|
|
212
|
+
- clarification requests and responses
|
|
213
|
+
- blocker notices
|
|
214
|
+
- artifact-ready notifications
|
|
215
|
+
- explicit acknowledgement state
|
|
216
|
+
|
|
217
|
+
They are not intended to imply direct peer-to-peer runner transport. The
|
|
218
|
+
protocol defines the message shape, but routing, persistence, and delivery are
|
|
219
|
+
owned by the orchestrator.
|
|
220
|
+
|
|
221
|
+
`TaskMessage` carries:
|
|
222
|
+
|
|
223
|
+
- sender and recipient task ids
|
|
224
|
+
- message kind
|
|
225
|
+
- optional subject/body
|
|
226
|
+
- referenced artifact ids
|
|
227
|
+
- optional reply chaining
|
|
228
|
+
- acknowledgement requirement
|
|
229
|
+
|
|
230
|
+
`TaskMessageAck` records recipient acknowledgement state separately so mailbox
|
|
231
|
+
delivery can remain append-only and auditable.
|
|
232
|
+
|
|
233
|
+
Recommended acknowledgement semantics:
|
|
234
|
+
|
|
235
|
+
- `received`: the recipient has seen the message in its inbox
|
|
236
|
+
- `accepted`: the recipient accepts the request and plans to act on it
|
|
237
|
+
- `rejected`: the recipient explicitly declines or cannot act on it
|
|
238
|
+
- `resolved`: the recipient completed the requested follow-up or supplied the
|
|
239
|
+
final response
|
|
240
|
+
|
|
241
|
+
Recommended routing semantics:
|
|
242
|
+
|
|
243
|
+
- message ids should be unique within one run
|
|
244
|
+
- sender and recipient should be tasks from the same run
|
|
245
|
+
- `reply_to`, when present, should reference an earlier message id from the
|
|
246
|
+
same run log
|
|
247
|
+
- `requires_ack=true` should imply at least one corresponding
|
|
248
|
+
`TaskMessageAck` record from the recipient
|
|
89
249
|
|
|
90
250
|
### AgentRole
|
|
91
251
|
|
|
@@ -98,6 +258,7 @@ Enum values:
|
|
|
98
258
|
- `reviewer`
|
|
99
259
|
- `security`
|
|
100
260
|
- `ops`
|
|
261
|
+
- `publisher`
|
|
101
262
|
|
|
102
263
|
Example:
|
|
103
264
|
|
|
@@ -107,6 +268,78 @@ Example:
|
|
|
107
268
|
}
|
|
108
269
|
```
|
|
109
270
|
|
|
271
|
+
### PipelineSpec
|
|
272
|
+
|
|
273
|
+
Represents a planned pipeline before execution.
|
|
274
|
+
|
|
275
|
+
Required fields:
|
|
276
|
+
|
|
277
|
+
- `version`: `"v1"`
|
|
278
|
+
- `pipeline_id`: stable identifier
|
|
279
|
+
- `objective`: human-readable campaign or pipeline objective
|
|
280
|
+
- `project_key`: member/project scope identifier
|
|
281
|
+
- `tasks`: ordered `PipelineTask[]`
|
|
282
|
+
|
|
283
|
+
This is the shared planning shape that bootstrap generation, orchestration
|
|
284
|
+
validation, and UI preview should converge on.
|
|
285
|
+
|
|
286
|
+
Current shared planning fields now include:
|
|
287
|
+
|
|
288
|
+
- `PipelineSpec`
|
|
289
|
+
- `PipelineTask`
|
|
290
|
+
- `TaskDependency`
|
|
291
|
+
- `SkillRef`
|
|
292
|
+
- `RoleDefinition`
|
|
293
|
+
- `ResolvedRoleBundle`
|
|
294
|
+
|
|
295
|
+
These are available in the protobuf and language bindings even where the checked-in
|
|
296
|
+
JSON Schema index has not yet been expanded to cover each planning helper type.
|
|
297
|
+
|
|
298
|
+
### RoleDefinition and ResolvedRoleBundle
|
|
299
|
+
|
|
300
|
+
These types provide the shared contract between:
|
|
301
|
+
|
|
302
|
+
- role catalogs in `monarchic-agent-roles`
|
|
303
|
+
- orchestration-time validation
|
|
304
|
+
- runner-time execution bundles
|
|
305
|
+
|
|
306
|
+
`RoleDefinition` describes a canonical role, its capabilities, and its declared
|
|
307
|
+
skill requirements. `ResolvedRoleBundle` is the runtime handoff shape that can
|
|
308
|
+
pair a concrete role definition with the resolved skills and rendered template
|
|
309
|
+
path used for one task execution.
|
|
310
|
+
|
|
311
|
+
### Canonical Pipeline Layout
|
|
312
|
+
|
|
313
|
+
`PipelineSpec` and `PipelineTask` are now the canonical role-aware planning
|
|
314
|
+
layout across the stack.
|
|
315
|
+
|
|
316
|
+
For compatibility, older minimal pipeline files may still only carry:
|
|
317
|
+
|
|
318
|
+
- `pipeline_id`
|
|
319
|
+
- `tasks[].id`
|
|
320
|
+
- `tasks[].task`
|
|
321
|
+
|
|
322
|
+
But once a pipeline opts into the role-aware contract by declaring any of:
|
|
323
|
+
|
|
324
|
+
- `objective`
|
|
325
|
+
- `project_key`
|
|
326
|
+
- `tasks[].role`
|
|
327
|
+
- `tasks[].goal`
|
|
328
|
+
- `tasks[].required_skills`
|
|
329
|
+
|
|
330
|
+
the intended canonical shape is:
|
|
331
|
+
|
|
332
|
+
- `PipelineSpec.objective`: required, non-empty
|
|
333
|
+
- `PipelineSpec.project_key`: required, non-empty
|
|
334
|
+
- `PipelineTask.role`: required, non-empty
|
|
335
|
+
- `PipelineTask.goal`: required, non-empty
|
|
336
|
+
- `PipelineTask.required_skills`: optional list of `SkillRef`, but when present it
|
|
337
|
+
must be internally well-formed and deduplicated
|
|
338
|
+
|
|
339
|
+
This is the contract `monarch` should generate, `monarchic-orchestrator` should
|
|
340
|
+
validate, and `monarchic-runner` should ultimately execute through resolved role
|
|
341
|
+
bundles.
|
|
342
|
+
|
|
110
343
|
### Task
|
|
111
344
|
|
|
112
345
|
Represents work assigned to an agent.
|
|
@@ -124,7 +357,6 @@ Optional fields:
|
|
|
124
357
|
- `constraints`: free-form object
|
|
125
358
|
- `gates_required`: list of gate names to run (ex: `["qa", "security"]`)
|
|
126
359
|
- `run_context`: `RunContext`
|
|
127
|
-
- `delivery_contract`: typed acceptance and risk contract for autonomous delivery loops
|
|
128
360
|
- `objective_spec`: objective scoring contract for deterministic outcome evaluation
|
|
129
361
|
- `experiment_spec`: typed experiment design contract for deterministic in silico runs
|
|
130
362
|
|
|
@@ -154,19 +386,6 @@ Example:
|
|
|
154
386
|
}
|
|
155
387
|
```
|
|
156
388
|
|
|
157
|
-
### DeliveryContract
|
|
158
|
-
|
|
159
|
-
Typed acceptance contract for autonomous delivery execution.
|
|
160
|
-
|
|
161
|
-
Required fields:
|
|
162
|
-
|
|
163
|
-
- `objective`: plain-language objective statement
|
|
164
|
-
- `definition_of_done`: ordered completion checklist
|
|
165
|
-
- `required_checks`: required gate/check names for merge readiness
|
|
166
|
-
- `risk_tier`: `low | medium | high | critical`
|
|
167
|
-
|
|
168
|
-
Optional fields include cycle/turn budgets (`max_cycle_minutes`, `max_agent_turns`) and PR/review/rollback strategy hints.
|
|
169
|
-
|
|
170
389
|
### RunContext
|
|
171
390
|
|
|
172
391
|
Execution hints for a runner.
|
|
@@ -243,6 +462,7 @@ Optional fields:
|
|
|
243
462
|
- `message`: human-readable details
|
|
244
463
|
- `provenance`: typed runtime/source hashes for event attribution
|
|
245
464
|
- `eval_results`: optional metric snapshot payloads
|
|
465
|
+
- `failure_class`: typed failure taxonomy payload for machine-actionable triage
|
|
246
466
|
|
|
247
467
|
Example:
|
|
248
468
|
|
|
@@ -270,6 +490,7 @@ Required fields:
|
|
|
270
490
|
Optional fields:
|
|
271
491
|
|
|
272
492
|
- `reason`: short explanation
|
|
493
|
+
- `failure_class`: typed failure taxonomy payload for deterministic failure routing
|
|
273
494
|
- `evidence`: free-form object with supporting data
|
|
274
495
|
|
|
275
496
|
Example:
|
|
@@ -287,21 +508,125 @@ Example:
|
|
|
287
508
|
}
|
|
288
509
|
```
|
|
289
510
|
|
|
290
|
-
###
|
|
511
|
+
### FailureClass
|
|
291
512
|
|
|
292
|
-
Typed
|
|
513
|
+
Typed taxonomy payload for classifying protocol failures.
|
|
293
514
|
|
|
294
515
|
Required fields:
|
|
295
516
|
|
|
296
|
-
- `
|
|
297
|
-
- `
|
|
298
|
-
- `
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
517
|
+
- `category`: `validation`, `dependency`, `environment`, `timeout`, `conflict`, `permission`, `resource`, `internal`, or `unknown`
|
|
518
|
+
- `code`: stable machine-readable failure code
|
|
519
|
+
- `retryable`: whether automated retry is expected to be useful
|
|
520
|
+
|
|
521
|
+
Optional fields include `detail`, `scope`, `source`, and `next_action`.
|
|
522
|
+
|
|
523
|
+
### PlanStatus
|
|
524
|
+
|
|
525
|
+
Plan lifecycle status used for typed execution plans and receipts.
|
|
526
|
+
|
|
527
|
+
Allowed values:
|
|
528
|
+
|
|
529
|
+
- `unspecified`
|
|
530
|
+
- `draft`
|
|
531
|
+
- `planned`
|
|
532
|
+
- `executing`
|
|
533
|
+
- `complete`
|
|
534
|
+
- `bounded`
|
|
535
|
+
- `failed`
|
|
536
|
+
- `cancelled`
|
|
537
|
+
- `unknown`
|
|
538
|
+
|
|
539
|
+
### FailureDetail
|
|
540
|
+
|
|
541
|
+
Failure detail attached to a plan or receipt.
|
|
542
|
+
|
|
543
|
+
Required fields:
|
|
544
|
+
|
|
545
|
+
- `class`: one of `validation`, `execution`, `agent`, `infra`, `policy`, or `unknown`
|
|
546
|
+
- `code`: machine-readable failure code
|
|
547
|
+
- `message`: operator-readable failure message
|
|
548
|
+
|
|
549
|
+
Optional fields:
|
|
550
|
+
|
|
551
|
+
- `details`: bounded extension object with implementation diagnostics
|
|
552
|
+
|
|
553
|
+
### RoleProvenance
|
|
554
|
+
|
|
555
|
+
Role metadata for deterministic role-template binding.
|
|
556
|
+
|
|
557
|
+
Required fields:
|
|
558
|
+
|
|
559
|
+
- `role_name`
|
|
560
|
+
- `template_hash`
|
|
561
|
+
- `render_hash`
|
|
562
|
+
|
|
563
|
+
### PlanProvenance
|
|
564
|
+
|
|
565
|
+
Generation metadata for a plan and policy context.
|
|
566
|
+
|
|
567
|
+
Required fields:
|
|
568
|
+
|
|
569
|
+
- `generated_by`
|
|
570
|
+
- `generated_at_ms`
|
|
571
|
+
|
|
572
|
+
Optional fields:
|
|
573
|
+
|
|
574
|
+
- `policy_profile`
|
|
575
|
+
- `role`
|
|
302
576
|
|
|
303
|
-
|
|
304
|
-
|
|
577
|
+
### PlanStep
|
|
578
|
+
|
|
579
|
+
Execution step in a plan, with dependency and template fields.
|
|
580
|
+
|
|
581
|
+
Required fields:
|
|
582
|
+
|
|
583
|
+
- `step_id`
|
|
584
|
+
- `description`
|
|
585
|
+
- `task_template`
|
|
586
|
+
|
|
587
|
+
Optional fields:
|
|
588
|
+
|
|
589
|
+
- `depends_on`
|
|
590
|
+
- `failure`
|
|
591
|
+
|
|
592
|
+
### Plan
|
|
593
|
+
|
|
594
|
+
Canonical plan contract.
|
|
595
|
+
|
|
596
|
+
Required fields:
|
|
597
|
+
|
|
598
|
+
- `contract_version`: required contract tag (for now `"v1"`)
|
|
599
|
+
- `plan_id`
|
|
600
|
+
- `objective`
|
|
601
|
+
- `status`
|
|
602
|
+
- `created_at_ms`
|
|
603
|
+
- `updated_at_ms`
|
|
604
|
+
- `provenance`
|
|
605
|
+
- `steps`
|
|
606
|
+
|
|
607
|
+
Optional fields:
|
|
608
|
+
|
|
609
|
+
- `run_id`
|
|
610
|
+
|
|
611
|
+
### ExecutionReceipt
|
|
612
|
+
|
|
613
|
+
Deterministic execution contract for a run.
|
|
614
|
+
|
|
615
|
+
Required fields:
|
|
616
|
+
|
|
617
|
+
- `contract_version`: required contract tag (for now `"v1"`)
|
|
618
|
+
- `run_id`
|
|
619
|
+
- `plan_id`
|
|
620
|
+
- `plan_hash`
|
|
621
|
+
- `task_hashes`
|
|
622
|
+
- `artifact_hashes`
|
|
623
|
+
- `outcome_hash`
|
|
624
|
+
- `status`
|
|
625
|
+
- `generated_at_ms`
|
|
626
|
+
|
|
627
|
+
Optional fields:
|
|
628
|
+
|
|
629
|
+
- `failure`
|
|
305
630
|
|
|
306
631
|
### DatasetRef
|
|
307
632
|
|
|
@@ -367,10 +692,7 @@ Required fields:
|
|
|
367
692
|
|
|
368
693
|
Optional fields include dataset hashes/references and command/task/pipeline hashes.
|
|
369
694
|
|
|
370
|
-
|
|
371
|
-
### Language bindings
|
|
372
|
-
|
|
373
|
-
#### Rust
|
|
695
|
+
## Rust
|
|
374
696
|
|
|
375
697
|
The crate lives at the repo root with sources under `src/rust/lib.rs`.
|
|
376
698
|
|
|
@@ -381,6 +703,7 @@ let task = Task {
|
|
|
381
703
|
version: PROTOCOL_VERSION.to_string(),
|
|
382
704
|
task_id: "task-123".to_string(),
|
|
383
705
|
role: AgentRole::Dev as i32,
|
|
706
|
+
role_id: "dev".to_string(),
|
|
384
707
|
goal: "Implement protocol".to_string(),
|
|
385
708
|
inputs: None,
|
|
386
709
|
constraints: None,
|
|
@@ -415,7 +738,11 @@ github.com/monarchic-ai/monarchic-agent-protocol/src/go
|
|
|
415
738
|
|
|
416
739
|
#### Protobuf
|
|
417
740
|
|
|
418
|
-
The v1 protobuf schema lives at `schemas/v1/monarchic_agent_protocol.proto`.
|
|
741
|
+
The v1 protobuf schema lives at `schemas/v1/monarchic_agent_protocol.proto`. Its portable object messages mirror the JSON schema and use `google.protobuf.Struct` for free-form objects (`inputs`, `constraints`, `evidence`, `extensions`). Additional JSON properties should be stored in the `extensions` field on each message.
|
|
742
|
+
|
|
743
|
+
The protobuf file also contains transport-only service definitions for machine-to-machine control-plane RPC, starting with `RunnerControlService`. Those protobuf-only contracts cover registration, heartbeats, lease acquisition, lease renewal, lease resume, step progress/outcome reporting, and cancellation acknowledgement, and they are not mirrored into the JSON schema index.
|
|
744
|
+
|
|
745
|
+
The Rust crate published from this repository currently exports protobuf message types. Runtime repositories that need gRPC client/server bindings should generate transport stubs from the canonical proto with their chosen toolchain, such as `tonic-build`.
|
|
419
746
|
|
|
420
747
|
Language packages are published per registry. Use the registry package for your language instead of generating local outputs.
|
|
421
748
|
|
|
@@ -454,11 +781,15 @@ Dart sources live under `src/dart`.
|
|
|
454
781
|
- `nix develop` provides Rust, Node, jq, Python `jsonschema`, and `protoc`.
|
|
455
782
|
- `nix flake check` validates JSON schemas, protobuf codegen, and package imports (PyPI + Rust + npm + Go).
|
|
456
783
|
- JSON Schema test: `scripts/test-json-schema.sh`.
|
|
784
|
+
- Language-agnostic schema validation helper: `scripts/validate-protocol-json.sh`.
|
|
785
|
+
- Language-agnostic schema validator regression test: `scripts/test-validate-protocol-json.sh`.
|
|
457
786
|
- Pre-commit schema JSON parse check: `scripts/pre-commit-schema-json-parse.sh`.
|
|
458
787
|
- Pre-commit schema parse smoke test: `scripts/test-pre-commit-schema-json-parse.sh`.
|
|
459
788
|
- Schema edit changelog: `schemas/SCHEMA_CHANGELOG.md`.
|
|
460
789
|
- Schema changelog format test: `scripts/test-schema-changelog-format.sh`.
|
|
461
790
|
- README schema index coverage test: `scripts/test-readme-schema-index-coverage.sh`.
|
|
791
|
+
- README examples coverage test: `scripts/test-readme-examples-coverage.sh`.
|
|
792
|
+
- README/examples examples synchronization test: `scripts/test-readme-examples-sync.sh`.
|
|
462
793
|
- Protobuf codegen test (all languages): `scripts/test-proto.sh`.
|
|
463
794
|
- Protobuf availability smoke test: `scripts/test-proto-availability-smoke.sh`.
|
|
464
795
|
- Protobuf codegen (write to `src/<lang>`): `scripts/generate-proto.sh`.
|
|
@@ -466,28 +797,20 @@ Dart sources live under `src/dart`.
|
|
|
466
797
|
- JSON Schema regeneration only: `scripts/generate-json-schema.sh`.
|
|
467
798
|
- JSON Schema generation requires `protoc-gen-jsonschema` (install with `go install github.com/chrusty/protoc-gen-jsonschema/cmd/protoc-gen-jsonschema@latest`).
|
|
468
799
|
|
|
469
|
-
Use the Nix apps (preferred) or the scripts directly:
|
|
470
|
-
|
|
471
|
-
- `nix run .#generate-proto` (`scripts/generate-proto.sh`): regenerate protobuf outputs into `src/<lang>`.
|
|
472
|
-
- `nix run .#generate-json-schema` (`scripts/generate-json-schema.sh`): regenerate JSON Schemas from the protobuf source.
|
|
473
|
-
- `nix run .#update-local-hashes` (`scripts/update-local-hashes.sh`): refresh hashes for local build inputs.
|
|
474
|
-
- `nix run .#update-version -- <version>` (`scripts/update-version.sh`): bump version across manifests and tags (expects `vX.Y.Z` input).
|
|
475
|
-
- `nix run .#update-registry-hashes` (`scripts/update-registry-hashes.sh`): refresh hashes for published registries (npm, crates, PyPI, RubyGems, NuGet, JitPack, GitHub source).
|
|
476
|
-
|
|
477
|
-
For every schema change, generate protobuf outputs and update local hashes.
|
|
478
|
-
|
|
479
|
-
For every release, tag the commit, update versions, push, and update registry hashes *after pushing*.
|
|
480
|
-
|
|
481
800
|
### Schema validation workflow
|
|
482
801
|
|
|
483
802
|
1. Run full schema lint and semantic checks: `bash scripts/lint-schemas.sh`.
|
|
484
803
|
2. Run direct schema fixture checks: `bash scripts/test-json-schema.sh`.
|
|
485
|
-
3. Validate
|
|
486
|
-
4. Verify
|
|
487
|
-
5.
|
|
488
|
-
6. Verify
|
|
489
|
-
|
|
490
|
-
|
|
804
|
+
3. Validate language-agnostic payloads through JSON schema: `bash scripts/validate-protocol-json.sh schemas/v1/objective_spec.json schemas/fixtures/valid/objective_spec.minimal.json`.
|
|
805
|
+
4. Verify schema validator behavior is deterministic: `bash scripts/test-validate-protocol-json.sh`.
|
|
806
|
+
5. Validate staged schema JSON before commit: `bash scripts/pre-commit-schema-json-parse.sh`.
|
|
807
|
+
6. Verify pre-commit checker behavior is deterministic: `bash scripts/test-pre-commit-schema-json-parse.sh`.
|
|
808
|
+
7. Verify schema changelog entry format: `bash scripts/test-schema-changelog-format.sh`.
|
|
809
|
+
8. Verify README schema index coverage stays aligned: `bash scripts/test-readme-schema-index-coverage.sh`.
|
|
810
|
+
9. Verify README examples coverage for non-protobuf and protobuf paths: `bash scripts/test-readme-examples-coverage.sh`.
|
|
811
|
+
10. Verify README and examples/README example entries stay synchronized: `bash scripts/test-readme-examples-sync.sh`.
|
|
812
|
+
|
|
813
|
+
## Nix packages
|
|
491
814
|
|
|
492
815
|
- `packages.default`: Rust crate for protocol types
|
|
493
816
|
- `packages.rs-lib`: Rust crate for protocol types (local)
|
data/schemas/v1/agent_role.json
CHANGED
data/schemas/v1/artifact.json
CHANGED
|
@@ -72,6 +72,24 @@
|
|
|
72
72
|
"version": {
|
|
73
73
|
"default": "",
|
|
74
74
|
"type": "string"
|
|
75
|
+
},
|
|
76
|
+
"provenance": {
|
|
77
|
+
"$ref": "provenance.json"
|
|
78
|
+
},
|
|
79
|
+
"dataset_refs": {
|
|
80
|
+
"type": "array",
|
|
81
|
+
"items": {
|
|
82
|
+
"$ref": "dataset_ref.json"
|
|
83
|
+
}
|
|
84
|
+
},
|
|
85
|
+
"eval_results": {
|
|
86
|
+
"type": "array",
|
|
87
|
+
"items": {
|
|
88
|
+
"$ref": "eval_result.json"
|
|
89
|
+
}
|
|
90
|
+
},
|
|
91
|
+
"experiment_spec": {
|
|
92
|
+
"$ref": "experiment_spec.json"
|
|
75
93
|
}
|
|
76
94
|
},
|
|
77
95
|
"title": "Artifact",
|
data/schemas/v1/dataset_ref.json
CHANGED
|
@@ -4,11 +4,7 @@
|
|
|
4
4
|
"title": "DatasetRef",
|
|
5
5
|
"type": "object",
|
|
6
6
|
"additionalProperties": true,
|
|
7
|
-
"required": [
|
|
8
|
-
"dataset_id",
|
|
9
|
-
"sha256",
|
|
10
|
-
"format"
|
|
11
|
-
],
|
|
7
|
+
"required": ["dataset_id", "sha256", "format"],
|
|
12
8
|
"properties": {
|
|
13
9
|
"dataset_id": {
|
|
14
10
|
"type": "string"
|
|
@@ -25,14 +21,7 @@
|
|
|
25
21
|
},
|
|
26
22
|
"split": {
|
|
27
23
|
"type": "string",
|
|
28
|
-
"enum": [
|
|
29
|
-
"train",
|
|
30
|
-
"validation",
|
|
31
|
-
"test",
|
|
32
|
-
"holdout",
|
|
33
|
-
"reference",
|
|
34
|
-
"other"
|
|
35
|
-
]
|
|
24
|
+
"enum": ["train", "validation", "test", "holdout", "reference", "other"]
|
|
36
25
|
},
|
|
37
26
|
"size_bytes": {
|
|
38
27
|
"type": "integer",
|
data/schemas/v1/eval_result.json
CHANGED