codeassembly-agent-logic 0.2.1 → 0.4.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 (93) hide show
  1. package/.meta/changelog.json +95 -0
  2. package/CHANGELOG.md +33 -0
  3. package/README.md +85 -5
  4. package/bin/agent-logic.js +1 -0
  5. package/dist/esm/agent/convert-with-agent.d.ts +53 -0
  6. package/dist/esm/agent/convert-with-agent.js +107 -0
  7. package/dist/esm/agent/index.d.ts +3 -0
  8. package/dist/esm/agent/index.js +2 -0
  9. package/dist/esm/cli/check-coverage-command.js +7 -10
  10. package/dist/esm/cli/convert-command.d.ts +8 -0
  11. package/dist/esm/cli/convert-command.js +3 -1
  12. package/dist/esm/cli/convert-with-agent-command.d.ts +11 -0
  13. package/dist/esm/cli/convert-with-agent-command.js +183 -0
  14. package/dist/esm/cli/index.js +3 -3
  15. package/dist/esm/cli/run.d.ts +1 -1
  16. package/dist/esm/cli/run.js +9 -5
  17. package/dist/esm/client/create-conversion-client.d.ts +44 -0
  18. package/dist/esm/client/create-conversion-client.js +86 -0
  19. package/dist/esm/client/index.d.ts +3 -0
  20. package/dist/esm/client/index.js +1 -0
  21. package/dist/esm/conversion-protocol/conversion-schemas.d.ts +70 -0
  22. package/dist/esm/conversion-protocol/conversion-schemas.js +32 -0
  23. package/dist/esm/conversion-session/conversion-tools.d.ts +4 -0
  24. package/dist/esm/conversion-session/conversion-tools.js +2 -0
  25. package/dist/esm/conversion-session/create-conversion-session.d.ts +39 -0
  26. package/dist/esm/conversion-session/create-conversion-session.js +67 -0
  27. package/dist/esm/conversion-session/format-conversion-input.d.ts +4 -0
  28. package/dist/esm/conversion-session/format-conversion-input.js +3 -0
  29. package/dist/esm/convert/convert-prompt.js +8 -3
  30. package/dist/esm/coverage-map/format-coverage-result.d.ts +6 -0
  31. package/dist/esm/coverage-map/format-coverage-result.js +7 -0
  32. package/dist/esm/instructions/conversion-instructions.d.ts +2 -0
  33. package/dist/esm/instructions/conversion-instructions.js +1 -0
  34. package/dist/esm/instructions/write-conversion-instructions.d.ts +6 -0
  35. package/dist/esm/instructions/write-conversion-instructions.js +20 -0
  36. package/dist/esm/job/create-conversion-job.d.ts +28 -0
  37. package/dist/esm/job/create-conversion-job.js +33 -0
  38. package/dist/esm/job/index.d.ts +4 -0
  39. package/dist/esm/job/index.js +2 -0
  40. package/dist/esm/react/canvas/FocusNavigation.js +5 -5
  41. package/dist/esm/react/canvas/StateNode.js +3 -3
  42. package/dist/esm/react/canvas/StatechartCanvas.js +26 -26
  43. package/dist/esm/react/hooks/describe-load-outcome.d.ts +0 -2
  44. package/dist/esm/react/hooks/describe-load-outcome.js +0 -3
  45. package/dist/esm/react/index.d.ts +0 -7
  46. package/dist/esm/react/index.js +0 -7
  47. package/dist/esm/react/styles.css +1 -1
  48. package/dist/esm/server/conversion-store.d.ts +13 -0
  49. package/dist/esm/server/conversion-store.js +1 -0
  50. package/dist/esm/server/create-conversion-handler.d.ts +36 -0
  51. package/dist/esm/server/create-conversion-handler.js +199 -0
  52. package/dist/esm/server/create-memory-conversion-store.d.ts +12 -0
  53. package/dist/esm/server/create-memory-conversion-store.js +30 -0
  54. package/dist/esm/server/index.d.ts +5 -7
  55. package/dist/esm/server/index.js +2 -6
  56. package/docs/agent-instructions.md +19 -0
  57. package/package.json +33 -15
  58. package/dist/esm/contract/built-in-harnesses.d.ts +0 -22
  59. package/dist/esm/contract/built-in-harnesses.js +0 -30
  60. package/dist/esm/contract/conversion-job.d.ts +0 -36
  61. package/dist/esm/contract/conversion-job.js +0 -17
  62. package/dist/esm/contract/index.d.ts +0 -4
  63. package/dist/esm/contract/index.js +0 -3
  64. package/dist/esm/contract/viewer-contract.d.ts +0 -804
  65. package/dist/esm/contract/viewer-contract.js +0 -38
  66. package/dist/esm/react/hooks/conversion-client.d.ts +0 -77
  67. package/dist/esm/react/hooks/conversion-client.js +0 -132
  68. package/dist/esm/react/hooks/describe-agent-selection.d.ts +0 -6
  69. package/dist/esm/react/hooks/describe-agent-selection.js +0 -18
  70. package/dist/esm/react/hooks/useAgentBridge.d.ts +0 -28
  71. package/dist/esm/react/hooks/useAgentBridge.js +0 -52
  72. package/dist/esm/react/hooks/useAgentSync.d.ts +0 -29
  73. package/dist/esm/react/hooks/useAgentSync.js +0 -75
  74. package/dist/esm/react/hooks/useConversion.d.ts +0 -31
  75. package/dist/esm/react/hooks/useConversion.js +0 -177
  76. package/dist/esm/react/hooks/useHarnessList.d.ts +0 -26
  77. package/dist/esm/react/hooks/useHarnessList.js +0 -24
  78. package/dist/esm/react/hooks/usePromptDirectory.d.ts +0 -27
  79. package/dist/esm/react/hooks/usePromptDirectory.js +0 -34
  80. package/dist/esm/server/conversion-job-implementation.d.ts +0 -11
  81. package/dist/esm/server/conversion-job-implementation.js +0 -84
  82. package/dist/esm/server/create-prompts-app.d.ts +0 -26
  83. package/dist/esm/server/create-prompts-app.js +0 -41
  84. package/dist/esm/server/create-viewer-server-plugins.d.ts +0 -15
  85. package/dist/esm/server/create-viewer-server-plugins.js +0 -76
  86. package/dist/esm/server/prompt-directory-schemas.d.ts +0 -30
  87. package/dist/esm/server/prompt-directory-schemas.js +0 -11
  88. package/dist/esm/server/prompt-directory.d.ts +0 -40
  89. package/dist/esm/server/prompt-directory.js +0 -86
  90. package/dist/esm/server/viewer-contract-implementation.d.ts +0 -12
  91. package/dist/esm/server/viewer-contract-implementation.js +0 -85
  92. /package/dist/esm/{cli → package-files}/find-package-root.d.ts +0 -0
  93. /package/dist/esm/{cli → package-files}/find-package-root.js +0 -0
@@ -1,4 +1,99 @@
1
1
  [
2
+ {
3
+ "version": "0.4.0",
4
+ "date": "2026-11-18",
5
+ "sections": [
6
+ {
7
+ "title": "🎉 Features",
8
+ "audience": "all",
9
+ "items": [
10
+ {
11
+ "description": "Adds the experimental `codeassembly-agent-logic/job` entry, whose `createConversionJob` returns a job that `runJob` of `@williamthorsen/toolbelt.llm` runs in a page or a hosted function to convert a prompt with the instructions, the `check_coverage` and `submit_draft` tools, and the caps that `convertWithAgent` uses. (#2290)",
12
+ "hash": "731cb417a800fbb51f2c04cd6dce503056ef53dd",
13
+ "entry": 1
14
+ }
15
+ ]
16
+ },
17
+ {
18
+ "title": "📦 Dependencies",
19
+ "audience": "dev",
20
+ "items": [
21
+ {
22
+ "description": "Upgrades `@xyflow/react` in `codeassembly-agent-logic` from 12.12.1 to 13.0.1 and adapts the statechart canvas to the major version's separate viewport and options stores, its `NodeChangeset` and `EdgeChangeset` change handlers, and its stylesheet path `@xyflow/react/style.css`. (#2289)",
23
+ "hash": "d8b0c600d6ff7ae2eba0e4e428bf50e1247376ae",
24
+ "entry": 1
25
+ }
26
+ ]
27
+ }
28
+ ]
29
+ },
30
+ {
31
+ "version": "0.3.0",
32
+ "date": "2026-11-16",
33
+ "sections": [
34
+ {
35
+ "title": "🎉 Features",
36
+ "audience": "all",
37
+ "items": [
38
+ {
39
+ "description": "Adds the `codeassembly-agent-logic/agent` entry, whose `convertWithAgent` converts a prompt by directing an Agent Client Protocol (ACP) agent that can call only the `check_coverage` and `submit_draft` tools, and yields an event for each coverage check and draft submission, then a `result` event that contains the outcome of the last submission. (#2283)",
40
+ "hash": "37b7b1d22998e613e187200135f6c3f51a83ef3f",
41
+ "entry": 1
42
+ },
43
+ {
44
+ "description": "Adds the `agent-logic convert-with-agent --agent <profile> <prompt-file> [output-file]` command, which reports each coverage check and draft submission on stderr, writes the config only when it is valid, and exits 130 without writing any output file when Ctrl+C stops the conversion. (#2283)",
45
+ "hash": "37b7b1d22998e613e187200135f6c3f51a83ef3f",
46
+ "entry": 2
47
+ },
48
+ {
49
+ "description": "Adds `createConversionHandler` to `codeassembly-agent-logic/server`, a Fetch handler that starts, reads, and cancels conversions on an ACP agent under a base path, together with the `ConversionStore` interface and `createMemoryConversionStore`, which keeps conversions in process memory and drops each ended one after a retention period, one hour by default. (#2285)",
50
+ "hash": "2529cac0cf94ffc7298d50ccf4dd90b0b48e8b42",
51
+ "entry": 1
52
+ },
53
+ {
54
+ "description": "Adds the `codeassembly-agent-logic/client` entry, whose browser-safe `createConversionClient` starts, reads, cancels, and watches conversions on the routes that `createConversionHandler` serves, so that a page can resume a conversion by its id after a reload. (#2285)",
55
+ "hash": "2529cac0cf94ffc7298d50ccf4dd90b0b48e8b42",
56
+ "entry": 2
57
+ }
58
+ ]
59
+ },
60
+ {
61
+ "title": "🪦 Removed",
62
+ "audience": "all",
63
+ "items": [
64
+ {
65
+ "description": "Removes the telefactor-backed conversion path from `codeassembly-agent-logic`: the `./contract` entry, the `createViewerServerPlugins`, `createPromptsApp`, prompt-directory, and viewer-contract exports of `./server`, and the `useAgentBridge`, `useAgentSync`, `useConversion`, `useHarnessList`, and `usePromptDirectory` hooks of `./react`, together with the `@williamthorsen/telefactor` peer dependency. (#2286)",
66
+ "breaking": true,
67
+ "migration": "Serve conversions with `createConversionHandler` from `codeassembly-agent-logic/server` and call them from the browser with `createConversionClient` from `codeassembly-agent-logic/client`, then remove `@williamthorsen/telefactor`; the handler runs conversions on an ACP agent and needs the `@williamthorsen/toolbelt.acp` and `@modelcontextprotocol/server` peers, and the package no longer provides a replacement that serves a prompts directory.",
68
+ "hash": "9acb9605722bab87149159de3afc0d8ea580b984",
69
+ "entry": 1
70
+ }
71
+ ]
72
+ },
73
+ {
74
+ "title": "🧪 Tests",
75
+ "audience": "dev",
76
+ "items": [
77
+ {
78
+ "description": "Replaces the `vi.waitFor` polls in `conversion-job-implementation.tool.test.ts` and `create-viewer-server-plugins.dev-server.tool.test.ts` with waits that end when the job ends, which only each test's own timeout limits, so that a slow fake-harness start no longer fails either test on a 1 s or 10 s limit. (#2277)",
79
+ "hash": "a5ab31fe194e633d9e665a7b51184a40ff6a71e7",
80
+ "entry": 1
81
+ }
82
+ ]
83
+ },
84
+ {
85
+ "title": "⚙️ Tooling",
86
+ "audience": "dev",
87
+ "items": [
88
+ {
89
+ "description": "Upgrade the lint and TypeScript config packages (#2280)",
90
+ "body": "Upgrades `@williamthorsen/eslint-config-typescript` to 22.0.0, `@williamthorsen/strict-lint` to 15.0.0, and `@williamthorsen/tsconfig` to 0.13.0, and removes the TypeScript import resolver and its `eslint-import-resolver-typescript` dev dependency from the root lint setup.",
91
+ "hash": "a68dff407958bbc82b969e0edfdd58cfde9d861e"
92
+ }
93
+ ]
94
+ }
95
+ ]
96
+ },
2
97
  {
3
98
  "version": "0.2.1",
4
99
  "date": "2026-11-12",
package/CHANGELOG.md CHANGED
@@ -2,6 +2,39 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## 0.4.0 — 2026-11-18
6
+
7
+ ### 🎉 Features
8
+
9
+ - Adds the experimental `codeassembly-agent-logic/job` entry, whose `createConversionJob` returns a job that `runJob` of `@williamthorsen/toolbelt.llm` runs in a page or a hosted function to convert a prompt with the instructions, the `check_coverage` and `submit_draft` tools, and the caps that `convertWithAgent` uses. (#2290)
10
+
11
+ ### 📦 Dependencies
12
+
13
+ - Upgrades `@xyflow/react` in `codeassembly-agent-logic` from 12.12.1 to 13.0.1 and adapts the statechart canvas to the major version's separate viewport and options stores, its `NodeChangeset` and `EdgeChangeset` change handlers, and its stylesheet path `@xyflow/react/style.css`. (#2289)
14
+
15
+ ## 0.3.0 — 2026-11-16
16
+
17
+ ### 🎉 Features
18
+
19
+ - Adds the `codeassembly-agent-logic/agent` entry, whose `convertWithAgent` converts a prompt by directing an Agent Client Protocol (ACP) agent that can call only the `check_coverage` and `submit_draft` tools, and yields an event for each coverage check and draft submission, then a `result` event that contains the outcome of the last submission. (#2283)
20
+ - Adds the `agent-logic convert-with-agent --agent <profile> <prompt-file> [output-file]` command, which reports each coverage check and draft submission on stderr, writes the config only when it is valid, and exits 130 without writing any output file when Ctrl+C stops the conversion. (#2283)
21
+ - Adds `createConversionHandler` to `codeassembly-agent-logic/server`, a Fetch handler that starts, reads, and cancels conversions on an ACP agent under a base path, together with the `ConversionStore` interface and `createMemoryConversionStore`, which keeps conversions in process memory and drops each ended one after a retention period, one hour by default. (#2285)
22
+ - Adds the `codeassembly-agent-logic/client` entry, whose browser-safe `createConversionClient` starts, reads, cancels, and watches conversions on the routes that `createConversionHandler` serves, so that a page can resume a conversion by its id after a reload. (#2285)
23
+
24
+ ### 🪦 Removed
25
+
26
+ - 🚨 **Breaking:** Removes the telefactor-backed conversion path from `codeassembly-agent-logic`: the `./contract` entry, the `createViewerServerPlugins`, `createPromptsApp`, prompt-directory, and viewer-contract exports of `./server`, and the `useAgentBridge`, `useAgentSync`, `useConversion`, `useHarnessList`, and `usePromptDirectory` hooks of `./react`, together with the `@williamthorsen/telefactor` peer dependency. (#2286)
27
+
28
+ ### 🧪 Tests
29
+
30
+ - Replaces the `vi.waitFor` polls in `conversion-job-implementation.tool.test.ts` and `create-viewer-server-plugins.dev-server.tool.test.ts` with waits that end when the job ends, which only each test's own timeout limits, so that a slow fake-harness start no longer fails either test on a 1 s or 10 s limit. (#2277)
31
+
32
+ ### ⚙️ Tooling
33
+
34
+ - Upgrade the lint and TypeScript config packages (#2280)
35
+
36
+ Upgrades `@williamthorsen/eslint-config-typescript` to 22.0.0, `@williamthorsen/strict-lint` to 15.0.0, and `@williamthorsen/tsconfig` to 0.13.0, and removes the TypeScript import resolver and its `eslint-import-resolver-typescript` dev dependency from the root lint setup.
37
+
5
38
  ## 0.2.1 — 2026-11-12
6
39
 
7
40
  ### Notes
package/README.md CHANGED
@@ -1,3 +1,11 @@
1
+ <!-- section:release-notes -->
2
+ ## Release notes — v0.4.0 (2026-11-18)
3
+
4
+ ### 🎉 Features
5
+
6
+ - Adds the experimental `codeassembly-agent-logic/job` entry, whose `createConversionJob` returns a job that `runJob` of `@williamthorsen/toolbelt.llm` runs in a page or a hosted function to convert a prompt with the instructions, the `check_coverage` and `submit_draft` tools, and the caps that `convertWithAgent` uses. (#2290)
7
+ <!-- /section:release-notes -->
8
+
1
9
  <!-- readme-type: library -->
2
10
 
3
11
  # codeassembly-agent-logic
@@ -25,17 +33,88 @@ if (result.ok) {
25
33
  | Entry | Exports |
26
34
  | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
27
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/agent` | `convertWithAgent`, which converts a prompt by directing an ACP agent through the conversion. |
28
37
  | `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. |
29
38
  | `codeassembly-agent-logic/react/styles.css` | The canvas stylesheet. |
30
- | `codeassembly-agent-logic/server` | `createViewerServerPlugins`, the Vite plugins that serve the prompts directory and run conversions through a harness that telefactor hosts. |
31
- | `codeassembly-agent-logic/contract` | The contracts between a page and its server: the viewer contract, the conversion job, and the built-in harnesses. |
39
+ | `codeassembly-agent-logic/server` | `createConversionHandler`, which serves conversions on an ACP agent, and its stores. |
40
+ | `codeassembly-agent-logic/client` | `createConversionClient`, the browser client of the routes that `createConversionHandler` serves. |
41
+ | `codeassembly-agent-logic/job` | `createConversionJob`, which converts a prompt as a job of `@williamthorsen/toolbelt.llm`, in a page or a function. |
32
42
  | `codeassembly-agent-logic/agent-logic.schema.json` | The config's JSON Schema. |
33
43
 
34
- React 19 is a peer of `./react`, and `@williamthorsen/telefactor` a peer of `./server` and `./contract`.
44
+ React 19 is a peer of `./react`, `@williamthorsen/toolbelt.acp` and `@modelcontextprotocol/server` peers of `./agent` and `./server`, and `@williamthorsen/toolbelt.llm` a peer of `./job`.
45
+
46
+ ## Converting on an ACP agent
47
+
48
+ ```ts
49
+ import { convertWithAgent } from 'codeassembly-agent-logic/agent';
50
+ import { claudeCodeProfile } from '@williamthorsen/toolbelt.acp/proposed';
51
+
52
+ for await (const event of convertWithAgent({ prompt, name: 'refund-request.md', agent: claudeCodeProfile() })) {
53
+ if (event.type === 'result') console.log(event.result);
54
+ }
55
+ ```
56
+
57
+ `convertWithAgent` runs the agent through [`@williamthorsen/toolbelt.acp`](https://github.com/williamthorsen/toolbelt/tree/main/packages/acp#readme) in an empty temporary directory and gives it two tools: `check_coverage`, which answers 3 checks of its coverage map, and `submit_draft`, which converts a draft and accepts 5. Every other request of the agent is refused. It yields the agent's message text and each check and submission, then a `result` event whose `ConvertResult` is the outcome of the last submission, with the usage and cost that the agent reports. The agent's instructions are [`docs/agent-instructions.md`](docs/agent-instructions.md) followed by the [extraction rules](docs/extraction-rules.md), the same text that a [conversion job](#converting-in-a-page-or-a-function) sends. The doc comment of `convertWithAgent` states when it rejects.
58
+
59
+ The agent's harness must be installed and signed in. Each profile signs in as follows:
60
+
61
+ | Profile | Signs in with |
62
+ | -------------------- | ------------------------------------------------------------------------------------------------------------- |
63
+ | `claudeCodeProfile` | The `claude` CLI's login, or `ANTHROPIC_API_KEY` in the environment |
64
+ | `antigravityProfile` | The CLI's personal Google login |
65
+ | `codexProfile` | Not supported: The profile cannot identify calls of the conversion's tools, so `convertWithAgent` rejects it. |
66
+
67
+ ## Converting in a page or a function
68
+
69
+ ```ts
70
+ import { createConversionJob } from 'codeassembly-agent-logic/job';
71
+ import { runJob } from '@williamthorsen/toolbelt.llm/proposed';
72
+
73
+ const outcome = await runJob(createConversionJob({ prompt, name: 'refund-request.md' }), {
74
+ provider: 'anthropic',
75
+ apiKey,
76
+ model: 'claude-sonnet-5-5',
77
+ });
78
+ if (outcome.status === 'completed') console.log(outcome.result);
79
+ ```
80
+
81
+ `createConversionJob` returns a job for [`@williamthorsen/toolbelt.llm`](https://github.com/williamthorsen/toolbelt/tree/main/packages/llm#readme), which runs it in the page on a user's connection or at an operator's endpoint, without a harness. The job sends the instructions and the message that `convertWithAgent` sends, offers the same two tools with the same caps, and makes at most `MAX_ROUNDS` model requests. Its result is a `ConvertResult`, available once the conversion is finished: the config accepted, the prompt recorded out of scope, or the last of the 5 submissions rejected. A run that the model ends earlier is `unfinished`. Create a job for each run.
82
+
83
+ ## Serving conversions
84
+
85
+ ```ts
86
+ import { createConversionHandler, createMemoryConversionStore } from 'codeassembly-agent-logic/server';
87
+ import { claudeCodeProfile } from '@williamthorsen/toolbelt.acp/proposed';
88
+
89
+ const handleConversion = createConversionHandler({
90
+ agent: claudeCodeProfile(),
91
+ store: createMemoryConversionStore(),
92
+ authorize: (request) => isSignedIn(request),
93
+ timeoutMs: 10 * 60_000,
94
+ basePath: '/api/conversions',
95
+ });
96
+ ```
97
+
98
+ ```ts
99
+ import { createConversionClient } from 'codeassembly-agent-logic/client';
100
+
101
+ const client = createConversionClient({ url: '/api/conversions' });
102
+ const started = await client.start({ prompt, name: 'refund-request.md' });
103
+ if (started.ok) {
104
+ for await (const outcome of client.watch(started.conversion.id)) console.log(outcome);
105
+ }
106
+ ```
107
+
108
+ `createConversionHandler` is a Fetch handler (`Request → Response`) that starts a conversion with `POST {basePath}`, reads it with `GET {basePath}/{id}`, and cancels it with `DELETE {basePath}/{id}`, running each one through `convertWithAgent`. A page that reloads resumes by calling `watch` with the id that it kept. The doc comments of `createConversionHandler` and `ConversionClient` state the status codes and the edge cases. The host supplies:
109
+
110
+ - Mounting: The host's server passes each request under `basePath` to the handler.
111
+ - Authorization: `authorize` decides whether the handler serves a request.
112
+ - Store: `createMemoryConversionStore` keeps conversions in one process and drops each ended one after an hour; a durable store implements `ConversionStore`.
113
+ - Timeout: `timeoutMs` bounds each conversion, after which it fails.
35
114
 
36
115
  ## What the app supplies
37
116
 
38
- 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`.
117
+ 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 URL of the conversions resource to `./client`'s `createConversionClient`.
39
118
 
40
119
  ## Styling and theming
41
120
 
@@ -64,6 +143,7 @@ The properties, whose defaults [`styles.css`](src/react/styles.css) declares:
64
143
  pnpm dlx codeassembly-agent-logic rules
65
144
  pnpm dlx codeassembly-agent-logic convert prompt.md draft.json prompt.agent-logic.json
66
145
  pnpm dlx codeassembly-agent-logic check-coverage prompt.md coverage-map.json
146
+ pnpm dlx --package codeassembly-agent-logic --package @williamthorsen/toolbelt.acp --package @modelcontextprotocol/server agent-logic convert-with-agent --agent claude-code prompt.md
67
147
  ```
68
148
 
69
- `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.
149
+ `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; `convert-with-agent` converts a prompt on an ACP agent through `convertWithAgent`, which needs the optional peers. `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.
@@ -20,6 +20,7 @@ if (!existsSync(entryPoint)) {
20
20
  try {
21
21
  await import(entryPoint.href);
22
22
  } catch (error) {
23
+ // eslint-disable-next-line no-restricted-syntax -- The shared helper is not a builtin; see the import note above.
23
24
  const message = error instanceof Error ? error.message : String(error);
24
25
  process.stderr.write(`agent-logic: failed to load: ${message}\n`);
25
26
  process.exit(1);
@@ -0,0 +1,53 @@
1
+ import { type AgentProfile, runPrompt } from '@williamthorsen/toolbelt.acp/proposed';
2
+ import { type SessionEvent } from '../conversion-session/create-conversion-session.js';
3
+ import type { ConvertResult } from '../convert/convert-prompt.js';
4
+ /** The name of the MCP server through which the agent reaches the conversion's tools. */
5
+ export declare const CONVERSION_SERVER_NAME = "agent_logic";
6
+ /** What `convertWithAgent` converts, and on which agent. */
7
+ export interface ConvertWithAgentOptions {
8
+ /** The prompt, verbatim. */
9
+ readonly prompt: string;
10
+ /** The prompt's file name, from which the config's root id derives. */
11
+ readonly name: string;
12
+ /** The agent profile, which must define `isToolServerCall`. */
13
+ readonly agent: AgentProfile;
14
+ /** Ends the run, which then rejects with the signal's reason. */
15
+ readonly signal?: AbortSignal;
16
+ }
17
+ /** A step of a conversion, or its outcome, which is always the last event. */
18
+ export type ConversionEvent = SessionEvent | {
19
+ readonly type: 'message';
20
+ readonly text: string;
21
+ } | {
22
+ readonly type: 'result';
23
+ readonly result: ConvertResult;
24
+ /** Token counts, when the agent reports them. */
25
+ readonly usage?: {
26
+ readonly inputTokens: number;
27
+ readonly outputTokens: number;
28
+ readonly totalTokens: number;
29
+ };
30
+ /** The session's cost, when the agent reports one. */
31
+ readonly cost?: {
32
+ readonly amount: number;
33
+ readonly currency: string;
34
+ };
35
+ };
36
+ /**
37
+ * Converts a prompt by directing an ACP agent through the conversion: The agent receives the conversion's instructions
38
+ * and the extraction rules, checks its coverage map through a `check_coverage` tool, and submits each draft through a
39
+ * `submit_draft` tool, which converts it. The agent runs in an empty temporary directory, which is removed when the run
40
+ * ends, and every request other than a call of those tools is refused. Yields the agent's message text and each check
41
+ * and submission, then a `result` event that contains the outcome of the last submission.
42
+ *
43
+ * Rejects before the agent starts when the profile cannot identify calls of the conversion's tools, which
44
+ * `codexProfile` cannot; when the agent ends its turn without submitting a draft; with the signal's reason when the
45
+ * signal aborts; and, when the agent fails, with an error that names the cause, such as a harness that is not signed
46
+ * in.
47
+ *
48
+ * @stage proposed
49
+ * @experimental
50
+ */
51
+ export declare const convertWithAgent: (options: ConvertWithAgentOptions) => AsyncGenerator<ConversionEvent>;
52
+ /** Returns `convertWithAgent` running prompts through `runPromptImpl`, which tests replace. */
53
+ export declare function createConvertWithAgent(runPromptImpl: typeof runPrompt): (options: ConvertWithAgentOptions) => AsyncGenerator<ConversionEvent>;
@@ -0,0 +1,107 @@
1
+ import { mkdtemp, rm } from 'node:fs/promises';
2
+ import os from 'node:os';
3
+ import path from 'node:path';
4
+ import { McpServer } from '@modelcontextprotocol/server';
5
+ import { AgentRunError, runPrompt } from '@williamthorsen/toolbelt.acp/proposed';
6
+ import { z } from 'zod';
7
+ import { CHECK_COVERAGE_DESCRIPTION, SUBMIT_DRAFT_DESCRIPTION } from "../conversion-session/conversion-tools.js";
8
+ import { createConversionSession } from "../conversion-session/create-conversion-session.js";
9
+ import { formatConversionInput } from "../conversion-session/format-conversion-input.js";
10
+ import { coverageMapSchema } from "../coverage-map/coverage-map-schema.js";
11
+ import { CONVERSION_INSTRUCTIONS } from "../instructions/conversion-instructions.js";
12
+ export const CONVERSION_SERVER_NAME = 'agent_logic';
13
+ const AUTH_REQUIRED_CODE = -32_000;
14
+ export const convertWithAgent = createConvertWithAgent(runPrompt);
15
+ export function createConvertWithAgent(runPromptImpl) {
16
+ return async function* ({ prompt, name, agent, signal }) {
17
+ if (agent.isToolServerCall === undefined) {
18
+ throw new Error(`The agent \`${agent.command}\` cannot convert a prompt: Its profile cannot identify calls of the conversion's tools, so they would be refused.`);
19
+ }
20
+ signal?.throwIfAborted();
21
+ const pending = [];
22
+ const session = createConversionSession({
23
+ prompt,
24
+ name,
25
+ onEvent: (event) => {
26
+ pending.push(event);
27
+ },
28
+ });
29
+ const cwd = await mkdtemp(path.join(os.tmpdir(), 'agent-logic-conversion-'));
30
+ try {
31
+ let stopped;
32
+ try {
33
+ const run = runPromptImpl({
34
+ agent,
35
+ cwd,
36
+ instructions: CONVERSION_INSTRUCTIONS,
37
+ prompt: formatConversionInput(prompt, name),
38
+ tools: {
39
+ name: CONVERSION_SERVER_NAME,
40
+ createServer: () => createConversionServer(session),
41
+ isPreapproved: true,
42
+ },
43
+ ...(signal !== undefined && { signal }),
44
+ });
45
+ for await (const event of run) {
46
+ yield* pending.splice(0);
47
+ if (event.type === 'stopped')
48
+ stopped = event;
49
+ else if (event.update.sessionUpdate === 'agent_message_chunk' && event.update.content.type === 'text') {
50
+ yield { type: 'message', text: event.update.content.text };
51
+ }
52
+ }
53
+ }
54
+ catch (error) {
55
+ if (signal?.aborted === true)
56
+ throw signal.reason;
57
+ throw describeRunError(error);
58
+ }
59
+ yield* pending.splice(0);
60
+ if (signal?.aborted === true)
61
+ throw signal.reason;
62
+ const { result } = session;
63
+ if (result === undefined) {
64
+ const stopReason = stopped?.stopReason ?? 'unknown';
65
+ throw new Error(`The agent ended its turn (stop reason: ${stopReason}) without submitting a draft.`);
66
+ }
67
+ yield {
68
+ type: 'result',
69
+ result,
70
+ ...(stopped?.usage !== undefined && {
71
+ usage: {
72
+ inputTokens: stopped.usage.inputTokens,
73
+ outputTokens: stopped.usage.outputTokens,
74
+ totalTokens: stopped.usage.totalTokens,
75
+ },
76
+ }),
77
+ ...(stopped?.cost !== undefined && { cost: { amount: stopped.cost.amount, currency: stopped.cost.currency } }),
78
+ };
79
+ }
80
+ finally {
81
+ await rm(cwd, { recursive: true, force: true });
82
+ }
83
+ };
84
+ }
85
+ function createConversionServer(session) {
86
+ const server = new McpServer({ name: CONVERSION_SERVER_NAME, version: '1.0.0' });
87
+ server.registerTool('check_coverage', {
88
+ description: CHECK_COVERAGE_DESCRIPTION,
89
+ inputSchema: z.object({ map: coverageMapSchema }),
90
+ }, ({ map }) => ({ content: [{ type: 'text', text: session.checkCoverage(map) }] }));
91
+ server.registerTool('submit_draft', {
92
+ description: SUBMIT_DRAFT_DESCRIPTION,
93
+ inputSchema: z.object({ draft: z.string().describe("The draft's JSON text.") }),
94
+ }, ({ draft }) => ({ content: [{ type: 'text', text: session.submitDraft(draft) }] }));
95
+ return server;
96
+ }
97
+ function describeRunError(error) {
98
+ if (!(error instanceof AgentRunError))
99
+ return error;
100
+ const { cause } = error;
101
+ const isSignInRequired = typeof cause === 'object' && cause !== null && 'code' in cause && cause.code === AUTH_REQUIRED_CODE;
102
+ if (!isSignInRequired)
103
+ return error;
104
+ return new Error(`The agent \`${error.command}\` is not signed in: Sign in to its harness, then convert again.`, {
105
+ cause: error,
106
+ });
107
+ }
@@ -0,0 +1,3 @@
1
+ /** `./agent` entry: converts a prompt by directing an ACP agent through the conversion. */
2
+ export { MAX_COVERAGE_CHECKS, MAX_SUBMISSIONS, type SessionEvent, } from '../conversion-session/create-conversion-session.js';
3
+ export { CONVERSION_SERVER_NAME, type ConversionEvent, convertWithAgent, type ConvertWithAgentOptions, } from './convert-with-agent.js';
@@ -0,0 +1,2 @@
1
+ export { MAX_COVERAGE_CHECKS, MAX_SUBMISSIONS, } from "../conversion-session/create-conversion-session.js";
2
+ export { CONVERSION_SERVER_NAME, convertWithAgent, } from "./convert-with-agent.js";
@@ -1,9 +1,10 @@
1
1
  import { readFileSync } from 'node:fs';
2
2
  import { parseArgs } from 'node:util';
3
3
  import { describeError } from '@williamthorsen/toolbelt.errors';
4
- import { checkCoverage, describeBlock } from "../coverage-map/check-coverage.js";
4
+ import { checkCoverage } from "../coverage-map/check-coverage.js";
5
5
  import { coverageMapSchema } from "../coverage-map/coverage-map-schema.js";
6
- import { readPackageVersion } from "./find-package-root.js";
6
+ import { formatCoverageResult } from "../coverage-map/format-coverage-result.js";
7
+ import { readPackageVersion } from "../package-files/find-package-root.js";
7
8
  const PROGRAM = 'agent-logic check-coverage';
8
9
  const HELP = `Lists the parts of a prompt that a coverage map does not quote.
9
10
 
@@ -85,14 +86,10 @@ function runCli(args, stdout, stderr) {
85
86
  }
86
87
  return 1;
87
88
  }
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)
89
+ const lines = formatCoverageResult(prompt, checkCoverage(prompt, map.data));
90
+ for (const line of lines)
91
+ stdout.push(`${line}\n`);
92
+ if (lines.length > 0)
96
93
  return 1;
97
94
  stdout.push(`${PROGRAM}: every block is mapped\n`);
98
95
  return 0;
@@ -1,3 +1,11 @@
1
+ import { z } from 'zod';
1
2
  import type { CommandOutput } from './run.js';
2
3
  /** Runs `agent-logic convert`: converts a draft of a prompt's logic into a config and writes it. */
3
4
  export declare function runConvertCommand(args: readonly string[]): CommandOutput;
5
+ /** The shape of the problems file that `--problems-file` writes for a draft that cannot be converted. */
6
+ export declare const problemsFileSchema: z.ZodObject<{
7
+ problems: z.ZodArray<z.ZodObject<{
8
+ path: z.ZodString;
9
+ message: z.ZodString;
10
+ }, z.core.$strip>>;
11
+ }, z.core.$strip>;
@@ -1,8 +1,9 @@
1
1
  import { readFileSync, rmSync, writeFileSync } from 'node:fs';
2
2
  import { parseArgs } from 'node:util';
3
3
  import { describeError } from '@williamthorsen/toolbelt.errors';
4
+ import { z } from 'zod';
4
5
  import { convertPrompt } from "../convert/convert-prompt.js";
5
- import { readPackageVersion } from "./find-package-root.js";
6
+ import { readPackageVersion } from "../package-files/find-package-root.js";
6
7
  const PROGRAM = 'agent-logic convert';
7
8
  const HELP = `Converts a draft of an agent prompt's logic into an agent-logic config.
8
9
 
@@ -36,6 +37,7 @@ export function runConvertCommand(args) {
36
37
  const exitCode = runCli(args, stdout, stderr);
37
38
  return { exitCode, stderr: stderr.join(''), stdout: stdout.join('') };
38
39
  }
40
+ export const problemsFileSchema = z.object({ problems: z.array(z.object({ path: z.string(), message: z.string() })) });
39
41
  function runCli(args, stdout, stderr) {
40
42
  let parsed;
41
43
  try {
@@ -0,0 +1,11 @@
1
+ import type { ConversionEvent, ConvertWithAgentOptions } from '../agent/convert-with-agent.js';
2
+ import type { CommandOutput } from './run.js';
3
+ /** What the command uses that a test replaces. */
4
+ export interface ConvertWithAgentCommandDependencies {
5
+ /** Converts the prompt; defaults to `convertWithAgent`. */
6
+ convert?: (options: ConvertWithAgentOptions) => AsyncIterable<ConversionEvent>;
7
+ /** Writes a progress line as it happens; defaults to the process's stderr. */
8
+ writeProgress?: (line: string) => void;
9
+ }
10
+ /** Runs `agent-logic convert-with-agent`: converts a prompt file on a named agent profile and writes the config. */
11
+ export declare function runConvertWithAgentCommand(args: readonly string[], dependencies?: ConvertWithAgentCommandDependencies): Promise<CommandOutput>;