codeassembly-agent-logic 0.0.0 → 0.1.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 +77 -0
- package/CHANGELOG.md +28 -0
- package/LICENSE +7 -0
- package/README.md +86 -1
- package/bin/agent-logic.js +26 -0
- package/dist/esm/cli/check-coverage-command.d.ts +3 -0
- package/dist/esm/cli/check-coverage-command.js +99 -0
- package/dist/esm/cli/convert-command.d.ts +3 -0
- package/dist/esm/cli/convert-command.js +116 -0
- package/dist/esm/cli/find-package-root.d.ts +7 -0
- package/dist/esm/cli/find-package-root.js +31 -0
- package/dist/esm/cli/index.d.ts +1 -0
- package/dist/esm/cli/index.js +11 -0
- package/dist/esm/cli/run.d.ts +8 -0
- package/dist/esm/cli/run.js +62 -0
- package/dist/esm/contract/built-in-harnesses.d.ts +22 -0
- package/dist/esm/contract/built-in-harnesses.js +30 -0
- package/dist/esm/contract/conversion-job.d.ts +36 -0
- package/dist/esm/contract/conversion-job.js +17 -0
- package/dist/esm/contract/index.d.ts +4 -0
- package/dist/esm/contract/index.js +3 -0
- package/dist/esm/contract/viewer-contract.d.ts +804 -0
- package/dist/esm/contract/viewer-contract.js +38 -0
- package/dist/esm/convert/convert-prompt.d.ts +21 -0
- package/dist/esm/convert/convert-prompt.js +60 -0
- package/dist/esm/convert/draft-schema.d.ts +308 -0
- package/dist/esm/convert/draft-schema.js +57 -0
- package/dist/esm/convert/find-gate-spans.d.ts +6 -0
- package/dist/esm/convert/find-gate-spans.js +18 -0
- package/dist/esm/convert/format-state-name.d.ts +6 -0
- package/dist/esm/convert/format-state-name.js +6 -0
- package/dist/esm/convert/normalize-config.d.ts +11 -0
- package/dist/esm/convert/normalize-config.js +164 -0
- package/dist/esm/convert/resolve-quotes.d.ts +18 -0
- package/dist/esm/convert/resolve-quotes.js +169 -0
- package/dist/esm/convert/sanitize-name.d.ts +5 -0
- package/dist/esm/convert/sanitize-name.js +8 -0
- package/dist/esm/coverage-map/check-coverage.d.ts +20 -0
- package/dist/esm/coverage-map/check-coverage.js +21 -0
- package/dist/esm/coverage-map/coverage-map-schema.d.ts +11 -0
- package/dist/esm/coverage-map/coverage-map-schema.js +2 -0
- package/dist/esm/coverage-map/find-prompt-blocks.d.ts +15 -0
- package/dist/esm/coverage-map/find-prompt-blocks.js +140 -0
- package/dist/esm/examples/change-approval.d.ts +2 -0
- package/dist/esm/examples/change-approval.js +438 -0
- package/dist/esm/examples/examples.d.ts +9 -0
- package/dist/esm/examples/examples.js +8 -0
- package/dist/esm/examples/password-reset.d.ts +2 -0
- package/dist/esm/examples/password-reset.js +235 -0
- package/dist/esm/examples/refund-request.d.ts +2 -0
- package/dist/esm/examples/refund-request.js +233 -0
- package/dist/esm/index.d.ts +13 -0
- package/dist/esm/index.js +12 -0
- package/dist/esm/layout/build-elk-graph.d.ts +18 -0
- package/dist/esm/layout/build-elk-graph.js +96 -0
- package/dist/esm/layout/card-limits.d.ts +8 -0
- package/dist/esm/layout/card-limits.js +4 -0
- package/dist/esm/layout/describe-config.d.ts +118 -0
- package/dist/esm/layout/describe-config.js +199 -0
- package/dist/esm/layout/layout-config.d.ts +5 -0
- package/dist/esm/layout/layout-config.js +73 -0
- package/dist/esm/layout/layout-metrics.d.ts +6 -0
- package/dist/esm/layout/layout-metrics.js +6 -0
- package/dist/esm/layout/pack-preamble.d.ts +20 -0
- package/dist/esm/layout/pack-preamble.js +66 -0
- package/dist/esm/layout/to-flow-elements.d.ts +46 -0
- package/dist/esm/layout/to-flow-elements.js +83 -0
- package/dist/esm/react/canvas/AmbientSelectionContext.d.ts +7 -0
- package/dist/esm/react/canvas/AmbientSelectionContext.js +5 -0
- package/dist/esm/react/canvas/DetailLevelContext.d.ts +3 -0
- package/dist/esm/react/canvas/DetailLevelContext.js +2 -0
- package/dist/esm/react/canvas/FocusNavigation.d.ts +8 -0
- package/dist/esm/react/canvas/FocusNavigation.js +92 -0
- package/dist/esm/react/canvas/StateNode.d.ts +5 -0
- package/dist/esm/react/canvas/StateNode.js +91 -0
- package/dist/esm/react/canvas/StatechartCanvas.d.ts +16 -0
- package/dist/esm/react/canvas/StatechartCanvas.js +184 -0
- package/dist/esm/react/canvas/TransitionEdge.d.ts +5 -0
- package/dist/esm/react/canvas/TransitionEdge.js +22 -0
- package/dist/esm/react/canvas/canvas-key-entries.d.ts +14 -0
- package/dist/esm/react/canvas/canvas-key-entries.js +51 -0
- package/dist/esm/react/canvas/find-element-box.d.ts +8 -0
- package/dist/esm/react/canvas/find-element-box.js +25 -0
- package/dist/esm/react/canvas/find-view-centre.d.ts +15 -0
- package/dist/esm/react/canvas/find-view-centre.js +16 -0
- package/dist/esm/react/canvas/list-chart-marks.d.ts +5 -0
- package/dist/esm/react/canvas/list-chart-marks.js +37 -0
- package/dist/esm/react/canvas/marks.d.ts +19 -0
- package/dist/esm/react/canvas/marks.js +24 -0
- package/dist/esm/react/canvas/useNewLayout.d.ts +17 -0
- package/dist/esm/react/canvas/useNewLayout.js +44 -0
- package/dist/esm/react/canvas/zoom-levels.d.ts +28 -0
- package/dist/esm/react/canvas/zoom-levels.js +54 -0
- package/dist/esm/react/hooks/conversion-client.d.ts +77 -0
- package/dist/esm/react/hooks/conversion-client.js +132 -0
- package/dist/esm/react/hooks/describe-agent-selection.d.ts +6 -0
- package/dist/esm/react/hooks/describe-agent-selection.js +18 -0
- package/dist/esm/react/hooks/describe-load-outcome.d.ts +13 -0
- package/dist/esm/react/hooks/describe-load-outcome.js +30 -0
- package/dist/esm/react/hooks/download-config.d.ts +6 -0
- package/dist/esm/react/hooks/download-config.js +11 -0
- package/dist/esm/react/hooks/example-location.d.ts +7 -0
- package/dist/esm/react/hooks/example-location.js +14 -0
- package/dist/esm/react/hooks/label-source.d.ts +21 -0
- package/dist/esm/react/hooks/label-source.js +19 -0
- package/dist/esm/react/hooks/parse-config-text.d.ts +16 -0
- package/dist/esm/react/hooks/parse-config-text.js +38 -0
- package/dist/esm/react/hooks/useAgentBridge.d.ts +28 -0
- package/dist/esm/react/hooks/useAgentBridge.js +52 -0
- package/dist/esm/react/hooks/useAgentSync.d.ts +29 -0
- package/dist/esm/react/hooks/useAgentSync.js +75 -0
- package/dist/esm/react/hooks/useChartLayout.d.ts +25 -0
- package/dist/esm/react/hooks/useChartLayout.js +29 -0
- package/dist/esm/react/hooks/useConversion.d.ts +31 -0
- package/dist/esm/react/hooks/useConversion.js +177 -0
- package/dist/esm/react/hooks/useConvertDraft.d.ts +18 -0
- package/dist/esm/react/hooks/useConvertDraft.js +11 -0
- package/dist/esm/react/hooks/useDocumentTitle.d.ts +2 -0
- package/dist/esm/react/hooks/useDocumentTitle.js +7 -0
- package/dist/esm/react/hooks/useEscapeToClear.d.ts +2 -0
- package/dist/esm/react/hooks/useEscapeToClear.js +16 -0
- package/dist/esm/react/hooks/useHarnessList.d.ts +26 -0
- package/dist/esm/react/hooks/useHarnessList.js +24 -0
- package/dist/esm/react/hooks/usePromptDirectory.d.ts +27 -0
- package/dist/esm/react/hooks/usePromptDirectory.js +34 -0
- package/dist/esm/react/hooks/useSelection.d.ts +17 -0
- package/dist/esm/react/hooks/useSelection.js +21 -0
- package/dist/esm/react/hooks/useShowAmbient.d.ts +7 -0
- package/dist/esm/react/hooks/useShowAmbient.js +22 -0
- package/dist/esm/react/hooks/useUnknownExample.d.ts +7 -0
- package/dist/esm/react/hooks/useUnknownExample.js +26 -0
- package/dist/esm/react/index.d.ts +24 -0
- package/dist/esm/react/index.js +23 -0
- package/dist/esm/react/styles.css +482 -0
- package/dist/esm/schema/agent-logic-schema.d.ts +439 -0
- package/dist/esm/schema/agent-logic-schema.js +100 -0
- package/dist/esm/schema/config-traversal.d.ts +19 -0
- package/dist/esm/schema/config-traversal.js +32 -0
- package/dist/esm/schema/validate-config.d.ts +17 -0
- package/dist/esm/schema/validate-config.js +205 -0
- package/dist/esm/schema/write-json-schema.d.ts +4 -0
- package/dist/esm/schema/write-json-schema.js +12 -0
- package/dist/esm/server/conversion-job-implementation.d.ts +11 -0
- package/dist/esm/server/conversion-job-implementation.js +84 -0
- package/dist/esm/server/create-prompts-app.d.ts +26 -0
- package/dist/esm/server/create-prompts-app.js +41 -0
- package/dist/esm/server/create-viewer-server-plugins.d.ts +15 -0
- package/dist/esm/server/create-viewer-server-plugins.js +76 -0
- package/dist/esm/server/index.d.ts +7 -0
- package/dist/esm/server/index.js +6 -0
- package/dist/esm/server/prompt-directory-schemas.d.ts +30 -0
- package/dist/esm/server/prompt-directory-schemas.js +11 -0
- package/dist/esm/server/prompt-directory.d.ts +40 -0
- package/dist/esm/server/prompt-directory.js +86 -0
- package/dist/esm/server/viewer-contract-implementation.d.ts +12 -0
- package/dist/esm/server/viewer-contract-implementation.js +85 -0
- package/dist/esm/source/fence.d.ts +16 -0
- package/dist/esm/source/fence.js +15 -0
- package/dist/esm/source/find-comment-spans.d.ts +6 -0
- package/dist/esm/source/find-comment-spans.js +60 -0
- package/dist/esm/source/find-occurrences.d.ts +2 -0
- package/dist/esm/source/find-occurrences.js +7 -0
- package/dist/esm/source/prompt-segments.d.ts +21 -0
- package/dist/esm/source/prompt-segments.js +65 -0
- package/docs/conversion-agreement.md +37 -0
- package/docs/extraction-rules.md +123 -0
- package/package.json +106 -2
- package/schema/agent-logic.schema.json +475 -0
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
export const MAX_PROMPT_FILE_BYTES = 1024 * 1024;
|
|
4
|
+
const AGENT_LOGIC_SUFFIX = '.agent-logic.json';
|
|
5
|
+
const PROMPT_EXTENSIONS = ['.md', '.txt'];
|
|
6
|
+
export async function listPromptDirectory(directory) {
|
|
7
|
+
let names;
|
|
8
|
+
try {
|
|
9
|
+
const dirents = await readdir(directory, { withFileTypes: true });
|
|
10
|
+
names = dirents.filter((dirent) => dirent.isFile() && !dirent.name.startsWith('.')).map((dirent) => dirent.name);
|
|
11
|
+
}
|
|
12
|
+
catch (error) {
|
|
13
|
+
if (isMissing(error))
|
|
14
|
+
return { ok: false, reason: 'missing' };
|
|
15
|
+
throw error;
|
|
16
|
+
}
|
|
17
|
+
const entries = new Map();
|
|
18
|
+
for (const name of names) {
|
|
19
|
+
const match = classify(name);
|
|
20
|
+
if (match === undefined)
|
|
21
|
+
continue;
|
|
22
|
+
const entry = entries.get(match.base) ?? { name: match.base };
|
|
23
|
+
if (match.kind === 'agent-logic')
|
|
24
|
+
entry.agentLogicFile = name;
|
|
25
|
+
else if (entry.promptFile === undefined || rankPrompt(name) < rankPrompt(entry.promptFile))
|
|
26
|
+
entry.promptFile = name;
|
|
27
|
+
entries.set(match.base, entry);
|
|
28
|
+
}
|
|
29
|
+
return {
|
|
30
|
+
ok: true,
|
|
31
|
+
entries: entries
|
|
32
|
+
.values()
|
|
33
|
+
.toArray()
|
|
34
|
+
.toSorted((a, b) => compareNames(a.name, b.name)),
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
export async function readPromptDirectoryFile(directory, fileName) {
|
|
38
|
+
const listing = await listPromptDirectory(directory);
|
|
39
|
+
if (!listing.ok)
|
|
40
|
+
return { ok: false, reason: 'missing' };
|
|
41
|
+
const isListed = listing.entries.some((entry) => entry.promptFile === fileName || entry.agentLogicFile === fileName);
|
|
42
|
+
if (!isListed)
|
|
43
|
+
return { ok: false, reason: 'not-listed' };
|
|
44
|
+
const filePath = path.join(directory, fileName);
|
|
45
|
+
try {
|
|
46
|
+
if ((await stat(filePath)).size > MAX_PROMPT_FILE_BYTES)
|
|
47
|
+
return { ok: false, reason: 'too-large' };
|
|
48
|
+
return { ok: true, text: await readFile(filePath, 'utf8') };
|
|
49
|
+
}
|
|
50
|
+
catch (error) {
|
|
51
|
+
if (isMissing(error))
|
|
52
|
+
return { ok: false, reason: 'not-listed' };
|
|
53
|
+
throw error;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
export async function writePromptDirectoryFile(directory, fileName, text) {
|
|
57
|
+
const filePath = path.join(directory, fileName);
|
|
58
|
+
try {
|
|
59
|
+
await writeFile(filePath, text, { encoding: 'utf8', flag: 'wx' });
|
|
60
|
+
}
|
|
61
|
+
catch (error) {
|
|
62
|
+
if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'EEXIST') {
|
|
63
|
+
return { ok: false, reason: 'exists' };
|
|
64
|
+
}
|
|
65
|
+
throw error;
|
|
66
|
+
}
|
|
67
|
+
return { ok: true, path: filePath };
|
|
68
|
+
}
|
|
69
|
+
function classify(name) {
|
|
70
|
+
if (name.endsWith(AGENT_LOGIC_SUFFIX))
|
|
71
|
+
return toMatch(name.slice(0, -AGENT_LOGIC_SUFFIX.length), 'agent-logic');
|
|
72
|
+
const extension = PROMPT_EXTENSIONS.find((candidate) => name.endsWith(candidate));
|
|
73
|
+
return extension === undefined ? undefined : toMatch(name.slice(0, -extension.length), 'prompt');
|
|
74
|
+
}
|
|
75
|
+
function compareNames(a, b) {
|
|
76
|
+
return a.localeCompare(b, 'en', { numeric: true });
|
|
77
|
+
}
|
|
78
|
+
function isMissing(error) {
|
|
79
|
+
return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
|
|
80
|
+
}
|
|
81
|
+
function rankPrompt(name) {
|
|
82
|
+
return PROMPT_EXTENSIONS.findIndex((extension) => name.endsWith(extension));
|
|
83
|
+
}
|
|
84
|
+
function toMatch(base, kind) {
|
|
85
|
+
return base === '' ? undefined : { base, kind };
|
|
86
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { type ContractImplementation } from '@williamthorsen/telefactor/server';
|
|
2
|
+
import { type ViewerSettingsResult } from './create-prompts-app.js';
|
|
3
|
+
interface ViewerContractOptions {
|
|
4
|
+
/** Resolves the settings; called by each action that reaches the prompts directory, so that an edit applies at once. */
|
|
5
|
+
readSettings: () => Promise<ViewerSettingsResult>;
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* Implements the viewer's contract on the dev server: the prompts-directory actions read the directory that the
|
|
9
|
+
* settings name, and a refusal throws, which leaves the state unchanged and names the reason to the caller.
|
|
10
|
+
*/
|
|
11
|
+
export declare function createViewerContractImplementation({ readSettings }: ViewerContractOptions): ContractImplementation;
|
|
12
|
+
export {};
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { implementContract } from '@williamthorsen/telefactor/server';
|
|
2
|
+
import { viewerContract } from "../contract/viewer-contract.js";
|
|
3
|
+
import { sanitizeName } from "../convert/sanitize-name.js";
|
|
4
|
+
import { describeConfig } from "../layout/describe-config.js";
|
|
5
|
+
import { labelSource } from "../react/hooks/label-source.js";
|
|
6
|
+
import { parseConfigText } from "../react/hooks/parse-config-text.js";
|
|
7
|
+
import { validateConfig } from "../schema/validate-config.js";
|
|
8
|
+
import { resolvePromptsDirectory } from "./create-prompts-app.js";
|
|
9
|
+
import { listPromptDirectory, MAX_PROMPT_FILE_BYTES, readPromptDirectoryFile, writePromptDirectoryFile, } from "./prompt-directory.js";
|
|
10
|
+
export function createViewerContractImplementation({ readSettings }) {
|
|
11
|
+
return implementContract(viewerContract, {
|
|
12
|
+
initialState: {},
|
|
13
|
+
handlers: {
|
|
14
|
+
save_prompt: async (state, { name, text }) => {
|
|
15
|
+
if (name.trim() === '')
|
|
16
|
+
throw new Error('Enter a name.');
|
|
17
|
+
if (!/[a-z0-9]/i.test(name))
|
|
18
|
+
throw new Error('Enter a name that contains a letter from a to z or a digit.');
|
|
19
|
+
if (Buffer.byteLength(text, 'utf8') > MAX_PROMPT_FILE_BYTES) {
|
|
20
|
+
throw new Error('The prompt is larger than 1 MiB, which the prompts directory does not read.');
|
|
21
|
+
}
|
|
22
|
+
const directory = await readDirectory(readSettings);
|
|
23
|
+
const base = sanitizeName(name);
|
|
24
|
+
const listing = await listPromptDirectory(directory);
|
|
25
|
+
if (!listing.ok)
|
|
26
|
+
throw new Error(`The prompts directory ${directory} does not exist.`);
|
|
27
|
+
const taken = `The prompts directory already has files named ${base}. Choose another name.`;
|
|
28
|
+
if (listing.entries.some((entry) => entry.name === base))
|
|
29
|
+
throw new Error(taken);
|
|
30
|
+
const fileName = `${base}.md`;
|
|
31
|
+
const written = await writePromptDirectoryFile(directory, fileName, text);
|
|
32
|
+
if (!written.ok)
|
|
33
|
+
throw new Error(taken);
|
|
34
|
+
return { ...state, savedPrompt: { fileName, path: written.path } };
|
|
35
|
+
},
|
|
36
|
+
load_chart: async (state, { fileName }) => {
|
|
37
|
+
const directory = await readDirectory(readSettings);
|
|
38
|
+
const read = await readPromptDirectoryFile(directory, fileName);
|
|
39
|
+
if (!read.ok) {
|
|
40
|
+
throw new Error(read.reason === 'too-large'
|
|
41
|
+
? `${fileName} is larger than 1 MiB.`
|
|
42
|
+
: `The prompts directory does not list ${fileName}. Pass a file name from ${directory}, not a path.`);
|
|
43
|
+
}
|
|
44
|
+
const parsed = parseConfigText(read.text, 'file');
|
|
45
|
+
if (!parsed.ok)
|
|
46
|
+
throw new Error(formatProblems(fileName, parsed.problems));
|
|
47
|
+
const validated = validateConfig(parsed.value);
|
|
48
|
+
if (!validated.ok)
|
|
49
|
+
throw new Error(formatProblems(fileName, validated.problems));
|
|
50
|
+
return {
|
|
51
|
+
...state,
|
|
52
|
+
chart: { ...labelSource({ kind: 'file', fileName }), config: validated.config },
|
|
53
|
+
selectedPath: undefined,
|
|
54
|
+
};
|
|
55
|
+
},
|
|
56
|
+
show_chart: (state, chart) => ({ ...state, chart, selectedPath: undefined }),
|
|
57
|
+
select_element: (state, { path }) => {
|
|
58
|
+
if (path === undefined)
|
|
59
|
+
return { ...state, selectedPath: undefined };
|
|
60
|
+
if (state.chart === undefined)
|
|
61
|
+
throw new Error('No chart is loaded.');
|
|
62
|
+
if (!listElementPaths(state.chart.config).has(path)) {
|
|
63
|
+
throw new Error(`The loaded chart does not contain an element at ${path}.`);
|
|
64
|
+
}
|
|
65
|
+
return { ...state, selectedPath: path };
|
|
66
|
+
},
|
|
67
|
+
},
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
function formatProblems(fileName, problems) {
|
|
71
|
+
const lines = problems.map(({ path, message }) => (path === '' ? `- ${message}` : `- ${path}: ${message}`));
|
|
72
|
+
return [`${fileName} is not a valid agent-logic file:`, ...lines].join('\n');
|
|
73
|
+
}
|
|
74
|
+
function listElementPaths(config) {
|
|
75
|
+
const { states, transitions, ambient } = describeConfig(config);
|
|
76
|
+
return new Set([...states, ...transitions, ...ambient].map((element) => element.path));
|
|
77
|
+
}
|
|
78
|
+
async function readDirectory(readSettings) {
|
|
79
|
+
const resolved = await readSettings();
|
|
80
|
+
if (!resolved.ok) {
|
|
81
|
+
const lines = resolved.problems.map(({ path, message }) => (path === '' ? message : `${path}: ${message}`));
|
|
82
|
+
throw new Error(['The harness config file has problems:', ...lines].join('\n'));
|
|
83
|
+
}
|
|
84
|
+
return resolvePromptsDirectory(resolved);
|
|
85
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/** The character and length of the run that opens a fenced code block. */
|
|
2
|
+
export interface Fence {
|
|
3
|
+
character: '`' | '~';
|
|
4
|
+
length: number;
|
|
5
|
+
}
|
|
6
|
+
/**
|
|
7
|
+
* Returns whether the line closes the fence: a run of the fence's character at least as long as its opener, alone on
|
|
8
|
+
* the line. The line excludes its `\r`. Any indentation is accepted, so that a fence nested in a list item closes.
|
|
9
|
+
*/
|
|
10
|
+
export declare function isFenceCloser(line: string, fence: Fence): boolean;
|
|
11
|
+
/**
|
|
12
|
+
* Returns the fence that the line opens, if any. The line excludes its `\r`. Any indentation is accepted, so that a
|
|
13
|
+
* fence nested in a list item opens. A backtick run followed by another backtick on its line opens an inline code span
|
|
14
|
+
* instead, as in CommonMark.
|
|
15
|
+
*/
|
|
16
|
+
export declare function matchFenceOpener(line: string): Fence | undefined;
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
const OPENER = /^[ \t]*(`{3,}|~{3,})(.*)$/;
|
|
2
|
+
export function isFenceCloser(line, fence) {
|
|
3
|
+
const run = line.trim();
|
|
4
|
+
return run.length >= fence.length && run.replaceAll(fence.character, '') === '';
|
|
5
|
+
}
|
|
6
|
+
export function matchFenceOpener(line) {
|
|
7
|
+
const match = OPENER.exec(line);
|
|
8
|
+
const run = match?.[1];
|
|
9
|
+
if (run === undefined)
|
|
10
|
+
return undefined;
|
|
11
|
+
const character = run.startsWith('`') ? '`' : '~';
|
|
12
|
+
if (character === '`' && match?.[2]?.includes('`') === true)
|
|
13
|
+
return undefined;
|
|
14
|
+
return { character, length: run.length };
|
|
15
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { Span } from '../schema/agent-logic-schema.js';
|
|
2
|
+
/**
|
|
3
|
+
* Returns the span of each HTML comment in the prompt, delimiters included, in order. An unclosed `<!--` has none, and
|
|
4
|
+
* a `<!--` inside a Markdown code span or fenced code block is code rather than a comment.
|
|
5
|
+
*/
|
|
6
|
+
export declare function findCommentSpans(prompt: string): Span[];
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import { isFenceCloser, matchFenceOpener } from "./fence.js";
|
|
2
|
+
export function findCommentSpans(prompt) {
|
|
3
|
+
const spans = [];
|
|
4
|
+
const tokens = /^[ \t]*(`{3,}|~{3,})|`+|<!--/gm;
|
|
5
|
+
for (let match = tokens.exec(prompt); match !== null; match = tokens.exec(prompt)) {
|
|
6
|
+
const [token, run] = match;
|
|
7
|
+
const fence = run === undefined ? undefined : matchFenceOpener(readLine(prompt, match.index));
|
|
8
|
+
if (fence !== undefined) {
|
|
9
|
+
tokens.lastIndex = findFenceEnd(prompt, match.index, fence);
|
|
10
|
+
}
|
|
11
|
+
else if (token.trimStart().startsWith('`')) {
|
|
12
|
+
const length = run?.length ?? token.length;
|
|
13
|
+
const closing = findClosingRun(prompt, tokens.lastIndex, length);
|
|
14
|
+
if (closing !== undefined)
|
|
15
|
+
tokens.lastIndex = closing;
|
|
16
|
+
}
|
|
17
|
+
else if (token === '<!--') {
|
|
18
|
+
const close = prompt.indexOf('-->', tokens.lastIndex);
|
|
19
|
+
if (close === -1)
|
|
20
|
+
continue;
|
|
21
|
+
const end = close + '-->'.length;
|
|
22
|
+
spans.push({ start: match.index, end });
|
|
23
|
+
tokens.lastIndex = end;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
return spans;
|
|
27
|
+
}
|
|
28
|
+
function findClosingRun(prompt, from, length) {
|
|
29
|
+
const limit = findParagraphEnd(prompt, from);
|
|
30
|
+
const runs = /`+/g;
|
|
31
|
+
runs.lastIndex = from;
|
|
32
|
+
for (let run = runs.exec(prompt); run !== null && run.index < limit; run = runs.exec(prompt)) {
|
|
33
|
+
if (run[0].length === length)
|
|
34
|
+
return runs.lastIndex;
|
|
35
|
+
}
|
|
36
|
+
return undefined;
|
|
37
|
+
}
|
|
38
|
+
function findFenceEnd(prompt, opening, fence) {
|
|
39
|
+
let lineEnd = prompt.indexOf('\n', opening);
|
|
40
|
+
while (lineEnd !== -1) {
|
|
41
|
+
const lineStart = lineEnd + 1;
|
|
42
|
+
lineEnd = prompt.indexOf('\n', lineStart);
|
|
43
|
+
if (isFenceCloser(readLine(prompt, lineStart), fence))
|
|
44
|
+
return lineEnd === -1 ? prompt.length : lineEnd;
|
|
45
|
+
}
|
|
46
|
+
return prompt.length;
|
|
47
|
+
}
|
|
48
|
+
function findParagraphEnd(prompt, from) {
|
|
49
|
+
for (let lineEnd = prompt.indexOf('\n', from); lineEnd !== -1; lineEnd = prompt.indexOf('\n', lineEnd + 1)) {
|
|
50
|
+
const line = readLine(prompt, lineEnd + 1);
|
|
51
|
+
if (line.trim() === '' || matchFenceOpener(line) !== undefined)
|
|
52
|
+
return lineEnd + 1;
|
|
53
|
+
}
|
|
54
|
+
return prompt.length;
|
|
55
|
+
}
|
|
56
|
+
function readLine(prompt, from) {
|
|
57
|
+
const lineEnd = prompt.indexOf('\n', from);
|
|
58
|
+
const line = prompt.slice(from, lineEnd === -1 ? prompt.length : lineEnd);
|
|
59
|
+
return line.endsWith('\r') ? line.slice(0, -1) : line;
|
|
60
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { ConfigDescription, ElementDescription } from '../layout/describe-config.js';
|
|
2
|
+
import type { Span, UnconvertedSpan } from '../schema/agent-logic-schema.js';
|
|
3
|
+
export type Coverage = 'ambient' | 'comment' | 'used' | 'unused' | 'unconverted';
|
|
4
|
+
/** A run of prompt text that the same element spans cover. */
|
|
5
|
+
export interface PromptSegment {
|
|
6
|
+
start: number;
|
|
7
|
+
end: number;
|
|
8
|
+
text: string;
|
|
9
|
+
coverage: Coverage;
|
|
10
|
+
/** Paths of the elements whose spans cover the segment, narrowest span first. */
|
|
11
|
+
paths: string[];
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Cuts the prompt at every span, comment, and shown-span boundary into contiguous segments, each with the elements
|
|
15
|
+
* that cover it.
|
|
16
|
+
*/
|
|
17
|
+
export declare function buildPromptSegments(prompt: string, description: ConfigDescription, unconverted: UnconvertedSpan[], shown?: Span[]): PromptSegment[];
|
|
18
|
+
/** Lists the lowercase words of an element's identifiers and prose, without common function words. */
|
|
19
|
+
export declare function listElementWords(element: ElementDescription): Set<string>;
|
|
20
|
+
/** Splits text into its lowercase words, dropping common function words. */
|
|
21
|
+
export declare function splitWords(text: string): string[];
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { findCommentSpans } from "./find-comment-spans.js";
|
|
2
|
+
export function buildPromptSegments(prompt, description, unconverted, shown = []) {
|
|
3
|
+
const elements = [...description.states.filter(({ parentId }) => parentId !== undefined), ...description.transitions];
|
|
4
|
+
const elementSpans = [
|
|
5
|
+
...[...elements, ...description.ambient].map(({ path, source }) => ({
|
|
6
|
+
path,
|
|
7
|
+
start: source.start,
|
|
8
|
+
end: source.end,
|
|
9
|
+
})),
|
|
10
|
+
...elements.flatMap((element) => (element.kind === 'state' ? [...element.entry, ...element.exit] : element.actions)
|
|
11
|
+
.map(({ source }) => source)
|
|
12
|
+
.filter((source) => source !== undefined)
|
|
13
|
+
.map(({ start, end }) => ({ path: element.path, start, end }))),
|
|
14
|
+
];
|
|
15
|
+
const ambientSpans = description.ambient.map(({ source }) => source);
|
|
16
|
+
const commentSpans = findCommentSpans(prompt);
|
|
17
|
+
const cuts = new Set([0, prompt.length]);
|
|
18
|
+
for (const { start, end } of [...elementSpans, ...unconverted, ...commentSpans, ...shown]) {
|
|
19
|
+
cuts.add(start);
|
|
20
|
+
cuts.add(end);
|
|
21
|
+
}
|
|
22
|
+
const points = [...cuts].toSorted((a, b) => a - b);
|
|
23
|
+
const segments = [];
|
|
24
|
+
for (let index = 0; index < points.length - 1; index += 1) {
|
|
25
|
+
const start = points[index] ?? 0;
|
|
26
|
+
const end = points[index + 1] ?? prompt.length;
|
|
27
|
+
const covering = elementSpans.filter((span) => span.start <= start && span.end >= end);
|
|
28
|
+
const paths = covering.toSorted((a, b) => a.end - a.start - (b.end - b.start)).map(({ path }) => path);
|
|
29
|
+
segments.push({
|
|
30
|
+
start,
|
|
31
|
+
end,
|
|
32
|
+
text: prompt.slice(start, end),
|
|
33
|
+
coverage: findCoverage(start, end, { unconverted, ambient: ambientSpans, comments: commentSpans }, paths),
|
|
34
|
+
paths,
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
return segments;
|
|
38
|
+
}
|
|
39
|
+
export function listElementWords(element) {
|
|
40
|
+
if (element.kind === 'ambient')
|
|
41
|
+
return new Set();
|
|
42
|
+
const texts = element.kind === 'state'
|
|
43
|
+
? [element.id, ...[...element.entry, ...element.exit].map(({ text }) => text)]
|
|
44
|
+
: [element.event ?? '', element.guard ?? '', ...element.actions.map(({ text }) => text)];
|
|
45
|
+
return new Set(texts.flatMap(splitWords));
|
|
46
|
+
}
|
|
47
|
+
export function splitWords(text) {
|
|
48
|
+
return text
|
|
49
|
+
.toLowerCase()
|
|
50
|
+
.split(/[^a-z0-9]+/)
|
|
51
|
+
.filter((word) => word !== '' && !STOP_WORDS.has(word));
|
|
52
|
+
}
|
|
53
|
+
function findCoverage(start, end, { unconverted, ambient, comments }, paths) {
|
|
54
|
+
if (unconverted.some(covers))
|
|
55
|
+
return 'unconverted';
|
|
56
|
+
if (ambient.some(covers))
|
|
57
|
+
return 'ambient';
|
|
58
|
+
if (paths.length > 0)
|
|
59
|
+
return 'used';
|
|
60
|
+
return comments.some(covers) ? 'comment' : 'unused';
|
|
61
|
+
function covers(span) {
|
|
62
|
+
return span.start <= start && span.end >= end;
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
const STOP_WORDS = new Set('a an and are as at be by do does for from has have i if in into is it its no not of on once or our so that the their them then they this to us was we what when whether which with yes you your'.split(' '));
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Conversion agreement
|
|
2
|
+
|
|
3
|
+
How often repeated runs of the `convert-agent-prompt` skill, now in [williamthorsen/codeassembly-guidance](https://github.com/williamthorsen/codeassembly-guidance), produce the same config from the same prompt. The skill's model cannot guarantee identical extractions, so agreement is measured here rather than asserted.
|
|
4
|
+
|
|
5
|
+
## Method
|
|
6
|
+
|
|
7
|
+
- **Prompts:** the `meta.prompt` of each bundled example in [`src/examples/`](../src/examples/), written verbatim to `refund-request.md` and `password-reset.md`. The refund-request prompt was measured before its last sentence, a standing rule of the refund flow, was added.
|
|
8
|
+
- **Runs:** 5 per prompt, each by a fresh Claude Code subagent that reads `SKILL.md` by path and follows it. The subagents may not read the bundled examples.
|
|
9
|
+
- **Comparison:** the output files, which the `convert` script has already normalized, are grouped at four levels:
|
|
10
|
+
- **Exact:** identical bytes.
|
|
11
|
+
- **Without text:** identical once guard, action, and reason text is removed.
|
|
12
|
+
- **Without spans:** identical once that text and every span are removed, which leaves states, kinds, events, targets, and flags.
|
|
13
|
+
- **State ids:** the same state ids in the same order.
|
|
14
|
+
|
|
15
|
+
A cell such as `3+1+1` lists the sizes of the groups: three identical runs and two that each differ from the rest.
|
|
16
|
+
|
|
17
|
+
## Results
|
|
18
|
+
|
|
19
|
+
Measured on 2026-10-29 with Claude Opus 5.5 (`claude-opus-5-5`), with a version of the skill that predates its copy in [williamthorsen/codeassembly-guidance](https://github.com/williamthorsen/codeassembly-guidance).
|
|
20
|
+
|
|
21
|
+
| Prompt | Exact | Without text | Without spans | State ids |
|
|
22
|
+
| -------------- | --------- | ------------ | ------------- | --------- |
|
|
23
|
+
| Refund request | 3+1+1 | 4+1 | 4+1 | 4+1 |
|
|
24
|
+
| Password reset | 1+1+1+1+1 | 2+1+1+1 | 2+1+1+1 | 3+1+1 |
|
|
25
|
+
|
|
26
|
+
Every run converted on its first `convert` run. Every run left out the persona and tone lines, and every refund-request run listed the seasonal-promotion habit as unconverted. Every run contains a state for each step of the hand-written example. Two steps are expressed differently: the refund runs end in separate final states rather than a shared `closed` state, and the password runs put the attempt check on the code reply rather than in a counting state.
|
|
27
|
+
|
|
28
|
+
Where the runs still differ:
|
|
29
|
+
|
|
30
|
+
- **Unconverted reasons.** The reason's wording varies between otherwise identical refund runs.
|
|
31
|
+
- **Leading phrases in a compound state's quote.** One refund run dropped "At any point, if" from the quote of the compound state, which changes that state's id.
|
|
32
|
+
- **Resend rule.** Password runs disagree on whether "If the employee asks to resend the code" belongs on the code-asking state or on a compound state around the code steps, and which passage that compound state quotes.
|
|
33
|
+
- **Guard and action wording.** Paraphrases of the same condition or action differ between password runs.
|
|
34
|
+
|
|
35
|
+
## Earlier round
|
|
36
|
+
|
|
37
|
+
Before the skill showed the shape of a guard and stated what transitions and compound states quote, no two runs of either prompt were identical, and two of ten runs needed a second `convert` run to correct a guard written as a string.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Extraction rules
|
|
2
|
+
|
|
3
|
+
The rules by which a model converts an agent prompt into a draft, which `agent-logic convert` turns into an agent-logic config; `agent-logic rules` prints them. The `convert-agent-prompt` skill in [williamthorsen/codeassembly-guidance](https://github.com/williamthorsen/codeassembly-guidance) directs a harness agent to read them, and any other converter gives them to its model in full.
|
|
4
|
+
|
|
5
|
+
## What to extract
|
|
6
|
+
|
|
7
|
+
Extract the prompt's logic, then its [ambient instructions](#ambient-instructions), and record each flaw that you find while reading the prompt as a [finding](#findings):
|
|
8
|
+
|
|
9
|
+
- **States.** A step in which the agent does something or waits for the user. A state's `entry` lists the actions that the agent takes on entering it. An outcome at which the conversation ends is a `final` state; ending the conversation is what `final` means, so do not list it as an action.
|
|
10
|
+
- **Actions within a step.** Keep every instruction of a step as an action of its state, rather than summarize the step: a condition that changes what the agent does without changing where it goes next is an action that states its condition, such as "when the milestone has no open tickets, suggest closing it", and a prohibition that limits one step, such as "do not comment on the title's format", is an action of that step's state.
|
|
11
|
+
- **Transitions.** What moves the agent from one state to another. An event from the user is named `user.<what_happened>`, such as `user.gives_order_number`; another event takes another dotted lowercase prefix. A step that proceeds without waiting uses `always`. An outcome that the prompt says may happen, and that changes who acts next or where the step leads, is an event of that step's state with its own transition, beside the step's usual way out: "you may get no turn after it, because the platform reports the result" is `platform.reports_result`, named with the prefix of the actor that causes it. The prompt states the outcome, so its transition quotes that passage and is not inferred. When the prompt defines an event by a list of signs, such as "watch for these redirections", the transition quotes the passage that lists them and takes no guard.
|
|
12
|
+
- **Guards.** A condition that a transition requires, as `guard`: `{ "type": "nl", "params": { "text": "the code is correct" } }`, the same shape as an action. In a list of transitions for one event or for `always`, put the guarded transitions first and the unguarded fallback last: The list is evaluated in order, so its guards are alternatives: Use a list only for conditions of which at most one leads on. Conditions that can hold together, such as "after a split" and "when the remote ticket is stale", are actions of one shared state that each state their condition. A guarded transition whose alternative the prompt implies, such as staying while a step's own handling takes over or waiting for the user's reply, takes that alternative as an unguarded fallback: a transition without a target, or to the state that waits. A requirement that only orders two steps, such as "MUST have a failing test before fixing", is not a guard: The step proceeds with `always`. Neither is a condition that only restates its event, such as "a helper result has `ok: false`" on `helper.returns_failure`: Leave it out. A guarded transition of a state inside a flow needs no fallback for an event that the flow's global transition handles, because the global transition then applies. A condition on the user's reply goes on that reply's transitions, not in a separate checking state.
|
|
13
|
+
- **Global transitions.** A rule that applies at any point of a flow, such as "at any point, if the customer asks for a human". Group the states of that flow under a compound state, with `initial` naming its first child, and put the transition on the compound state. Create a compound state only for a global transition or an exit action that applies to more than one state. A step that the prompt exempts from the rule, such as one that continues after a failure that stops every other step, stays outside the compound state, and only that step: The step after it is inside, and the exempt step's transition targets it there. A rule that applies at any point is a global transition only of a flow that the prompt states; in a prompt that states no flow, it is a standing rule, together with any remedies that it orders, such as "try A, then B, and only then C".
|
|
14
|
+
- **Exit actions.** An action taken whenever the agent leaves a flow goes in the compound state's `exit`.
|
|
15
|
+
- **Actions without leaving.** A transition that runs actions and stays in the same state omits `target`.
|
|
16
|
+
- **Independent choices in one reply.** When the prompt asks the user for two or more independent choices in one reply, such as "confirm the shipping address, and choose standard or express delivery", each choice is an event of the state that waits for the reply. A choice that only runs actions, such as consenting to an update, is a transition without a target that quotes that choice and runs its actions; the choice that moves the agent takes the transitions to its targets. Never put two independent choices in one list of alternatives, and do not create a state for a choice that only runs actions. An option that does nothing, such as "leave it as it is", takes no transition. A choice in the user's reply is an event, not one of the conditions that can hold together, which are actions of a state.
|
|
17
|
+
|
|
18
|
+
Write each guard and action as a short imperative or condition in the prompt's words, with pronouns resolved: "explain that the order is outside the refund window", not "explain that it is". A message that the prompt gives the agent to present, such as a fenced template, is one action that presents it and states its content; do not recast its sentences as instructions to the agent.
|
|
19
|
+
|
|
20
|
+
### Ambient instructions
|
|
21
|
+
|
|
22
|
+
An ambient instruction holds in every state of a flow, or of the whole prompt, without moving the agent between states: persona, tone, style, and background knowledge, such as "You help customers with refund requests" or "Be warm and concise", and a standing rule that constrains every step, such as which sources the agent may use or what it may never change. List each under the `meta.ambient` of the narrowest container to which it applies, as `{ "quote": "…" }`: the compound state of the flow that it names, or the root. Do not create a compound state for an ambient instruction alone; attach it to the root when the prompt does not state its flow. A leaf state takes none: An instruction that limits one step is an action of that step's state. Quote each as an element is quoted, and list a passage under `meta.ambient` or `meta.unconverted`, never both.
|
|
23
|
+
|
|
24
|
+
### Gates
|
|
25
|
+
|
|
26
|
+
A `<HARD-GATE>` encloses an absolute instruction. Its tags mark emphasis, not a kind of element: Represent the gate where its content puts it, and add `"gate": true` to the element that quotes it.
|
|
27
|
+
|
|
28
|
+
- **A precondition on entering a step**, such as "Do NOT start this phase until the ticket has been approved", is the transition into that step. Its event or guard states the precondition, with an inferred event when the prompt states none; when the event already states it, such as `user.approves_ticket`, the transition takes no guard. The transition quotes the gate and has `meta.gate`.
|
|
29
|
+
- **A constraint on how a step is done**, such as "Follow the options and output format exactly", is an action of that step's state. A gated action quotes the gate in a `meta` of its own, which no other action has: `{ "type": "nl", "params": { "text": "follow the output format exactly" }, "meta": { "quote": "Follow the options and output format exactly", "gate": true } }`.
|
|
30
|
+
- **A standing rule**, such as a gate that holds throughout the prompt, is an ambient instruction: `{ "quote": "…", "gate": true }`.
|
|
31
|
+
|
|
32
|
+
A state is never a gate. When one gate states more than one of these, quote each part from its element. When two gates state the same precondition, the transition quotes the one at the step that it guards, and the other, which restates the precondition for the whole prompt, is a gated ambient instruction. The script reports a gate body that no quote overlaps, and a `gate` flag on a quote that overlaps no gate body. A gate inside an HTML comment is markup, not a gate.
|
|
33
|
+
|
|
34
|
+
### Quotes
|
|
35
|
+
|
|
36
|
+
Every state and transition contains `meta.quote`: a passage copied verbatim from the prompt, character for character, which must occur in the prompt exactly once.
|
|
37
|
+
|
|
38
|
+
- Quote the clause that states the element, without leading connectives such as "First,", "Then", "If", or "When": A state quotes its action from the verb ("Look up the order"), and a transition quotes its condition or event from the subject ("the order is older than 30 days"). An unguarded fallback quotes "Otherwise" when the prompt says it.
|
|
39
|
+
- A compound state quotes the passage that states its first global transition or, if it has none, its exit action.
|
|
40
|
+
- A gated action quotes the gate that it represents. No other action quotes the prompt.
|
|
41
|
+
- If the script reports that a quote occurs more than once, lengthen it with neighbouring words until it occurs once.
|
|
42
|
+
- An element that the prompt does not state, but that the logic needs, such as the user's reply that a question implies, has `meta.inferred: true` and quotes the passage from which you inferred it: the words of that passage that name this element, such as "or stop" for the state that stopping reaches, not the step before it. An event's quote names what happened and who did it.
|
|
43
|
+
|
|
44
|
+
### Passages you cannot convert
|
|
45
|
+
|
|
46
|
+
List under `meta.unconverted` each passage of logic that you cannot express as a state or transition, with a quote and a one-sentence reason, rather than guess at it. A habit with no stated trigger, such as "Mention our seasonal promotion whenever it feels natural", is one. A directive that includes a file whose content the prompt does not contain is a state whose action names the file when it stands for a step of the flow; otherwise, it is listed when it is prose and left out when it is an HTML comment. An ambient instruction is listed under `meta.ambient`, not here.
|
|
47
|
+
|
|
48
|
+
An HTML comment (`<!--` through the next `-->`) is markup, not logic: Never list one, or a passage inside one, under `meta.unconverted` or any `meta.ambient`. The script reports an entry whose quote lies inside a comment. A state may still quote an include directive written as a comment.
|
|
49
|
+
|
|
50
|
+
### Findings
|
|
51
|
+
|
|
52
|
+
A finding records a flaw that you see in the prompt's prose but that the chart's structure does not show. Never resolve a flaw silently: When the prompt leaves you to choose, chart the reading that you choose, mark the element that it needs `inferred`, and record a finding. List each finding under the `meta.findings` of the element that it concerns, or of the root when it concerns no single element, as `{ "kind": "…", "quotes": ["…"], "reason": "…" }`:
|
|
53
|
+
|
|
54
|
+
- **`contradiction`.** Two passages that cannot both hold, such as a page named as "the only source of … the verdict rule" and a verdict rule that the prompt states itself. Quote both passages.
|
|
55
|
+
- **`unused-input`.** An input that the prompt tells the agent to read, fetch, or receive, such as "the list of pre-approved changes", that no later step, condition, or rule uses. Put the finding on the state whose action reads the input.
|
|
56
|
+
- **`unhandled-case`.** A value or outcome of an input or a step that the prompt never branches on although it would change what the agent does, such as an empty change type or several pages that match a title. Put the finding on the state at which the case arises.
|
|
57
|
+
- **`inferred-resolution`.** A passage that admits two readings, of which you chart one. Put the finding on the inferred element that charts your reading, quote the unclear passage, and name both readings and why you chose yours in the reason.
|
|
58
|
+
|
|
59
|
+
Quote each passage verbatim, as an element is quoted; a finding may quote a passage that an element also quotes. The reason is one sentence that names the flaw and what the prompt leaves unstated. A finding is not a gap: Do not record a state without an exit, a condition without an alternative, or an unreachable state, which the viewer reports from the structure. The `convert` script reports a finding quote that lies inside an HTML comment, and an `inferred-resolution` finding that is not on an inferred element.
|
|
60
|
+
|
|
61
|
+
## Prompts outside the representation
|
|
62
|
+
|
|
63
|
+
Decide first whether the prompt is out of scope. It is when the logic that it states, once its ambient instructions and the passages that you would list under `meta.unconverted` are left out, does not contain a transition between two states: A chart of it would be one state or none. Write the draft below in its place, and do not write a logic draft:
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
{ "outOfScope": { "reason": "The prompt states standing rules for writing code, but no steps that the agent moves between." } }
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The reason is one sentence that names what the prompt contains and what it lacks. The `convert` script then writes no config, writes the draft to the problems file, and exits 3.
|
|
70
|
+
|
|
71
|
+
## Known limits
|
|
72
|
+
|
|
73
|
+
What a conversion under these rules does not achieve. [`corpus/scorecard.md`](../corpus/scorecard.md) names each instance in the corpus.
|
|
74
|
+
|
|
75
|
+
- **Run variance.** A conversion of a long prompt can drop or add an element that these rules already cover, such as a guarded alternative stated apart from its rule, a condition under which a step does nothing, or a wait for a reply that the prompt does not ask for. The skill's check of a draft against the prompt, and its coverage map, recover some dropped instructions but not all of them: Under the map, most converted prompts of the corpus still fail coverage, and one run per prompt cannot tell the map's effect from run variance. Another run may drop the same instruction again or a different one, so a review of the chart is what catches it.
|
|
76
|
+
- **Inferred events quoted by the request before them.** An inferred event, such as the user's pick or a subagent's report, often quotes the words of the agent's request that precedes it, such as "asks for the pick", although the prompt contains words that name the event. The skill's check of inferred quotes does not reliably catch it.
|
|
77
|
+
- **Ambient instructions quoted by their heading.** An ambient instruction quoted by the heading or opening clause of its paragraph, such as "Check the leader before rendering.", leaves the instructions after that clause off the chart, because an ambient instruction shows only its quote. Most coverage gaps in the corpus are of this kind. The coverage map's check does not catch it, because the check counts a paragraph as mapped once any quote overlaps it.
|
|
78
|
+
- **Execution order.** A step whose action can fail proceeds with `always`, and the failure is the event of a global transition; likewise, an outcome that the prompt says may happen is an event beside a step's `always`. Run as a machine, the `always` transition would be taken before the event arrives; the chart describes the prompt, and the viewer never runs it.
|
|
79
|
+
- **Independent choices that each move the agent.** When two independent choices of one reply each lead to a different step, the chart cannot hold both, because that takes parallel states, which the representation does not have. A conversion charts the choice that the prompt acts on first, and a review of the chart catches the choice that it drops.
|
|
80
|
+
- **Quotes from marked-up text.** A quote is verbatim, so a quote taken from a bold heading or a link either contains the markup or starts after it, and the state's id follows the quote.
|
|
81
|
+
|
|
82
|
+
## The draft
|
|
83
|
+
|
|
84
|
+
The package's `draftSchema` export, in [`src/convert/draft-schema.ts`](https://github.com/williamthorsen/codeassembly/blob/main/packages/agent-logic/src/convert/draft-schema.ts), defines the draft's shape. The draft is the config without ids or offsets: states are keyed by names that you choose, unique across the draft; `initial` names a child's key; a `target` is `#` followed by a state's key. The script writes each key as words to the state's name, which the viewer shows, and gives each state an id derived from its quote.
|
|
85
|
+
|
|
86
|
+
Key each state by a short snake_case verb phrase that names its step, such as `ask_for_the_email`. Write an acronym in capitals, such as `open_the_PR`, because the script capitalizes only the first word.
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
{
|
|
90
|
+
"initial": "ask_for_the_email",
|
|
91
|
+
"states": {
|
|
92
|
+
"ask_for_the_email": {
|
|
93
|
+
"entry": [{ "type": "nl", "params": { "text": "ask the employee for their work email" } }],
|
|
94
|
+
"on": {
|
|
95
|
+
"user.gives_email": [
|
|
96
|
+
{
|
|
97
|
+
"target": "#send_the_code",
|
|
98
|
+
"guard": { "type": "nl", "params": { "text": "the email is a work email" } },
|
|
99
|
+
"meta": { "quote": "their work email", "inferred": true }
|
|
100
|
+
},
|
|
101
|
+
{ "target": "#ask_for_the_email", "meta": { "quote": "Ask the employee for their work email", "inferred": true } }
|
|
102
|
+
]
|
|
103
|
+
},
|
|
104
|
+
"meta": {
|
|
105
|
+
"quote": "Ask the employee for their work email",
|
|
106
|
+
"findings": [
|
|
107
|
+
{
|
|
108
|
+
"kind": "unhandled-case",
|
|
109
|
+
"quotes": ["their work email"],
|
|
110
|
+
"reason": "The prompt does not say what to do when the employee has no work email."
|
|
111
|
+
}
|
|
112
|
+
]
|
|
113
|
+
}
|
|
114
|
+
},
|
|
115
|
+
"send_the_code": {
|
|
116
|
+
"type": "final",
|
|
117
|
+
"entry": [{ "type": "nl", "params": { "text": "send a verification code to the email" } }],
|
|
118
|
+
"meta": { "quote": "send a verification code to it" }
|
|
119
|
+
}
|
|
120
|
+
},
|
|
121
|
+
"meta": { "unconverted": [], "ambient": [{ "quote": "You reset passwords for employees." }] }
|
|
122
|
+
}
|
|
123
|
+
```
|