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
@@ -0,0 +1,183 @@
1
+ import { readFileSync, writeFileSync } from 'node:fs';
2
+ import path from 'node:path';
3
+ import { parseArgs } from 'node:util';
4
+ import { describeError } from '@williamthorsen/toolbelt.errors';
5
+ import { readPackageVersion } from "../package-files/find-package-root.js";
6
+ const PROGRAM = 'agent-logic convert-with-agent';
7
+ const AGENT_NAMES = ['antigravity', 'claude-code', 'codex'];
8
+ const INTERRUPTED_EXIT_CODE = 130;
9
+ const HELP = `Converts an agent prompt into an agent-logic config by directing an ACP agent through the conversion.
10
+
11
+ Usage: ${PROGRAM} [options] <prompt-file> [output-file]
12
+
13
+ Arguments:
14
+ prompt-file the prompt, read verbatim
15
+ output-file where to write the config; written only when the config is valid.
16
+ Default: <base>.agent-logic.json beside the prompt
17
+
18
+ Options:
19
+ --agent <name> the agent profile: ${AGENT_NAMES.join(', ')} (required)
20
+ -h, --help print this help
21
+ -V, --version print the version
22
+
23
+ The command needs the optional peers @williamthorsen/toolbelt.acp and
24
+ @modelcontextprotocol/server, and the agent's harness installed and signed in.
25
+ It reports each coverage check and draft submission on stderr as it happens.
26
+
27
+ Exit codes:
28
+ 0 the config was written
29
+ 1 the agent's last draft has problems, which are listed
30
+ 2 the arguments or files are wrong, or the run failed
31
+ 3 the agent reports the prompt out of scope
32
+ 130 the run was interrupted, and the conversion stopped its agent
33
+
34
+ Example:
35
+ ${PROGRAM} --agent claude-code prompts/refund-request.md
36
+ `;
37
+ export async function runConvertWithAgentCommand(args, dependencies = {}) {
38
+ const stdout = [];
39
+ const stderr = [];
40
+ const exitCode = await runCli(args, dependencies, stdout, stderr);
41
+ return { exitCode, stderr: stderr.join(''), stdout: stdout.join('') };
42
+ }
43
+ function deriveOutputPath(promptFile) {
44
+ const base = path.basename(promptFile, path.extname(promptFile));
45
+ return path.join(path.dirname(promptFile), `${base}.agent-logic.json`);
46
+ }
47
+ function describeEvent(event) {
48
+ switch (event.type) {
49
+ case 'coverage-checked':
50
+ return `coverage check ${event.check}: ${event.unmapped} unmapped blocks, ${event.quoteProblems} quote problems`;
51
+ case 'draft-submitted':
52
+ return `draft ${event.submission}: ${event.outcome === 'problems' ? `${event.problems} problems` : event.outcome}`;
53
+ case 'message':
54
+ return undefined;
55
+ case 'result': {
56
+ const usage = event.usage === undefined ? undefined : `${event.usage.totalTokens} tokens`;
57
+ const cost = event.cost === undefined ? undefined : `${event.cost.amount} ${event.cost.currency}`;
58
+ const parts = [usage, cost].filter((part) => part !== undefined);
59
+ return parts.length === 0 ? undefined : `used ${parts.join(', ')}`;
60
+ }
61
+ }
62
+ }
63
+ function isAgentName(value) {
64
+ return AGENT_NAMES.some((name) => name === value);
65
+ }
66
+ async function loadAgent(agentName, convert) {
67
+ const acp = await import('@williamthorsen/toolbelt.acp/proposed');
68
+ const agent = agentName === 'antigravity'
69
+ ? acp.antigravityProfile()
70
+ : agentName === 'claude-code'
71
+ ? acp.claudeCodeProfile()
72
+ : acp.codexProfile();
73
+ return { agent, convert: convert ?? (await import("../agent/convert-with-agent.js")).convertWithAgent };
74
+ }
75
+ function reportResult(result, outputFile, stdout, stderr) {
76
+ if ('outOfScope' in result) {
77
+ stderr.push(`${PROGRAM}: the prompt is out of scope: ${result.outOfScope.reason}\n`);
78
+ return 3;
79
+ }
80
+ if (!result.ok) {
81
+ for (const { path: problemPath, message } of result.problems) {
82
+ stderr.push(`${PROGRAM}: ${problemPath === '' ? '' : `${problemPath}: `}${message}\n`);
83
+ }
84
+ stderr.push(`${PROGRAM}: wrote nothing; the agent's last draft has these problems\n`);
85
+ return 1;
86
+ }
87
+ try {
88
+ writeFileSync(outputFile, result.text);
89
+ }
90
+ catch (error) {
91
+ stderr.push(`${PROGRAM}: ${describeError(error)}; pass a path in a directory that exists and is writable\n`);
92
+ return 2;
93
+ }
94
+ stdout.push(`${PROGRAM}: wrote ${outputFile}\n`);
95
+ return 0;
96
+ }
97
+ async function runCli(args, dependencies, stdout, stderr) {
98
+ let parsed;
99
+ try {
100
+ parsed = parseArgs({
101
+ args: [...args],
102
+ allowPositionals: true,
103
+ options: {
104
+ agent: { type: 'string' },
105
+ help: { type: 'boolean', short: 'h' },
106
+ version: { type: 'boolean', short: 'V' },
107
+ },
108
+ });
109
+ }
110
+ catch (error) {
111
+ stderr.push(`${PROGRAM}: ${describeError(error)}; run ${PROGRAM} --help for usage\n`);
112
+ return 2;
113
+ }
114
+ if (parsed.values.help === true) {
115
+ stdout.push(HELP);
116
+ return 0;
117
+ }
118
+ if (parsed.values.version === true) {
119
+ stdout.push(`${readPackageVersion()}\n`);
120
+ return 0;
121
+ }
122
+ const [promptFile, outputArgument, ...extra] = parsed.positionals;
123
+ if (promptFile === undefined || extra.length > 0) {
124
+ stderr.push(`${PROGRAM}: expected 1 or 2 arguments, received ${parsed.positionals.length}; run ${PROGRAM} --help for usage\n`);
125
+ return 2;
126
+ }
127
+ const agentName = parsed.values.agent;
128
+ if (!isAgentName(agentName)) {
129
+ const received = agentName === undefined ? 'none' : JSON.stringify(agentName);
130
+ stderr.push(`${PROGRAM}: --agent must be one of ${AGENT_NAMES.join(', ')}, received ${received}\n`);
131
+ return 2;
132
+ }
133
+ const outputFile = outputArgument ?? deriveOutputPath(promptFile);
134
+ let prompt;
135
+ try {
136
+ prompt = readFileSync(promptFile, 'utf8');
137
+ }
138
+ catch (error) {
139
+ stderr.push(`${PROGRAM}: ${describeError(error)}; pass the path of an existing file\n`);
140
+ return 2;
141
+ }
142
+ const result = await runConversion({ agentName, prompt, name: path.basename(promptFile) }, dependencies, stderr);
143
+ return typeof result === 'number' ? result : reportResult(result, outputFile, stdout, stderr);
144
+ }
145
+ async function runConversion({ agentName, prompt, name }, dependencies, stderr) {
146
+ const writeProgress = dependencies.writeProgress ??
147
+ ((line) => {
148
+ process.stderr.write(`${line}\n`);
149
+ });
150
+ const controller = new AbortController();
151
+ function interrupt() {
152
+ controller.abort(new Error('Interrupted.'));
153
+ }
154
+ process.once('SIGINT', interrupt);
155
+ let result;
156
+ try {
157
+ const { agent, convert } = await loadAgent(agentName, dependencies.convert);
158
+ const events = convert({ prompt, name, agent, signal: controller.signal });
159
+ for await (const event of events) {
160
+ const line = describeEvent(event);
161
+ if (line !== undefined)
162
+ writeProgress(`${PROGRAM}: ${line}`);
163
+ if (event.type === 'result')
164
+ result = event.result;
165
+ }
166
+ }
167
+ catch (error) {
168
+ if (controller.signal.aborted) {
169
+ stderr.push(`${PROGRAM}: interrupted; wrote nothing\n`);
170
+ return INTERRUPTED_EXIT_CODE;
171
+ }
172
+ stderr.push(`${PROGRAM}: ${describeError(error)}\n`);
173
+ return 2;
174
+ }
175
+ finally {
176
+ process.off('SIGINT', interrupt);
177
+ }
178
+ if (result === undefined) {
179
+ stderr.push(`${PROGRAM}: the conversion ended without a result\n`);
180
+ return 2;
181
+ }
182
+ return result;
183
+ }
@@ -1,11 +1,11 @@
1
1
  import process from 'node:process';
2
2
  import { run } from "./run.js";
3
- function main() {
4
- const output = run(process.argv.slice(2));
3
+ async function main() {
4
+ const output = await run(process.argv.slice(2));
5
5
  if (output.stdout !== '')
6
6
  process.stdout.write(output.stdout);
7
7
  if (output.stderr !== '')
8
8
  process.stderr.write(output.stderr);
9
9
  process.exit(output.exitCode);
10
10
  }
11
- main();
11
+ await main();
@@ -5,4 +5,4 @@ export interface CommandOutput {
5
5
  stdout: string;
6
6
  }
7
7
  /** Dispatches the bin's arguments to a command and returns its output without touching the process. */
8
- export declare function run(argv: readonly string[]): CommandOutput;
8
+ export declare function run(argv: readonly string[]): Promise<CommandOutput>;
@@ -1,14 +1,16 @@
1
1
  import { readFileSync } from 'node:fs';
2
2
  import path from 'node:path';
3
+ import { findPackageRoot, readPackageVersion } from "../package-files/find-package-root.js";
3
4
  import { runCheckCoverageCommand } from "./check-coverage-command.js";
4
5
  import { runConvertCommand } from "./convert-command.js";
5
- import { findPackageRoot, readPackageVersion } from "./find-package-root.js";
6
+ import { runConvertWithAgentCommand } from "./convert-with-agent-command.js";
6
7
  const USAGE = `Usage: agent-logic <command> [arguments]
7
8
 
8
9
  Commands:
9
- convert convert a draft of a prompt's logic into an agent-logic config
10
- check-coverage check a coverage map of a prompt against the prompt
11
- rules print the extraction rules by which a model drafts a prompt's logic
10
+ convert convert a draft of a prompt's logic into an agent-logic config
11
+ convert-with-agent convert a prompt into an agent-logic config on an ACP agent
12
+ check-coverage check a coverage map of a prompt against the prompt
13
+ rules print the extraction rules by which a model drafts a prompt's logic
12
14
 
13
15
  Run agent-logic <command> --help for a command's arguments and options.
14
16
 
@@ -16,7 +18,7 @@ Options:
16
18
  -h, --help print this help
17
19
  -V, --version print the version
18
20
  `;
19
- export function run(argv) {
21
+ export async function run(argv) {
20
22
  const [command, ...args] = argv;
21
23
  switch (command) {
22
24
  case undefined:
@@ -30,6 +32,8 @@ export function run(argv) {
30
32
  return runCheckCoverageCommand(args);
31
33
  case 'convert':
32
34
  return runConvertCommand(args);
35
+ case 'convert-with-agent':
36
+ return runConvertWithAgentCommand(args);
33
37
  case 'rules':
34
38
  return runRulesCommand(args);
35
39
  default:
@@ -0,0 +1,44 @@
1
+ import { type ConversionState, type StartConversionRequest } from '../conversion-protocol/conversion-schemas.js';
2
+ import type { Problem } from '../schema/validate-config.js';
3
+ /**
4
+ * A request's outcome: the conversion's state, or why there is none. `not-found` is a conversion that the server does
5
+ * not have, such as one that it dropped after its retention period; `failed` covers every other failure, the problems
6
+ * naming why.
7
+ */
8
+ export type ConversionOutcome = {
9
+ ok: true;
10
+ conversion: ConversionState;
11
+ } | {
12
+ ok: false;
13
+ reason: 'failed' | 'not-found';
14
+ problems: Problem[];
15
+ };
16
+ /** Starts, reads, cancels, and watches conversions on a server that `createConversionHandler` serves. */
17
+ export interface ConversionClient {
18
+ /** Cancels a conversion; a conversion that had already ended is reported with its ended state. */
19
+ cancel(id: string): Promise<ConversionOutcome>;
20
+ /** Returns the conversion's current state. */
21
+ read(id: string): Promise<ConversionOutcome>;
22
+ /** Starts a conversion and returns its `running` state. */
23
+ start(request: StartConversionRequest): Promise<ConversionOutcome>;
24
+ /**
25
+ * Reads the conversion every `intervalMs` (2 s by default) and yields each outcome, stopping after an ended state or
26
+ * a failed outcome. Returns without yielding again once the signal aborts.
27
+ */
28
+ watch(id: string, options?: {
29
+ signal?: AbortSignal;
30
+ intervalMs?: number;
31
+ }): AsyncGenerator<ConversionOutcome>;
32
+ }
33
+ export interface ConversionClientOptions {
34
+ /** The URL of the conversions resource, at which the server's handler serves its `basePath`. */
35
+ url: string;
36
+ fetch?: typeof globalThis.fetch;
37
+ }
38
+ /**
39
+ * Creates a client for the conversion routes, which validates every response body.
40
+ *
41
+ * @stage proposed
42
+ * @experimental
43
+ */
44
+ export declare function createConversionClient({ url, fetch, }: ConversionClientOptions): ConversionClient;
@@ -0,0 +1,86 @@
1
+ import { describeError } from '@williamthorsen/toolbelt.errors';
2
+ import { conversionStateSchema, problemsBodySchema, } from "../conversion-protocol/conversion-schemas.js";
3
+ const DEFAULT_WATCH_INTERVAL_MS = 2000;
4
+ export function createConversionClient({ url, fetch = globalThis.fetch.bind(globalThis), }) {
5
+ const collectionUrl = url.replace(/\/+$/, '');
6
+ async function send(target, init, successStatuses) {
7
+ let response;
8
+ try {
9
+ response = await fetch(target, init);
10
+ }
11
+ catch (error) {
12
+ return fail(`The conversion server could not be reached (${describeError(error)}).`);
13
+ }
14
+ let body;
15
+ try {
16
+ body = await response.json();
17
+ }
18
+ catch {
19
+ return fail(`The conversion server answered ${response.status} with a body that is not JSON.`);
20
+ }
21
+ const { status } = response;
22
+ if (successStatuses.includes(status)) {
23
+ return readBody(conversionStateSchema, body, status, (conversion) => ({ ok: true, conversion }));
24
+ }
25
+ const reason = status === 404 ? 'not-found' : 'failed';
26
+ return readBody(problemsBodySchema, body, status, ({ problems }) => ({ ok: false, reason, problems }));
27
+ }
28
+ async function readOnce(id, signal) {
29
+ if (isAborted(signal))
30
+ return undefined;
31
+ const outcome = await send(toConversionUrl(id), { method: 'GET', ...(signal !== undefined && { signal }) }, [200]);
32
+ return isAborted(signal) ? undefined : outcome;
33
+ }
34
+ function toConversionUrl(id) {
35
+ return `${collectionUrl}/${encodeURIComponent(id)}`;
36
+ }
37
+ return {
38
+ async cancel(id) {
39
+ return send(toConversionUrl(id), { method: 'DELETE' }, [200, 409]);
40
+ },
41
+ async read(id) {
42
+ return send(toConversionUrl(id), { method: 'GET' }, [200]);
43
+ },
44
+ async start(request) {
45
+ const init = { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(request) };
46
+ return send(collectionUrl, init, [201]);
47
+ },
48
+ async *watch(id, { signal, intervalMs = DEFAULT_WATCH_INTERVAL_MS } = {}) {
49
+ let outcome = await readOnce(id, signal);
50
+ while (outcome !== undefined) {
51
+ yield outcome;
52
+ if (!outcome.ok || outcome.conversion.status !== 'running')
53
+ return;
54
+ await waitFor(intervalMs, signal);
55
+ outcome = await readOnce(id, signal);
56
+ }
57
+ },
58
+ };
59
+ }
60
+ function fail(message) {
61
+ return { ok: false, reason: 'failed', problems: [{ path: '', message }] };
62
+ }
63
+ function isAborted(signal) {
64
+ return signal?.aborted === true;
65
+ }
66
+ function readBody(schema, body, status, toOutcome) {
67
+ const parsed = schema.safeParse(body);
68
+ return parsed.success
69
+ ? toOutcome(parsed.data)
70
+ : fail(`The conversion server answered ${status} with a body of an unexpected shape.`);
71
+ }
72
+ function waitFor(durationMs, signal) {
73
+ return new Promise((resolve) => {
74
+ if (isAborted(signal)) {
75
+ resolve();
76
+ return;
77
+ }
78
+ const timer = setTimeout(finish, durationMs);
79
+ signal?.addEventListener('abort', finish, { once: true });
80
+ function finish() {
81
+ clearTimeout(timer);
82
+ signal?.removeEventListener('abort', finish);
83
+ resolve();
84
+ }
85
+ });
86
+ }
@@ -0,0 +1,3 @@
1
+ /** `./client` entry: the browser client of the conversion routes that `./server`'s handler serves. */
2
+ export type { ConversionResult, ConversionState, EndedConversionState, StartConversionRequest, } from '../conversion-protocol/conversion-schemas.js';
3
+ export { type ConversionClient, type ConversionClientOptions, type ConversionOutcome, createConversionClient, } from './create-conversion-client.js';
@@ -0,0 +1 @@
1
+ export { createConversionClient, } from "./create-conversion-client.js";
@@ -0,0 +1,70 @@
1
+ import { z } from 'zod';
2
+ import type { Problem } from '../schema/validate-config.js';
3
+ /** The largest prompt that a start request accepts, in bytes of UTF-8. */
4
+ export declare const MAX_PROMPT_BYTES: number;
5
+ /** The longest name that a start request accepts, in characters. */
6
+ export declare const MAX_NAME_LENGTH = 100;
7
+ /** The body of every error response: the problems that refused the request. */
8
+ export declare const problemsBodySchema: z.ZodObject<{
9
+ problems: z.ZodArray<z.ZodType<Problem, unknown, z.core.$ZodTypeInternals<Problem, unknown>>>;
10
+ }, z.core.$strip>;
11
+ /**
12
+ * The body that starts a conversion: the prompt, verbatim, and its file name, from which the config's root id derives.
13
+ */
14
+ export declare const startConversionRequestSchema: z.ZodObject<{
15
+ prompt: z.ZodString;
16
+ name: z.ZodString;
17
+ }, z.core.$strip>;
18
+ /** A conversion's result: the config text, the problems of the last draft, or an out-of-scope verdict. */
19
+ export declare const conversionResultSchema: z.ZodUnion<readonly [z.ZodObject<{
20
+ ok: z.ZodLiteral<true>;
21
+ text: z.ZodString;
22
+ }, z.core.$strip>, z.ZodObject<{
23
+ ok: z.ZodLiteral<false>;
24
+ problems: z.ZodArray<z.ZodType<Problem, unknown, z.core.$ZodTypeInternals<Problem, unknown>>>;
25
+ }, z.core.$strip>, z.ZodObject<{
26
+ ok: z.ZodLiteral<false>;
27
+ outOfScope: z.ZodObject<{
28
+ reason: z.ZodString;
29
+ }, z.core.$strip>;
30
+ }, z.core.$strip>]>;
31
+ /** A conversion's state: `running` until its deadline, then one of the ended states, which never change. */
32
+ export declare const conversionStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
33
+ status: z.ZodLiteral<"running">;
34
+ id: z.ZodString;
35
+ name: z.ZodString;
36
+ startedAt: z.ZodISODateTime;
37
+ deadline: z.ZodISODateTime;
38
+ }, z.core.$strip>, z.ZodObject<{
39
+ status: z.ZodLiteral<"done">;
40
+ id: z.ZodString;
41
+ name: z.ZodString;
42
+ result: z.ZodUnion<readonly [z.ZodObject<{
43
+ ok: z.ZodLiteral<true>;
44
+ text: z.ZodString;
45
+ }, z.core.$strip>, z.ZodObject<{
46
+ ok: z.ZodLiteral<false>;
47
+ problems: z.ZodArray<z.ZodType<Problem, unknown, z.core.$ZodTypeInternals<Problem, unknown>>>;
48
+ }, z.core.$strip>, z.ZodObject<{
49
+ ok: z.ZodLiteral<false>;
50
+ outOfScope: z.ZodObject<{
51
+ reason: z.ZodString;
52
+ }, z.core.$strip>;
53
+ }, z.core.$strip>]>;
54
+ }, z.core.$strip>, z.ZodObject<{
55
+ status: z.ZodLiteral<"failed">;
56
+ id: z.ZodString;
57
+ name: z.ZodString;
58
+ reason: z.ZodString;
59
+ }, z.core.$strip>, z.ZodObject<{
60
+ status: z.ZodLiteral<"cancelled">;
61
+ id: z.ZodString;
62
+ name: z.ZodString;
63
+ }, z.core.$strip>], "status">;
64
+ export type ConversionResult = z.output<typeof conversionResultSchema>;
65
+ export type ConversionState = z.output<typeof conversionStateSchema>;
66
+ export type EndedConversionState = Exclude<ConversionState, {
67
+ status: 'running';
68
+ }>;
69
+ export type ProblemsBody = z.output<typeof problemsBodySchema>;
70
+ export type StartConversionRequest = z.output<typeof startConversionRequestSchema>;
@@ -0,0 +1,32 @@
1
+ import { z } from 'zod';
2
+ export const MAX_PROMPT_BYTES = 1024 * 1024;
3
+ export const MAX_NAME_LENGTH = 100;
4
+ const problemSchema = z.object({ path: z.string(), message: z.string() });
5
+ export const problemsBodySchema = z.object({ problems: z.array(problemSchema) });
6
+ export const startConversionRequestSchema = z.object({
7
+ prompt: z
8
+ .string()
9
+ .refine((value) => value !== '', 'Enter a prompt')
10
+ .refine((value) => new TextEncoder().encode(value).byteLength <= MAX_PROMPT_BYTES, `The prompt must not exceed ${MAX_PROMPT_BYTES} bytes`),
11
+ name: z
12
+ .string()
13
+ .max(MAX_NAME_LENGTH)
14
+ .refine((value) => value.trim() !== '', 'Enter a name'),
15
+ });
16
+ export const conversionResultSchema = z.union([
17
+ z.object({ ok: z.literal(true), text: z.string() }),
18
+ z.object({ ok: z.literal(false), problems: z.array(problemSchema) }),
19
+ z.object({ ok: z.literal(false), outOfScope: z.object({ reason: z.string() }) }),
20
+ ]);
21
+ export const conversionStateSchema = z.discriminatedUnion('status', [
22
+ z.object({
23
+ status: z.literal('running'),
24
+ id: z.string(),
25
+ name: z.string(),
26
+ startedAt: z.iso.datetime(),
27
+ deadline: z.iso.datetime(),
28
+ }),
29
+ z.object({ status: z.literal('done'), id: z.string(), name: z.string(), result: conversionResultSchema }),
30
+ z.object({ status: z.literal('failed'), id: z.string(), name: z.string(), reason: z.string() }),
31
+ z.object({ status: z.literal('cancelled'), id: z.string(), name: z.string() }),
32
+ ]);
@@ -0,0 +1,4 @@
1
+ /** The description of the `check_coverage` tool, for the model. */
2
+ export declare const CHECK_COVERAGE_DESCRIPTION = "Checks a coverage map of the prompt against the prompt.";
3
+ /** The description of the `submit_draft` tool, for the model. */
4
+ export declare const SUBMIT_DRAFT_DESCRIPTION = "Converts a draft of the prompt's logic into an agent-logic config, or reports its problems.";
@@ -0,0 +1,2 @@
1
+ export const CHECK_COVERAGE_DESCRIPTION = 'Checks a coverage map of the prompt against the prompt.';
2
+ export const SUBMIT_DRAFT_DESCRIPTION = "Converts a draft of the prompt's logic into an agent-logic config, or reports its problems.";
@@ -0,0 +1,39 @@
1
+ import { type ConvertResult } from '../convert/convert-prompt.js';
2
+ import type { CoverageMap } from '../coverage-map/coverage-map-schema.js';
3
+ /** The number of coverage checks that a session answers. */
4
+ export declare const MAX_COVERAGE_CHECKS = 3;
5
+ /** The number of drafts that a session accepts. */
6
+ export declare const MAX_SUBMISSIONS = 5;
7
+ /** A step of the conversion that the session reports as it happens. */
8
+ export type SessionEvent = {
9
+ readonly type: 'coverage-checked';
10
+ readonly check: number;
11
+ readonly unmapped: number;
12
+ readonly quoteProblems: number;
13
+ } | {
14
+ readonly type: 'draft-submitted';
15
+ readonly submission: number;
16
+ readonly outcome: 'config' | 'out-of-scope' | 'problems';
17
+ readonly problems: number;
18
+ };
19
+ /** The state of one conversion behind its tools: Each method returns the text that the tool answers the agent with. */
20
+ export interface ConversionSession {
21
+ /**
22
+ * Whether the conversion has ended: A config was accepted, the prompt was recorded as out of scope, or the last
23
+ * submission was taken. It stays true through later submissions.
24
+ */
25
+ readonly isFinished: boolean;
26
+ /** The outcome of the last accepted submission, or `undefined` before the first. */
27
+ readonly result: ConvertResult | undefined;
28
+ checkCoverage(map: CoverageMap): string;
29
+ submitDraft(draftText: string): string;
30
+ }
31
+ /**
32
+ * Creates the session for converting `prompt`, whose file is named `name`. It answers {@link MAX_COVERAGE_CHECKS}
33
+ * coverage checks and accepts {@link MAX_SUBMISSIONS} drafts, and refuses every call after those.
34
+ */
35
+ export declare function createConversionSession({ prompt, name, onEvent, }: {
36
+ prompt: string;
37
+ name: string;
38
+ onEvent: (event: SessionEvent) => void;
39
+ }): ConversionSession;
@@ -0,0 +1,67 @@
1
+ import { convertPrompt } from "../convert/convert-prompt.js";
2
+ import { checkCoverage } from "../coverage-map/check-coverage.js";
3
+ import { formatCoverageResult } from "../coverage-map/format-coverage-result.js";
4
+ export const MAX_COVERAGE_CHECKS = 3;
5
+ export const MAX_SUBMISSIONS = 5;
6
+ export function createConversionSession({ prompt, name, onEvent, }) {
7
+ let checks = 0;
8
+ let submissions = 0;
9
+ let result;
10
+ let isFinished = false;
11
+ return {
12
+ checkCoverage(map) {
13
+ if (checks >= MAX_COVERAGE_CHECKS) {
14
+ return 'The coverage checks are used up. Go on to the next check of the draft.';
15
+ }
16
+ checks += 1;
17
+ const coverage = checkCoverage(prompt, map);
18
+ onEvent({
19
+ type: 'coverage-checked',
20
+ check: checks,
21
+ unmapped: coverage.unmapped.length,
22
+ quoteProblems: coverage.quoteProblems.length,
23
+ });
24
+ const lines = formatCoverageResult(prompt, coverage);
25
+ if (lines.length === 0)
26
+ return 'Every block of the prompt is mapped. Go on to the next check of the draft.';
27
+ const left = MAX_COVERAGE_CHECKS - checks;
28
+ const next = left === 0
29
+ ? 'That was the last coverage check. Go on to the next check of the draft.'
30
+ : `Map every listed block, lengthen every listed quote, and check again. ${describeCount(left, 'check')} left.`;
31
+ return [...lines, next].join('\n');
32
+ },
33
+ submitDraft(draftText) {
34
+ if (submissions >= MAX_SUBMISSIONS)
35
+ return 'No more drafts are accepted. End your turn.';
36
+ submissions += 1;
37
+ result = convertPrompt(prompt, draftText, name);
38
+ isFinished ||= submissions >= MAX_SUBMISSIONS || result.ok || 'outOfScope' in result;
39
+ const problems = 'problems' in result ? result.problems : [];
40
+ onEvent({
41
+ type: 'draft-submitted',
42
+ submission: submissions,
43
+ outcome: result.ok ? 'config' : 'outOfScope' in result ? 'out-of-scope' : 'problems',
44
+ problems: problems.length,
45
+ });
46
+ if (result.ok)
47
+ return 'The config is accepted. End your turn.';
48
+ if ('outOfScope' in result)
49
+ return 'The prompt is recorded as out of scope. End your turn.';
50
+ const left = MAX_SUBMISSIONS - submissions;
51
+ const lines = problems.map(({ path, message }) => (path === '' ? message : `${path}: ${message}`));
52
+ const next = left === 0
53
+ ? 'That was the last submission: No more drafts are accepted. End your turn.'
54
+ : `Correct every listed entry and submit the draft again. ${describeCount(left, 'submission')} left.`;
55
+ return [...lines, next].join('\n');
56
+ },
57
+ get isFinished() {
58
+ return isFinished;
59
+ },
60
+ get result() {
61
+ return result;
62
+ },
63
+ };
64
+ }
65
+ function describeCount(count, noun) {
66
+ return `${count} ${noun}${count === 1 ? '' : 's'}`;
67
+ }
@@ -0,0 +1,4 @@
1
+ /**
2
+ * Returns the message that starts a conversion: a header line naming the prompt's file, a blank line, and the prompt.
3
+ */
4
+ export declare function formatConversionInput(prompt: string, name: string): string;
@@ -0,0 +1,3 @@
1
+ export function formatConversionInput(prompt, name) {
2
+ return `Prompt file: ${name}\n\n${prompt}`;
3
+ }
@@ -1,4 +1,3 @@
1
- import path from 'node:path';
2
1
  import { describeError } from '@williamthorsen/toolbelt.errors';
3
2
  import { formatPath, validateConfig } from "../schema/validate-config.js";
4
3
  import { draftSchema, outOfScopeSchema } from "./draft-schema.js";
@@ -38,8 +37,9 @@ export function convertPrompt(prompt, draftText, promptFileName) {
38
37
  return { ok: true, config: validated.config, text: `${JSON.stringify(validated.config, undefined, 2)}\n` };
39
38
  }
40
39
  export function deriveRootId(promptFileName) {
41
- const baseName = path.basename(promptFileName, path.extname(promptFileName));
42
- const words = baseName.toLowerCase().match(/[a-z0-9]+/g) ?? [];
40
+ const words = readBaseName(promptFileName)
41
+ .toLowerCase()
42
+ .match(/[a-z0-9]+/g) ?? [];
43
43
  const id = words.join('_');
44
44
  if (id === '')
45
45
  return 'agent';
@@ -58,3 +58,8 @@ function describeDraftIssue(issue, parentPath) {
58
58
  function maxPathLength(issues) {
59
59
  return Math.max(0, ...issues.map((issue) => issue.path.length));
60
60
  }
61
+ function readBaseName(filePath) {
62
+ const segment = filePath.replace(/\/+$/, '').split('/').at(-1) ?? '';
63
+ const dot = segment.lastIndexOf('.');
64
+ return dot > 0 ? segment.slice(0, dot) : segment;
65
+ }
@@ -0,0 +1,6 @@
1
+ import { type CoverageResult } from './check-coverage.js';
2
+ /**
3
+ * Formats a coverage check's findings as lines: each quote that does not occur exactly once, as `map[<index>]: …`,
4
+ * then each unmapped block, as `line <N>: <opening words>`. Returns no lines when every block is mapped.
5
+ */
6
+ export declare function formatCoverageResult(prompt: string, { unmapped, quoteProblems }: CoverageResult): string[];
@@ -0,0 +1,7 @@
1
+ import { describeBlock } from "./check-coverage.js";
2
+ export function formatCoverageResult(prompt, { unmapped, quoteProblems }) {
3
+ return [
4
+ ...quoteProblems.map(({ index, quote, occurrences }) => `map[${index}]: ${JSON.stringify(quote)} occurs ${occurrences} times`),
5
+ ...unmapped.map((block) => `line ${block.line}: ${describeBlock(prompt, block)}`),
6
+ ];
7
+ }