codeassembly-agent-logic 0.0.0 → 0.2.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 (169) hide show
  1. package/.meta/changelog.json +105 -0
  2. package/CHANGELOG.md +38 -0
  3. package/LICENSE +7 -0
  4. package/README.md +77 -1
  5. package/bin/agent-logic.js +26 -0
  6. package/dist/esm/cli/check-coverage-command.d.ts +3 -0
  7. package/dist/esm/cli/check-coverage-command.js +99 -0
  8. package/dist/esm/cli/convert-command.d.ts +3 -0
  9. package/dist/esm/cli/convert-command.js +116 -0
  10. package/dist/esm/cli/find-package-root.d.ts +7 -0
  11. package/dist/esm/cli/find-package-root.js +31 -0
  12. package/dist/esm/cli/index.d.ts +1 -0
  13. package/dist/esm/cli/index.js +11 -0
  14. package/dist/esm/cli/run.d.ts +8 -0
  15. package/dist/esm/cli/run.js +62 -0
  16. package/dist/esm/contract/built-in-harnesses.d.ts +22 -0
  17. package/dist/esm/contract/built-in-harnesses.js +30 -0
  18. package/dist/esm/contract/conversion-job.d.ts +36 -0
  19. package/dist/esm/contract/conversion-job.js +17 -0
  20. package/dist/esm/contract/index.d.ts +4 -0
  21. package/dist/esm/contract/index.js +3 -0
  22. package/dist/esm/contract/viewer-contract.d.ts +804 -0
  23. package/dist/esm/contract/viewer-contract.js +38 -0
  24. package/dist/esm/convert/convert-prompt.d.ts +21 -0
  25. package/dist/esm/convert/convert-prompt.js +60 -0
  26. package/dist/esm/convert/draft-schema.d.ts +308 -0
  27. package/dist/esm/convert/draft-schema.js +57 -0
  28. package/dist/esm/convert/find-gate-spans.d.ts +6 -0
  29. package/dist/esm/convert/find-gate-spans.js +18 -0
  30. package/dist/esm/convert/format-state-name.d.ts +6 -0
  31. package/dist/esm/convert/format-state-name.js +6 -0
  32. package/dist/esm/convert/normalize-config.d.ts +11 -0
  33. package/dist/esm/convert/normalize-config.js +164 -0
  34. package/dist/esm/convert/resolve-quotes.d.ts +18 -0
  35. package/dist/esm/convert/resolve-quotes.js +169 -0
  36. package/dist/esm/convert/sanitize-name.d.ts +5 -0
  37. package/dist/esm/convert/sanitize-name.js +8 -0
  38. package/dist/esm/coverage-map/check-coverage.d.ts +20 -0
  39. package/dist/esm/coverage-map/check-coverage.js +21 -0
  40. package/dist/esm/coverage-map/coverage-map-schema.d.ts +11 -0
  41. package/dist/esm/coverage-map/coverage-map-schema.js +2 -0
  42. package/dist/esm/coverage-map/find-prompt-blocks.d.ts +15 -0
  43. package/dist/esm/coverage-map/find-prompt-blocks.js +140 -0
  44. package/dist/esm/examples/change-approval.d.ts +2 -0
  45. package/dist/esm/examples/change-approval.js +438 -0
  46. package/dist/esm/examples/examples.d.ts +9 -0
  47. package/dist/esm/examples/examples.js +8 -0
  48. package/dist/esm/examples/password-reset.d.ts +2 -0
  49. package/dist/esm/examples/password-reset.js +235 -0
  50. package/dist/esm/examples/refund-request.d.ts +2 -0
  51. package/dist/esm/examples/refund-request.js +233 -0
  52. package/dist/esm/index.d.ts +14 -0
  53. package/dist/esm/index.js +13 -0
  54. package/dist/esm/layout/build-elk-graph.d.ts +18 -0
  55. package/dist/esm/layout/build-elk-graph.js +96 -0
  56. package/dist/esm/layout/card-limits.d.ts +8 -0
  57. package/dist/esm/layout/card-limits.js +4 -0
  58. package/dist/esm/layout/describe-config.d.ts +118 -0
  59. package/dist/esm/layout/describe-config.js +199 -0
  60. package/dist/esm/layout/layout-config.d.ts +5 -0
  61. package/dist/esm/layout/layout-config.js +73 -0
  62. package/dist/esm/layout/layout-metrics.d.ts +6 -0
  63. package/dist/esm/layout/layout-metrics.js +6 -0
  64. package/dist/esm/layout/pack-preamble.d.ts +20 -0
  65. package/dist/esm/layout/pack-preamble.js +66 -0
  66. package/dist/esm/layout/to-flow-elements.d.ts +46 -0
  67. package/dist/esm/layout/to-flow-elements.js +83 -0
  68. package/dist/esm/react/canvas/AmbientSelectionContext.d.ts +7 -0
  69. package/dist/esm/react/canvas/AmbientSelectionContext.js +5 -0
  70. package/dist/esm/react/canvas/DetailLevelContext.d.ts +3 -0
  71. package/dist/esm/react/canvas/DetailLevelContext.js +2 -0
  72. package/dist/esm/react/canvas/FocusNavigation.d.ts +8 -0
  73. package/dist/esm/react/canvas/FocusNavigation.js +92 -0
  74. package/dist/esm/react/canvas/StateNode.d.ts +5 -0
  75. package/dist/esm/react/canvas/StateNode.js +91 -0
  76. package/dist/esm/react/canvas/StatechartCanvas.d.ts +16 -0
  77. package/dist/esm/react/canvas/StatechartCanvas.js +184 -0
  78. package/dist/esm/react/canvas/TransitionEdge.d.ts +5 -0
  79. package/dist/esm/react/canvas/TransitionEdge.js +22 -0
  80. package/dist/esm/react/canvas/canvas-key-entries.d.ts +14 -0
  81. package/dist/esm/react/canvas/canvas-key-entries.js +51 -0
  82. package/dist/esm/react/canvas/find-element-box.d.ts +8 -0
  83. package/dist/esm/react/canvas/find-element-box.js +25 -0
  84. package/dist/esm/react/canvas/find-view-centre.d.ts +15 -0
  85. package/dist/esm/react/canvas/find-view-centre.js +16 -0
  86. package/dist/esm/react/canvas/list-chart-marks.d.ts +5 -0
  87. package/dist/esm/react/canvas/list-chart-marks.js +37 -0
  88. package/dist/esm/react/canvas/marks.d.ts +19 -0
  89. package/dist/esm/react/canvas/marks.js +24 -0
  90. package/dist/esm/react/canvas/useNewLayout.d.ts +17 -0
  91. package/dist/esm/react/canvas/useNewLayout.js +44 -0
  92. package/dist/esm/react/canvas/zoom-levels.d.ts +28 -0
  93. package/dist/esm/react/canvas/zoom-levels.js +54 -0
  94. package/dist/esm/react/hooks/conversion-client.d.ts +77 -0
  95. package/dist/esm/react/hooks/conversion-client.js +132 -0
  96. package/dist/esm/react/hooks/describe-agent-selection.d.ts +6 -0
  97. package/dist/esm/react/hooks/describe-agent-selection.js +18 -0
  98. package/dist/esm/react/hooks/describe-load-outcome.d.ts +13 -0
  99. package/dist/esm/react/hooks/describe-load-outcome.js +30 -0
  100. package/dist/esm/react/hooks/download-config.d.ts +6 -0
  101. package/dist/esm/react/hooks/download-config.js +11 -0
  102. package/dist/esm/react/hooks/example-location.d.ts +7 -0
  103. package/dist/esm/react/hooks/example-location.js +14 -0
  104. package/dist/esm/react/hooks/label-source.d.ts +21 -0
  105. package/dist/esm/react/hooks/label-source.js +19 -0
  106. package/dist/esm/react/hooks/parse-config-text.d.ts +16 -0
  107. package/dist/esm/react/hooks/parse-config-text.js +38 -0
  108. package/dist/esm/react/hooks/useAgentBridge.d.ts +28 -0
  109. package/dist/esm/react/hooks/useAgentBridge.js +52 -0
  110. package/dist/esm/react/hooks/useAgentSync.d.ts +29 -0
  111. package/dist/esm/react/hooks/useAgentSync.js +75 -0
  112. package/dist/esm/react/hooks/useChartLayout.d.ts +25 -0
  113. package/dist/esm/react/hooks/useChartLayout.js +29 -0
  114. package/dist/esm/react/hooks/useConversion.d.ts +31 -0
  115. package/dist/esm/react/hooks/useConversion.js +177 -0
  116. package/dist/esm/react/hooks/useConvertDraft.d.ts +18 -0
  117. package/dist/esm/react/hooks/useConvertDraft.js +11 -0
  118. package/dist/esm/react/hooks/useDocumentTitle.d.ts +2 -0
  119. package/dist/esm/react/hooks/useDocumentTitle.js +7 -0
  120. package/dist/esm/react/hooks/useEscapeToClear.d.ts +2 -0
  121. package/dist/esm/react/hooks/useEscapeToClear.js +16 -0
  122. package/dist/esm/react/hooks/useHarnessList.d.ts +26 -0
  123. package/dist/esm/react/hooks/useHarnessList.js +24 -0
  124. package/dist/esm/react/hooks/usePromptDirectory.d.ts +27 -0
  125. package/dist/esm/react/hooks/usePromptDirectory.js +34 -0
  126. package/dist/esm/react/hooks/useSelection.d.ts +17 -0
  127. package/dist/esm/react/hooks/useSelection.js +21 -0
  128. package/dist/esm/react/hooks/useShowAmbient.d.ts +7 -0
  129. package/dist/esm/react/hooks/useShowAmbient.js +22 -0
  130. package/dist/esm/react/hooks/useUnknownExample.d.ts +7 -0
  131. package/dist/esm/react/hooks/useUnknownExample.js +26 -0
  132. package/dist/esm/react/index.d.ts +24 -0
  133. package/dist/esm/react/index.js +23 -0
  134. package/dist/esm/react/styles.css +482 -0
  135. package/dist/esm/schema/agent-logic-schema.d.ts +439 -0
  136. package/dist/esm/schema/agent-logic-schema.js +100 -0
  137. package/dist/esm/schema/config-traversal.d.ts +19 -0
  138. package/dist/esm/schema/config-traversal.js +32 -0
  139. package/dist/esm/schema/validate-config.d.ts +17 -0
  140. package/dist/esm/schema/validate-config.js +205 -0
  141. package/dist/esm/schema/write-json-schema.d.ts +4 -0
  142. package/dist/esm/schema/write-json-schema.js +12 -0
  143. package/dist/esm/server/conversion-job-implementation.d.ts +11 -0
  144. package/dist/esm/server/conversion-job-implementation.js +84 -0
  145. package/dist/esm/server/create-prompts-app.d.ts +26 -0
  146. package/dist/esm/server/create-prompts-app.js +41 -0
  147. package/dist/esm/server/create-viewer-server-plugins.d.ts +15 -0
  148. package/dist/esm/server/create-viewer-server-plugins.js +76 -0
  149. package/dist/esm/server/index.d.ts +7 -0
  150. package/dist/esm/server/index.js +6 -0
  151. package/dist/esm/server/prompt-directory-schemas.d.ts +30 -0
  152. package/dist/esm/server/prompt-directory-schemas.js +11 -0
  153. package/dist/esm/server/prompt-directory.d.ts +40 -0
  154. package/dist/esm/server/prompt-directory.js +86 -0
  155. package/dist/esm/server/viewer-contract-implementation.d.ts +12 -0
  156. package/dist/esm/server/viewer-contract-implementation.js +85 -0
  157. package/dist/esm/source/fence.d.ts +16 -0
  158. package/dist/esm/source/fence.js +15 -0
  159. package/dist/esm/source/find-comment-spans.d.ts +6 -0
  160. package/dist/esm/source/find-comment-spans.js +60 -0
  161. package/dist/esm/source/find-occurrences.d.ts +2 -0
  162. package/dist/esm/source/find-occurrences.js +7 -0
  163. package/dist/esm/source/prompt-segments.d.ts +21 -0
  164. package/dist/esm/source/prompt-segments.js +65 -0
  165. package/docs/conversion-agreement.md +37 -0
  166. package/docs/corpus.md +19 -0
  167. package/docs/extraction-rules.md +123 -0
  168. package/package.json +108 -2
  169. package/schema/agent-logic.schema.json +475 -0
@@ -0,0 +1,105 @@
1
+ [
2
+ {
3
+ "version": "0.2.0",
4
+ "date": "2026-11-09",
5
+ "sections": [
6
+ {
7
+ "title": "🎉 Features",
8
+ "audience": "all",
9
+ "items": [
10
+ {
11
+ "description": "Exports `buildElkGraph` and its `ElkGraphOptions` type from the root entry of `codeassembly-agent-logic`, so that a consumer can build the unpositioned graph that `toFlowElements` reads without running the ELK layout engine. (#2265)",
12
+ "hash": "7496ad815a8c3548be94cecb66e6c0d1875fa403",
13
+ "entry": 1
14
+ }
15
+ ]
16
+ },
17
+ {
18
+ "title": "⚙️ Tooling",
19
+ "audience": "dev",
20
+ "items": [
21
+ {
22
+ "description": "Adds the agent-logic corpus under `packages/agent-logic/corpus/` and the `refresh-corpus` and `score-corpus` scripts, which copy each prompt from the file that Claude Code loads and regenerate `corpus/scorecard.md`, with a test that fails when the committed scorecard differs. (#2264)",
23
+ "hash": "a44d71443b85af4c25b2ac593c8bcab87c1e2b2c",
24
+ "entry": 1
25
+ }
26
+ ]
27
+ }
28
+ ]
29
+ },
30
+ {
31
+ "version": "0.1.0",
32
+ "date": "2026-11-09",
33
+ "sections": [
34
+ {
35
+ "title": "🎉 Features",
36
+ "audience": "all",
37
+ "items": [
38
+ {
39
+ "description": "Adds the initial `codeassembly-agent-logic` package, whose `contract`, `react`, and `server` subpath entries are placeholders and whose `agent-logic` command prints a usage message that doesn't list any commands yet. (#2257)",
40
+ "hash": "31e8c6a216923573684d79616fab1e6e4ec5b185",
41
+ "entry": 1
42
+ },
43
+ {
44
+ "description": "Adds the agent-logic config schema, its validation, the converter, the coverage check, the chart layout, source marking, and the bundled examples to the root entry of `codeassembly-agent-logic`, and exports the config's JSON Schema as `codeassembly-agent-logic/agent-logic.schema.json`. (#2260)",
45
+ "hash": "1c5e60ae35d1cc4da908491eccc2215987368dee",
46
+ "entry": 1
47
+ },
48
+ {
49
+ "description": "Adds `StatechartCanvas` and the hooks of a page that presents a chart to `codeassembly-agent-logic/react`, with a `renderKey` slot through which each app draws the canvas's key, and a `react/styles.css` stylesheet that an app themes through `--agent-logic-*` custom properties. (#2260)",
50
+ "hash": "1c5e60ae35d1cc4da908491eccc2215987368dee",
51
+ "entry": 2
52
+ },
53
+ {
54
+ "description": "Adds `createViewerServerPlugins` to `codeassembly-agent-logic/server`, which returns the Vite plugins that serve a prompts directory and run conversions through a harness hosted by telefactor, and adds the viewer contract, the conversion job contract, and the built-in harnesses to `codeassembly-agent-logic/contract`. (#2260)",
55
+ "hash": "1c5e60ae35d1cc4da908491eccc2215987368dee",
56
+ "entry": 3
57
+ },
58
+ {
59
+ "description": "Adds the `convert`, `check-coverage`, and `rules` commands to the `agent-logic` bin, which turn a model's draft of a prompt's logic into a config, check a coverage map against the prompt, and print the extraction rules that the package ships, so that a skill can run them through `pnpm dlx` without an installed copy. (#2260)",
60
+ "hash": "1c5e60ae35d1cc4da908491eccc2215987368dee",
61
+ "entry": 4
62
+ }
63
+ ]
64
+ },
65
+ {
66
+ "title": "🐛 Bug fixes",
67
+ "audience": "all",
68
+ "items": [
69
+ {
70
+ "description": "Fixes the issue that `agent-logic check-coverage` did not recognize a fenced code block indented under a list item, so that it reported the block's lines as unmapped and ran the block to the end of the prompt. (#2261)",
71
+ "hash": "0cc0406dc9d5a7581181a5ca3dab517867c02f4c",
72
+ "entry": 1
73
+ },
74
+ {
75
+ "description": "Fixes the issue that `agent-logic` read an HTML comment as prompt text when the comment followed a lone backtick or a line that opens with an inline triple-backtick span. (#2261)",
76
+ "hash": "0cc0406dc9d5a7581181a5ca3dab517867c02f4c",
77
+ "entry": 2
78
+ }
79
+ ]
80
+ },
81
+ {
82
+ "title": "⚙️ Tooling",
83
+ "audience": "dev",
84
+ "items": [
85
+ {
86
+ "description": "Configures ESLint and Vitest in `packages/agent-logic` to lint and test TSX, using the shared config's React and Testing Library rules and the jest-dom matchers. (#2257)",
87
+ "hash": "31e8c6a216923573684d79616fab1e6e4ec5b185",
88
+ "entry": 2
89
+ }
90
+ ]
91
+ },
92
+ {
93
+ "title": "📚 Documentation",
94
+ "audience": "dev",
95
+ "items": [
96
+ {
97
+ "description": "Adds the `codeassembly-agent-logic` README, which describes the entries, what an app supplies, theming, and the bin, and adds `docs/conversion-agreement.md`, which records how consistently a model converts the same prompt. (#2260)",
98
+ "hash": "1c5e60ae35d1cc4da908491eccc2215987368dee",
99
+ "entry": 5
100
+ }
101
+ ]
102
+ }
103
+ ]
104
+ }
105
+ ]
package/CHANGELOG.md ADDED
@@ -0,0 +1,38 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ ## 0.2.0 — 2026-11-09
6
+
7
+ ### 🎉 Features
8
+
9
+ - Exports `buildElkGraph` and its `ElkGraphOptions` type from the root entry of `codeassembly-agent-logic`, so that a consumer can build the unpositioned graph that `toFlowElements` reads without running the ELK layout engine. (#2265)
10
+
11
+ ### ⚙️ Tooling
12
+
13
+ - Adds the agent-logic corpus under `packages/agent-logic/corpus/` and the `refresh-corpus` and `score-corpus` scripts, which copy each prompt from the file that Claude Code loads and regenerate `corpus/scorecard.md`, with a test that fails when the committed scorecard differs. (#2264)
14
+
15
+ ## 0.1.0 — 2026-11-09
16
+
17
+ ### 🎉 Features
18
+
19
+ - Adds the initial `codeassembly-agent-logic` package, whose `contract`, `react`, and `server` subpath entries are placeholders and whose `agent-logic` command prints a usage message that doesn't list any commands yet. (#2257)
20
+ - Adds the agent-logic config schema, its validation, the converter, the coverage check, the chart layout, source marking, and the bundled examples to the root entry of `codeassembly-agent-logic`, and exports the config's JSON Schema as `codeassembly-agent-logic/agent-logic.schema.json`. (#2260)
21
+ - Adds `StatechartCanvas` and the hooks of a page that presents a chart to `codeassembly-agent-logic/react`, with a `renderKey` slot through which each app draws the canvas's key, and a `react/styles.css` stylesheet that an app themes through `--agent-logic-*` custom properties. (#2260)
22
+ - Adds `createViewerServerPlugins` to `codeassembly-agent-logic/server`, which returns the Vite plugins that serve a prompts directory and run conversions through a harness hosted by telefactor, and adds the viewer contract, the conversion job contract, and the built-in harnesses to `codeassembly-agent-logic/contract`. (#2260)
23
+ - Adds the `convert`, `check-coverage`, and `rules` commands to the `agent-logic` bin, which turn a model's draft of a prompt's logic into a config, check a coverage map against the prompt, and print the extraction rules that the package ships, so that a skill can run them through `pnpm dlx` without an installed copy. (#2260)
24
+
25
+ ### 🐛 Bug fixes
26
+
27
+ - Fixes the issue that `agent-logic check-coverage` did not recognize a fenced code block indented under a list item, so that it reported the block's lines as unmapped and ran the block to the end of the prompt. (#2261)
28
+ - Fixes the issue that `agent-logic` read an HTML comment as prompt text when the comment followed a lone backtick or a line that opens with an inline triple-backtick span. (#2261)
29
+
30
+ ### ⚙️ Tooling
31
+
32
+ - Configures ESLint and Vitest in `packages/agent-logic` to lint and test TSX, using the shared config's React and Testing Library rules and the jest-dom matchers. (#2257)
33
+
34
+ ### 📚 Documentation
35
+
36
+ - Adds the `codeassembly-agent-logic` README, which describes the entries, what an app supplies, theming, and the bin, and adds `docs/conversion-agreement.md`, which records how consistently a model converts the same prompt. (#2260)
37
+
38
+ <!-- Generated by release-kit. Do not edit this file. Use .meta/changelog-overrides.json to override entries. -->
package/LICENSE ADDED
@@ -0,0 +1,7 @@
1
+ ISC License
2
+
3
+ Copyright (c) 2026 William Thorsen
4
+
5
+ Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
6
+
7
+ The software is provided "as is" and the author disclaims all warranties with regard to this software including all implied warranties of merchantability and fitness. In no event shall the author be liable for any special, direct, indirect, or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.
package/README.md CHANGED
@@ -1 +1,77 @@
1
- Placeholder for `codeassembly-agent-logic`, awaiting first release.
1
+ <!-- section:release-notes -->
2
+ ## Release notes — v0.2.0 (2026-11-09)
3
+
4
+ ### 🎉 Features
5
+
6
+ - Exports `buildElkGraph` and its `ElkGraphOptions` type from the root entry of `codeassembly-agent-logic`, so that a consumer can build the unpositioned graph that `toFlowElements` reads without running the ELK layout engine. (#2265)
7
+ <!-- /section:release-notes -->
8
+
9
+ <!-- readme-type: library -->
10
+
11
+ # codeassembly-agent-logic
12
+
13
+ The agent-logic model: a schema for an agent prompt's states and transitions, the tools that convert a prompt into it, and the React canvas and server glue for apps that present it as a statechart.
14
+
15
+ ```shell
16
+ pnpm add codeassembly-agent-logic
17
+ ```
18
+
19
+ ```tsx
20
+ import { examples, layoutConfig, validateConfig } from 'codeassembly-agent-logic';
21
+ import { StatechartCanvas } from 'codeassembly-agent-logic/react';
22
+ import 'codeassembly-agent-logic/react/styles.css';
23
+
24
+ const result = validateConfig(examples[0]?.value);
25
+ if (result.ok) {
26
+ const elements = await layoutConfig(result.config);
27
+ root.render(<StatechartCanvas elements={elements} selectedPath={undefined} onSelect={console.log} />);
28
+ }
29
+ ```
30
+
31
+ ## Entries
32
+
33
+ | Entry | Exports |
34
+ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
35
+ | `codeassembly-agent-logic` | The config schema and its validation, the converter and coverage check, the chart description, its ELK graph (`buildElkGraph`), its layout, source marking, and the bundled examples. |
36
+ | `codeassembly-agent-logic/react` | `StatechartCanvas`, the key's entries as data (`CANVAS_KEY_ENTRIES` and the mark glyphs), and the hooks of a page that presents a chart. |
37
+ | `codeassembly-agent-logic/react/styles.css` | The canvas stylesheet. |
38
+ | `codeassembly-agent-logic/server` | `createViewerServerPlugins`, the Vite plugins that serve the prompts directory and run conversions through a harness that telefactor hosts. |
39
+ | `codeassembly-agent-logic/contract` | The contracts between a page and its server: the viewer contract, the conversion job, and the built-in harnesses. |
40
+ | `codeassembly-agent-logic/agent-logic.schema.json` | The config's JSON Schema. |
41
+
42
+ React 19 is a peer of `./react`, and `@williamthorsen/telefactor` a peer of `./server` and `./contract`.
43
+
44
+ ## What the app supplies
45
+
46
+ The package draws the chart; the page around it is the app's. The app renders the load controls, the inspector, the source pane, and the terminal in its own design system, and it renders the canvas's key: `StatechartCanvas` passes the marks that the chart draws to its `renderKey` prop, and `CANVAS_KEY_ENTRIES` gives each mark's name, gloss, and drawing. The app also supplies the conversion server's URL to `createConversionClient`.
47
+
48
+ ## Styling and theming
49
+
50
+ Import `codeassembly-agent-logic/react/styles.css` once, through a bundler: It imports React Flow's base styles from this package's own dependency. It declares a default for each custom property on `:root` at zero specificity, so an app overrides any of them on `:root` or on an ancestor of the canvas, for example to map them to its design tokens:
51
+
52
+ ```css
53
+ :root {
54
+ --agent-logic-text: var(--ds-text);
55
+ --agent-logic-selected: var(--ds-border-selected);
56
+ }
57
+ ```
58
+
59
+ The properties, whose defaults [`styles.css`](src/react/styles.css) declares:
60
+
61
+ - `--agent-logic-ambient-background`, `--agent-logic-compound-background`, `--agent-logic-hover-background`, `--agent-logic-node-background`, `--agent-logic-selected-background`, `--agent-logic-surface`, `--agent-logic-tooltip-background`: backgrounds
62
+ - `--agent-logic-text`, `--agent-logic-text-subtle`, `--agent-logic-tooltip-text`: text
63
+ - `--agent-logic-border`, `--agent-logic-border-strong`, `--agent-logic-focus-ring`, `--agent-logic-selected`: borders and outlines
64
+ - `--agent-logic-global`, `--agent-logic-waiting`, `--agent-logic-warning`: the marks for an any-time transition, a state that waits for the user, and an unreachable state
65
+ - `--agent-logic-font-code`: the code font
66
+
67
+ ## The bin
68
+
69
+ `agent-logic` converts a prompt without installing anything:
70
+
71
+ ```shell
72
+ pnpm dlx codeassembly-agent-logic rules
73
+ pnpm dlx codeassembly-agent-logic convert prompt.md draft.json prompt.agent-logic.json
74
+ pnpm dlx codeassembly-agent-logic check-coverage prompt.md coverage-map.json
75
+ ```
76
+
77
+ `rules` prints the [extraction rules](docs/extraction-rules.md) by which a model drafts a prompt's logic; `convert` turns the draft into a config; `check-coverage` checks a map of the prompt's instructions against the prompt. `agent-logic <command> --help` describes each command's arguments. [Conversion agreement](docs/conversion-agreement.md) records how consistently a model converts the same prompt, and the [corpus](docs/corpus.md) measures conversions of real prompts.
@@ -0,0 +1,26 @@
1
+ #!/usr/bin/env node
2
+
3
+ // Imports only node builtins: A top-level import resolves before the gate below runs, so an
4
+ // unresolvable dependency would replace this file's build-first message with ERR_MODULE_NOT_FOUND.
5
+ import { existsSync } from 'node:fs';
6
+
7
+ // See packages/agents/README.md ("Bin wrapper pattern") for why this indirection exists.
8
+ const entryPoint = new URL('../dist/esm/cli/index.js', import.meta.url);
9
+
10
+ // Gate on the entry file itself: Because Node raises ERR_MODULE_NOT_FOUND for any
11
+ // unresolved module in the graph, keying the build-first message off the error code
12
+ // would also fire when the build is present and one of its imports is missing.
13
+ if (!existsSync(entryPoint)) {
14
+ process.stderr.write(
15
+ 'agent-logic: build output not found. In a source checkout, run `pnpm run bootstrap`; otherwise reinstall the package.\n',
16
+ );
17
+ process.exit(1);
18
+ }
19
+
20
+ try {
21
+ await import(entryPoint.href);
22
+ } catch (error) {
23
+ const message = error instanceof Error ? error.message : String(error);
24
+ process.stderr.write(`agent-logic: failed to load: ${message}\n`);
25
+ process.exit(1);
26
+ }
@@ -0,0 +1,3 @@
1
+ import type { CommandOutput } from './run.js';
2
+ /** Runs `agent-logic check-coverage`: checks a coverage map against its prompt. */
3
+ export declare function runCheckCoverageCommand(args: readonly string[]): CommandOutput;
@@ -0,0 +1,99 @@
1
+ import { readFileSync } from 'node:fs';
2
+ import { parseArgs } from 'node:util';
3
+ import { describeError } from '@williamthorsen/toolbelt.errors';
4
+ import { checkCoverage, describeBlock } from "../coverage-map/check-coverage.js";
5
+ import { coverageMapSchema } from "../coverage-map/coverage-map-schema.js";
6
+ import { readPackageVersion } from "./find-package-root.js";
7
+ const PROGRAM = 'agent-logic check-coverage';
8
+ const HELP = `Lists the parts of a prompt that a coverage map does not quote.
9
+
10
+ Usage: ${PROGRAM} [options] <prompt-file> <map-file>
11
+
12
+ Arguments:
13
+ prompt-file the prompt, read verbatim
14
+ map-file the coverage map JSON, whose shape the package exports as coverageMapSchema
15
+
16
+ Each paragraph, list item, table body row, and fenced block of the prompt, outside HTML
17
+ comments, must overlap the quote of some map entry; each quote must occur in the prompt
18
+ exactly once. Each problem is one line on stdout:
19
+ line <N>: <opening words> a block that no quote overlaps
20
+ map[<i>]: "<quote>" occurs <K> times a quote that does not occur exactly once
21
+ map<path>: <message> an entry that does not match the schema
22
+
23
+ Options:
24
+ -h, --help print this help
25
+ -V, --version print the version
26
+
27
+ Exit codes:
28
+ 0 every block is mapped
29
+ 1 the map has problems; correct them and run again
30
+ 2 the arguments or files are wrong
31
+
32
+ Example:
33
+ ${PROGRAM} prompts/refund-request.md "$TMPDIR/refund-request.coverage-map.json"
34
+ `;
35
+ export function runCheckCoverageCommand(args) {
36
+ const stdout = [];
37
+ const stderr = [];
38
+ const exitCode = runCli(args, stdout, stderr);
39
+ return { exitCode, stderr: stderr.join(''), stdout: stdout.join('') };
40
+ }
41
+ function runCli(args, stdout, stderr) {
42
+ let parsed;
43
+ try {
44
+ parsed = parseArgs({
45
+ args: [...args],
46
+ allowPositionals: true,
47
+ options: {
48
+ help: { type: 'boolean', short: 'h' },
49
+ version: { type: 'boolean', short: 'V' },
50
+ },
51
+ });
52
+ }
53
+ catch (error) {
54
+ stderr.push(`${PROGRAM}: ${describeError(error)}; run ${PROGRAM} --help for usage\n`);
55
+ return 2;
56
+ }
57
+ if (parsed.values.help === true) {
58
+ stdout.push(HELP);
59
+ return 0;
60
+ }
61
+ if (parsed.values.version === true) {
62
+ stdout.push(`${readPackageVersion()}\n`);
63
+ return 0;
64
+ }
65
+ const [promptFile, mapFile, ...extra] = parsed.positionals;
66
+ if (promptFile === undefined || mapFile === undefined || extra.length > 0) {
67
+ stderr.push(`${PROGRAM}: expected 2 arguments, received ${parsed.positionals.length}; run ${PROGRAM} --help for usage\n`);
68
+ return 2;
69
+ }
70
+ let prompt;
71
+ let mapBody;
72
+ try {
73
+ prompt = readFileSync(promptFile, 'utf8');
74
+ mapBody = JSON.parse(readFileSync(mapFile, 'utf8'));
75
+ }
76
+ catch (error) {
77
+ stderr.push(`${PROGRAM}: ${describeError(error)}; pass the paths of existing files, the map as JSON\n`);
78
+ return 2;
79
+ }
80
+ const map = coverageMapSchema.safeParse(mapBody);
81
+ if (!map.success) {
82
+ for (const issue of map.error.issues) {
83
+ const issuePath = issue.path.map((key) => (typeof key === 'number' ? `[${key}]` : `.${String(key)}`)).join('');
84
+ stdout.push(`map${issuePath}: ${issue.message}\n`);
85
+ }
86
+ return 1;
87
+ }
88
+ const { unmapped, quoteProblems } = checkCoverage(prompt, map.data);
89
+ for (const { index, quote, occurrences } of quoteProblems) {
90
+ stdout.push(`map[${index}]: ${JSON.stringify(quote)} occurs ${occurrences} times\n`);
91
+ }
92
+ for (const block of unmapped) {
93
+ stdout.push(`line ${block.line}: ${describeBlock(prompt, block)}\n`);
94
+ }
95
+ if (unmapped.length > 0 || quoteProblems.length > 0)
96
+ return 1;
97
+ stdout.push(`${PROGRAM}: every block is mapped\n`);
98
+ return 0;
99
+ }
@@ -0,0 +1,3 @@
1
+ import type { CommandOutput } from './run.js';
2
+ /** Runs `agent-logic convert`: converts a draft of a prompt's logic into a config and writes it. */
3
+ export declare function runConvertCommand(args: readonly string[]): CommandOutput;
@@ -0,0 +1,116 @@
1
+ import { readFileSync, rmSync, writeFileSync } from 'node:fs';
2
+ import { parseArgs } from 'node:util';
3
+ import { describeError } from '@williamthorsen/toolbelt.errors';
4
+ import { convertPrompt } from "../convert/convert-prompt.js";
5
+ import { readPackageVersion } from "./find-package-root.js";
6
+ const PROGRAM = 'agent-logic convert';
7
+ const HELP = `Converts a draft of an agent prompt's logic into an agent-logic config.
8
+
9
+ Usage: ${PROGRAM} [options] <prompt-file> <draft-file> <output-file>
10
+
11
+ Arguments:
12
+ prompt-file the prompt, read verbatim
13
+ draft-file the draft JSON, whose shape the package exports as draftSchema
14
+ output-file where to write the config; written only when the config is valid
15
+
16
+ A draft of { "outOfScope": { "reason": "..." } } reports that the prompt is out of
17
+ scope: nothing is written to output-file.
18
+
19
+ Options:
20
+ --problems-file <file> on a problem, write { "problems": [...] } to this file; on success, delete it
21
+ -h, --help print this help
22
+ -V, --version print the version
23
+
24
+ Exit codes:
25
+ 0 the config was written
26
+ 1 the draft has problems; correct them and run again
27
+ 2 the arguments or files are wrong
28
+ 3 the draft reports the prompt out of scope; the problems file contains the draft
29
+
30
+ Example:
31
+ ${PROGRAM} prompts/refund-request.md "$TMPDIR/draft.json" prompts/refund-request.agent-logic.json
32
+ `;
33
+ export function runConvertCommand(args) {
34
+ const stdout = [];
35
+ const stderr = [];
36
+ const exitCode = runCli(args, stdout, stderr);
37
+ return { exitCode, stderr: stderr.join(''), stdout: stdout.join('') };
38
+ }
39
+ function runCli(args, stdout, stderr) {
40
+ let parsed;
41
+ try {
42
+ parsed = parseArgs({
43
+ args: [...args],
44
+ allowPositionals: true,
45
+ options: {
46
+ help: { type: 'boolean', short: 'h' },
47
+ 'problems-file': { type: 'string' },
48
+ version: { type: 'boolean', short: 'V' },
49
+ },
50
+ });
51
+ }
52
+ catch (error) {
53
+ const reason = describeError(error);
54
+ stderr.push(`${PROGRAM}: ${reason}; run ${PROGRAM} --help for usage\n`);
55
+ return 2;
56
+ }
57
+ if (parsed.values.help === true) {
58
+ stdout.push(HELP);
59
+ return 0;
60
+ }
61
+ if (parsed.values.version === true) {
62
+ stdout.push(`${readPackageVersion()}\n`);
63
+ return 0;
64
+ }
65
+ const [promptFile, draftFile, outputFile, ...extra] = parsed.positionals;
66
+ if (promptFile === undefined || draftFile === undefined || outputFile === undefined || extra.length > 0) {
67
+ stderr.push(`${PROGRAM}: expected 3 arguments, received ${parsed.positionals.length}; run ${PROGRAM} --help for usage\n`);
68
+ return 2;
69
+ }
70
+ let prompt;
71
+ let draftText;
72
+ try {
73
+ prompt = readFileSync(promptFile, 'utf8');
74
+ draftText = readFileSync(draftFile, 'utf8');
75
+ }
76
+ catch (error) {
77
+ const reason = describeError(error);
78
+ stderr.push(`${PROGRAM}: ${reason}; pass the path of an existing file\n`);
79
+ return 2;
80
+ }
81
+ const result = convertPrompt(prompt, draftText, promptFile);
82
+ const problemsFile = parsed.values['problems-file'];
83
+ if ('outOfScope' in result) {
84
+ const text = `${JSON.stringify({ outOfScope: result.outOfScope }, undefined, 2)}\n`;
85
+ if (problemsFile !== undefined && !runFileOperation(() => writeFileSync(problemsFile, text), stderr))
86
+ return 2;
87
+ stderr.push(`${PROGRAM}: the prompt is out of scope: ${result.outOfScope.reason}\n`, `${PROGRAM}: wrote no config\n`);
88
+ return 3;
89
+ }
90
+ if (!result.ok) {
91
+ const text = `${JSON.stringify({ problems: result.problems }, undefined, 2)}\n`;
92
+ if (problemsFile !== undefined && !runFileOperation(() => writeFileSync(problemsFile, text), stderr))
93
+ return 2;
94
+ for (const { path: problemPath, message } of result.problems) {
95
+ stderr.push(`${PROGRAM}: ${problemPath === '' ? '' : `${problemPath}: `}${message}\n`);
96
+ }
97
+ stderr.push(`${PROGRAM}: wrote nothing; correct the draft, then run ${PROGRAM} again\n`);
98
+ return 1;
99
+ }
100
+ if (!runFileOperation(() => writeFileSync(outputFile, result.text), stderr))
101
+ return 2;
102
+ if (problemsFile !== undefined && !runFileOperation(() => rmSync(problemsFile, { force: true }), stderr))
103
+ return 2;
104
+ stdout.push(`${PROGRAM}: wrote ${outputFile}\n`);
105
+ return 0;
106
+ }
107
+ function runFileOperation(operation, stderr) {
108
+ try {
109
+ operation();
110
+ return true;
111
+ }
112
+ catch (error) {
113
+ stderr.push(`${PROGRAM}: ${describeError(error)}; pass a path in a directory that exists and is writable\n`);
114
+ return false;
115
+ }
116
+ }
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Returns the directory of this package's `package.json`, found by walking up from this module, so that the source and
3
+ * the build output resolve the same root.
4
+ */
5
+ export declare function findPackageRoot(): string;
6
+ /** Returns the version that this package's `package.json` declares. */
7
+ export declare function readPackageVersion(): string;
@@ -0,0 +1,31 @@
1
+ import { existsSync, readFileSync } from 'node:fs';
2
+ import path from 'node:path';
3
+ import { fileURLToPath } from 'node:url';
4
+ const PACKAGE_NAME = 'codeassembly-agent-logic';
5
+ export function findPackageRoot() {
6
+ let directory = path.dirname(fileURLToPath(import.meta.url));
7
+ while (!isPackageRoot(directory)) {
8
+ const parent = path.dirname(directory);
9
+ if (parent === directory)
10
+ throw new Error(`${PACKAGE_NAME}: package.json not found above ${import.meta.url}`);
11
+ directory = parent;
12
+ }
13
+ return directory;
14
+ }
15
+ export function readPackageVersion() {
16
+ const manifest = JSON.parse(readFileSync(path.join(findPackageRoot(), 'package.json'), 'utf8'));
17
+ const version = isRecord(manifest) ? manifest['version'] : undefined;
18
+ if (typeof version !== 'string')
19
+ throw new TypeError(`${PACKAGE_NAME}: package.json does not declare a version`);
20
+ return version;
21
+ }
22
+ function isPackageRoot(directory) {
23
+ const manifestPath = path.join(directory, 'package.json');
24
+ if (!existsSync(manifestPath))
25
+ return false;
26
+ const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
27
+ return isRecord(manifest) && manifest['name'] === PACKAGE_NAME;
28
+ }
29
+ function isRecord(value) {
30
+ return typeof value === 'object' && value !== null;
31
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,11 @@
1
+ import process from 'node:process';
2
+ import { run } from "./run.js";
3
+ function main() {
4
+ const output = run(process.argv.slice(2));
5
+ if (output.stdout !== '')
6
+ process.stdout.write(output.stdout);
7
+ if (output.stderr !== '')
8
+ process.stderr.write(output.stderr);
9
+ process.exit(output.exitCode);
10
+ }
11
+ main();
@@ -0,0 +1,8 @@
1
+ /** What a CLI invocation writes to each stream and the code with which it exits. */
2
+ export interface CommandOutput {
3
+ exitCode: number;
4
+ stderr: string;
5
+ stdout: string;
6
+ }
7
+ /** Dispatches the bin's arguments to a command and returns its output without touching the process. */
8
+ export declare function run(argv: readonly string[]): CommandOutput;
@@ -0,0 +1,62 @@
1
+ import { readFileSync } from 'node:fs';
2
+ import path from 'node:path';
3
+ import { runCheckCoverageCommand } from "./check-coverage-command.js";
4
+ import { runConvertCommand } from "./convert-command.js";
5
+ import { findPackageRoot, readPackageVersion } from "./find-package-root.js";
6
+ const USAGE = `Usage: agent-logic <command> [arguments]
7
+
8
+ Commands:
9
+ convert convert a draft of a prompt's logic into an agent-logic config
10
+ check-coverage check a coverage map of a prompt against the prompt
11
+ rules print the extraction rules by which a model drafts a prompt's logic
12
+
13
+ Run agent-logic <command> --help for a command's arguments and options.
14
+
15
+ Options:
16
+ -h, --help print this help
17
+ -V, --version print the version
18
+ `;
19
+ export function run(argv) {
20
+ const [command, ...args] = argv;
21
+ switch (command) {
22
+ case undefined:
23
+ case '--help':
24
+ case '-h':
25
+ return { exitCode: 0, stderr: '', stdout: USAGE };
26
+ case '--version':
27
+ case '-V':
28
+ return { exitCode: 0, stderr: '', stdout: `${readPackageVersion()}\n` };
29
+ case 'check-coverage':
30
+ return runCheckCoverageCommand(args);
31
+ case 'convert':
32
+ return runConvertCommand(args);
33
+ case 'rules':
34
+ return runRulesCommand(args);
35
+ default:
36
+ return { exitCode: 2, stderr: `agent-logic: unknown command: ${command}\n\n${USAGE}`, stdout: '' };
37
+ }
38
+ }
39
+ const RULES_HELP = `Prints the extraction rules by which a model drafts a prompt's logic for agent-logic convert.
40
+
41
+ Usage: agent-logic rules
42
+
43
+ Options:
44
+ -h, --help print this help
45
+ `;
46
+ function runRulesCommand(args) {
47
+ if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
48
+ return { exitCode: 0, stderr: '', stdout: RULES_HELP };
49
+ }
50
+ if (args.length > 0) {
51
+ return {
52
+ exitCode: 2,
53
+ stderr: `agent-logic rules: expected no arguments, received ${args.length}; run agent-logic rules --help for usage\n`,
54
+ stdout: '',
55
+ };
56
+ }
57
+ return {
58
+ exitCode: 0,
59
+ stderr: '',
60
+ stdout: readFileSync(path.join(findPackageRoot(), 'docs/extraction-rules.md'), 'utf8'),
61
+ };
62
+ }
@@ -0,0 +1,22 @@
1
+ import { z } from 'zod';
2
+ /** The prompts directory, relative to the config file's directory, when the config names none. */
3
+ export declare const DEFAULT_PROMPTS_DIRECTORY = "prompts";
4
+ /** The harnesses that apply when neither the environment variable nor the config file defines any. */
5
+ export declare const viewerBuiltInHarnesses: {
6
+ default: string;
7
+ harnesses: {
8
+ 'claude-code': {
9
+ label: string;
10
+ command: string[];
11
+ test: string[];
12
+ interactive: string[];
13
+ mcpArgs: string[];
14
+ };
15
+ };
16
+ };
17
+ /** The viewer's own keys in `harness.config.json`: `promptsDirectory` is resolved against the file's directory. */
18
+ export declare const viewerConfigSchema: z.ZodObject<{
19
+ promptsDirectory: z.ZodDefault<z.ZodString>;
20
+ }, z.core.$strip>;
21
+ /** Returns the text of a `harness.config.json` that defines the built-in settings. */
22
+ export declare function buildConfigTemplate(): string;