overlord-cli 0.2610241050.0 → 0.2610261104.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 (43) hide show
  1. package/README.md +2 -2
  2. package/dist/connectors/AGENTS.md +22 -5
  3. package/dist/connectors/VERSION +1 -1
  4. package/dist/connectors/adapters/antigravity/conformance-manifest.yaml +1 -1
  5. package/dist/connectors/adapters/antigravity/plugin.json +1 -1
  6. package/dist/connectors/adapters/antigravity/skills/record-work.md +2 -3
  7. package/dist/connectors/adapters/claude/.claude-plugin/plugin.json +1 -1
  8. package/dist/connectors/adapters/claude/codec/claude.codec.yaml +5 -0
  9. package/dist/connectors/adapters/claude/commands/record-work.md +2 -3
  10. package/dist/connectors/adapters/claude/conformance-manifest.yaml +1 -1
  11. package/dist/connectors/adapters/claude/fixtures/normalize-post-tool-use-notebook.json +1 -0
  12. package/dist/connectors/adapters/claude/fixtures/normalize-post-tool-use-shell.json +1 -0
  13. package/dist/connectors/adapters/claude/fixtures/normalize-post-tool-use-write.json +1 -0
  14. package/dist/connectors/adapters/codex/.codex-plugin/plugin.json +2 -2
  15. package/dist/connectors/adapters/codex/CAPABILITIES.md +2 -2
  16. package/dist/connectors/adapters/codex/codec/codex.codec.yaml +10 -1
  17. package/dist/connectors/adapters/codex/conformance-manifest.yaml +2 -2
  18. package/dist/connectors/adapters/codex/fixtures/normalize-post-tool-use-failed.json +42 -0
  19. package/dist/connectors/adapters/codex/fixtures/normalize-post-tool-use-rename.json +42 -0
  20. package/dist/connectors/adapters/codex/fixtures/normalize-post-tool-use.json +6 -3
  21. package/dist/connectors/adapters/codex/harness-capabilities.yaml +2 -0
  22. package/dist/connectors/adapters/cursor/.cursor-plugin/plugin.json +1 -1
  23. package/dist/connectors/adapters/cursor/codec/cursor.codec.yaml +5 -0
  24. package/dist/connectors/adapters/cursor/commands/record-work.md +2 -3
  25. package/dist/connectors/adapters/cursor/conformance-manifest.yaml +1 -1
  26. package/dist/connectors/adapters/cursor/fixtures/normalize-post-tool-use-write.json +1 -0
  27. package/dist/connectors/adapters/cursor/rules/overlord-local.mdc +1 -1
  28. package/dist/connectors/adapters/opencode/conformance-manifest.yaml +1 -1
  29. package/dist/connectors/adapters/pi/conformance-manifest.yaml +1 -1
  30. package/dist/connectors/core/README.md +1 -1
  31. package/dist/connectors/core/overlord-mission/SKILL.md +113 -70
  32. package/dist/connectors/core/overlord-mission/reference/cli.md +53 -63
  33. package/dist/connectors/core/overlord-mission/reference/context.md +1 -1
  34. package/dist/connectors/core/overlord-mission/reference/mcp.md +3 -2
  35. package/dist/connectors/core/overlord-mission/reference/record-work.md +23 -43
  36. package/dist/connectors/core/overlord-mission/reference/shell-escaping.md +7 -5
  37. package/dist/connectors/core/scripts/capture-change-hook.sh +6 -4
  38. package/dist/connectors/core/scripts/overlord-mcp.mjs +81 -164
  39. package/dist/connectors/docs/05-connectors-and-agent-plugins.md +3 -3
  40. package/dist/connectors/docs/testing.md +5 -0
  41. package/dist/index.js +665 -236
  42. package/dist/index.js.map +4 -4
  43. package/package.json +1 -1
@@ -10,20 +10,22 @@ EOF
10
10
 
11
11
  ## Inline JSON size limits
12
12
 
13
- Oversized inline `--*-json` arguments are **rejected** by the CLI (limit ~8 KB per flag). This includes `--change-rationales-json`, `--payload-json`, `--artifacts-json`, and `--objectives-json`. Pass large JSON via the paired `--*-file -` flag and a single-quoted heredoc instead:
13
+ Oversized inline `--*-json` arguments are **rejected** by the CLI (limit ~8 KB per flag). This includes `--payload-json`, `--artifacts-json`, and `--objectives-json`. Pass large JSON via the paired `--*-file -` flag and a single-quoted heredoc instead:
14
14
 
15
15
  ```bash
16
16
  ovld protocol deliver --session-key <sessionKey> --mission-id $MISSION_ID \
17
17
  --summary "Short narrative summary stays inline." \
18
- --change-rationales-file - <<'EOF'
19
- [{"label":"Example","filePath":"lib/api.ts","summary":"...","why":"...","impact":"..."}]
18
+ --payload-file - <<'EOF'
19
+ {"deliveryReport":{"schemaVersion":1,"agentReport":{"humanActions":[],"tradeoffsMade":[],"knownRisks":[],"deferredWork":[],"assumptions":[]}}}
20
20
  EOF
21
21
  ```
22
22
 
23
23
  If `heartbeat` succeeds but `deliver` or `update` fails, the session is likely fine — retry with the corresponding `--*-file -` flag rather than inline `--*-json`.
24
24
 
25
- Use `--payload-file -` when the full delivery object (summary, artifacts, and change rationales together) exceeds the inline limit.
25
+ Declared paths that contain commas, or long path lists, go through `--paths-file -` as a JSON string array rather than `--paths`.
26
+
27
+ Use `--payload-file -` when the full delivery object (summary, artifacts, delivery report, and declared paths together) exceeds the inline limit.
26
28
 
27
29
  If the summary contains special characters, use `--summary-file -` and pipe via a single-quoted heredoc (`<<'EOF'`) to prevent shell expansion.
28
30
 
29
- If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data under `.overlord/tmp` and remove it after delivery.
31
+ If you use `--payload-file`, `--artifacts-file`, or `--paths-file` with a real path, treat that file as ephemeral scratch data under `.overlord/tmp` and remove it after delivery.
@@ -1,9 +1,11 @@
1
1
  #!/bin/bash
2
2
  # Overlord post-tool capture callback. `capture-change --agent __OVERLORD_ADAPTER_KEY__`
3
- # applies the connector-owned codec; only a normalized `file.edited` path becomes
4
- # objective-bound, non-exclusive `declared_edit`/`direct` evidence. Normalized reads,
5
- # searches, and fetches are ignored. Mutation-capable callbacks without a normalized edit
6
- # path, plus shell, generic, unknown, and unmapped callbacks, record unavailable health.
3
+ # applies the connector-owned codec; only a normalized `file.edited` path whose outcome is
4
+ # `ok` (decoded from the payload, or guaranteed by a success-only hook) becomes
5
+ # objective-bound, non-exclusive `declared_edit` evidence. Every scoped callback, including a
6
+ # harmless read, records callback observation. Failed/cancelled edits record outcome_partial,
7
+ # unknown outcomes outcome_unavailable, shell calls shell_activity_unverified, and other
8
+ # no-path callbacks direct_path_unavailable; none of them appends a path.
7
9
 
8
10
  OBJECTIVE_REF="${OVERLORD_OBJECTIVE_ID:-}"
9
11
 
@@ -450,6 +450,34 @@ const tools = [
450
450
  openWorldHint: false
451
451
  }
452
452
  },
453
+ {
454
+ name: 'overlord_changes',
455
+ title: 'List objective file changes',
456
+ description:
457
+ 'Use this to read the synchronized changed-file evidence of one objective across every session, resource, and device. Returns ObjectiveFileChangesDto { scope: "server_objective", items, total, limit, truncated, capture }: compact rows (resourceKey, filePath, source declared_edit | agent_declared | null for unknown, observedAt, hookHealth) ordered by resource then path and capped at 200, total as the pre-cap count, and persisted capture diagnostics with warnings. It never includes unsynchronized local evidence, needs no attached session, and does not mutate anything.',
458
+ inputSchema: {
459
+ type: 'object',
460
+ properties: {
461
+ missionId: {
462
+ type: 'string',
463
+ description:
464
+ 'Mission UUID or workspace display id. Optional when objectiveId is a display id such as coo:756.k7xm, which already names its mission.'
465
+ },
466
+ objectiveId: {
467
+ type: 'string',
468
+ description:
469
+ 'Required objective UUID or display id such as coo:756.k7xm. An objective that does not belong to missionId is rejected.'
470
+ }
471
+ },
472
+ required: [],
473
+ additionalProperties: false
474
+ },
475
+ annotations: {
476
+ readOnlyHint: true,
477
+ destructiveHint: false,
478
+ openWorldHint: false
479
+ }
480
+ },
453
481
  {
454
482
  name: 'overlord_launch_objective',
455
483
  title: 'Launch objective execution',
@@ -945,51 +973,14 @@ const tools = [
945
973
  type: 'string',
946
974
  description: 'Optional event type. Defaults to update.'
947
975
  },
948
- changeRationales: {
976
+ declaredPaths: {
949
977
  type: 'array',
950
- description: 'Optional reviewer-facing annotations for objective-ledger file evidence.',
978
+ description:
979
+ 'Optional paths written by shell commands, generators, or scripts that native capture could not name. Recorded as agent_declared evidence; never an exhaustive list.',
951
980
  items: {
952
- type: 'object',
953
- properties: {
954
- filePath: {
955
- type: 'string',
956
- description: 'Repository-relative path of the changed file.'
957
- },
958
- label: {
959
- type: 'string',
960
- description: 'Short reviewer title for the change.'
961
- },
962
- summary: {
963
- type: 'string',
964
- description: 'What changed in this file.'
965
- },
966
- why: {
967
- type: 'string',
968
- description: 'Why the change was made.'
969
- },
970
- impact: {
971
- type: 'string',
972
- description: 'Behavioral impact of the change.'
973
- },
974
- hunks: {
975
- type: 'array',
976
- description:
977
- 'Optional diff-hunk headers only; file contents and diffs are prohibited.',
978
- items: {
979
- type: 'object',
980
- properties: {
981
- header: {
982
- type: 'string',
983
- description: 'Unified-diff hunk header.'
984
- }
985
- },
986
- required: ['header'],
987
- additionalProperties: false
988
- }
989
- }
990
- },
991
- required: ['filePath', 'label', 'summary', 'why', 'impact'],
992
- additionalProperties: false
981
+ type: 'string',
982
+ description:
983
+ 'Canonical repository-relative path. Deleted and renamed paths (both endpoints) are valid.'
993
984
  }
994
985
  }
995
986
  },
@@ -1006,7 +997,7 @@ const tools = [
1006
997
  name: 'overlord_deliver_session',
1007
998
  title: 'Deliver mission session',
1008
999
  description:
1009
- 'Use this only when the user-requested mission work is complete. It delivers the attached session with an explicit summary, optional file-change rationales, and optional authoritative human-action/tradeoff evidence.',
1000
+ 'Use this only when the user-requested mission work is complete. It delivers the attached session with an explicit summary, optional declared shell/script output paths, and optional authoritative human-action/tradeoff evidence.',
1010
1001
  inputSchema: {
1011
1002
  type: 'object',
1012
1003
  properties: {
@@ -1057,51 +1048,14 @@ const tools = [
1057
1048
  additionalProperties: false
1058
1049
  }
1059
1050
  },
1060
- changeRationales: {
1051
+ declaredPaths: {
1061
1052
  type: 'array',
1062
- description: 'Optional reviewer-facing annotations for objective-ledger file evidence.',
1053
+ description:
1054
+ 'Optional paths written by shell commands, generators, or scripts that native capture could not name. Recorded as agent_declared evidence; never an exhaustive list and never required.',
1063
1055
  items: {
1064
- type: 'object',
1065
- properties: {
1066
- filePath: {
1067
- type: 'string',
1068
- description: 'Repository-relative path of the changed file.'
1069
- },
1070
- label: {
1071
- type: 'string',
1072
- description: 'Short reviewer title for the change.'
1073
- },
1074
- summary: {
1075
- type: 'string',
1076
- description: 'What changed in this file.'
1077
- },
1078
- why: {
1079
- type: 'string',
1080
- description: 'Why the change was made.'
1081
- },
1082
- impact: {
1083
- type: 'string',
1084
- description: 'Behavioral impact of the change.'
1085
- },
1086
- hunks: {
1087
- type: 'array',
1088
- description:
1089
- 'Optional diff-hunk headers only; file contents and diffs are prohibited.',
1090
- items: {
1091
- type: 'object',
1092
- properties: {
1093
- header: {
1094
- type: 'string',
1095
- description: 'Unified-diff hunk header.'
1096
- }
1097
- },
1098
- required: ['header'],
1099
- additionalProperties: false
1100
- }
1101
- }
1102
- },
1103
- required: ['filePath', 'label', 'summary', 'why', 'impact'],
1104
- additionalProperties: false
1056
+ type: 'string',
1057
+ description:
1058
+ 'Canonical repository-relative path. Deleted and renamed paths (both endpoints) are valid.'
1105
1059
  }
1106
1060
  },
1107
1061
  humanActions: {
@@ -1189,10 +1143,33 @@ const tools = [
1189
1143
  },
1190
1144
  deferredWork: {
1191
1145
  type: 'array',
1146
+ description:
1147
+ 'Each deferredWork item is one recommended objective outside this mission. Be very concise. title names the work in an imperative phrase. change states only the specific change that is needed. location says where to find it in the code: the file, function, component, or command. doneWhen states the observable result in one sentence. Do not add instructions on how to do the work, background, or rationale. The operator turns the item into an objective or a mission as written, so it must read as a task, not as a note. Omit queued future objectives, leftover current-objective work, and human follow-up (those belong in humanActions). Vague: { title: "Fix flaky test", change: "The sync worker has a flaky test.", location: "backend", doneWhen: "It passes." }. Good: { title: "Advance the fake clock before the second retry", change: "The test asserts the retry fired but never advances the fake clock between attempts, so it passes or fails on real time.", location: "backend/sync-worker.test.ts › retries after a 503", doneWhen: "The test passes 20 consecutive runs with the fake clock driving both attempts." }.',
1192
1148
  items: {
1193
- type: 'string',
1194
- description:
1195
- 'Recommended new objective outside this mission (for example an out-of-scope bug). Name the component or file and why it was left. Omit queued future objectives, leftover current-objective work, and human follow-up (those belong in humanActions).'
1149
+ type: 'object',
1150
+ properties: {
1151
+ title: {
1152
+ type: 'string',
1153
+ description: 'Required. The work as an imperative phrase, at most 80 characters.'
1154
+ },
1155
+ change: {
1156
+ type: 'string',
1157
+ description:
1158
+ 'Required. The specific change that is needed, one or two sentences, at most 400 characters.'
1159
+ },
1160
+ location: {
1161
+ type: 'string',
1162
+ description:
1163
+ 'Required. Where to find it: file, function, component, or command, at most 200 characters.'
1164
+ },
1165
+ doneWhen: {
1166
+ type: 'string',
1167
+ description:
1168
+ 'Required. The observable result in one sentence, at most 200 characters.'
1169
+ }
1170
+ },
1171
+ required: ['title', 'change', 'location', 'doneWhen'],
1172
+ additionalProperties: false
1196
1173
  }
1197
1174
  },
1198
1175
  assumptions: {
@@ -1314,7 +1291,7 @@ const tools = [
1314
1291
  name: 'overlord_record_work',
1315
1292
  title: 'Record completed work as a mission',
1316
1293
  description:
1317
- 'Use this to log work already finished in this chat as a completed Overlord mission — one call, no attach/deliver cycle. It creates a mission and a single completed objective, records the file changes and their rationales, lands the mission in the review column, and runs the delivery through the standard Gemini summarizer so it reads like any other delivered mission. Provide an objective (what was asked/done) and a reviewer-facing summary; optional changeRationales may annotate meaningful file changes. Only use this when the work is genuinely complete; use overlord_create_mission for work still to be done.',
1294
+ 'Use this to log work already finished in this chat as a completed Overlord mission — one call, no attach/deliver cycle. It creates a mission and a single completed objective, records the explicitly declared changed paths, lands the mission in the review column, and runs the delivery through the standard Gemini summarizer so it reads like any other delivered mission. Provide an objective (what was asked/done) and a reviewer-facing summary; optional declaredPaths lists the files the work changed. Only use this when the work is genuinely complete; use overlord_create_mission for work still to be done.',
1318
1295
  inputSchema: {
1319
1296
  type: 'object',
1320
1297
  properties: {
@@ -1335,70 +1312,14 @@ const tools = [
1335
1312
  type: 'string',
1336
1313
  description: 'Optional mission title; defaults to a title derived from the objective.'
1337
1314
  },
1338
- changeRationales: {
1315
+ declaredPaths: {
1339
1316
  type: 'array',
1340
- description: 'One optional reviewer annotation per meaningful file change.',
1341
- items: {
1342
- type: 'object',
1343
- properties: {
1344
- filePath: {
1345
- type: 'string',
1346
- description: 'Repository-relative path of the changed file.'
1347
- },
1348
- label: {
1349
- type: 'string',
1350
- description: 'Short reviewer title for the change.'
1351
- },
1352
- summary: {
1353
- type: 'string',
1354
- description: 'What changed in this file.'
1355
- },
1356
- why: {
1357
- type: 'string',
1358
- description: 'Why the change was made.'
1359
- },
1360
- impact: {
1361
- type: 'string',
1362
- description: 'Behavioral impact of the change.'
1363
- },
1364
- hunks: {
1365
- type: 'array',
1366
- description:
1367
- 'Optional diff-hunk headers only; file contents and diffs are prohibited.',
1368
- items: {
1369
- type: 'object',
1370
- properties: {
1371
- header: {
1372
- type: 'string',
1373
- description: 'Unified-diff hunk header.'
1374
- }
1375
- },
1376
- required: ['header'],
1377
- additionalProperties: false
1378
- }
1379
- }
1380
- },
1381
- required: ['filePath', 'label', 'summary', 'why', 'impact'],
1382
- additionalProperties: false
1383
- }
1384
- },
1385
- changedFiles: {
1386
- type: 'array',
1387
- description: 'Optional explicit file observations for this sessionless record.',
1317
+ description:
1318
+ 'Optional repository-relative paths this work changed, recorded as agent_declared evidence for the completed objective.',
1388
1319
  items: {
1389
- type: 'object',
1390
- properties: {
1391
- filePath: {
1392
- type: 'string',
1393
- description: 'Repository-relative path.'
1394
- },
1395
- vcsStatus: {
1396
- type: 'string',
1397
- description: 'Optional VCS status such as M, A, or D.'
1398
- }
1399
- },
1400
- required: ['filePath'],
1401
- additionalProperties: false
1320
+ type: 'string',
1321
+ description:
1322
+ 'Canonical repository-relative path. Deleted and renamed paths (both endpoints) are valid.'
1402
1323
  }
1403
1324
  },
1404
1325
  artifacts: {
@@ -1598,6 +1519,9 @@ async function callOverlordTool(name, args) {
1598
1519
  if (name === 'overlord_list_deliveries') {
1599
1520
  return runProtocol('list-deliveries', missionScopeFlags(args));
1600
1521
  }
1522
+ if (name === 'overlord_changes') {
1523
+ return runProtocol('objective-changes', missionScopeFlags(args));
1524
+ }
1601
1525
  if (name === 'overlord_launch_objective') {
1602
1526
  return runProtocol('launch-objective', {
1603
1527
  'objective-id': requiredString(args, 'objectiveId'),
@@ -1818,9 +1742,7 @@ async function callOverlordTool(name, args) {
1818
1742
  ...(optionalString(args, 'eventType')
1819
1743
  ? { 'event-type': requiredString(args, 'eventType') }
1820
1744
  : {}),
1821
- ...(Array.isArray(args.changeRationales)
1822
- ? { 'change-rationales-json': args.changeRationales }
1823
- : {})
1745
+ ...(Array.isArray(args.declaredPaths) ? { 'declared-paths-json': args.declaredPaths } : {})
1824
1746
  });
1825
1747
  }
1826
1748
  if (name === 'overlord_deliver_session') {
@@ -1829,9 +1751,7 @@ async function callOverlordTool(name, args) {
1829
1751
  'session-key': requiredString(args, 'sessionKey'),
1830
1752
  summary: requiredString(args, 'summary'),
1831
1753
  ...(Array.isArray(args.artifacts) ? { 'artifacts-json': args.artifacts } : {}),
1832
- ...(Array.isArray(args.changeRationales)
1833
- ? { 'change-rationales-json': args.changeRationales }
1834
- : {}),
1754
+ ...(Array.isArray(args.declaredPaths) ? { 'declared-paths-json': args.declaredPaths } : {}),
1835
1755
  ...(Array.isArray(args.humanActions) ||
1836
1756
  Array.isArray(args.tradeoffsMade) ||
1837
1757
  Array.isArray(args.knownRisks) ||
@@ -1899,10 +1819,7 @@ async function callOverlordTool(name, args) {
1899
1819
  objective: requiredString(args, 'objective'),
1900
1820
  summary: requiredString(args, 'summary'),
1901
1821
  ...(optionalString(args, 'title') ? { title: requiredString(args, 'title') } : {}),
1902
- ...(Array.isArray(args.changeRationales)
1903
- ? { changeRationales: args.changeRationales }
1904
- : {}),
1905
- ...(Array.isArray(args.changedFiles) ? { changedFiles: args.changedFiles } : {}),
1822
+ ...(Array.isArray(args.declaredPaths) ? { declaredPaths: args.declaredPaths } : {}),
1906
1823
  ...(Array.isArray(args.artifacts) ? { artifacts: args.artifacts } : {})
1907
1824
  }
1908
1825
  });
@@ -1920,7 +1837,7 @@ process.stdin.on('data', async chunk => {
1920
1837
  result: {
1921
1838
  protocolVersion: PROTOCOL_VERSION,
1922
1839
  capabilities: { tools: { listChanged: false } },
1923
- serverInfo: { name: 'overlord-__OVERLORD_ADAPTER_KEY__', version: '0.3.53' }
1840
+ serverInfo: { name: 'overlord-__OVERLORD_ADAPTER_KEY__', version: '0.3.57' }
1924
1841
  }
1925
1842
  });
1926
1843
  continue;
@@ -35,12 +35,12 @@ Required content:
35
35
  - Attach first.
36
36
  - Treat mission prompt/context as authoritative.
37
37
  - Post meaningful progress updates.
38
- - Include changed-file tracking with normal progress updates when the CLI/runtime can do so without extra agent calls.
38
+ - Let native capture record changed files; read the objective's captured paths once before delivering and never diff a shared worktree.
39
39
  - Use heartbeat during long mechanical work with no meaningful update.
40
40
  - Ask exactly one blocking question and stop when blocked.
41
- - Deliver last with summary, artifacts, and change rationales.
41
+ - Deliver last with a summary written by behavior or component, plus artifacts when they add review value.
42
42
  - Never revert, restore, or delete concurrent work from other agents or missions to deliver; ask instead.
43
- - Record all meaningful file changes as structured rationales.
43
+ - Declare only known shell/script/generator outputs, deletes, and rename endpoints that capture missed (`--paths` / `--paths-file`); there is no per-file explanation input.
44
44
  - Use stdin/file flags for shell-special content.
45
45
  - Use stdin/file flags for oversized JSON payloads (`--*-json` values above ~8 KB are rejected; use `--*-file -`).
46
46
  - Do not continue implementation after delivery unless follow-up execution is explicitly requested.
@@ -114,6 +114,11 @@ For adapter hook scripts and installed hook paths, including the shared
114
114
  explicit, and must not require a separate mission environment value; unbound hooks remain
115
115
  silent and write nothing. Each hook passes its connector key through `--agent`; tests reject a
116
116
  generic path parser that could misclassify a Read input as an edit. No real DB, no real agent.
117
+ - **Outcome gating:** every adapter whose post-tool rule captures edits pins its outcome
118
+ semantics with `normalized-event` fixtures: a `successOnly` rule shows `outcome: ok`, and a
119
+ decoded result (Codex `Exit code: <n>`) has both a success and a failure fixture. Capture unit
120
+ tests prove failed, cancelled, and unknown outcomes append no path. These are source/payload
121
+ fixtures, not live harness smokes; record that distinction in validation.
117
122
  - **Shared capture rendering:** Claude, Codex, and Cursor fixtures execute the one core capture
118
123
  template with their adapter key substituted. Setup tests assert that it lands at each existing
119
124
  harness-native managed path, is executable, and contains no unresolved placeholder.