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.
- package/.meta/changelog.json +95 -0
- package/CHANGELOG.md +33 -0
- package/README.md +85 -5
- package/bin/agent-logic.js +1 -0
- package/dist/esm/agent/convert-with-agent.d.ts +53 -0
- package/dist/esm/agent/convert-with-agent.js +107 -0
- package/dist/esm/agent/index.d.ts +3 -0
- package/dist/esm/agent/index.js +2 -0
- package/dist/esm/cli/check-coverage-command.js +7 -10
- package/dist/esm/cli/convert-command.d.ts +8 -0
- package/dist/esm/cli/convert-command.js +3 -1
- package/dist/esm/cli/convert-with-agent-command.d.ts +11 -0
- package/dist/esm/cli/convert-with-agent-command.js +183 -0
- package/dist/esm/cli/index.js +3 -3
- package/dist/esm/cli/run.d.ts +1 -1
- package/dist/esm/cli/run.js +9 -5
- package/dist/esm/client/create-conversion-client.d.ts +44 -0
- package/dist/esm/client/create-conversion-client.js +86 -0
- package/dist/esm/client/index.d.ts +3 -0
- package/dist/esm/client/index.js +1 -0
- package/dist/esm/conversion-protocol/conversion-schemas.d.ts +70 -0
- package/dist/esm/conversion-protocol/conversion-schemas.js +32 -0
- package/dist/esm/conversion-session/conversion-tools.d.ts +4 -0
- package/dist/esm/conversion-session/conversion-tools.js +2 -0
- package/dist/esm/conversion-session/create-conversion-session.d.ts +39 -0
- package/dist/esm/conversion-session/create-conversion-session.js +67 -0
- package/dist/esm/conversion-session/format-conversion-input.d.ts +4 -0
- package/dist/esm/conversion-session/format-conversion-input.js +3 -0
- package/dist/esm/convert/convert-prompt.js +8 -3
- package/dist/esm/coverage-map/format-coverage-result.d.ts +6 -0
- package/dist/esm/coverage-map/format-coverage-result.js +7 -0
- package/dist/esm/instructions/conversion-instructions.d.ts +2 -0
- package/dist/esm/instructions/conversion-instructions.js +1 -0
- package/dist/esm/instructions/write-conversion-instructions.d.ts +6 -0
- package/dist/esm/instructions/write-conversion-instructions.js +20 -0
- package/dist/esm/job/create-conversion-job.d.ts +28 -0
- package/dist/esm/job/create-conversion-job.js +33 -0
- package/dist/esm/job/index.d.ts +4 -0
- package/dist/esm/job/index.js +2 -0
- package/dist/esm/react/canvas/FocusNavigation.js +5 -5
- package/dist/esm/react/canvas/StateNode.js +3 -3
- package/dist/esm/react/canvas/StatechartCanvas.js +26 -26
- package/dist/esm/react/hooks/describe-load-outcome.d.ts +0 -2
- package/dist/esm/react/hooks/describe-load-outcome.js +0 -3
- package/dist/esm/react/index.d.ts +0 -7
- package/dist/esm/react/index.js +0 -7
- package/dist/esm/react/styles.css +1 -1
- package/dist/esm/server/conversion-store.d.ts +13 -0
- package/dist/esm/server/conversion-store.js +1 -0
- package/dist/esm/server/create-conversion-handler.d.ts +36 -0
- package/dist/esm/server/create-conversion-handler.js +199 -0
- package/dist/esm/server/create-memory-conversion-store.d.ts +12 -0
- package/dist/esm/server/create-memory-conversion-store.js +30 -0
- package/dist/esm/server/index.d.ts +5 -7
- package/dist/esm/server/index.js +2 -6
- package/docs/agent-instructions.md +19 -0
- package/package.json +33 -15
- package/dist/esm/contract/built-in-harnesses.d.ts +0 -22
- package/dist/esm/contract/built-in-harnesses.js +0 -30
- package/dist/esm/contract/conversion-job.d.ts +0 -36
- package/dist/esm/contract/conversion-job.js +0 -17
- package/dist/esm/contract/index.d.ts +0 -4
- package/dist/esm/contract/index.js +0 -3
- package/dist/esm/contract/viewer-contract.d.ts +0 -804
- package/dist/esm/contract/viewer-contract.js +0 -38
- package/dist/esm/react/hooks/conversion-client.d.ts +0 -77
- package/dist/esm/react/hooks/conversion-client.js +0 -132
- package/dist/esm/react/hooks/describe-agent-selection.d.ts +0 -6
- package/dist/esm/react/hooks/describe-agent-selection.js +0 -18
- package/dist/esm/react/hooks/useAgentBridge.d.ts +0 -28
- package/dist/esm/react/hooks/useAgentBridge.js +0 -52
- package/dist/esm/react/hooks/useAgentSync.d.ts +0 -29
- package/dist/esm/react/hooks/useAgentSync.js +0 -75
- package/dist/esm/react/hooks/useConversion.d.ts +0 -31
- package/dist/esm/react/hooks/useConversion.js +0 -177
- package/dist/esm/react/hooks/useHarnessList.d.ts +0 -26
- package/dist/esm/react/hooks/useHarnessList.js +0 -24
- package/dist/esm/react/hooks/usePromptDirectory.d.ts +0 -27
- package/dist/esm/react/hooks/usePromptDirectory.js +0 -34
- package/dist/esm/server/conversion-job-implementation.d.ts +0 -11
- package/dist/esm/server/conversion-job-implementation.js +0 -84
- package/dist/esm/server/create-prompts-app.d.ts +0 -26
- package/dist/esm/server/create-prompts-app.js +0 -41
- package/dist/esm/server/create-viewer-server-plugins.d.ts +0 -15
- package/dist/esm/server/create-viewer-server-plugins.js +0 -76
- package/dist/esm/server/prompt-directory-schemas.d.ts +0 -30
- package/dist/esm/server/prompt-directory-schemas.js +0 -11
- package/dist/esm/server/prompt-directory.d.ts +0 -40
- package/dist/esm/server/prompt-directory.js +0 -86
- package/dist/esm/server/viewer-contract-implementation.d.ts +0 -12
- package/dist/esm/server/viewer-contract-implementation.js +0 -85
- /package/dist/esm/{cli → package-files}/find-package-root.d.ts +0 -0
- /package/dist/esm/{cli → package-files}/find-package-root.js +0 -0
package/.meta/changelog.json
CHANGED
|
@@ -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` | `
|
|
31
|
-
| `codeassembly-agent-logic/
|
|
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 `@
|
|
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
|
|
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.
|
package/bin/agent-logic.js
CHANGED
|
@@ -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';
|
|
@@ -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
|
|
4
|
+
import { checkCoverage } from "../coverage-map/check-coverage.js";
|
|
5
5
|
import { coverageMapSchema } from "../coverage-map/coverage-map-schema.js";
|
|
6
|
-
import {
|
|
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
|
|
89
|
-
for (const
|
|
90
|
-
stdout.push(
|
|
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 "
|
|
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>;
|