agent-contracts 0.21.0 → 0.22.0

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.
Files changed (6) hide show
  1. package/README.md +35 -1
  2. package/cli-contract.yaml +38 -89
  3. package/dist/cli.js +1813 -1513
  4. package/dist/cli.js.map +1 -1
  5. package/docs/cli-reference.md +1 -528
  6. package/package.json +4 -3
package/docs/cli-reference.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Declarative YAML DSL toolkit for defining, validating, and rendering multi-agent development workflows. Provides static validation, semantic linting, prompt rendering, guardrail generation, and completeness scoring for agent contract definitions.
4
4
 
5
- **Version:** 0.21.0
5
+ **Version:** 0.22.0
6
6
 
7
7
  ## Table of Contents
8
8
 
@@ -78,20 +78,6 @@ agent-contracts resolve -c agent-contracts.config.yaml
78
78
 
79
79
  - **stderr:** format=`text`
80
80
 
81
- #### Extensions
82
-
83
- ```yaml
84
- x-agent:
85
- riskLevel: low
86
- requiresConfirmation: false
87
- idempotent: true
88
- sideEffects:
89
-
90
- expectedDurationMs: 3000
91
- retryableExitCodes:
92
-
93
- ```
94
-
95
81
  ---
96
82
 
97
83
  ### validate
@@ -144,20 +130,6 @@ agent-contracts validate --quiet
144
130
 
145
131
  - **stderr:** format=`text`
146
132
 
147
- #### Extensions
148
-
149
- ```yaml
150
- x-agent:
151
- riskLevel: low
152
- requiresConfirmation: false
153
- idempotent: true
154
- sideEffects:
155
-
156
- expectedDurationMs: 3000
157
- retryableExitCodes:
158
-
159
- ```
160
-
161
133
  ---
162
134
 
163
135
  ### lint
@@ -207,20 +179,6 @@ agent-contracts lint --format json
207
179
 
208
180
  - **stderr:** format=`text`
209
181
 
210
- #### Extensions
211
-
212
- ```yaml
213
- x-agent:
214
- riskLevel: low
215
- requiresConfirmation: false
216
- idempotent: true
217
- sideEffects:
218
-
219
- expectedDurationMs: 3000
220
- retryableExitCodes:
221
-
222
- ```
223
-
224
182
  ---
225
183
 
226
184
  ### render
@@ -267,20 +225,9 @@ agent-contracts render --quiet
267
225
 
268
226
  ```yaml
269
227
  x-agent:
270
- riskLevel: medium
271
- requiresConfirmation: false
272
- idempotent: true
273
- idempotentNote: Output is deterministic from DSL input and templates. Repeated runs produce identical files. This is a deprecated alias; prefer 'generate templates'.
274
- sideEffects:
275
- - file_write
276
- sideEffectNote: Writes rendered files to configured output paths. No file writes occur when --check is specified.
277
- safeDryRunOption: check
278
228
  recommendedBeforeUse:
279
229
  - Ensure agent-contracts.config.yaml exists with render targets.
280
230
  - Run validate first to confirm DSL is valid.
281
- expectedDurationMs: 5000
282
- retryableExitCodes:
283
-
284
231
  ```
285
232
 
286
233
  ---
@@ -327,16 +274,8 @@ agent-contracts check --format json --quiet
327
274
 
328
275
  ```yaml
329
276
  x-agent:
330
- riskLevel: low
331
- requiresConfirmation: false
332
- idempotent: true
333
- sideEffects:
334
-
335
277
  recommendedBeforeUse:
336
278
  - Ensure agent-contracts.config.yaml exists.
337
- expectedDurationMs: 10000
338
- retryableExitCodes:
339
-
340
279
  ```
341
280
 
342
281
  ---
@@ -387,20 +326,6 @@ agent-contracts score -c agent-contracts.config.yaml
387
326
 
388
327
  - **stderr:** format=`text`
389
328
 
390
- #### Extensions
391
-
392
- ```yaml
393
- x-agent:
394
- riskLevel: low
395
- requiresConfirmation: false
396
- idempotent: true
397
- sideEffects:
398
-
399
- expectedDurationMs: 5000
400
- retryableExitCodes:
401
-
402
- ```
403
-
404
329
  ---
405
330
 
406
331
  ### audit
@@ -460,222 +385,6 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
460
385
 
461
386
  - **stdout:** format=`{options.format}`
462
387
 
463
- | Property | Type | Required | Description |
464
- |---|---|---|---|
465
- | `summary` | `string` | Yes | |
466
- | `riskLevel` | `"low" \| "medium" \| "high" \| "critical"` | Yes | |
467
- | `findings` | `object[]` | Yes | |
468
- | `findings[].id` | `string` | No | Unique finding identifier. |
469
- | `findings[].severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes | |
470
- | `findings[].category` | `string` | Yes | Finding category (e.g. missing-policy, inconsistent-risk). |
471
- | `findings[].target` | `string` | No | Target of the finding (command ID, schema path). |
472
- | `findings[].location` | `string` | No | Location within the target. |
473
- | `findings[].message` | `string` | Yes | |
474
- | `findings[].recommendation` | `string` | No | |
475
- | `findings[].confidence` | `number (min: 0, max: 1)` | No | Confidence score (0-1) for LLM-generated findings. |
476
- | `findings[].evidence` | `object[]` | No | |
477
- | `findings[].evidence[].kind` | `enum(7 values)` | Yes | |
478
- | `findings[].evidence[].target` | `string` | No | Target identifier (file path, command ID, schema name). |
479
- | `findings[].evidence[].location` | `string` | No | Location within the target (line number, JSON pointer). |
480
- | `findings[].evidence[].excerpt` | `string` | No | Relevant excerpt from the target. |
481
- | `findings[].details` | `Record<string, any>` | No | |
482
- | `recommendedActions` | `object[]` | No | |
483
- | `recommendedActions[].kind` | `enum(6 values)` | Yes | |
484
- | `recommendedActions[].title` | `string` | Yes | |
485
- | `recommendedActions[].command` | `string` | No | CLI command to run (for run_command kind). |
486
- | `recommendedActions[].target` | `string` | No | Target file or resource. |
487
- | `recommendedActions[].rationale` | `string` | No | |
488
- | `metadata` | `object` | No | |
489
- | `metadata.tool` | `string` | No | |
490
- | `metadata.command` | `string` | No | |
491
- | `metadata.version` | `string` | No | |
492
- | `metadata.generatedAt` | `string` | No | |
493
- | `metadata.adapter` | `string` | No | |
494
- | `metadata.model` | `string` | No | |
495
-
496
- <details>
497
- <summary>JSON Schema</summary>
498
-
499
- ```json
500
- {
501
- "type": "object",
502
- "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
503
- "required": [
504
- "summary",
505
- "riskLevel",
506
- "findings"
507
- ],
508
- "properties": {
509
- "summary": {
510
- "type": "string"
511
- },
512
- "riskLevel": {
513
- "type": "string",
514
- "enum": [
515
- "low",
516
- "medium",
517
- "high",
518
- "critical"
519
- ]
520
- },
521
- "findings": {
522
- "type": "array",
523
- "items": {
524
- "type": "object",
525
- "description": "A single finding from an agent audit or analysis.",
526
- "required": [
527
- "severity",
528
- "category",
529
- "message"
530
- ],
531
- "properties": {
532
- "id": {
533
- "type": "string",
534
- "description": "Unique finding identifier."
535
- },
536
- "severity": {
537
- "type": "string",
538
- "enum": [
539
- "info",
540
- "warning",
541
- "error",
542
- "critical"
543
- ]
544
- },
545
- "category": {
546
- "type": "string",
547
- "description": "Finding category (e.g. missing-policy, inconsistent-risk)."
548
- },
549
- "target": {
550
- "type": "string",
551
- "description": "Target of the finding (command ID, schema path)."
552
- },
553
- "location": {
554
- "type": "string",
555
- "description": "Location within the target."
556
- },
557
- "message": {
558
- "type": "string"
559
- },
560
- "recommendation": {
561
- "type": "string"
562
- },
563
- "confidence": {
564
- "type": "number",
565
- "minimum": 0,
566
- "maximum": 1,
567
- "description": "Confidence score (0-1) for LLM-generated findings."
568
- },
569
- "evidence": {
570
- "type": "array",
571
- "items": {
572
- "type": "object",
573
- "description": "Evidence supporting an agent finding.",
574
- "required": [
575
- "kind"
576
- ],
577
- "properties": {
578
- "kind": {
579
- "type": "string",
580
- "enum": [
581
- "file",
582
- "command",
583
- "schema",
584
- "diff",
585
- "stdout",
586
- "stderr",
587
- "text"
588
- ]
589
- },
590
- "target": {
591
- "type": "string",
592
- "description": "Target identifier (file path, command ID, schema name)."
593
- },
594
- "location": {
595
- "type": "string",
596
- "description": "Location within the target (line number, JSON pointer)."
597
- },
598
- "excerpt": {
599
- "type": "string",
600
- "description": "Relevant excerpt from the target."
601
- }
602
- }
603
- }
604
- },
605
- "details": {
606
- "type": "object",
607
- "additionalProperties": true
608
- }
609
- }
610
- }
611
- },
612
- "recommendedActions": {
613
- "type": "array",
614
- "items": {
615
- "type": "object",
616
- "description": "A recommended action from an agent audit.",
617
- "required": [
618
- "kind",
619
- "title"
620
- ],
621
- "properties": {
622
- "kind": {
623
- "type": "string",
624
- "enum": [
625
- "run_command",
626
- "edit_file",
627
- "review",
628
- "confirm",
629
- "block",
630
- "ignore"
631
- ]
632
- },
633
- "title": {
634
- "type": "string"
635
- },
636
- "command": {
637
- "type": "string",
638
- "description": "CLI command to run (for run_command kind)."
639
- },
640
- "target": {
641
- "type": "string",
642
- "description": "Target file or resource."
643
- },
644
- "rationale": {
645
- "type": "string"
646
- }
647
- }
648
- }
649
- },
650
- "metadata": {
651
- "type": "object",
652
- "properties": {
653
- "tool": {
654
- "type": "string"
655
- },
656
- "command": {
657
- "type": "string"
658
- },
659
- "version": {
660
- "type": "string"
661
- },
662
- "generatedAt": {
663
- "type": "string"
664
- },
665
- "adapter": {
666
- "type": "string"
667
- },
668
- "model": {
669
- "type": "string"
670
- }
671
- }
672
- }
673
- }
674
- }
675
- ```
676
-
677
- </details>
678
-
679
388
  **Exit 1:** Unexpected error (invalid input, config error, or internal failure).
680
389
 
681
390
  - **stderr:** format=`text`
@@ -684,222 +393,6 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
684
393
 
685
394
  - **stdout:** format=`{options.format}`
686
395
 
687
- | Property | Type | Required | Description |
688
- |---|---|---|---|
689
- | `summary` | `string` | Yes | |
690
- | `riskLevel` | `"low" \| "medium" \| "high" \| "critical"` | Yes | |
691
- | `findings` | `object[]` | Yes | |
692
- | `findings[].id` | `string` | No | Unique finding identifier. |
693
- | `findings[].severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes | |
694
- | `findings[].category` | `string` | Yes | Finding category (e.g. missing-policy, inconsistent-risk). |
695
- | `findings[].target` | `string` | No | Target of the finding (command ID, schema path). |
696
- | `findings[].location` | `string` | No | Location within the target. |
697
- | `findings[].message` | `string` | Yes | |
698
- | `findings[].recommendation` | `string` | No | |
699
- | `findings[].confidence` | `number (min: 0, max: 1)` | No | Confidence score (0-1) for LLM-generated findings. |
700
- | `findings[].evidence` | `object[]` | No | |
701
- | `findings[].evidence[].kind` | `enum(7 values)` | Yes | |
702
- | `findings[].evidence[].target` | `string` | No | Target identifier (file path, command ID, schema name). |
703
- | `findings[].evidence[].location` | `string` | No | Location within the target (line number, JSON pointer). |
704
- | `findings[].evidence[].excerpt` | `string` | No | Relevant excerpt from the target. |
705
- | `findings[].details` | `Record<string, any>` | No | |
706
- | `recommendedActions` | `object[]` | No | |
707
- | `recommendedActions[].kind` | `enum(6 values)` | Yes | |
708
- | `recommendedActions[].title` | `string` | Yes | |
709
- | `recommendedActions[].command` | `string` | No | CLI command to run (for run_command kind). |
710
- | `recommendedActions[].target` | `string` | No | Target file or resource. |
711
- | `recommendedActions[].rationale` | `string` | No | |
712
- | `metadata` | `object` | No | |
713
- | `metadata.tool` | `string` | No | |
714
- | `metadata.command` | `string` | No | |
715
- | `metadata.version` | `string` | No | |
716
- | `metadata.generatedAt` | `string` | No | |
717
- | `metadata.adapter` | `string` | No | |
718
- | `metadata.model` | `string` | No | |
719
-
720
- <details>
721
- <summary>JSON Schema</summary>
722
-
723
- ```json
724
- {
725
- "type": "object",
726
- "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
727
- "required": [
728
- "summary",
729
- "riskLevel",
730
- "findings"
731
- ],
732
- "properties": {
733
- "summary": {
734
- "type": "string"
735
- },
736
- "riskLevel": {
737
- "type": "string",
738
- "enum": [
739
- "low",
740
- "medium",
741
- "high",
742
- "critical"
743
- ]
744
- },
745
- "findings": {
746
- "type": "array",
747
- "items": {
748
- "type": "object",
749
- "description": "A single finding from an agent audit or analysis.",
750
- "required": [
751
- "severity",
752
- "category",
753
- "message"
754
- ],
755
- "properties": {
756
- "id": {
757
- "type": "string",
758
- "description": "Unique finding identifier."
759
- },
760
- "severity": {
761
- "type": "string",
762
- "enum": [
763
- "info",
764
- "warning",
765
- "error",
766
- "critical"
767
- ]
768
- },
769
- "category": {
770
- "type": "string",
771
- "description": "Finding category (e.g. missing-policy, inconsistent-risk)."
772
- },
773
- "target": {
774
- "type": "string",
775
- "description": "Target of the finding (command ID, schema path)."
776
- },
777
- "location": {
778
- "type": "string",
779
- "description": "Location within the target."
780
- },
781
- "message": {
782
- "type": "string"
783
- },
784
- "recommendation": {
785
- "type": "string"
786
- },
787
- "confidence": {
788
- "type": "number",
789
- "minimum": 0,
790
- "maximum": 1,
791
- "description": "Confidence score (0-1) for LLM-generated findings."
792
- },
793
- "evidence": {
794
- "type": "array",
795
- "items": {
796
- "type": "object",
797
- "description": "Evidence supporting an agent finding.",
798
- "required": [
799
- "kind"
800
- ],
801
- "properties": {
802
- "kind": {
803
- "type": "string",
804
- "enum": [
805
- "file",
806
- "command",
807
- "schema",
808
- "diff",
809
- "stdout",
810
- "stderr",
811
- "text"
812
- ]
813
- },
814
- "target": {
815
- "type": "string",
816
- "description": "Target identifier (file path, command ID, schema name)."
817
- },
818
- "location": {
819
- "type": "string",
820
- "description": "Location within the target (line number, JSON pointer)."
821
- },
822
- "excerpt": {
823
- "type": "string",
824
- "description": "Relevant excerpt from the target."
825
- }
826
- }
827
- }
828
- },
829
- "details": {
830
- "type": "object",
831
- "additionalProperties": true
832
- }
833
- }
834
- }
835
- },
836
- "recommendedActions": {
837
- "type": "array",
838
- "items": {
839
- "type": "object",
840
- "description": "A recommended action from an agent audit.",
841
- "required": [
842
- "kind",
843
- "title"
844
- ],
845
- "properties": {
846
- "kind": {
847
- "type": "string",
848
- "enum": [
849
- "run_command",
850
- "edit_file",
851
- "review",
852
- "confirm",
853
- "block",
854
- "ignore"
855
- ]
856
- },
857
- "title": {
858
- "type": "string"
859
- },
860
- "command": {
861
- "type": "string",
862
- "description": "CLI command to run (for run_command kind)."
863
- },
864
- "target": {
865
- "type": "string",
866
- "description": "Target file or resource."
867
- },
868
- "rationale": {
869
- "type": "string"
870
- }
871
- }
872
- }
873
- },
874
- "metadata": {
875
- "type": "object",
876
- "properties": {
877
- "tool": {
878
- "type": "string"
879
- },
880
- "command": {
881
- "type": "string"
882
- },
883
- "version": {
884
- "type": "string"
885
- },
886
- "generatedAt": {
887
- "type": "string"
888
- },
889
- "adapter": {
890
- "type": "string"
891
- },
892
- "model": {
893
- "type": "string"
894
- }
895
- }
896
- }
897
- }
898
- }
899
- ```
900
-
901
- </details>
902
-
903
396
  - **stderr:** format=`text`
904
397
 
905
398
  **Exit 11:** Runtime dependency missing (agent-contracts-runtime not installed).
@@ -914,15 +407,6 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
914
407
 
915
408
  ```yaml
916
409
  x-agent:
917
- riskLevel: medium
918
- requiresConfirmation: false
919
- idempotent: false
920
- idempotentNote: Safe to repeat (no persistent side effects beyond network calls), but LLM inference is non-deterministic — identical inputs may produce different findings, severity assignments, and recommendation text across runs.
921
- sideEffects:
922
- - network
923
- sideEffectNote: Makes LLM API calls to the configured adapter (e.g. OpenAI, Gemini, Cursor) unless --dry-run is specified. Incurs token cost and sends DSL content to the LLM provider.
924
- safeDryRunOption: dry-run
925
- expectedDurationMs: 120000
926
410
  retryableExitCodes:
927
411
  - 12
928
412
  recommendedBeforeUse:
@@ -1005,20 +489,9 @@ agent-contracts generate interface -o team-interface.yaml --dry-run
1005
489
 
1006
490
  ```yaml
1007
491
  x-agent:
1008
- riskLevel: medium
1009
- requiresConfirmation: false
1010
- idempotent: true
1011
- idempotentNote: Output is deterministic from DSL input, templates, policies, and bindings. Repeated runs produce identical files. Confirmation is not required because the command is idempotent and --dry-run / --check provide side-effect-free preview modes.
1012
- sideEffects:
1013
- - file_write
1014
- sideEffectNote: Writes rendered template files, guardrail binding files, and/or team interface files to configured output paths. No file writes occur when --dry-run or --check is specified (--check applies to templates only).
1015
- safeDryRunOption: dry-run
1016
492
  recommendedBeforeUse:
1017
493
  - Ensure agent-contracts.config.yaml exists with render targets and/or binding definitions.
1018
494
  - Run validate first to confirm DSL is valid.
1019
- expectedDurationMs: 5000
1020
- retryableExitCodes:
1021
-
1022
495
  ```
1023
496
 
1024
497
  ---
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-contracts",
3
- "version": "0.21.0",
3
+ "version": "0.22.0",
4
4
  "description": "Declarative YAML DSL toolkit for defining, validating, and rendering multi-agent development workflows",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -31,6 +31,7 @@
31
31
  "lint": "eslint src/ test/",
32
32
  "typecheck": "tsc --noEmit",
33
33
  "generate:schema": "tsx scripts/generate-json-schema.ts",
34
+ "generate:cli": "cli-contracts generate typescript",
34
35
  "generate:docs": "cli-contracts docs",
35
36
  "version": "node -e \"const fs=require('fs');const f='cli-contract.yaml';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace(/^ version: .*/m,' version: '+process.env.npm_package_version))\" && git add cli-contract.yaml",
36
37
  "prepublishOnly": "npm run clean && npm run build"
@@ -67,7 +68,8 @@
67
68
  "handlebars": "^4.7.9",
68
69
  "yaml": "^2.8.3",
69
70
  "zod": "^4.3.6",
70
- "zod-to-json-schema": "^3.25.2"
71
+ "zod-to-json-schema": "^3.25.2",
72
+ "cli-contracts": "^0.7.0"
71
73
  },
72
74
  "devDependencies": {
73
75
  "@anthropic-ai/claude-agent-sdk": "^0.2.138",
@@ -77,7 +79,6 @@
77
79
  "@openai/agents": "^0.11.1",
78
80
  "@types/node": "^25.6.0",
79
81
  "agent-contracts-runtime": "^0.13.0",
80
- "cli-contracts": "^0.6.0",
81
82
  "eslint": "^10.2.0",
82
83
  "globals": "^17.5.0",
83
84
  "prettier": "^3.8.2",