@otea/cli 0.0.1 → 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.
Files changed (243) hide show
  1. package/LICENSE +661 -0
  2. package/README.es.md +151 -0
  3. package/README.md +251 -3
  4. package/THIRD_PARTY_NOTICES.md +114 -0
  5. package/bin/otea.mjs +28 -0
  6. package/dist/app/agent-detail.js +26 -0
  7. package/dist/app/agent-draft.js +429 -0
  8. package/dist/app/agent-prompts.js +52 -0
  9. package/dist/app/agents.js +77 -0
  10. package/dist/app/asking.js +43 -0
  11. package/dist/app/board-archive.js +243 -0
  12. package/dist/app/board-migration.js +272 -0
  13. package/dist/app/boards.js +870 -0
  14. package/dist/app/branch-owner.js +48 -0
  15. package/dist/app/brief.js +53 -0
  16. package/dist/app/choices.js +61 -0
  17. package/dist/app/collections.js +101 -0
  18. package/dist/app/context.js +1 -0
  19. package/dist/app/crop.js +56 -0
  20. package/dist/app/devices.js +62 -0
  21. package/dist/app/draft-request.js +82 -0
  22. package/dist/app/events.js +12 -0
  23. package/dist/app/evidence.js +287 -0
  24. package/dist/app/gates.js +610 -0
  25. package/dist/app/guide.js +37 -0
  26. package/dist/app/home.js +145 -0
  27. package/dist/app/init-boards.js +36 -0
  28. package/dist/app/intake.js +25 -0
  29. package/dist/app/item-search.js +141 -0
  30. package/dist/app/items.js +318 -0
  31. package/dist/app/keep-waiting.js +44 -0
  32. package/dist/app/land-order.js +107 -0
  33. package/dist/app/language.js +52 -0
  34. package/dist/app/launcher.js +56 -0
  35. package/dist/app/lease-take.js +54 -0
  36. package/dist/app/leases.js +86 -0
  37. package/dist/app/machine.js +39 -0
  38. package/dist/app/merged.js +89 -0
  39. package/dist/app/migrate.js +171 -0
  40. package/dist/app/next.js +1637 -0
  41. package/dist/app/notes.js +319 -0
  42. package/dist/app/notify-targets.js +113 -0
  43. package/dist/app/opened.js +25 -0
  44. package/dist/app/owner-only.js +34 -0
  45. package/dist/app/performance.js +28 -0
  46. package/dist/app/phone.js +97 -0
  47. package/dist/app/presence.js +596 -0
  48. package/dist/app/preset-views.js +25 -0
  49. package/dist/app/presets.js +129 -0
  50. package/dist/app/priority.js +156 -0
  51. package/dist/app/profile.js +86 -0
  52. package/dist/app/project.js +247 -0
  53. package/dist/app/proofs.js +179 -0
  54. package/dist/app/questions.js +215 -0
  55. package/dist/app/reader-filter.js +58 -0
  56. package/dist/app/relations.js +164 -0
  57. package/dist/app/relay.js +98 -0
  58. package/dist/app/repos.js +176 -0
  59. package/dist/app/restart.js +92 -0
  60. package/dist/app/set-aside.js +64 -0
  61. package/dist/app/system-locale.js +6 -0
  62. package/dist/app/tailscale-cli.js +77 -0
  63. package/dist/app/tailscale-testing.js +41 -0
  64. package/dist/app/tailscale.js +177 -0
  65. package/dist/app/tips.js +30 -0
  66. package/dist/app/topics-everywhere.js +53 -0
  67. package/dist/app/topics.js +453 -0
  68. package/dist/app/undo.js +52 -0
  69. package/dist/app/validate.js +131 -0
  70. package/dist/app/watch.js +48 -0
  71. package/dist/cli/command.js +44 -0
  72. package/dist/cli/commands.js +3303 -0
  73. package/dist/cli/exit-codes.js +70 -0
  74. package/dist/cli/forge.js +176 -0
  75. package/dist/cli/format.js +340 -0
  76. package/dist/cli/gh.js +17 -0
  77. package/dist/cli/gitrepo.js +489 -0
  78. package/dist/cli/help.js +101 -0
  79. package/dist/cli/hooks.js +232 -0
  80. package/dist/cli/main.js +37 -0
  81. package/dist/cli/merged-outside.js +58 -0
  82. package/dist/cli/names.js +154 -0
  83. package/dist/cli/opener.js +21 -0
  84. package/dist/cli/owner.js +154 -0
  85. package/dist/cli/phone.js +221 -0
  86. package/dist/cli/ports.js +24 -0
  87. package/dist/cli/probe.js +18 -0
  88. package/dist/cli/run.js +246 -0
  89. package/dist/cli/serve-file.js +21 -0
  90. package/dist/cli/stats.js +55 -0
  91. package/dist/cli/version.js +3 -0
  92. package/dist/core/agent-guide.js +31 -0
  93. package/dist/core/agent-prompts.js +139 -0
  94. package/dist/core/authority.js +94 -0
  95. package/dist/core/board/analysis.js +86 -0
  96. package/dist/core/board/choices.js +100 -0
  97. package/dist/core/board/compile.js +362 -0
  98. package/dist/core/board/engine.js +523 -0
  99. package/dist/core/board/hints.js +46 -0
  100. package/dist/core/board/history.js +146 -0
  101. package/dist/core/board/ids.js +87 -0
  102. package/dist/core/board/joins.js +30 -0
  103. package/dist/core/board/mentions.js +68 -0
  104. package/dist/core/board/merged.js +18 -0
  105. package/dist/core/board/model.js +135 -0
  106. package/dist/core/board/next.js +1116 -0
  107. package/dist/core/board/notes.js +298 -0
  108. package/dist/core/board/performance.js +218 -0
  109. package/dist/core/board/plan.js +299 -0
  110. package/dist/core/board/problems.js +232 -0
  111. package/dist/core/board/proofs.js +84 -0
  112. package/dist/core/board/questions.js +114 -0
  113. package/dist/core/board/reading.js +220 -0
  114. package/dist/core/board/readings.js +534 -0
  115. package/dist/core/board/schema.js +335 -0
  116. package/dist/core/board/shape-words.js +179 -0
  117. package/dist/core/board/template-words.js +23 -0
  118. package/dist/core/board/templates-catalogue.js +965 -0
  119. package/dist/core/board/templates-coverage.js +261 -0
  120. package/dist/core/board/templates-flows.js +779 -0
  121. package/dist/core/board/templates.js +586 -0
  122. package/dist/core/brief.js +93 -0
  123. package/dist/core/diagram.js +80 -0
  124. package/dist/core/errors.js +12 -0
  125. package/dist/core/evidence.js +33 -0
  126. package/dist/core/fields.js +129 -0
  127. package/dist/core/hierarchy.js +30 -0
  128. package/dist/core/icons.js +181 -0
  129. package/dist/core/image-crop.js +166 -0
  130. package/dist/core/item.js +49 -0
  131. package/dist/core/lease.js +31 -0
  132. package/dist/core/modules.js +318 -0
  133. package/dist/core/notify/planner.js +117 -0
  134. package/dist/core/notify/signals.js +66 -0
  135. package/dist/core/notify/text.js +60 -0
  136. package/dist/core/path-key.js +22 -0
  137. package/dist/core/placement.js +161 -0
  138. package/dist/core/preset-labels.js +66 -0
  139. package/dist/core/preset-notes.js +109 -0
  140. package/dist/core/preset.js +541 -0
  141. package/dist/core/profile.js +55 -0
  142. package/dist/core/project-id.js +20 -0
  143. package/dist/core/refusal.js +1 -0
  144. package/dist/core/relations.js +208 -0
  145. package/dist/core/repo.js +54 -0
  146. package/dist/core/samples.js +161 -0
  147. package/dist/core/search-words.js +68 -0
  148. package/dist/core/test-report.js +120 -0
  149. package/dist/core/time.js +8 -0
  150. package/dist/core/validation.js +60 -0
  151. package/dist/core/views.js +171 -0
  152. package/dist/core/workflow.js +51 -0
  153. package/dist/mcp/commands.js +101 -0
  154. package/dist/mcp/server.js +239 -0
  155. package/dist/mcp/words.js +95 -0
  156. package/dist/server/boards.js +232 -0
  157. package/dist/server/changes.js +42 -0
  158. package/dist/server/diff-tip.js +83 -0
  159. package/dist/server/drift.js +87 -0
  160. package/dist/server/errors.js +87 -0
  161. package/dist/server/evidence.js +82 -0
  162. package/dist/server/hosts.js +6 -0
  163. package/dist/server/hub.js +98 -0
  164. package/dist/server/lan-access.js +62 -0
  165. package/dist/server/lan.js +164 -0
  166. package/dist/server/listen.js +70 -0
  167. package/dist/server/notifier.js +156 -0
  168. package/dist/server/notify-api.js +151 -0
  169. package/dist/server/pairing.js +124 -0
  170. package/dist/server/projects.js +191 -0
  171. package/dist/server/push.js +199 -0
  172. package/dist/server/server.js +960 -0
  173. package/dist/server/session.js +43 -0
  174. package/dist/server/stream.js +36 -0
  175. package/dist/server/test-push.js +38 -0
  176. package/dist/server/token.js +37 -0
  177. package/dist/server/transports.js +54 -0
  178. package/dist/server/ui.js +44 -0
  179. package/dist/server/writes.js +361 -0
  180. package/dist/server/wrong-address.js +36 -0
  181. package/dist/store/boards.js +111 -0
  182. package/dist/store/database.js +45 -0
  183. package/dist/store/machine.js +77 -0
  184. package/dist/store/migrations.js +493 -0
  185. package/dist/store/queries.js +585 -0
  186. package/dist/store/registry.js +72 -0
  187. package/package.json +72 -4
  188. package/presets/architecture/playbook.md +69 -0
  189. package/presets/architecture/preset.yaml +80 -0
  190. package/presets/architecture/samples.yaml +23 -0
  191. package/presets/bug-triage/playbook.md +129 -0
  192. package/presets/bug-triage/preset.yaml +127 -0
  193. package/presets/bug-triage/samples/wall-slide-after.png +0 -0
  194. package/presets/bug-triage/samples/wall-slide-before.png +0 -0
  195. package/presets/bug-triage/samples.yaml +72 -0
  196. package/presets/change/playbook.md +115 -0
  197. package/presets/change/preset.yaml +141 -0
  198. package/presets/change/samples.yaml +62 -0
  199. package/presets/review/playbook.md +51 -0
  200. package/presets/review/preset.yaml +62 -0
  201. package/presets/review/samples.yaml +27 -0
  202. package/presets/tasks/playbook.md +78 -0
  203. package/presets/tasks/preset.yaml +61 -0
  204. package/presets/tasks/samples.yaml +46 -0
  205. package/schemas/board.schema.json +764 -0
  206. package/ui/dist/THIRD_PARTY_NOTICES.md +114 -0
  207. package/ui/dist/assets/dm-mono-latin-400-normal--0xN8mdc.woff +0 -0
  208. package/ui/dist/assets/dm-mono-latin-400-normal-4GdczIuU.woff2 +0 -0
  209. package/ui/dist/assets/dm-mono-latin-500-normal-CN8Miw6E.woff +0 -0
  210. package/ui/dist/assets/dm-mono-latin-500-normal-DRMDZjhP.woff2 +0 -0
  211. package/ui/dist/assets/dm-mono-latin-ext-400-normal-1aZr6b2b.woff +0 -0
  212. package/ui/dist/assets/dm-mono-latin-ext-400-normal-C2zvOubV.woff2 +0 -0
  213. package/ui/dist/assets/dm-mono-latin-ext-500-normal-BtRyHRi6.woff2 +0 -0
  214. package/ui/dist/assets/dm-mono-latin-ext-500-normal-Dw3M13d8.woff +0 -0
  215. package/ui/dist/assets/index-C3OzJope.js +103 -0
  216. package/ui/dist/assets/index-COdEjckQ.css +1 -0
  217. package/ui/dist/assets/newsreader-latin-ext-opsz-italic-CSPGnFdO.woff2 +0 -0
  218. package/ui/dist/assets/newsreader-latin-ext-opsz-normal-BQn1nviT.woff2 +0 -0
  219. package/ui/dist/assets/newsreader-latin-opsz-italic-kJKFiXvB.woff2 +0 -0
  220. package/ui/dist/assets/newsreader-latin-opsz-normal-s-izfB6B.woff2 +0 -0
  221. package/ui/dist/assets/newsreader-vietnamese-opsz-italic-DTr-ymY4.woff2 +0 -0
  222. package/ui/dist/assets/newsreader-vietnamese-opsz-normal-BjhtXyW2.woff2 +0 -0
  223. package/ui/dist/assets/pdf-YwugTw7Y.js +54 -0
  224. package/ui/dist/assets/pdf-engine-CkBopwck.js +1 -0
  225. package/ui/dist/assets/pdf-rELvHkft.js +56 -0
  226. package/ui/dist/assets/pdf.worker.min-B5Yc7dP4.mjs +27 -0
  227. package/ui/dist/assets/pdf.worker.min-B7U8ptvh.js +1 -0
  228. package/ui/dist/assets/pdf.worker.min-CIqJB0yW.mjs +28 -0
  229. package/ui/dist/assets/pdf.worker.min-UqOn5EDC.js +1 -0
  230. package/ui/dist/assets/schibsted-grotesk-latin-ext-wght-normal-hsMS0n0O.woff2 +0 -0
  231. package/ui/dist/assets/schibsted-grotesk-latin-wght-normal-Bb8VGrTG.woff2 +0 -0
  232. package/ui/dist/icons/apple-touch-icon.png +0 -0
  233. package/ui/dist/icons/otea-192.png +0 -0
  234. package/ui/dist/icons/otea-512.png +0 -0
  235. package/ui/dist/icons/otea-badge.png +0 -0
  236. package/ui/dist/icons/otea-maskable-512.png +0 -0
  237. package/ui/dist/index.html +25 -0
  238. package/ui/dist/manifest.webmanifest +24 -0
  239. package/ui/dist/otea-idle.svg +5 -0
  240. package/ui/dist/otea-working.svg +5 -0
  241. package/ui/dist/otea-yours-working.svg +5 -0
  242. package/ui/dist/otea-yours.svg +5 -0
  243. package/ui/dist/sw.js +1 -0
@@ -0,0 +1,60 @@
1
+ import { missingToComplete, valueProblem } from './fields.js';
2
+ function fieldMessages(type, item, of) {
3
+ const found = [];
4
+ for (const [name, value] of Object.entries(item.fields)) {
5
+ const spec = type.fields[name];
6
+ if (!spec || name === 'title') {
7
+ found.push(['warning', `field "${name}" is not declared by ${of}`]);
8
+ }
9
+ else if (typeof value !== 'string') {
10
+ found.push(['error', `field "${name}" must be a string, got ${typeof value}`]);
11
+ }
12
+ else {
13
+ const problem = valueProblem(name, spec, value);
14
+ if (problem)
15
+ found.push(['error', problem]);
16
+ }
17
+ }
18
+ const values = { ...item.fields, title: item.title };
19
+ for (const [name, spec] of Object.entries(type.fields)) {
20
+ const value = values[name];
21
+ const missing = value === undefined || (typeof value === 'string' && value.trim() === '');
22
+ if (spec.required === 'create' && missing) {
23
+ found.push(['error', `missing required field "${spec.label ?? name}"`]);
24
+ }
25
+ }
26
+ return found;
27
+ }
28
+ function typeMessages(type, item, of) {
29
+ const found = [];
30
+ const { workflow } = type;
31
+ const state = workflow.states.find(({ name }) => name === item.state);
32
+ if (!state)
33
+ found.push(['error', `unknown state "${item.state}" in ${of}`]);
34
+ found.push(...fieldMessages(type, item, of));
35
+ if (state && state.turn !== 'none' && state.name !== workflow.incomplete) {
36
+ for (const name of missingToComplete(type, item.fields)) {
37
+ found.push(['warning', `missing field "${name}" required to complete`]);
38
+ }
39
+ }
40
+ return found;
41
+ }
42
+ export function itemFindings(preset, item) {
43
+ const found = [];
44
+ const type = preset.types.find(({ name }) => name === item.type);
45
+ if (type) {
46
+ const own = preset.types.length === 1 ? '' : ` (type ${type.name})`;
47
+ found.push(...typeMessages(type, item, `preset ${preset.name}${own}`));
48
+ }
49
+ else {
50
+ const names = preset.types.map(({ name }) => name).join(', ');
51
+ found.push(['error', `unknown type "${item.type}" in preset ${preset.name} (types: ${names})`]);
52
+ }
53
+ if (item.presetVersion < preset.version) {
54
+ found.push([
55
+ 'warning',
56
+ `written under preset ${preset.name} v${item.presetVersion}; the preset is now v${preset.version}`,
57
+ ]);
58
+ }
59
+ return found.map(([severity, message]) => ({ severity, subject: item.id, message }));
60
+ }
@@ -0,0 +1,171 @@
1
+ import { availableMoves, relayableMoves } from './authority.js';
2
+ import { evidenceTypeOf } from './evidence.js';
3
+ import { missingToComplete } from './fields.js';
4
+ import { prefixFor } from './item.js';
5
+ import { holderOf } from './placement.js';
6
+ import { childrenSummary } from './relations.js';
7
+ import { gateVerdicts } from './workflow.js';
8
+ export function fieldViews(fields) {
9
+ return Object.entries(fields).map(([name, spec]) => ({ name, ...spec }));
10
+ }
11
+ export function typeViews(types) {
12
+ return types.map(({ name, label, icon, fields, workflow, layout, children, root, labels }) => {
13
+ const view = {
14
+ name,
15
+ label,
16
+ initial: workflow.initial,
17
+ states: workflow.states,
18
+ transitions: workflow.transitions,
19
+ fields: fieldViews(fields),
20
+ layout,
21
+ };
22
+ if (workflow.incomplete !== undefined)
23
+ view.incomplete = workflow.incomplete;
24
+ if (icon !== undefined)
25
+ view.icon = icon;
26
+ if (children !== undefined)
27
+ view.children = children;
28
+ if (root !== undefined)
29
+ view.root = root;
30
+ if (workflow.gates !== undefined && Object.keys(workflow.gates).length > 0) {
31
+ view.gates = workflow.gates;
32
+ }
33
+ if (labels !== undefined)
34
+ view.labels = labels;
35
+ return view;
36
+ });
37
+ }
38
+ // A collection of a draft preset, for the preview: named as given, with the preset's icon unless
39
+ // it is given its own.
40
+ export function draftCollectionView(preset, { name, icon }) {
41
+ return {
42
+ name,
43
+ prefix: prefixFor(name),
44
+ preset: preset.name,
45
+ icon: icon === undefined ? (preset.icon ?? null) : icon,
46
+ types: typeViews(preset.types),
47
+ view: preset.view,
48
+ };
49
+ }
50
+ export function itemMoves(type, state, fields, performer) {
51
+ const gates = gateVerdicts(type.workflow, state);
52
+ return {
53
+ transitions: availableMoves(type.workflow, state, performer),
54
+ relayable: relayableMoves(type.workflow, state),
55
+ missing: missingToComplete(type, fields),
56
+ ...(Object.keys(gates).length > 0 ? { gates } : {}),
57
+ };
58
+ }
59
+ const DESK = { actor: { kind: 'human', name: 'you' }, channel: 'ui' };
60
+ const UNITS = { m: 60_000, h: 3_600_000, d: 86_400_000 };
61
+ function before(now, ago) {
62
+ if (ago === undefined)
63
+ return now;
64
+ const unit = UNITS[ago.slice(-1)] ?? 0;
65
+ return new Date(Date.parse(now) - Number(ago.slice(0, -1)) * unit).toISOString();
66
+ }
67
+ function typeIn(preset, name) {
68
+ const type = preset.types.find((candidate) => candidate.name === name) ?? preset.types[0];
69
+ if (!type)
70
+ throw new Error(`Preset ${preset.name} has no types`);
71
+ return type;
72
+ }
73
+ function stateOf(workflow, name) {
74
+ return workflow.states.find((state) => state.name === name);
75
+ }
76
+ // A sample's sequence number: the end of its id (BUGS-12 is 12), or 1.
77
+ function seqOf(id) {
78
+ const digits = /(\d+)$/.exec(id)?.[1];
79
+ return digits === undefined ? 1 : Number(digits);
80
+ }
81
+ function actorOf(event) {
82
+ return { kind: event.actor, name: event.name };
83
+ }
84
+ // The other end of a sample's link: its turn read from the preset when it is one of its types in
85
+ // one of its states, else the agent's (it lives nowhere the preview can look).
86
+ function relatedOf(preset, sample) {
87
+ return sample.relations.map((relation) => {
88
+ const workflow = preset.types.find(({ name }) => name === relation.type)?.workflow;
89
+ const state = workflow && stateOf(workflow, relation.state ?? '');
90
+ const related = {
91
+ kind: relation.kind,
92
+ id: relation.id,
93
+ collection: relation.id.replace(/-\d+$/, '').toLowerCase(),
94
+ type: relation.type ?? '',
95
+ title: relation.title,
96
+ state: relation.state ?? '',
97
+ turn: state?.turn ?? 'agent',
98
+ lease: null,
99
+ };
100
+ if (state?.closes !== undefined)
101
+ related.closes = state.closes;
102
+ return related;
103
+ });
104
+ }
105
+ // A sample as a stored item reads in a list: what the row, the lanes and the grid draw.
106
+ export function sampleItem(preset, sample, options) {
107
+ const type = typeIn(preset, sample.type);
108
+ const state = stateOf(type.workflow, sample.state) ?? stateOf(type.workflow, type.workflow.initial);
109
+ const times = sample.history.map(({ ago }) => before(options.now, ago));
110
+ const first = sample.history[0];
111
+ const item = {
112
+ id: sample.id,
113
+ collection: options.collection,
114
+ seq: seqOf(sample.id),
115
+ type: type.name,
116
+ title: sample.title,
117
+ fields: sample.fields,
118
+ presetVersion: preset.version,
119
+ state: state?.name ?? type.workflow.initial,
120
+ turn: state?.turn ?? 'agent',
121
+ createdAt: times[0] ?? options.now,
122
+ updatedAt: times.at(-1) ?? options.now,
123
+ createdBy: first ? actorOf(first) : DESK.actor,
124
+ lease: null,
125
+ };
126
+ if (state?.closes !== undefined)
127
+ item.closes = state.closes;
128
+ const children = relatedOf(preset, sample).filter(({ kind }) => kind === 'child');
129
+ if (children.length > 0)
130
+ item.children = childrenSummary(children);
131
+ return item;
132
+ }
133
+ // A sample as the item detail reads it, as GET /api/items/:id answers for a stored item.
134
+ export function sampleItemView(preset, sample, options) {
135
+ const item = sampleItem(preset, sample, options);
136
+ const type = typeIn(preset, item.type);
137
+ const events = sample.history.map((event, index) => ({
138
+ id: index + 1,
139
+ itemId: item.id,
140
+ type: event.event,
141
+ actor: actorOf(event),
142
+ at: before(options.now, event.ago),
143
+ data: {
144
+ ...(event.event === 'created' ? { state: item.state } : {}),
145
+ ...(event.from === undefined ? {} : { from: event.from }),
146
+ ...(event.to === undefined ? {} : { to: event.to }),
147
+ ...(event.reason === undefined ? {} : { reason: event.reason }),
148
+ },
149
+ }));
150
+ const evidence = sample.evidence.map(({ file, role, module, caption }, index) => ({
151
+ id: index + 1,
152
+ itemId: item.id,
153
+ role,
154
+ module: holderOf(type.layout, { module: module ?? null, filename: file }),
155
+ ...evidenceTypeOf(file),
156
+ filename: file,
157
+ size: 0,
158
+ sha256: '',
159
+ caption: caption ?? null,
160
+ createdAt: item.createdAt,
161
+ actor: item.createdBy,
162
+ channel: 'cli',
163
+ }));
164
+ return {
165
+ ...item,
166
+ events,
167
+ ...itemMoves(type, item.state, item.fields, options.performer ?? DESK),
168
+ evidence,
169
+ relations: relatedOf(preset, sample),
170
+ };
171
+ }
@@ -0,0 +1,51 @@
1
+ import { OteaError } from './errors.js';
2
+ export const TURNS = ['human', 'agent', 'none'];
3
+ export const AUTHORITIES = ['agent', 'human', 'human-ui'];
4
+ export const CLOSINGS = ['done', 'discarded'];
5
+ // What must hold before an item may enter a state, whatever its turn: `children_closed`, that none
6
+ // of its children is still open, and `blockers_closed`, that nothing that blocks it is. A state may
7
+ // require both. An item's state is never derived from its children's or its blockers'.
8
+ export const REQUIREMENTS = ['children_closed', 'blockers_closed'];
9
+ export function turnOf(workflow, stateName) {
10
+ const state = workflow.states.find((candidate) => candidate.name === stateName);
11
+ if (!state)
12
+ throw new OteaError('not_found', `Unknown state "${stateName}" in ${workflow.name}`);
13
+ return state.turn;
14
+ }
15
+ // How an item in the state is closed, or nothing while it is still open.
16
+ export function closesOf(workflow, stateName) {
17
+ return workflow.states.find((candidate) => candidate.name === stateName)?.closes;
18
+ }
19
+ // What entering the state requires, in the order declared; empty when nothing.
20
+ export function requirementsOf(workflow, stateName) {
21
+ return workflow.states.find((candidate) => candidate.name === stateName)?.requires ?? [];
22
+ }
23
+ // Whether each action of the workflow's gates is allowed in the state; empty without gates.
24
+ export function gateVerdicts(workflow, stateName) {
25
+ return Object.fromEntries(Object.entries(workflow.gates ?? {}).map(([action, states]) => [
26
+ action,
27
+ states.includes(stateName),
28
+ ]));
29
+ }
30
+ export function transitionsFrom(workflow, from) {
31
+ return workflow.transitions.filter((transition) => transition.from === from);
32
+ }
33
+ export function transitionsBetween(workflow, from, to) {
34
+ return transitionsFrom(workflow, from).filter((transition) => transition.to === to);
35
+ }
36
+ // A state as a reader names it: its label, or its key.
37
+ export function stateLabel(workflow, state) {
38
+ return workflow.states.find(({ name }) => name === state)?.label ?? state;
39
+ }
40
+ export function assertTransition(workflow, from, to) {
41
+ const transitions = transitionsBetween(workflow, from, to);
42
+ if (transitions.length > 0)
43
+ return transitions;
44
+ const said = (state) => stateLabel(workflow, state);
45
+ throw new OteaError('invalid_transition', `Cannot move from "${said(from)}" to "${said(to)}"`, {
46
+ kind: 'move',
47
+ why: 'no_move',
48
+ from,
49
+ to,
50
+ });
51
+ }
@@ -0,0 +1,101 @@
1
+ // Which commands MCP serves as tools, and the tools' names: no dependencies, so the CLI's help
2
+ // reads them without loading the MCP server.
3
+ // The commands an agent runs, each served as the tool of the same name. The rest belong to the
4
+ // human or to setup and stay in the CLI.
5
+ export const AGENT_COMMANDS = [
6
+ 'board',
7
+ 'board draft',
8
+ 'list',
9
+ 'show',
10
+ 'create',
11
+ 'update',
12
+ 'attach',
13
+ 'detach',
14
+ 'link',
15
+ 'unlink',
16
+ 'next',
17
+ 'reply',
18
+ 'merged',
19
+ 'reopen',
20
+ 'tick',
21
+ 'topic add',
22
+ 'topic answer',
23
+ // Agents read the topics kept to answer what was said before.
24
+ 'topic list',
25
+ 'topic show',
26
+ 'ask',
27
+ // The person's answer to a question, given in the chat (P4-R2-2).
28
+ 'answer',
29
+ 'handoff',
30
+ 'drop',
31
+ 'approve',
32
+ 'send-back',
33
+ 'move',
34
+ 'claim',
35
+ 'profile',
36
+ 'whoami',
37
+ 'heartbeat',
38
+ 'release',
39
+ 'relay',
40
+ 'events',
41
+ 'wait',
42
+ ];
43
+ export const CLI_ONLY_COMMANDS = [
44
+ 'init',
45
+ 'brief',
46
+ // How each model performs is the person's reading, not an agent's.
47
+ 'stats',
48
+ 'projects list',
49
+ 'projects current',
50
+ 'projects add',
51
+ 'projects relink',
52
+ 'projects forget',
53
+ // A repo's name decides which items a gate checks, so agents never set it.
54
+ 'repos list',
55
+ 'repos add',
56
+ 'repos remove',
57
+ 'migrate',
58
+ 'connect',
59
+ 'board add',
60
+ // What the person pastes into an agent's chat: the person copies it, the agent never needs it.
61
+ 'prompt',
62
+ // A cut-out image is a file on the agent's own disk, which only the command line can hand it.
63
+ 'crop',
64
+ // Topics are the person's to turn on, keep going and close; agents record, answer and read them.
65
+ 'topic on',
66
+ 'topic off',
67
+ 'topic note',
68
+ 'topic close',
69
+ 'collection icon',
70
+ 'validate',
71
+ 'check',
72
+ 'hook install',
73
+ 'hook remove',
74
+ 'serve',
75
+ 'open',
76
+ 'devices list',
77
+ 'devices revoke',
78
+ 'phone status',
79
+ 'phone lan',
80
+ 'phone tailscale',
81
+ 'phone relay',
82
+ 'mcp',
83
+ ];
84
+ // next is not among them: it keeps what it offers each agent, and claims it with claim.
85
+ export const READ_ONLY = new Set([
86
+ 'board',
87
+ 'list',
88
+ 'show',
89
+ 'events',
90
+ 'wait',
91
+ 'topic list',
92
+ 'topic show',
93
+ 'whoami',
94
+ ]);
95
+ // Reads that need no name: what was concluded before is reference, not work an agent does, so a
96
+ // call that names nobody reads it, and nobody is seen.
97
+ export const NAMELESS_READS = new Set(['topic list', 'topic show']);
98
+ // A tool is named after its command, with words joined by underscores (send-back is send_back).
99
+ export function toolName(command) {
100
+ return command.replace(/[ -]/g, '_');
101
+ }
@@ -0,0 +1,239 @@
1
+ import { McpServer } from '@modelcontextprotocol/server';
2
+ import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
3
+ import { z } from 'zod';
4
+ import { NO_TAILSCALE } from '../app/tailscale.js';
5
+ import { errorData, UsageError, } from '../cli/command.js';
6
+ import { NO_FORGE } from '../cli/forge.js';
7
+ import { OTEA_VERSION } from '../cli/version.js';
8
+ import { agentGuideFor } from '../core/agent-guide.js';
9
+ import { OteaError } from '../core/errors.js';
10
+ import { agentActor, assertAgentName, PERSON_READER } from '../core/item.js';
11
+ import { parseDuration } from '../core/lease.js';
12
+ import { AGENT_COMMANDS, NAMELESS_READS, READ_ONLY, toolName } from './commands.js';
13
+ import { mcpWords } from './words.js';
14
+ export { AGENT_COMMANDS, CLI_ONLY_COMMANDS, toolName } from './commands.js';
15
+ // A tool call answers once, so it cannot follow the event log.
16
+ // --field-file reads a file or stdin for a long value, which a tool call carries as it is.
17
+ export const OMITTED_OPTIONS = {
18
+ events: ['follow'],
19
+ create: ['field-file'],
20
+ update: ['field-file'],
21
+ };
22
+ // Clients time out long tool calls, so a wait gives up after this unless told otherwise, and never
23
+ // waits longer than the cap.
24
+ const WAIT_TIMEOUT = '5m';
25
+ const WAIT_MAX = { text: '15m', ms: 15 * 60_000 };
26
+ const NOTES = {
27
+ attach: 'file is a path on this machine, which the server reads; a relative one is resolved against the directory otea mcp runs in. The file goes to an evidence module of the item type that accepts it: pass module (its id, shown by show) when several do, and role before or after for a compare.',
28
+ 'board draft': 'Pass id (the Pedido) or new (the name of a board the person asked you for, with why); not both. file is a path on this machine, which the server reads; a relative one is resolved against the directory otea mcp runs in.',
29
+ events: 'Returns the events after the event id given to since, one a line with its id first; call it again with the last id to read newer ones.',
30
+ wait: `Gives up with the timeout error after timeout (default ${WAIT_TIMEOUT}, at most ${WAIT_MAX.text}); call it again to keep waiting.`,
31
+ };
32
+ // A number an option takes (a note's, an event id) may come as a JSON number: it is read as its
33
+ // digits, as the CLI reads it.
34
+ const NUMBERED = new Set(['n', 'event id']);
35
+ function optionSchema(spec) {
36
+ if (spec.flag)
37
+ return z.boolean().optional();
38
+ const numbered = NUMBERED.has(spec.placeholder ?? '');
39
+ const text = numbered ? z.union([z.string(), z.number()]) : z.string();
40
+ const value = spec.choices ? z.enum(spec.choices) : text;
41
+ const said = spec.about ?? spec.placeholder;
42
+ const described = said ? value.describe(said) : value;
43
+ if (spec.multiple)
44
+ return z.array(described).optional();
45
+ return spec.required ? described : described.optional();
46
+ }
47
+ // Every tool takes the agent making the call, so subagents on one server stay apart.
48
+ const AS = z.string().optional().describe('your agent name; each subagent its own');
49
+ const NAME_YOURSELF = 'pass as with your agent name on every call';
50
+ // A server started under a name (otea mcp --as) is that agent's: a call names it, or one of its
51
+ // subagents (<name>-<role>), never another agent, which would spread one agent over several names.
52
+ export function assertPinnedName(pinned, agent) {
53
+ if (pinned === undefined || agent === undefined)
54
+ return;
55
+ assertAgentName(agent);
56
+ if (agent === pinned || agent.startsWith(`${pinned}-`))
57
+ return;
58
+ throw new OteaError('forbidden', `This MCP server is ${pinned}'s (otea mcp --as ${pinned}): call as ${pinned}, or as ${pinned}-<role> for a subagent; nothing was done as ${agent}`);
59
+ }
60
+ function inputSchema(command) {
61
+ const omitted = OMITTED_OPTIONS[command.name] ?? [];
62
+ const shape = { as: AS };
63
+ for (const arg of command.args) {
64
+ if (arg.endsWith('?'))
65
+ shape[arg.slice(0, -1)] = z.string().optional();
66
+ else
67
+ shape[arg] = z.string();
68
+ }
69
+ for (const [name, spec] of Object.entries(command.options)) {
70
+ if (!omitted.includes(name))
71
+ shape[name] = optionSchema(spec);
72
+ }
73
+ return z.object(shape);
74
+ }
75
+ function waitValues(values) {
76
+ const timeout = typeof values.timeout === 'string' ? values.timeout : WAIT_TIMEOUT;
77
+ const ms = parseDuration(timeout);
78
+ if (ms !== undefined && ms > WAIT_MAX.ms) {
79
+ throw new UsageError(`--timeout must be at most ${WAIT_MAX.text} over MCP`);
80
+ }
81
+ return { ...values, timeout };
82
+ }
83
+ // The tool call as the command's input: the same arguments and options the CLI would parse.
84
+ function inputFor(command, values, context, signal, records, harness, seen) {
85
+ const option = (name) => {
86
+ const value = values[name];
87
+ return typeof value === 'string' || typeof value === 'number' ? String(value) : undefined;
88
+ };
89
+ const agent = typeof values.as === 'string' && values.as !== '' ? values.as : context.agent;
90
+ // A name the CLI refuses is refused before the server hears it, so it never shows as an agent.
91
+ if (agent !== undefined)
92
+ assertAgentName(agent);
93
+ assertPinnedName(context.agent, agent);
94
+ // The first call of each agent on this server starts its session here.
95
+ const newSession = agent !== undefined && !seen.has(agent);
96
+ if (agent !== undefined) {
97
+ if (newSession)
98
+ context.heard?.(agent);
99
+ else
100
+ context.still?.(agent);
101
+ seen.add(agent);
102
+ }
103
+ return {
104
+ cwd: context.cwd,
105
+ ...(context.pin === undefined ? {} : { pin: context.pin }),
106
+ get actor() {
107
+ return agentActor(agent, NAME_YOURSELF);
108
+ },
109
+ // Over MCP the caller is always an agent: reading needs its name too, but for the topics.
110
+ get reader() {
111
+ if (agent === undefined && NAMELESS_READS.has(command.name))
112
+ return PERSON_READER;
113
+ return agentActor(agent, NAME_YOURSELF);
114
+ },
115
+ agent,
116
+ channel: 'mcp',
117
+ harness,
118
+ ...(newSession ? { newSession } : {}),
119
+ signal,
120
+ openUrl: async () => {
121
+ throw new Error('No browser to open over MCP');
122
+ },
123
+ tailscale: NO_TAILSCALE,
124
+ forge: NO_FORGE,
125
+ probe: async () => false,
126
+ terminal: false,
127
+ warn: context.warn,
128
+ ask: async () => undefined,
129
+ stdin: async () => '',
130
+ print: (data, text) => records.push({ data, text }),
131
+ args: command.args.flatMap((name) => {
132
+ const key = name.endsWith('?') ? name.slice(0, -1) : name;
133
+ const value = values[key];
134
+ return value === undefined && key !== name ? [] : [String(value ?? '')];
135
+ }),
136
+ flag: (name) => values[name] === true,
137
+ option,
138
+ options: (name) => {
139
+ const value = values[name];
140
+ return Array.isArray(value) ? value.map(String) : [];
141
+ },
142
+ required: (name) => {
143
+ const value = option(name);
144
+ if (value === undefined)
145
+ throw new UsageError(`Missing --${name} for "otea ${command.name}"`);
146
+ return value;
147
+ },
148
+ };
149
+ }
150
+ function reply(text, isError) {
151
+ return { content: [{ type: 'text', text }], isError };
152
+ }
153
+ // Runs the command as the CLI would: the text it prints, in the words of the tools, as the only
154
+ // content (no structuredContent, which some clients put in context next to it); a failure, its
155
+ // message. Under otea mcp --json: its data, or the records it printed one by one, and a failure as
156
+ // the same {"error":{"code","message"}} the CLI prints.
157
+ async function callCommand(command, values, context, signal, harness, seen, commands) {
158
+ const records = [];
159
+ let input;
160
+ const done = context.calling?.(command.name);
161
+ try {
162
+ const given = command.name === 'wait' ? waitValues(values) : values;
163
+ input = inputFor(command, given, context, signal, records, harness, seen);
164
+ const output = await command.execute(input);
165
+ if (context.json) {
166
+ const data = output === undefined ? records.map(({ data }) => data) : inMcpWords(output.data, commands);
167
+ return reply(JSON.stringify(data), false);
168
+ }
169
+ const text = output === undefined ? records.map(({ text }) => text).join('\n') : output.text;
170
+ // A command with nothing to say (no events yet) still answers: with its data.
171
+ if (text === '')
172
+ return reply(JSON.stringify(output === undefined ? [] : output.data), false);
173
+ return reply(mcpWords(text, commands), false);
174
+ }
175
+ catch (error) {
176
+ // A first call that failed starts no session: the next call is its first again (P2S-R2-3).
177
+ if (input?.newSession && input.agent !== undefined) {
178
+ seen.delete(input.agent);
179
+ context.failed?.(input.agent);
180
+ }
181
+ const { error: data } = errorData(error);
182
+ const message = typeof data.message === 'string' ? mcpWords(data.message, commands) : data.message;
183
+ if (!context.json)
184
+ return reply(String(message), true);
185
+ return reply(JSON.stringify({ error: { ...data, message } }), true);
186
+ }
187
+ finally {
188
+ done?.();
189
+ }
190
+ }
191
+ // What a command says to the agent (its `text`, show's `hint`: what to do with the item now, and
192
+ // wait's topics `reminder`), in the words of the tools it calls.
193
+ const SAID = ['text', 'hint', 'reminder'];
194
+ function inMcpWords(data, commands) {
195
+ if (data === null || typeof data !== 'object' || Array.isArray(data))
196
+ return data;
197
+ const said = data;
198
+ const words = SAID.flatMap((key) => {
199
+ const value = said[key];
200
+ return typeof value === 'string' ? [[key, mcpWords(value, commands)]] : [];
201
+ });
202
+ return words.length === 0 ? data : { ...data, ...Object.fromEntries(words) };
203
+ }
204
+ export function createMcpServer(commands, context) {
205
+ // Otea's agent guide as the server's instructions: clients such as Claude Code put them in the
206
+ // agent's context when it connects.
207
+ const server = new McpServer({ name: 'otea', version: OTEA_VERSION }, { instructions: agentGuideFor(context.topics ?? false) });
208
+ // The client names itself in initialize: its clientInfo is the harness the agent works through.
209
+ const harness = () => {
210
+ const client = server.server.getClientVersion();
211
+ return client && { name: client.name, version: client.version };
212
+ };
213
+ // The agents that called this server so far: each one's first call starts its session.
214
+ const seen = new Set();
215
+ server.server.oninitialized = () => context.greeted?.(harness());
216
+ for (const name of AGENT_COMMANDS) {
217
+ const command = commands.find((candidate) => candidate.name === name);
218
+ if (!command)
219
+ throw new Error(`No "otea ${name}" command to serve`);
220
+ const note = NOTES[name];
221
+ server.registerTool(toolName(name), {
222
+ description: note ? `${command.summary}. ${note}` : command.summary,
223
+ inputSchema: inputSchema(command),
224
+ annotations: { readOnlyHint: READ_ONLY.has(name) },
225
+ }, (values, { mcpReq }) => callCommand(command, values, context, mcpReq.signal, harness(), seen, commands));
226
+ }
227
+ return server;
228
+ }
229
+ // Serves on stdin and stdout until the client closes stdin, which the transport notices, or the
230
+ // signal aborts. Stdout carries the protocol alone.
231
+ export async function serveStdio(server, signal) {
232
+ const closed = new Promise((resolve) => {
233
+ server.server.onclose = resolve;
234
+ });
235
+ const close = () => void server.close();
236
+ signal.addEventListener('abort', close, { once: true });
237
+ await server.connect(new StdioServerTransport());
238
+ await closed;
239
+ }