@superjackfruitlabs/treaty-matrix-events 0.0.0-stage → 0.0.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 (69) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +29 -2
  3. package/dist/answers.d.ts +127 -0
  4. package/dist/answers.js +269 -0
  5. package/dist/attention.d.ts +87 -0
  6. package/dist/attention.js +244 -0
  7. package/dist/board-room.d.ts +20 -0
  8. package/dist/board-room.js +24 -0
  9. package/dist/cards.d.ts +115 -0
  10. package/dist/cards.js +106 -0
  11. package/dist/check.d.ts +123 -0
  12. package/dist/check.js +252 -0
  13. package/dist/checks.d.ts +118 -0
  14. package/dist/checks.js +332 -0
  15. package/dist/decision-timeout.d.ts +50 -0
  16. package/dist/decision-timeout.js +138 -0
  17. package/dist/deliveries.d.ts +337 -0
  18. package/dist/deliveries.js +20 -0
  19. package/dist/delivery.d.ts +72 -0
  20. package/dist/delivery.js +159 -0
  21. package/dist/elicitation.d.ts +60 -0
  22. package/dist/elicitation.js +123 -0
  23. package/dist/gate.d.ts +213 -0
  24. package/dist/gate.js +610 -0
  25. package/dist/index.d.ts +26 -0
  26. package/dist/index.js +26 -0
  27. package/dist/permission.d.ts +86 -0
  28. package/dist/permission.js +141 -0
  29. package/dist/question.d.ts +91 -0
  30. package/dist/question.js +230 -0
  31. package/dist/quorum.d.ts +87 -0
  32. package/dist/quorum.js +150 -0
  33. package/dist/release.d.ts +94 -0
  34. package/dist/release.js +260 -0
  35. package/dist/safe-url.d.ts +7 -0
  36. package/dist/safe-url.js +17 -0
  37. package/dist/unique.d.ts +13 -0
  38. package/dist/unique.js +37 -0
  39. package/examples.json +8113 -0
  40. package/package.json +31 -4
  41. package/schemas/dev.agentpod.check.failed.v2.json +113 -0
  42. package/schemas/dev.agentpod.check.overridden.v2.json +110 -0
  43. package/schemas/dev.agentpod.checks.waiting.v2.json +88 -0
  44. package/schemas/dev.agentpod.decision.pulled_back.v2.json +67 -0
  45. package/schemas/dev.agentpod.decision.released.v2.json +79 -0
  46. package/schemas/dev.agentpod.gate.progress.v2.json +119 -0
  47. package/schemas/dev.agentpod.permission.answer.v2.json +71 -0
  48. package/schemas/dev.agentpod.permission.json +46 -0
  49. package/schemas/dev.agentpod.permission.outcome.v1.json +85 -0
  50. package/schemas/dev.agentpod.permission.v1.json +46 -0
  51. package/schemas/dev.agentpod.permission.v2.json +195 -0
  52. package/schemas/dev.superpipeline.attention.answer.v2.json +83 -0
  53. package/schemas/dev.superpipeline.attention.outcome.v1.json +56 -0
  54. package/schemas/dev.superpipeline.attention.v2.json +192 -0
  55. package/schemas/dev.superpipeline.check.override.v2.json +64 -0
  56. package/schemas/dev.superpipeline.decision.escalated.v1.json +82 -0
  57. package/schemas/dev.superpipeline.decision.reminded.v1.json +101 -0
  58. package/schemas/dev.superpipeline.delivery.answer.v2.json +76 -0
  59. package/schemas/dev.superpipeline.delivery.v2.json +315 -0
  60. package/schemas/dev.superpipeline.elicitation.json +72 -0
  61. package/schemas/dev.superpipeline.gate.decision.v1.json +53 -0
  62. package/schemas/dev.superpipeline.gate.decision.v2.json +72 -0
  63. package/schemas/dev.superpipeline.gate.json +96 -0
  64. package/schemas/dev.superpipeline.gate.outcome.v1.json +65 -0
  65. package/schemas/dev.superpipeline.gate.pull_back.v2.json +51 -0
  66. package/schemas/dev.superpipeline.gate.v1.json +100 -0
  67. package/schemas/dev.superpipeline.gate.v2.json +392 -0
  68. package/schemas/dev.superpipeline.question.answer.v2.json +84 -0
  69. package/schemas/dev.superpipeline.question.v2.json +331 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Rakesh Gangwar
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,30 @@
1
- # Temporary Holding Version
1
+ # @superjackfruitlabs/treaty-matrix-events
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The board-room Matrix event contract: every event a board's work crosses chat on, as data and as
4
+ TypeScript. Moved from the AgentPod hub with its behaviour unchanged, so SuperExchange, the hub and
5
+ SuperMessage share one copy (treaty `docs/2026-11-11-matrix-contract-plan.md`).
6
+
7
+ - **`schemas/*.json`:** one JSON Schema (draft 2020-12) per type, named by its type string. The
8
+ contract for readers in any language. `x-uniqueBy` lists the paths whose values must not repeat.
9
+ - **`examples.json`:** the corpus the schemas are checked against: valid content, and invalid
10
+ content with what refuses it (`schema`, `unique`, or `recorded`: only the carrier, against what it
11
+ recorded when it posted).
12
+ - **TypeScript:** builders that take the bodies SuperPipeline sends (`GatePendingDelivery`,
13
+ `ElicitationPendingDelivery`, …) and return Matrix content, and parsers that take a person's answer
14
+ and return what a carrier acts on. Nothing touches a database, a homeserver or a log; judging an
15
+ answer against what was posted, and acting on it, stay with the carrier.
16
+
17
+ ```ts
18
+ import {
19
+ gateV2Content,
20
+ parseGateDecision,
21
+ } from "@superjackfruitlabs/treaty-matrix-events";
22
+ import gateV2 from "@superjackfruitlabs/treaty-matrix-events/schemas/dev.superpipeline.gate.v2.json" with { type: "json" };
23
+ ```
24
+
25
+ Type strings never change here. A breaking change is a new type (`.v2` → `.v3`) published beside
26
+ the old one; an additive change bumps `schema_version` inside the content, and readers ignore
27
+ properties they do not know.
28
+
29
+ The board-room names (`boardRoomAlias`, `boardSpeakerMxid`) are the names existing rooms have, in
30
+ the AgentPod appservice's namespace.
@@ -0,0 +1,127 @@
1
+ /**
2
+ * The way back: reading a person's answer out of an `m.room.message`, and the receipt that says the
3
+ * board accepted it.
4
+ *
5
+ * Moved from the hub's `gate-decision.ts`, `question-answer.ts`, `delivery-answer.ts` and
6
+ * `attention-answer.ts`: only the parsing and the content of the receipts. Judging an answer against
7
+ * what was posted, and acting on it, stay with the service that posted it.
8
+ *
9
+ * Every answer is an ordinary message carrying `suite_event_type` in content, not a custom type: a
10
+ * decision needs no renderer, so sending it as a message means it reads in every client. Where an
11
+ * answer must reference the message that asked, `m.relates_to` must be an **`m.reference`**:
12
+ * `m.in_reply_to` is a rendering hint every client sets when quoting, so accepting it would let an
13
+ * ordinary quoted reply decide.
14
+ */
15
+ /** The event an `m.reference` relation points at, or null. */
16
+ export declare function referenceOf(content: object): string | null;
17
+ /**
18
+ * An answer's `subject {id, digest}`, or null when it carries none or one that is not two non-empty
19
+ * strings within the gate's bound. Read off question and permission answers.
20
+ */
21
+ export declare function bindingOf(content: object): {
22
+ id: string;
23
+ digest: string;
24
+ } | null;
25
+ /** The subject an answer says it was shown: copied from the gate.v2 the person saw. */
26
+ export interface GateSubjectBinding {
27
+ id: string;
28
+ digest: string;
29
+ }
30
+ export interface ParsedGateDecision {
31
+ /** Which answer type it arrived as: `decision.v1` or `decision.v2`. */
32
+ version: 1 | 2;
33
+ gateId: string;
34
+ /**
35
+ * For v1, one of the three v1 ids. For v2, whatever the client sent: no list is kept, and the
36
+ * carrier checks it against the options it recorded for that gate.
37
+ */
38
+ optionId: string;
39
+ comment: string | null;
40
+ referencedEventId: string | null;
41
+ /** v2 only, and null when absent or malformed. */
42
+ subject: GateSubjectBinding | null;
43
+ }
44
+ /** Read a gate decision (v1 or v2) out of an `m.room.message`, or null when it is not one. */
45
+ export declare function parseGateDecision(content: unknown): ParsedGateDecision | null;
46
+ /** What a gate's receipt is built from. */
47
+ export interface GateOutcome {
48
+ gateId: string;
49
+ boardId: string;
50
+ decision: string;
51
+ /** The person's label, never an mxid; null when nobody in the room decided it. */
52
+ decidedBy: string | null;
53
+ /** The variant an approval chose, on a variant gate, when it is known. */
54
+ chosen?: {
55
+ id: string;
56
+ label: string;
57
+ } | null;
58
+ /** A held approval's release time: the receipt says it goes ahead then, unless pulled back. */
59
+ heldUntil?: string | null;
60
+ /** The gate's own event, which a card is drawn from. */
61
+ gateEventId: string;
62
+ }
63
+ /** The prose line of a gate's receipt. */
64
+ export declare function gateOutcomeBody(o: Pick<GateOutcome, "decision" | "decidedBy" | "chosen" | "heldUntil">): string;
65
+ /**
66
+ * The structured half of a gate's receipt. It points at the gate's own event rather than the prose:
67
+ * a client that finds it knows which card to close.
68
+ */
69
+ export declare function gateOutcomeContent(o: GateOutcome): Record<string, unknown>;
70
+ export interface ParsedQuestionAnswer {
71
+ elicitationId: string;
72
+ /** Null for a free-text answer. */
73
+ optionId: string | null;
74
+ /** Trimmed; null when absent or blank. */
75
+ text: string | null;
76
+ referencedEventId: string | null;
77
+ /** The binding copied from the question the person saw; absent when the answer carries none. */
78
+ subject?: {
79
+ id: string;
80
+ digest: string;
81
+ };
82
+ }
83
+ /** Read a question.answer.v2 out of an `m.room.message`, or null when it is not one. */
84
+ export declare function parseQuestionAnswer(content: unknown): ParsedQuestionAnswer | null;
85
+ /** A subject's binding as the carrier recorded it when it posted the question. */
86
+ export interface RecordedSubject {
87
+ id: string;
88
+ digest: string;
89
+ /** False (or unknown) refuses an approving answer: the card could not show it all. */
90
+ previewComplete: boolean;
91
+ /** Null when the subject named no expiry the carrier could read; the board still judges it. */
92
+ expiresAt: Date | null;
93
+ }
94
+ export type SubjectRefusal = "subject-missing" | "subject-mismatch" | "expired" | "preview-incomplete";
95
+ /**
96
+ * Why an answer to a subject-bound decision must not be carried, or null. The order: a binding
97
+ * first, then its match, then expiry, then the preview rule for approvals.
98
+ */
99
+ export declare function subjectRefusal(recorded: RecordedSubject, binding: {
100
+ id: string;
101
+ digest: string;
102
+ } | null, meaning: string | undefined, now: Date): SubjectRefusal | null;
103
+ /** What the room is told for each. */
104
+ export declare const SUBJECT_REFUSAL_TEXT: Record<SubjectRefusal, string>;
105
+ export interface ParsedDeliveryAnswer {
106
+ gateId: string;
107
+ optionId: string;
108
+ /** Trimmed; null when absent or blank. For `record_live_url`, the live link. */
109
+ text: string | null;
110
+ referencedEventId: string | null;
111
+ }
112
+ /** Read a delivery.answer.v2 out of an `m.room.message`, or null when it is not one. */
113
+ export declare function parseDeliveryAnswer(content: unknown): ParsedDeliveryAnswer | null;
114
+ /** Which wait an answer names: its board, card and wait id. */
115
+ export interface WaitKey {
116
+ boardId: string;
117
+ cardId: string;
118
+ waitId: string;
119
+ }
120
+ export interface ParsedAttentionAnswer extends WaitKey {
121
+ optionId: string;
122
+ /** Trimmed; null when absent or blank. For a resume, the instruction for the next attempt. */
123
+ text: string | null;
124
+ referencedEventId: string | null;
125
+ }
126
+ /** Read an attention.answer.v2 out of an `m.room.message`, or null when it is not one. */
127
+ export declare function parseAttentionAnswer(content: unknown): ParsedAttentionAnswer | null;
@@ -0,0 +1,269 @@
1
+ /**
2
+ * The way back: reading a person's answer out of an `m.room.message`, and the receipt that says the
3
+ * board accepted it.
4
+ *
5
+ * Moved from the hub's `gate-decision.ts`, `question-answer.ts`, `delivery-answer.ts` and
6
+ * `attention-answer.ts`: only the parsing and the content of the receipts. Judging an answer against
7
+ * what was posted, and acting on it, stay with the service that posted it.
8
+ *
9
+ * Every answer is an ordinary message carrying `suite_event_type` in content, not a custom type: a
10
+ * decision needs no renderer, so sending it as a message means it reads in every client. Where an
11
+ * answer must reference the message that asked, `m.relates_to` must be an **`m.reference`**:
12
+ * `m.in_reply_to` is a rendering hint every client sets when quoting, so accepting it would let an
13
+ * ordinary quoted reply decide.
14
+ */
15
+ import { ATTENTION_ANSWER_V2_SUITE_TYPE } from "./attention.js";
16
+ import { DELIVERY_ANSWER_V2_SUITE_TYPE } from "./delivery.js";
17
+ import { GATE_DECISION_SUITE_TYPE, GATE_DECISION_V2_SUITE_TYPE, GATE_OUTCOME_TYPE, isGateOptionId, } from "./gate.js";
18
+ import { heldTail, heldUntilOf } from "./release.js";
19
+ import { QUESTION_ANSWER_V2_SUITE_TYPE } from "./question.js";
20
+ /** The event an `m.reference` relation points at, or null. */
21
+ export function referenceOf(content) {
22
+ if (!("m.relates_to" in content))
23
+ return null;
24
+ const rel = content["m.relates_to"];
25
+ if (typeof rel !== "object" || rel === null)
26
+ return null;
27
+ if (!("rel_type" in rel) || rel.rel_type !== "m.reference")
28
+ return null;
29
+ if (!("event_id" in rel) || typeof rel.event_id !== "string")
30
+ return null;
31
+ return rel.event_id;
32
+ }
33
+ /** The longest subject id or digest read off an answer: the gate's bound. */
34
+ const SUBJECT_KEY_MAX = 512;
35
+ /**
36
+ * An answer's `subject {id, digest}`, or null when it carries none or one that is not two non-empty
37
+ * strings within the gate's bound. Read off question and permission answers.
38
+ */
39
+ export function bindingOf(content) {
40
+ if (!("subject" in content))
41
+ return null;
42
+ const s = content.subject;
43
+ if (typeof s !== "object" || s === null || !("id" in s) || !("digest" in s))
44
+ return null;
45
+ const { id, digest } = s;
46
+ if (typeof id !== "string" || typeof digest !== "string")
47
+ return null;
48
+ if (id === "" ||
49
+ digest === "" ||
50
+ id.length > SUBJECT_KEY_MAX ||
51
+ digest.length > SUBJECT_KEY_MAX) {
52
+ return null;
53
+ }
54
+ return { id, digest };
55
+ }
56
+ /** The subject binding a decision.v2 carries, or null when there is none to read. */
57
+ function subjectBinding(v) {
58
+ if (typeof v !== "object" || v === null)
59
+ return null;
60
+ if (!("id" in v) || !("digest" in v))
61
+ return null;
62
+ const { id, digest } = v;
63
+ if (typeof id !== "string" ||
64
+ id.length === 0 ||
65
+ typeof digest !== "string" ||
66
+ digest.length === 0) {
67
+ return null;
68
+ }
69
+ return { id, digest };
70
+ }
71
+ /** Read a gate decision (v1 or v2) out of an `m.room.message`, or null when it is not one. */
72
+ export function parseGateDecision(content) {
73
+ if (typeof content !== "object" || content === null)
74
+ return null;
75
+ const c = content;
76
+ const version = c.suite_event_type === GATE_DECISION_SUITE_TYPE
77
+ ? 1
78
+ : c.suite_event_type === GATE_DECISION_V2_SUITE_TYPE
79
+ ? 2
80
+ : null;
81
+ if (version === null)
82
+ return null;
83
+ if (typeof c.gate_id !== "string" || c.gate_id.length === 0)
84
+ return null;
85
+ // v1 keeps its three ids. v2 keeps no list (charter gate.v2 §2): any non-empty id is read, and
86
+ // checked against what the gate offered once the gate is known.
87
+ const optionId = c.option_id;
88
+ if (typeof optionId !== "string" || optionId.length === 0)
89
+ return null;
90
+ if (version === 1 && !isGateOptionId(optionId))
91
+ return null;
92
+ const rel = c["m.relates_to"];
93
+ let referencedEventId = null;
94
+ if (typeof rel === "object" && rel !== null) {
95
+ const r = rel;
96
+ if (r.rel_type === "m.reference" && typeof r.event_id === "string") {
97
+ referencedEventId = r.event_id;
98
+ }
99
+ }
100
+ return {
101
+ version,
102
+ gateId: c.gate_id,
103
+ optionId,
104
+ comment: typeof c.comment === "string" && c.comment.trim() !== ""
105
+ ? c.comment
106
+ : null,
107
+ referencedEventId,
108
+ subject: version === 2 ? subjectBinding(c.subject) : null,
109
+ };
110
+ }
111
+ // ── gate.outcome.v1 ──────────────────────────────────────────────────────────
112
+ /** How each decision reads in a sentence. Falls back to the option id. */
113
+ const OUTCOME_VERBS = {
114
+ approve: "Approved",
115
+ // An approval gate bound to a publishing subject offers these two instead of `approve`.
116
+ approve_automatic: "Approved for automatic delivery",
117
+ approve_manual: "Approved for manual delivery",
118
+ reject: "Rejected",
119
+ request_changes: "Changes requested",
120
+ expired: "Expired",
121
+ };
122
+ /**
123
+ * Outcomes nobody chose, said as a whole sentence. A subject-bound gate whose subject passed its
124
+ * `expires_at` is closed by the board as `expired`, and "Expired — the board has it" would read as
125
+ * though someone had answered.
126
+ */
127
+ const OUTCOME_SENTENCES = {
128
+ expired: "Expired — what this gate approves passed its expiry before anyone approved it, so it can no longer be approved here.",
129
+ };
130
+ /** How a decision reads in a sentence; an approval that chose a variant names it. */
131
+ function outcomeVerb(decision, chosen) {
132
+ const verb = OUTCOME_VERBS[decision] ?? decision;
133
+ if (!chosen || !verb.startsWith("Approved"))
134
+ return verb;
135
+ return `Approved "${chosen.label}"${verb.slice("Approved".length)}`;
136
+ }
137
+ /** The prose line of a gate's receipt. */
138
+ export function gateOutcomeBody(o) {
139
+ const verb = outcomeVerb(o.decision, o.chosen ?? null);
140
+ const heldUntil = heldUntilOf(o.heldUntil);
141
+ const tail = heldUntil ? heldTail(heldUntil) : "the board has it.";
142
+ return (OUTCOME_SENTENCES[o.decision] ??
143
+ (o.decidedBy ? `${verb} by ${o.decidedBy} — ${tail}` : `${verb} — ${tail}`));
144
+ }
145
+ /**
146
+ * The structured half of a gate's receipt. It points at the gate's own event rather than the prose:
147
+ * a client that finds it knows which card to close.
148
+ */
149
+ export function gateOutcomeContent(o) {
150
+ const heldUntil = heldUntilOf(o.heldUntil);
151
+ return {
152
+ suite_event_type: GATE_OUTCOME_TYPE,
153
+ gate_id: o.gateId,
154
+ board_id: o.boardId,
155
+ decision: o.decision,
156
+ decided_by: o.decidedBy,
157
+ ...(o.chosen
158
+ ? { chosen_variant: { id: o.chosen.id, label: o.chosen.label } }
159
+ : {}),
160
+ ...(heldUntil ? { held_until: heldUntil } : {}),
161
+ "m.relates_to": { rel_type: "m.reference", event_id: o.gateEventId },
162
+ };
163
+ }
164
+ // ── question.answer.v2 ───────────────────────────────────────────────────────
165
+ /** The longest id read off an answer; anything longer names nothing a carrier posted. */
166
+ const ID_MAX = 200;
167
+ /** Read a question.answer.v2 out of an `m.room.message`, or null when it is not one. */
168
+ export function parseQuestionAnswer(content) {
169
+ if (typeof content !== "object" || content === null)
170
+ return null;
171
+ if (!("suite_event_type" in content) ||
172
+ content.suite_event_type !== QUESTION_ANSWER_V2_SUITE_TYPE)
173
+ return null;
174
+ if (!("elicitation_id" in content))
175
+ return null;
176
+ const elicitationId = content.elicitation_id;
177
+ if (typeof elicitationId !== "string" ||
178
+ elicitationId.length === 0 ||
179
+ elicitationId.length > ID_MAX)
180
+ return null;
181
+ const optionId = "option_id" in content &&
182
+ typeof content.option_id === "string" &&
183
+ content.option_id !== ""
184
+ ? content.option_id
185
+ : null;
186
+ const text = "text" in content &&
187
+ typeof content.text === "string" &&
188
+ content.text.trim() !== ""
189
+ ? content.text.trim()
190
+ : null;
191
+ const subject = bindingOf(content);
192
+ return {
193
+ elicitationId,
194
+ optionId,
195
+ text,
196
+ referencedEventId: referenceOf(content),
197
+ ...(subject ? { subject } : {}),
198
+ };
199
+ }
200
+ /**
201
+ * Why an answer to a subject-bound decision must not be carried, or null. The order: a binding
202
+ * first, then its match, then expiry, then the preview rule for approvals.
203
+ */
204
+ export function subjectRefusal(recorded, binding, meaning, now) {
205
+ if (!binding)
206
+ return "subject-missing";
207
+ if (binding.id !== recorded.id || binding.digest !== recorded.digest)
208
+ return "subject-mismatch";
209
+ if (recorded.expiresAt !== null &&
210
+ now.getTime() >= recorded.expiresAt.getTime())
211
+ return "expired";
212
+ if (meaning === "approve" && !recorded.previewComplete)
213
+ return "preview-incomplete";
214
+ return null;
215
+ }
216
+ /** What the room is told for each. */
217
+ export const SUBJECT_REFUSAL_TEXT = {
218
+ "subject-missing": "That answer did not say which version it answers. Nothing has changed.",
219
+ "subject-mismatch": "That answer was for a different version of this decision. Open the latest one and answer again. Nothing has changed.",
220
+ expired: "This decision has expired, so it can no longer be answered. Nothing has changed.",
221
+ "preview-incomplete": "The card could not show everything being approved, so it cannot be approved from here. Open it on the board. Nothing has changed.",
222
+ };
223
+ /** Read a delivery.answer.v2 out of an `m.room.message`, or null when it is not one. */
224
+ export function parseDeliveryAnswer(content) {
225
+ if (typeof content !== "object" || content === null)
226
+ return null;
227
+ if (!("suite_event_type" in content) ||
228
+ content.suite_event_type !== DELIVERY_ANSWER_V2_SUITE_TYPE)
229
+ return null;
230
+ if (!("gate_id" in content) || !("option_id" in content))
231
+ return null;
232
+ const { gate_id: gateId, option_id: optionId } = content;
233
+ if (typeof gateId !== "string" ||
234
+ gateId.length === 0 ||
235
+ gateId.length > ID_MAX)
236
+ return null;
237
+ if (typeof optionId !== "string" || optionId.length === 0)
238
+ return null;
239
+ const text = "text" in content &&
240
+ typeof content.text === "string" &&
241
+ content.text.trim() !== ""
242
+ ? content.text.trim()
243
+ : null;
244
+ return { gateId, optionId, text, referencedEventId: referenceOf(content) };
245
+ }
246
+ const idOk = (v) => typeof v === "string" && v.length > 0 && v.length <= ID_MAX;
247
+ /** Read an attention.answer.v2 out of an `m.room.message`, or null when it is not one. */
248
+ export function parseAttentionAnswer(content) {
249
+ if (typeof content !== "object" || content === null)
250
+ return null;
251
+ if (!("suite_event_type" in content) ||
252
+ content.suite_event_type !== ATTENTION_ANSWER_V2_SUITE_TYPE)
253
+ return null;
254
+ const c = content;
255
+ if (!idOk(c.board_id) ||
256
+ !idOk(c.card_id) ||
257
+ !idOk(c.wait_id) ||
258
+ !idOk(c.option_id))
259
+ return null;
260
+ const text = typeof c.text === "string" && c.text.trim() !== "" ? c.text.trim() : null;
261
+ return {
262
+ boardId: c.board_id,
263
+ cardId: c.card_id,
264
+ waitId: c.wait_id,
265
+ optionId: c.option_id,
266
+ text,
267
+ referencedEventId: referenceOf(content),
268
+ };
269
+ }
@@ -0,0 +1,87 @@
1
+ /**
2
+ * attention.v2: a card waiting on a person — repeated failure, blocked, not authorised — in its
3
+ * board room, with what chat may do about it.
4
+ *
5
+ * charter → "Waiting cards and broker approvals reach chat" §1–2. The board pushes
6
+ * `attention.pending` when a card parks for a person for a reason other than a question or a
7
+ * review (and lists it at `GET /v1/boards/:id/attention/pending` until that wait ends). The hub
8
+ * posts it into the card's board room as one `m.room.message` / `m.text` with a real body and
9
+ * `suite_event_type: dev.superpipeline.attention.v2` — the gate.v2 message shape. There is no v1
10
+ * card to ride beside, so the prose stands alone for a client that has never heard of it.
11
+ *
12
+ * Pure; no database and no Matrix. Nothing is frozen, so there is no subject. Only the three
13
+ * answers this hub can carry are offered: resume here, resume at an earlier stage, archive.
14
+ * Forward moves are not: a move skips the stage's work and cancels its gates, which deserves the
15
+ * board.
16
+ */
17
+ import type { AttentionPendingDelivery } from "./deliveries.ts";
18
+ import { type GateOptionMeaning, type OptionInputV2 } from "./gate.ts";
19
+ export type { AttentionPendingDelivery };
20
+ export declare const ATTENTION_V2_SUITE_TYPE = "dev.superpipeline.attention.v2";
21
+ export declare const ATTENTION_ANSWER_V2_SUITE_TYPE = "dev.superpipeline.attention.answer.v2";
22
+ /**
23
+ * The receipt that closes a waiting card. Its own type rather than `gate.outcome.v1`: that one is
24
+ * keyed by `gate_id`, and a wait has no gate — borrowing the field would hand a client a gate id
25
+ * that names nothing.
26
+ */
27
+ export declare const ATTENTION_OUTCOME_TYPE = "dev.superpipeline.attention.outcome.v1";
28
+ export declare const RESUME_HERE = "resume_here";
29
+ export declare const RESUME_AT_PREFIX = "resume_at:";
30
+ export declare const ARCHIVE = "archive";
31
+ /**
32
+ * The longest instruction the board takes, in characters: a comment is bounded at 8192 bytes, and
33
+ * a character is at most three of them. Whatever a board advertises, never more.
34
+ */
35
+ export declare const ATTENTION_COMMENT_MAX = 2730;
36
+ /** One option of an attention.v2, as it rides on the Matrix wire. */
37
+ export interface AttentionOptionV2 {
38
+ id: string;
39
+ label: string;
40
+ meaning: GateOptionMeaning;
41
+ needs_comment: boolean;
42
+ input?: OptionInputV2;
43
+ }
44
+ /**
45
+ * Is this a waiting card this hub knows how to post? Used on both inbound paths — the signed push
46
+ * and the sweep's read — for the reason `isGatePending` gives: "authenticated" is not "checked".
47
+ * A card with no wait id has nothing an answer could name, so it is refused here.
48
+ */
49
+ export declare function isAttentionPending(v: unknown): v is AttentionPendingDelivery;
50
+ /** Which of the three answers an option id is, or null when it is none this hub can carry. */
51
+ export declare function attentionAction(id: string): {
52
+ kind: "resume";
53
+ toStageKey: string | null;
54
+ } | {
55
+ kind: "archive";
56
+ } | null;
57
+ /**
58
+ * The options a waiting card offers, for attention.v2, in the board's order.
59
+ *
60
+ * A resume always asks for a required text instruction, at most `ATTENTION_COMMENT_MAX`
61
+ * characters, whatever an older board said about its input: the board refuses a resume without
62
+ * one. Archive asks for nothing. Any other option is dropped — there is no call to make for it,
63
+ * and a forward move is the board's to offer, not chat's.
64
+ */
65
+ export declare function attentionOptionsV2(d: AttentionPendingDelivery): AttentionOptionV2[];
66
+ /**
67
+ * The sentence a stock client sees. It has to stand alone — no older card rides beside it — so it
68
+ * says what is wrong, what the agent said, the choices, and where they can be made.
69
+ */
70
+ export declare function attentionProseBody(d: AttentionPendingDelivery, options: AttentionOptionV2[], link?: string): string;
71
+ /** The attention.v2 content. Pinned by the shared fixture. */
72
+ export declare function attentionV2Content(d: AttentionPendingDelivery, deepLink?: string): Record<string, unknown>;
73
+ /** How a waiting card was closed: one of its answers, or on the board itself. */
74
+ export type AttentionOutcomeDecision = string;
75
+ /** The decision a settled-on-the-board card records. */
76
+ export declare const SETTLED_ELSEWHERE = "settled_elsewhere";
77
+ /**
78
+ * The structured half of a waiting card's receipt: which card, which wait, what was decided and by
79
+ * whom (the person's label; null when it was settled on the board), pointing at the card's message
80
+ * so a client knows which card to close.
81
+ */
82
+ export declare function attentionOutcomeContent(card: {
83
+ boardId: string;
84
+ cardId: string;
85
+ waitId: string;
86
+ eventId: string;
87
+ }, decision: AttentionOutcomeDecision, decidedBy: string | null): Record<string, unknown>;