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,233 @@
1
+ export const refundRequest = {
2
+ id: 'refund_agent',
3
+ initial: 'handling',
4
+ states: {
5
+ handling: {
6
+ id: 'handling',
7
+ initial: 'asking_for_order',
8
+ exit: [
9
+ {
10
+ type: 'nl',
11
+ params: {
12
+ text: 'log a summary of the conversation',
13
+ },
14
+ },
15
+ ],
16
+ on: {
17
+ 'user.asks_for_human': {
18
+ target: '#handed_off',
19
+ meta: {
20
+ source: {
21
+ start: 319,
22
+ end: 365,
23
+ },
24
+ },
25
+ },
26
+ },
27
+ states: {
28
+ asking_for_order: {
29
+ id: 'asking_for_order',
30
+ entry: [
31
+ {
32
+ type: 'nl',
33
+ params: {
34
+ text: 'ask the customer for their order number',
35
+ },
36
+ },
37
+ ],
38
+ on: {
39
+ 'user.gives_order_number': {
40
+ target: '#looking_up',
41
+ meta: {
42
+ source: {
43
+ start: 69,
44
+ end: 108,
45
+ },
46
+ inferred: true,
47
+ },
48
+ },
49
+ },
50
+ meta: {
51
+ name: 'Ask for the order number',
52
+ source: {
53
+ start: 62,
54
+ end: 109,
55
+ },
56
+ },
57
+ },
58
+ looking_up: {
59
+ id: 'looking_up',
60
+ entry: [
61
+ {
62
+ type: 'nl',
63
+ params: {
64
+ text: 'look up the order',
65
+ },
66
+ },
67
+ ],
68
+ always: [
69
+ {
70
+ target: '#outside_window',
71
+ guard: {
72
+ type: 'nl',
73
+ params: {
74
+ text: 'the order is older than 30 days',
75
+ },
76
+ },
77
+ meta: {
78
+ source: {
79
+ start: 129,
80
+ end: 163,
81
+ },
82
+ },
83
+ },
84
+ {
85
+ target: '#refunding',
86
+ meta: {
87
+ source: {
88
+ start: 236,
89
+ end: 245,
90
+ },
91
+ },
92
+ },
93
+ ],
94
+ meta: {
95
+ name: 'Look up the order',
96
+ source: {
97
+ start: 110,
98
+ end: 128,
99
+ },
100
+ },
101
+ },
102
+ outside_window: {
103
+ id: 'outside_window',
104
+ entry: [
105
+ {
106
+ type: 'nl',
107
+ params: {
108
+ text: 'explain that the order is outside the refund window',
109
+ },
110
+ },
111
+ ],
112
+ always: {
113
+ target: '#closed',
114
+ meta: {
115
+ source: {
116
+ start: 184,
117
+ end: 234,
118
+ },
119
+ },
120
+ },
121
+ meta: {
122
+ name: 'Explain the refund window',
123
+ source: {
124
+ start: 165,
125
+ end: 209,
126
+ },
127
+ },
128
+ },
129
+ refunding: {
130
+ id: 'refunding',
131
+ entry: [
132
+ {
133
+ type: 'nl',
134
+ params: {
135
+ text: 'issue the refund',
136
+ },
137
+ },
138
+ {
139
+ type: 'nl',
140
+ params: {
141
+ text: 'confirm the refund to the customer',
142
+ },
143
+ },
144
+ ],
145
+ always: {
146
+ target: '#closed',
147
+ meta: {
148
+ source: {
149
+ start: 265,
150
+ end: 317,
151
+ },
152
+ },
153
+ },
154
+ meta: {
155
+ name: 'Issue the refund',
156
+ source: {
157
+ start: 247,
158
+ end: 291,
159
+ },
160
+ },
161
+ },
162
+ },
163
+ meta: {
164
+ name: 'Handle the refund',
165
+ source: {
166
+ start: 409,
167
+ end: 454,
168
+ },
169
+ ambient: [
170
+ {
171
+ start: 549,
172
+ end: 628,
173
+ },
174
+ ],
175
+ },
176
+ },
177
+ handed_off: {
178
+ id: 'handed_off',
179
+ type: 'final',
180
+ entry: [
181
+ {
182
+ type: 'nl',
183
+ params: {
184
+ text: 'hand the conversation to a support agent',
185
+ },
186
+ },
187
+ ],
188
+ meta: {
189
+ name: 'Hand off to support',
190
+ source: {
191
+ start: 367,
192
+ end: 407,
193
+ },
194
+ },
195
+ },
196
+ closed: {
197
+ id: 'closed',
198
+ type: 'final',
199
+ meta: {
200
+ name: 'End the conversation',
201
+ source: {
202
+ start: 196,
203
+ end: 234,
204
+ },
205
+ },
206
+ },
207
+ },
208
+ meta: {
209
+ name: 'Refund agent',
210
+ prompt: 'You help customers with refund requests. Be warm and concise.\nFirst, ask the customer for their order number. Look up the order. If the order is older than 30 days, explain that it is outside the refund window and end the conversation. Otherwise, issue the refund, confirm it to the customer, and end the conversation.\nAt any point, if the customer asks for a human, hand the conversation to a support agent.\nWhen you leave the refund flow for any reason, log a summary of the conversation.\nMention our seasonal promotion whenever it feels natural.\nWhile in the refund flow, never promise a refund before the order is looked up.',
211
+ source: {
212
+ start: 0,
213
+ end: 628,
214
+ },
215
+ unconverted: [
216
+ {
217
+ start: 491,
218
+ end: 548,
219
+ reason: 'States a habit rather than a step, and does not say when it applies.',
220
+ },
221
+ ],
222
+ ambient: [
223
+ {
224
+ start: 0,
225
+ end: 40,
226
+ },
227
+ {
228
+ start: 41,
229
+ end: 61,
230
+ },
231
+ ],
232
+ },
233
+ };
@@ -0,0 +1,14 @@
1
+ /** Root entry of `codeassembly-agent-logic`: the agent-logic schema, validation, coverage, layout, source marking, and examples. */
2
+ export * from './convert/convert-prompt.js';
3
+ export * from './convert/draft-schema.js';
4
+ export * from './coverage-map/check-coverage.js';
5
+ export * from './coverage-map/coverage-map-schema.js';
6
+ export * from './examples/examples.js';
7
+ export { buildElkGraph, type ElkGraphOptions } from './layout/build-elk-graph.js';
8
+ export * from './layout/describe-config.js';
9
+ export * from './layout/layout-config.js';
10
+ export * from './layout/to-flow-elements.js';
11
+ export * from './schema/agent-logic-schema.js';
12
+ export * from './schema/config-traversal.js';
13
+ export * from './schema/validate-config.js';
14
+ export * from './source/prompt-segments.js';
@@ -0,0 +1,13 @@
1
+ export * from "./convert/convert-prompt.js";
2
+ export * from "./convert/draft-schema.js";
3
+ export * from "./coverage-map/check-coverage.js";
4
+ export * from "./coverage-map/coverage-map-schema.js";
5
+ export * from "./examples/examples.js";
6
+ export { buildElkGraph } from "./layout/build-elk-graph.js";
7
+ export * from "./layout/describe-config.js";
8
+ export * from "./layout/layout-config.js";
9
+ export * from "./layout/to-flow-elements.js";
10
+ export * from "./schema/agent-logic-schema.js";
11
+ export * from "./schema/config-traversal.js";
12
+ export * from "./schema/validate-config.js";
13
+ export * from "./source/prompt-segments.js";
@@ -0,0 +1,18 @@
1
+ import type { ElkNode } from 'elkjs/lib/elk-api.js';
2
+ import { type ConfigDescription } from './describe-config.js';
3
+ /** Id of the graph that contains the root state. */
4
+ export declare const GRAPH_ID = "__graph__";
5
+ /** The width below which a flow cannot hold its preamble. */
6
+ export declare const PREAMBLE_FLOW_WIDTH: number;
7
+ export interface ElkGraphOptions {
8
+ /** Whether each flow draws its ambient instructions as a preamble, for which the graph reserves room. */
9
+ showAmbient: boolean;
10
+ /** Width to add to the right padding of each listed flow, so that it reaches the width of its preamble. */
11
+ extraWidths?: ReadonlyMap<string, number> | undefined;
12
+ /** The number of columns in which each listed flow may lay out its preamble; a flow that is not listed takes one. */
13
+ preambleColumnLimits?: ReadonlyMap<string, number> | undefined;
14
+ }
15
+ /** Options that lay out a chart without its preambles. */
16
+ export declare const HIDDEN_AMBIENT: ElkGraphOptions;
17
+ /** Builds the ELK graph of a described config: one node per state, nested as the states are, and one edge per transition. */
18
+ export declare function buildElkGraph(description: ConfigDescription, options?: ElkGraphOptions): ElkNode;
@@ -0,0 +1,96 @@
1
+ import { MAX_ACTION_LINES, MAX_CARD_ACTIONS, PREAMBLE_WIDTH } from "./card-limits.js";
2
+ import { buildTransitionLabel, } from "./describe-config.js";
3
+ import { COMPOUND_PADDING_LEFT, COMPOUND_PADDING_RIGHT, countWrappedLines } from "./layout-metrics.js";
4
+ import { estimatePreambleHeight } from "./pack-preamble.js";
5
+ export const GRAPH_ID = '__graph__';
6
+ const CHARACTER_WIDTH = 7.5;
7
+ const LABEL_CHARACTER_WIDTH = 6.5;
8
+ const TITLE_CHARACTER_WIDTH = 7.6;
9
+ const MONO_LABEL_CHARACTER_WIDTH = 7.4;
10
+ const LINE_HEIGHT = 18;
11
+ const MAX_LABEL_WIDTH = 200;
12
+ const LABEL_PADDING = 12;
13
+ const STATE_WIDTH = 240;
14
+ const STATE_TITLE_LINE_HEIGHT = 20;
15
+ const STATE_PADDING_TOP = 8;
16
+ const STATE_PADDING = 12;
17
+ const COMPOUND_GAP = 16;
18
+ const GLYPH_COLUMN_WIDTH = 20;
19
+ const ACTION_INDENT = 18;
20
+ export const PREAMBLE_FLOW_WIDTH = COMPOUND_PADDING_LEFT + PREAMBLE_WIDTH + COMPOUND_PADDING_RIGHT;
21
+ export const HIDDEN_AMBIENT = { showAmbient: false };
22
+ export function buildElkGraph(description, options = HIDDEN_AMBIENT) {
23
+ const { showAmbient, extraWidths, preambleColumnLimits } = options;
24
+ const nodesById = new Map();
25
+ const graph = {
26
+ id: GRAPH_ID,
27
+ layoutOptions: {
28
+ 'elk.algorithm': 'layered',
29
+ 'elk.direction': 'DOWN',
30
+ 'elk.edgeRouting': 'ORTHOGONAL',
31
+ 'elk.hierarchyHandling': 'INCLUDE_CHILDREN',
32
+ 'elk.json.edgeCoords': 'ROOT',
33
+ 'elk.layered.spacing.nodeNodeBetweenLayers': '56',
34
+ 'elk.spacing.edgeLabel': '6',
35
+ 'elk.spacing.nodeNode': '40',
36
+ },
37
+ children: [],
38
+ edges: description.transitions.map((transition) => {
39
+ const { trigger, details } = buildTransitionLabel(transition);
40
+ const triggerLines = trigger === undefined ? [] : [trigger];
41
+ const longestLineWidth = Math.max(...triggerLines.map((line) => line.length * MONO_LABEL_CHARACTER_WIDTH), ...details.map((line) => line.length * LABEL_CHARACTER_WIDTH));
42
+ const width = Math.min(MAX_LABEL_WIDTH, Math.ceil(longestLineWidth) + LABEL_PADDING);
43
+ const textWidth = width - LABEL_PADDING;
44
+ const lineCount = countWrappedLines(triggerLines, textWidth, MONO_LABEL_CHARACTER_WIDTH) +
45
+ countWrappedLines(details, textWidth, LABEL_CHARACTER_WIDTH);
46
+ return {
47
+ id: transition.path,
48
+ sources: [transition.sourceId],
49
+ targets: [transition.targetId],
50
+ labels: [
51
+ {
52
+ text: [...triggerLines, ...details].join('\n'),
53
+ width,
54
+ height: lineCount * LINE_HEIGHT + 8,
55
+ },
56
+ ],
57
+ };
58
+ }),
59
+ };
60
+ for (const state of description.states) {
61
+ const ambient = showAmbient ? description.ambient.filter(({ containerId }) => containerId === state.id) : [];
62
+ const node = state.isCompound
63
+ ? {
64
+ id: state.id,
65
+ children: [],
66
+ layoutOptions: {
67
+ 'elk.padding': `[top=${estimatePreambleHeight(ambient, preambleColumnLimits?.get(state.id) ?? 1) + estimateStateBodyHeight(state) + COMPOUND_GAP},left=${COMPOUND_PADDING_LEFT},bottom=20,right=${COMPOUND_PADDING_RIGHT + (extraWidths?.get(state.id) ?? 0)}]`,
68
+ },
69
+ }
70
+ : { id: state.id, width: STATE_WIDTH, height: estimateStateHeight(state) };
71
+ nodesById.set(state.id, node);
72
+ const parent = state.parentId === undefined ? graph : nodesById.get(state.parentId);
73
+ parent?.children?.push(node);
74
+ }
75
+ return graph;
76
+ }
77
+ function countActionSectionLines(actions) {
78
+ if (actions.length === 0)
79
+ return 0;
80
+ const shown = actions.slice(0, MAX_CARD_ACTIONS).map(({ text, gate }) => (gate ? `gate ${text}` : text));
81
+ const width = STATE_WIDTH - 2 * STATE_PADDING - ACTION_INDENT;
82
+ const shownLines = shown.reduce((count, action) => count + Math.min(MAX_ACTION_LINES, countWrappedLines([action], width, CHARACTER_WIDTH)), 0);
83
+ const moreLine = actions.length > MAX_CARD_ACTIONS ? 1 : 0;
84
+ return 1 + shownLines + moreLine;
85
+ }
86
+ function estimateStateBodyHeight(state) {
87
+ const inferredHeight = state.inferred ? LINE_HEIGHT : 0;
88
+ const actionLines = countActionSectionLines(state.entry) + countActionSectionLines(state.exit);
89
+ const actionsHeight = actionLines === 0 ? 0 : actionLines * LINE_HEIGHT + 8;
90
+ return STATE_PADDING_TOP + inferredHeight + actionsHeight + STATE_PADDING;
91
+ }
92
+ function estimateStateHeight(state) {
93
+ const glyphWidth = state.waitsForUser || state.isFinal ? GLYPH_COLUMN_WIDTH : 0;
94
+ const titleLines = countWrappedLines([state.name], STATE_WIDTH - 2 * STATE_PADDING - glyphWidth, TITLE_CHARACTER_WIDTH);
95
+ return titleLines * STATE_TITLE_LINE_HEIGHT + estimateStateBodyHeight(state);
96
+ }
@@ -0,0 +1,8 @@
1
+ /** The number of actions that a card shows per section, before a line that counts the rest. */
2
+ export declare const MAX_CARD_ACTIONS = 2;
3
+ /** The number of lines to which a card clamps each action. */
4
+ export declare const MAX_ACTION_LINES = 2;
5
+ /** The width at which a flow's preamble of ambient instructions wraps; its flow is never narrower. */
6
+ export declare const PREAMBLE_WIDTH = 480;
7
+ /** The number of lines to which a preamble clamps each ambient instruction. */
8
+ export declare const MAX_AMBIENT_LINES = 2;
@@ -0,0 +1,4 @@
1
+ export const MAX_CARD_ACTIONS = 2;
2
+ export const MAX_ACTION_LINES = 2;
3
+ export const PREAMBLE_WIDTH = 480;
4
+ export const MAX_AMBIENT_LINES = 2;
@@ -0,0 +1,118 @@
1
+ import type { AgentLogicConfig, FindingKind, Span } from '../schema/agent-logic-schema.js';
2
+ /** What the viewer shows of an action. */
3
+ export interface ActionDescription {
4
+ text: string;
5
+ /** Whether the action represents a `<HARD-GATE>` of the prompt. */
6
+ gate: boolean;
7
+ /** The passage of the gate that the action represents; absent for an action that is not a gate. */
8
+ source: Span | undefined;
9
+ }
10
+ /** What the viewer shows of a state, the root included. */
11
+ export interface StateDescription {
12
+ kind: 'state';
13
+ id: string;
14
+ /** The name that the viewer shows: the state's `meta.name`, or its id when it has none. */
15
+ name: string;
16
+ /** Formatted path into the config; the element's selection key. */
17
+ path: string;
18
+ /** The id of the enclosing state; absent for the root. */
19
+ parentId: string | undefined;
20
+ isCompound: boolean;
21
+ isFinal: boolean;
22
+ /** Whether the enclosing state's `initial` names this state, so that its flow starts here. */
23
+ isInitial: boolean;
24
+ waitsForUser: boolean;
25
+ /** Whether the state is a leaf, is not final, and none of its own transitions leads to another state. */
26
+ hasNoExit: boolean;
27
+ /**
28
+ * Whether neither the root's initial state nor any transition enters the state, while its parent is entered, so that
29
+ * it is the outermost state of an unreachable subtree.
30
+ */
31
+ isUnreachable: boolean;
32
+ entry: ActionDescription[];
33
+ exit: ActionDescription[];
34
+ inferred: boolean;
35
+ source: Span;
36
+ }
37
+ /** What the viewer shows of a transition. */
38
+ export interface TransitionDescription {
39
+ kind: 'transition';
40
+ /** Formatted path into the config; the element's selection key. */
41
+ path: string;
42
+ sourceId: string;
43
+ sourceName: string;
44
+ /** The id of the target state; the source's id for a transition without a target. */
45
+ targetId: string;
46
+ targetName: string;
47
+ event: string | undefined;
48
+ guard: string | undefined;
49
+ actions: ActionDescription[];
50
+ /** Whether the transition belongs to a compound state, so that it applies from every state inside it. */
51
+ isGlobal: boolean;
52
+ /** Whether the transition has no guard and a sibling in its list has one, so that it is taken when no guard holds. */
53
+ isFallback: boolean;
54
+ /**
55
+ * Whether the transition has a guard, no sibling in its list, and no enclosing state that handles its trigger, so
56
+ * that nothing happens when the guard fails.
57
+ */
58
+ lacksAlternative: boolean;
59
+ inferred: boolean;
60
+ /** Whether the transition represents a `<HARD-GATE>` of the prompt. */
61
+ gate: boolean;
62
+ source: Span;
63
+ }
64
+ /** What the viewer shows of an ambient instruction: a passage that holds throughout its container. */
65
+ export interface AmbientDescription {
66
+ kind: 'ambient';
67
+ /** Formatted path into the config; the element's selection key. */
68
+ path: string;
69
+ /** The id of the root or compound state that the instruction belongs to. */
70
+ containerId: string;
71
+ containerName: string;
72
+ /** The passage's prompt text. */
73
+ text: string;
74
+ /** Whether the passage is the body of a `<HARD-GATE>`. */
75
+ gate: boolean;
76
+ source: Span;
77
+ }
78
+ export type ElementDescription = AmbientDescription | StateDescription | TransitionDescription;
79
+ /** What the viewer shows of a finding: a flaw that the converter judged from the prompt's prose. */
80
+ export interface FindingDescription {
81
+ kind: FindingKind;
82
+ /** Formatted path into the config, unique among findings. */
83
+ path: string;
84
+ reason: string;
85
+ sources: Span[];
86
+ /** The state or transition that the finding concerns; absent for a finding on the root. */
87
+ element: StateDescription | TransitionDescription | undefined;
88
+ }
89
+ /** A transition's label: a trigger line set as an identifier, then lines of prose. */
90
+ export interface TransitionLabel {
91
+ /** The event, or `Any time` for an eventless global transition; absent for any other eventless transition. */
92
+ trigger: string | undefined;
93
+ details: string[];
94
+ }
95
+ export interface ConfigDescription {
96
+ /** States in document order, each parent before its children. */
97
+ states: StateDescription[];
98
+ transitions: TransitionDescription[];
99
+ /** Ambient instructions, grouped by container in the order of `states`, each group in span order. */
100
+ ambient: AmbientDescription[];
101
+ /** Findings in the order of `states`, each state's own before those of its transitions, the root's first. */
102
+ findings: FindingDescription[];
103
+ }
104
+ /** Derives the states, transitions, and ambient instructions that the viewer shows from a valid config. */
105
+ export declare function describeConfig(config: AgentLogicConfig): ConfigDescription;
106
+ /**
107
+ * Builds a transition's label: its trigger, then its guard or the word that stands for one, whether it lacks an
108
+ * alternative, its actions, and whether it is inferred or a gate.
109
+ */
110
+ export declare function buildTransitionLabel(transition: TransitionDescription): TransitionLabel;
111
+ /** Lists the states and transitions that have a gap, each state before its own transitions, in document order. */
112
+ export declare function listGaps({ states, transitions }: ConfigDescription): (StateDescription | TransitionDescription)[];
113
+ /** Lists the kinds that a state shows, in the order in which the viewer names them. */
114
+ export declare function listStateKinds(state: StateDescription): string[];
115
+ /** Returns a state's name, or a transition's state name and trigger. */
116
+ export declare function nameElement(element: StateDescription | TransitionDescription): string;
117
+ /** Lists the kinds that a transition shows, in the order in which the viewer names them. */
118
+ export declare function listTransitionKinds(transition: TransitionDescription): string[];