@farmslot/agent-runtime 0.48.1 → 0.48.2

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 (61) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/dist/task-init/required-skills.js +1 -1
  3. package/dist/task-init/required-skills.js.map +1 -1
  4. package/dist/task-init/task-document.d.ts.map +1 -1
  5. package/dist/task-init/task-document.js +1 -1
  6. package/dist/task-init/task-document.js.map +1 -1
  7. package/dist/task-init/write.d.ts.map +1 -1
  8. package/dist/task-init/write.js +12 -2
  9. package/dist/task-init/write.js.map +1 -1
  10. package/dist/tool-usage/adapters/claude.d.ts +3 -0
  11. package/dist/tool-usage/adapters/claude.d.ts.map +1 -0
  12. package/dist/tool-usage/adapters/claude.js +56 -0
  13. package/dist/tool-usage/adapters/claude.js.map +1 -0
  14. package/dist/tool-usage/adapters/codex.d.ts +3 -0
  15. package/dist/tool-usage/adapters/codex.d.ts.map +1 -0
  16. package/dist/tool-usage/adapters/codex.js +81 -0
  17. package/dist/tool-usage/adapters/codex.js.map +1 -0
  18. package/dist/tool-usage/adapters/cursor.d.ts +3 -0
  19. package/dist/tool-usage/adapters/cursor.d.ts.map +1 -0
  20. package/dist/tool-usage/adapters/cursor.js +47 -0
  21. package/dist/tool-usage/adapters/cursor.js.map +1 -0
  22. package/dist/tool-usage/adapters/grok.d.ts +3 -0
  23. package/dist/tool-usage/adapters/grok.d.ts.map +1 -0
  24. package/dist/tool-usage/adapters/grok.js +55 -0
  25. package/dist/tool-usage/adapters/grok.js.map +1 -0
  26. package/dist/tool-usage/adapters/jsonl.d.ts +9 -0
  27. package/dist/tool-usage/adapters/jsonl.d.ts.map +1 -0
  28. package/dist/tool-usage/adapters/jsonl.js +40 -0
  29. package/dist/tool-usage/adapters/jsonl.js.map +1 -0
  30. package/dist/tool-usage/adapters/native.d.ts +3 -0
  31. package/dist/tool-usage/adapters/native.d.ts.map +1 -0
  32. package/dist/tool-usage/adapters/native.js +31 -0
  33. package/dist/tool-usage/adapters/native.js.map +1 -0
  34. package/dist/tool-usage/adapters/pi.d.ts +3 -0
  35. package/dist/tool-usage/adapters/pi.d.ts.map +1 -0
  36. package/dist/tool-usage/adapters/pi.js +46 -0
  37. package/dist/tool-usage/adapters/pi.js.map +1 -0
  38. package/dist/tool-usage/count.d.ts +13 -0
  39. package/dist/tool-usage/count.d.ts.map +1 -0
  40. package/dist/tool-usage/count.js +160 -0
  41. package/dist/tool-usage/count.js.map +1 -0
  42. package/dist/tool-usage/index.d.ts +19 -0
  43. package/dist/tool-usage/index.d.ts.map +1 -0
  44. package/dist/tool-usage/index.js +32 -0
  45. package/dist/tool-usage/index.js.map +1 -0
  46. package/dist/tool-usage/ledger.d.ts +11 -0
  47. package/dist/tool-usage/ledger.d.ts.map +1 -0
  48. package/dist/tool-usage/ledger.js +29 -0
  49. package/dist/tool-usage/ledger.js.map +1 -0
  50. package/dist/tool-usage/stream.d.ts +32 -0
  51. package/dist/tool-usage/stream.d.ts.map +1 -0
  52. package/dist/tool-usage/stream.js +17 -0
  53. package/dist/tool-usage/stream.js.map +1 -0
  54. package/package.json +10 -4
  55. package/scripts/check-task-artifact-contract.mjs +36 -0
  56. package/scripts/checklist-order.cjs +165 -0
  57. package/scripts/checklist-target.cjs +20 -0
  58. package/scripts/mark-checklist-step.cjs +285 -23
  59. package/scripts/proof-artifacts.cjs +258 -0
  60. package/scripts/subtask-unit.cjs +22 -1
  61. package/scripts/worker-terminal-contract.cjs +4 -6
@@ -0,0 +1,258 @@
1
+ // Proof-artifact declarations: the evidence a checklist step claims.
2
+ //
3
+ // ADR-064 froze a step's deterministic command so a checked box could not stand
4
+ // in for an execution. This is the same shape for a proof step's output: a row
5
+ // declares the artifact it produces,
6
+ //
7
+ // - [ ] 9. Retain the failing baseline run [PROOF: artifacts/recipe-baseline-run]
8
+ //
9
+ // and the declaration is frozen into the task's terminal contract at init.
10
+ // `./mark N` refuses the tick while that path is absent, and completion refuses a
11
+ // ticked step whose evidence is missing or was written after the step's last
12
+ // mark. A step without a declaration behaves exactly as before: templates that
13
+ // have not adopted the marker are untouched.
14
+
15
+ const fs = require('node:fs');
16
+ const path = require('node:path');
17
+
18
+ const { enumerateChecklistCheckboxes, signalFileForChecklist } = require('./checklist-target.cjs');
19
+ const { readJson } = require('./mark-io.cjs');
20
+ const checklistOrder = require('./checklist-order.cjs');
21
+
22
+ /** How an absent declared path reads in a refusal. */
23
+ const EVIDENCE_ABSENCE = {
24
+ empty: 'empty',
25
+ outside: 'outside the task directory',
26
+ missing: 'missing',
27
+ };
28
+
29
+ const PROOF_REFERENCE = /\[PROOF:\s*([^\]]+?)\s*\]/;
30
+
31
+ /**
32
+ * A declared path is task-relative: the worker writes it inside the task dir and
33
+ * the gate reads it from there. An absolute or escaping path would point at
34
+ * something the run does not own, so it is a template error, not a refusal.
35
+ */
36
+ function normalizeProofPath(raw, checklist, stepNumber) {
37
+ const normalized = String(raw).trim().split(path.sep).join('/');
38
+ const invalid =
39
+ normalized.length === 0 ||
40
+ normalized.startsWith('/') ||
41
+ /^[A-Za-z]:/.test(normalized) ||
42
+ normalized.split('/').includes('..');
43
+ if (invalid)
44
+ throw new Error(
45
+ `Invalid proof declaration in ${checklist} step ${stepNumber}: ` +
46
+ `'${raw}' must be a path inside the task directory`,
47
+ );
48
+ return normalized;
49
+ }
50
+
51
+ function proofDeclarations(markdown, checklist) {
52
+ return enumerateChecklistCheckboxes(markdown).flatMap((item) => {
53
+ const match = item.rawLabel.match(PROOF_REFERENCE);
54
+ if (!match && item.rawLabel.includes('[PROOF'))
55
+ throw new Error(`Invalid proof declaration in ${checklist} step ${item.stepNumber}`);
56
+ return match
57
+ ? [
58
+ {
59
+ checklist,
60
+ stepNumber: item.stepNumber,
61
+ path: normalizeProofPath(match[1], checklist, item.stepNumber),
62
+ },
63
+ ]
64
+ : [];
65
+ });
66
+ }
67
+
68
+ /** Freeze the checklist's declarations into the contract, as ADR-064 does for commands. */
69
+ function freezeProofArtifacts(contract, markdown, checklist) {
70
+ const steps = proofDeclarations(markdown, checklist);
71
+ return steps.length ? { ...contract, proofArtifacts: steps } : contract;
72
+ }
73
+
74
+ /**
75
+ * The frozen declarations plus any the live checklist carries. A row added after
76
+ * init still gates: the contract is the record, never the waiver.
77
+ */
78
+ function declaredProofArtifacts(taskDir, checklist, contract) {
79
+ const frozen = (contract?.proofArtifacts ?? []).filter((step) => step.checklist === checklist);
80
+ const file = path.join(taskDir, checklist);
81
+ const live = fs.existsSync(file)
82
+ ? proofDeclarations(fs.readFileSync(file, 'utf8'), checklist)
83
+ : [];
84
+ const steps = [...frozen];
85
+ for (const step of live) {
86
+ if (!steps.some((candidate) => candidate.stepNumber === step.stepNumber)) steps.push(step);
87
+ }
88
+ return steps;
89
+ }
90
+
91
+ /**
92
+ * Evidence is present when the path exists and holds something: an empty
93
+ * directory is the shape of a retained run that never ran.
94
+ */
95
+ function proofEvidence(taskDir, relPath) {
96
+ const target = path.join(taskDir, relPath);
97
+ let stat;
98
+ let resolved;
99
+ try {
100
+ // A declared path is evidence only where the task says it is: a symlink can
101
+ // point the gate at a populated directory the run never produced, so the
102
+ // resolved path has to stay inside the task directory.
103
+ resolved = fs.realpathSync(target);
104
+ const root = fs.realpathSync(taskDir);
105
+ if (resolved !== root && !resolved.startsWith(root + path.sep))
106
+ return { present: false, reason: 'outside', mtimeMs: null };
107
+ stat = fs.statSync(resolved);
108
+ } catch (error) {
109
+ if (error.code === 'ENOENT') return { present: false, reason: 'missing', mtimeMs: null };
110
+ throw error;
111
+ }
112
+ if (stat.isDirectory()) {
113
+ // Read the resolved directory and never follow a child link: an inside
114
+ // directory of symlinks must not stand in for files the run never wrote.
115
+ const entries = fs.readdirSync(resolved, { withFileTypes: true });
116
+ const own = entries.filter((entry) => !entry.isSymbolicLink());
117
+ if (own.length === 0) return { present: false, reason: 'empty', mtimeMs: null };
118
+ const newest = own.reduce((latest, entry) => {
119
+ try {
120
+ return Math.max(latest, fs.lstatSync(path.join(resolved, entry.name)).mtimeMs);
121
+ } catch {
122
+ return latest;
123
+ }
124
+ }, stat.mtimeMs);
125
+ return { present: true, reason: null, mtimeMs: newest };
126
+ }
127
+ if (stat.size === 0) return { present: false, reason: 'empty', mtimeMs: null };
128
+ return { present: true, reason: null, mtimeMs: stat.mtimeMs };
129
+ }
130
+
131
+ /**
132
+ * When each step was last marked, from the signal the mark engine writes. The
133
+ * caller passes the signal it selected (`mark --signal`), because a run using
134
+ * that escape hatch keeps its claims there and not in the derived name.
135
+ */
136
+ function stepMarkTimes(taskDir, checklist, signalFile) {
137
+ const signal = readJson(path.join(taskDir, signalFile ?? signalFileForChecklist(checklist)));
138
+ const events = Array.isArray(signal?.checklistTiming?.events)
139
+ ? signal.checklistTiming.events
140
+ : [];
141
+ const times = new Map();
142
+ for (const event of events) {
143
+ if (!event || typeof event.stepNumber !== 'number') continue;
144
+ const stamp = Date.parse(event.remarkedAt ?? event.checkedAt ?? '');
145
+ if (!Number.isNaN(stamp)) times.set(event.stepNumber, stamp);
146
+ }
147
+ return times;
148
+ }
149
+
150
+ function checkedSteps(taskDir, checklist) {
151
+ const file = path.join(taskDir, checklist);
152
+ if (!fs.existsSync(file)) return new Set();
153
+ return new Set(
154
+ enumerateChecklistCheckboxes(fs.readFileSync(file, 'utf8'))
155
+ .filter((item) => item.checked)
156
+ .map((item) => item.stepNumber),
157
+ );
158
+ }
159
+
160
+ /**
161
+ * Why `./mark N` cannot tick this step yet, or null when it can. Only a declared
162
+ * step can refuse, and only for absent evidence — the tick is the claim, so the
163
+ * artifact has to exist before it.
164
+ */
165
+ function pendingProofArtifact(taskDir, checklist, stepNumber, contract) {
166
+ const step = declaredProofArtifacts(taskDir, checklist, contract).find(
167
+ (candidate) => candidate.stepNumber === stepNumber,
168
+ );
169
+ if (!step) return null;
170
+ const evidence = proofEvidence(taskDir, step.path);
171
+ if (evidence.present) return null;
172
+ return (
173
+ `step ${stepNumber} declares its proof at ${step.path}, which is ` +
174
+ `${EVIDENCE_ABSENCE[evidence.reason] ?? 'missing'}. ` +
175
+ 'Produce the evidence, then mark the step.'
176
+ );
177
+ }
178
+
179
+ /**
180
+ * The one definition of "the evidence is newer than the claim". A mark and a
181
+ * completion must not decide this differently, so both callers come here. Null
182
+ * when the step declares nothing, has no evidence, or was never marked.
183
+ */
184
+ function claimOlderThanEvidence(taskDir, checklist, stepNumber, contract, signalFile) {
185
+ const step = declaredProofArtifacts(taskDir, checklist, contract).find(
186
+ (candidate) => candidate.stepNumber === stepNumber,
187
+ );
188
+ if (!step) return null;
189
+ const evidence = proofEvidence(taskDir, step.path);
190
+ const markedAt = stepMarkTimes(taskDir, checklist, signalFile).get(stepNumber);
191
+ if (!evidence.present || evidence.mtimeMs == null || markedAt == null) return null;
192
+ return evidence.mtimeMs > markedAt ? { step, evidence, markedAt } : null;
193
+ }
194
+
195
+ /**
196
+ * Completion issues for declared steps: a ticked step needs its evidence, and
197
+ * evidence written after the step's last mark means the claim came first. An
198
+ * unticked step is simply unfinished work and not an issue here.
199
+ */
200
+ function proofArtifactIssues(taskDir, checklist, contract, signalFile) {
201
+ const ticked = checkedSteps(taskDir, checklist);
202
+ // A skipped step claims the work did not apply, so it owes no evidence — but
203
+ // only where the frozen template granted the skip. A `skipped: true` ledger
204
+ // row on a step the contract never declared optional waives nothing, and the
205
+ // order check refuses it separately.
206
+ const skipped = checklistOrder.authorizedSkips(taskDir, checklist, contract, signalFile);
207
+ const issues = [];
208
+ for (const step of declaredProofArtifacts(taskDir, checklist, contract)) {
209
+ if (!ticked.has(step.stepNumber) || skipped.has(step.stepNumber)) continue;
210
+ const evidence = proofEvidence(taskDir, step.path);
211
+ if (!evidence.present) {
212
+ issues.push(
213
+ `${checklist} step ${step.stepNumber} is checked but its declared proof ${step.path} is ` +
214
+ `${EVIDENCE_ABSENCE[evidence.reason] ?? 'missing'}`,
215
+ );
216
+ continue;
217
+ }
218
+ const late = claimOlderThanEvidence(taskDir, checklist, step.stepNumber, contract, signalFile);
219
+ if (late) {
220
+ issues.push(
221
+ `${checklist} step ${step.stepNumber}: its declared proof ${step.path} was written ` +
222
+ `${new Date(late.evidence.mtimeMs).toISOString()}, after the step was marked ` +
223
+ `${new Date(late.markedAt).toISOString()}; mark the step again now the evidence is current`,
224
+ );
225
+ }
226
+ }
227
+ return issues;
228
+ }
229
+
230
+ /**
231
+ * Steps marked after a later-numbered step, recorded for the run record only.
232
+ * Order alone proves nothing about the work, so it never refuses anything.
233
+ */
234
+ function outOfOrderMarks(events) {
235
+ const ordered = (Array.isArray(events) ? events : [])
236
+ .filter((event) => event && typeof event.stepNumber === 'number' && event.checkedAt)
237
+ .map((event) => ({ stepNumber: event.stepNumber, checkedAt: event.checkedAt }));
238
+ const anomalies = [];
239
+ let highest = 0;
240
+ for (const event of ordered) {
241
+ if (event.stepNumber < highest)
242
+ anomalies.push({ stepNumber: event.stepNumber, checkedAt: event.checkedAt, after: highest });
243
+ highest = Math.max(highest, event.stepNumber);
244
+ }
245
+ return anomalies;
246
+ }
247
+
248
+ module.exports = {
249
+ PROOF_REFERENCE,
250
+ declarations: proofDeclarations,
251
+ freeze: freezeProofArtifacts,
252
+ declared: declaredProofArtifacts,
253
+ evidence: proofEvidence,
254
+ pending: pendingProofArtifact,
255
+ issues: proofArtifactIssues,
256
+ claimOlderThanEvidence,
257
+ outOfOrderMarks,
258
+ };
@@ -5,6 +5,7 @@ const { isDeepStrictEqual } = require('node:util');
5
5
  const { ACCEPTANCE_REGISTRATION_INPUT } = require('@farmslot/protocol/scripts/acceptance.mjs');
6
6
  const { literalReplacement } = require('@farmslot/protocol/scripts/literal-replacement.mjs');
7
7
  const { pendingInitialAcceptanceDerivation } = require('./acceptance-ledger.cjs');
8
+ const checklistOrder = require('./checklist-order.cjs');
8
9
 
9
10
  const {
10
11
  checklistNumberingMismatches,
@@ -15,6 +16,7 @@ const {
15
16
  SUBTASK_ID_PATTERN,
16
17
  SUBTASK_INDEX_FILE,
17
18
  SUBTASKS_DIR,
19
+ readFrozenTerminalContract,
18
20
  subtaskPaths,
19
21
  targetForChecklistBasename,
20
22
  } = require('./checklist-target.cjs');
@@ -41,6 +43,7 @@ const {
41
43
  // never changes the run's active task file.
42
44
 
43
45
  const HANDOFF_INPUT = path.join('inputs', 'handoff.json');
46
+
44
47
  const SUBTASK_INDEX_REL = `${SUBTASKS_DIR}/${SUBTASK_INDEX_FILE}`;
45
48
 
46
49
  /** A refused command: the message is worker-facing, the code is the exit code. */
@@ -462,7 +465,6 @@ function subStart(taskDir, rest) {
462
465
  if (!parentRow) {
463
466
  throw new SubtaskRefusal(`checklist step ${stepNumber} not found in ${target.checklist}`);
464
467
  }
465
-
466
468
  const index = readSubtaskIndex(taskDir) ?? { schemaVersion: 1, units: [] };
467
469
  // One child per step for the LIFE of the task directory: a settled child has
468
470
  // already ticked the box, so a second registration would reopen finished work.
@@ -481,6 +483,25 @@ function subStart(taskDir, rest) {
481
483
  );
482
484
  }
483
485
 
486
+ // Registering a child on a step claims the work has reached it, and the child's
487
+ // own completion ticks that box. Order is therefore enforced here rather than at
488
+ // the child's tick (ADR-064 Amendment 7).
489
+ if (!parentRow.checked) {
490
+ const earlier = checklistOrder.firstUnmarkedEarlierStep(parent.items, stepNumber);
491
+ if (earlier) {
492
+ const when = checklistOrder
493
+ .declared(taskDir, target.checklist, readFrozenTerminalContract(taskDir, target.checklist))
494
+ .get(earlier.stepNumber);
495
+ throw new SubtaskRefusal(
496
+ `step ${stepNumber} cannot take a child while step ${earlier.stepNumber} ` +
497
+ `(${earlier.label}) is unchecked. ` +
498
+ (when
499
+ ? `That step is optional (${when}); skip it with ./mark ${earlier.stepNumber} --skip "<reason>"`
500
+ : 'Do that step first.'),
501
+ );
502
+ }
503
+ }
504
+
484
505
  const source = readSubtaskSource(flags.from, taskDir);
485
506
  const body = stripMarkdownFrontmatter(source.text);
486
507
  const label = `Subtask ${id} source ${source.ref ?? '(inline)'}`;
@@ -4,8 +4,8 @@ const { createHash, randomUUID } = require('node:crypto');
4
4
  const { spawnSync } = require('node:child_process');
5
5
  const {
6
6
  enumerateChecklistCheckboxes,
7
- terminalContractInputForChecklist,
8
7
  resolveChecklistTarget,
8
+ readFrozenTerminalContract,
9
9
  } = require('./checklist-target.cjs');
10
10
  const { atomicWrite } = require('./mark-io.cjs');
11
11
 
@@ -518,11 +518,9 @@ function readOptionalJson(file) {
518
518
  }
519
519
 
520
520
  function deterministicContract(taskDir, checklist) {
521
- return (
522
- readOptionalJson(path.join(taskDir, terminalContractInputForChecklist(checklist))) ??
523
- readOptionalJson(path.join(taskDir, 'inputs', 'worker-terminal-contract.json')) ??
524
- {}
525
- );
521
+ // One reader for the frozen contract, shared with the mark engine and the
522
+ // order checks so their idea of "this checklist's contract" cannot drift.
523
+ return readFrozenTerminalContract(taskDir, checklist) ?? {};
526
524
  }
527
525
 
528
526
  function recordedDeterministicSteps(taskDir, checklist) {