@joe-broadhead/opencode-mem 0.9.5 → 0.9.14

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 (63) hide show
  1. package/CHANGELOG.md +1408 -0
  2. package/README.md +120 -41
  3. package/docs/agent-instructions.md +17 -0
  4. package/docs/agent-protocol.md +28 -27
  5. package/docs/permissions.md +150 -0
  6. package/package.json +386 -17
  7. package/skills/mem.pages/SKILL.md +40 -16
  8. package/skills/mem.sharing/SKILL.md +39 -6
  9. package/skills/mem.sources/SKILL.md +41 -10
  10. package/skills/mem.usage/SKILL.md +37 -16
  11. package/src/backend/records.js +8 -0
  12. package/src/backend/v3.js +15 -10
  13. package/src/call-shapes.js +18 -25
  14. package/src/capture-pause.js +136 -0
  15. package/src/capture.js +7 -5
  16. package/src/collector-service.js +212 -35
  17. package/src/collector.js +187 -47
  18. package/src/commands.js +37 -0
  19. package/src/compaction.js +4 -2
  20. package/src/config.js +151 -1
  21. package/src/curation.js +6 -10
  22. package/src/events.js +144 -36
  23. package/src/forget-purge.js +377 -0
  24. package/src/forgotten.js +152 -0
  25. package/src/hooks.js +9 -4
  26. package/src/index.js +5 -3
  27. package/src/permissions.js +116 -38
  28. package/src/protocol.js +32 -11
  29. package/src/recall.js +13 -1
  30. package/src/records.js +4 -1
  31. package/src/runtime.js +202 -15
  32. package/src/shapes.js +63 -0
  33. package/src/sources.js +205 -12
  34. package/src/spaces.js +58 -1
  35. package/src/spool.js +442 -64
  36. package/src/stated.js +334 -0
  37. package/src/storable.js +477 -0
  38. package/src/tools/aliases.js +36 -147
  39. package/src/tools/commitments.js +79 -13
  40. package/src/tools/held-write.js +5 -1
  41. package/src/tools/index.js +25 -43
  42. package/src/tools/ingest.js +33 -128
  43. package/src/tools/memory.js +525 -911
  44. package/src/tools/page-sections.js +147 -0
  45. package/src/tools/page.js +314 -82
  46. package/src/tools/recall-browse.js +173 -0
  47. package/src/tools/recall.js +36 -8
  48. package/src/tools/records-kit.js +2 -1
  49. package/src/tools/share.js +494 -131
  50. package/src/tools/shared.js +97 -19
  51. package/src/tools/spaces.js +194 -101
  52. package/src/tools/status.js +31 -3
  53. package/src/tools/wiki.js +5 -13
  54. package/src/util.js +10 -59
  55. package/src/views/contracts.js +258 -20
  56. package/src/views/overdue.js +1 -1
  57. package/src/views/profile.js +2 -3
  58. package/src/views/receipt.js +81 -0
  59. package/src/views/records-reads.js +545 -25
  60. package/src/views/rpc.js +41 -3
  61. package/views/memory.html +16 -3
  62. package/views/remembered.html +130 -0
  63. package/src/erase.js +0 -36
@@ -68,15 +68,81 @@ export const EVIDENCE_MAX = 3
68
68
  /** Pages one Pages answer lists, and the folders it names. */
69
69
  export const PAGES_MAX = 150
70
70
  export const FOLDERS_MAX = 50
71
+ /**
72
+ * A paged listing's cursor, as an opaque token: the records service's own
73
+ * (`records.list`'s `cursor`, a base64url pair of the last row's update time and
74
+ * id). A folder's listing reads exactly `PAGES_MAX` rows, so the token continues
75
+ * after the last row listed; a listing that had to be cut short for size says
76
+ * `more` without one (`src/views/records-reads.js`).
77
+ */
78
+ export const CURSOR_CHARS = 600
79
+ /**
80
+ * The most backlinks one listed page's count stands for. The count is read
81
+ * bounded, one `records.backlinks` read per page that asks for `BACKLINKS_MAX + 1`
82
+ * rows: a page with more says `backlinksMore`, so a listing never walks a
83
+ * page's whole backlink list (0.9.13 review).
84
+ */
85
+ export const BACKLINKS_MAX = 20
86
+ /** Backlink reads in flight at once, when a listing counts them. */
87
+ export const BACKLINKS_CONCURRENCY = 4
71
88
  /** A page's fields, outlinks and backlinks one answer carries. */
72
89
  export const FIELDS_MAX = 24
73
90
  export const LINKS_MAX = 50
74
91
  /** Versions and lineage one history answer lists. */
75
92
  export const HISTORY_MAX = 50
76
93
  export const LINEAGE_MAX = 20
94
+ /**
95
+ * The terms one answer may list (Jelly's ask 3), the most it may ask for, and
96
+ * the characters of one term; the answer itself is held under
97
+ * `TERMS_ANSWER_BYTES`, well inside Jelly's 64 KB cap.
98
+ */
99
+ export const TERMS_MAX = 500
100
+ export const TERMS_DEFAULT = 100
101
+ export const TERM_TEXT_CHARS = 80
102
+ export const TERMS_ANSWER_BYTES = 32_000
103
+ /**
104
+ * The page types a term may come from. `glossary` is a page's entries, not its
105
+ * title; the others are the page's own title (`people/ama` says "Ama Mensah").
106
+ */
107
+ export const TERM_TYPES = Object.freeze(["person", "project", "team", "glossary"])
108
+ /** Glossary pages one space's terms are read from, and their bodies read in one call. */
109
+ export const TERM_GLOSSARIES_MAX = 10
110
+
77
111
  /** The graph's caps: nodes (the records service's own cap) and edges. */
78
112
  export const GRAPH_NODES_MAX = 200
79
113
  export const GRAPH_EDGES_MAX = 600
114
+ /**
115
+ * A page's owner, as a view names one: the user id the record holds, and the
116
+ * person's name from the space's own member roster (control's `listMembers`,
117
+ * read once per call). `name` is the key Jelly's `readPage` reads (`owner.name`,
118
+ * at most 120 characters) and is the issue's `label`.
119
+ *
120
+ * **A person Memory can name, or no owner at all.** An id is not a name: control's
121
+ * member list needs the viewer role (`control/src/service/spaces.js`), so a reader
122
+ * holding only a page grant is refused it, and Jelly would print `usr_…` where a
123
+ * person's name goes. So `owner` is left out (Jelly reads absent as none) unless
124
+ * the roster names that person, and never for the routines' own user.
125
+ */
126
+ export const OWNER_ID_CHARS = 200
127
+ export const OWNER_NAME_CHARS = 120
128
+ /**
129
+ * The user the routines write as (`records/src/access.js`, `ROUTINE_USER`), which
130
+ * owns every page a routine writes. It is not a person, so a view never shows it
131
+ * as a page's owner.
132
+ */
133
+ export const ROUTINE_OWNER = "routines"
134
+ /**
135
+ * The page fields a page's own metadata may carry a review with, each a date
136
+ * (`YYYY-MM-DD`) or a date-time: `fields.reviewed` (when it was last reviewed)
137
+ * and `fields.review_due` (when it is next due). Memory keeps no review schedule
138
+ * of its own, so a page that names neither says nothing about a review. Anything
139
+ * that is not a date is not one, and the field is left out rather than guessed.
140
+ */
141
+ export const REVIEWED_FIELD = "reviewed"
142
+ export const REVIEW_DUE_FIELD = "review_due"
143
+
144
+ /** Characters of the oldest capture queue entry's time (an ISO instant). */
145
+ export const SPOOL_TIME_CHARS = 40
80
146
 
81
147
  /** Spaces one recent-memories list reads (the person's own first), and how many it reads at once. */
82
148
  export const RECENT_SPACES_MAX = 20
@@ -84,22 +150,47 @@ export const RECENT_CONCURRENCY = 4
84
150
  /** Characters of a status or a where-it-came-from line on a memory row. */
85
151
  export const STATUS_CHARS = 20
86
152
  export const SOURCE_CHARS = 200
153
+ /** Characters of the agent that wrote a memory, and of the task key it was written for. */
154
+ export const AGENT_CHARS = 80
155
+ export const TASK_CHARS = 200
156
+ /** Copies (the ids a memory supersedes) one row carries; the record's own cap is 20. */
157
+ export const COPIES_MAX = 20
87
158
  /** Memories held for review one space adds to the recent list (the newest). */
88
159
  export const HELD_MEMORIES_MAX = 50
89
160
 
90
161
  /** The most items one Inbox read carries: Jelly's own cap (`INBOX_CAP`). */
91
162
  export const INBOX_MAX = 64
163
+ /**
164
+ * Whether an Inbox item carries the session a proposal was made in.
165
+ *
166
+ * **False, and Jelly's to change.** Jelly reads an Inbox item with a strict
167
+ * schema that knows only `key, category, kind?, label, name?, line?,
168
+ * explanation?, action?, at, count?` (`PluginInboxReadItemSchema`,
169
+ * `protocol/contracts/src/plugin-inbox.ts` on its master): a field it does not
170
+ * know makes it refuse the whole Inbox, not just that item. The session is
171
+ * stored on a held write already (`source.session`, `src/tools/held-write.js`)
172
+ * and read here (`reviewWith`), so the day Jelly adds `session?` this becomes
173
+ * true and the field in `inboxOutput` beside it turns on with it.
174
+ *
175
+ * `scripts/check-jelly-master.sh` is the check: it runs the declaration against
176
+ * Jelly's own master and fails while a declared field is one it refuses.
177
+ */
178
+ export const INBOX_ITEM_SESSION = false
92
179
  /**
93
180
  * Overdue commitments one Inbox read lists, the most overdue first. With the
94
181
  * proposals (`REVIEW_MAX`) the read stays within `INBOX_MAX`.
95
182
  */
96
183
  export const OVERDUE_MAX = INBOX_MAX - REVIEW_MAX
97
184
  /**
98
- * The Jelly notice category an overdue commitment is published under. Jelly's
99
- * own words name `alert` "Security alerts" (reserved for account and device
100
- * security, which breaks through Pause) and `commitment` "Commitments", so an
101
- * overdue reminder is a `commitment`. The one line to change if Jelly asks for
102
- * another.
185
+ * The Jelly notice category an overdue commitment is published under: decided
186
+ * in issue #48, and `commitment`, not the `alert` that issue first proposed.
187
+ * Jelly's own words name `alert` "Security alerts" - reserved for account and
188
+ * device security, which breaks through the person's Pause - and `commitment`
189
+ * "Commitments". An overdue reminder is neither security nor urgent, and the
190
+ * item's own key already says `commitment:<id>`, so the category agrees with
191
+ * what the host routes. Jelly's expectations for the notice (one item per
192
+ * commitment, updated in place, cleared by a new due date) do not depend on
193
+ * the category. The one line to change if Jelly asks for another.
103
194
  */
104
195
  export const OVERDUE_CATEGORY = "commitment"
105
196
  /** The Inbox item's label (the banner's title) and its stable key prefix. */
@@ -182,6 +273,20 @@ const overviewOutput = {
182
273
  failing_since: line(40),
183
274
  /** Whether the records service answers (memories are records from 0.9); "unavailable" says the page shows `RECORDS_OFF`. */
184
275
  records: { type: "string", enum: ["ok", "unavailable"] },
276
+ /**
277
+ * The engine's own capture queue on this machine, as `mem_status` tells the
278
+ * agent: `depth` is what still waits to be sent (a capture the server has not
279
+ * taken yet), and `oldest` when the oldest of those was queued. Absent when
280
+ * the engine keeps no queue, and on a memory that cannot be used. It is the
281
+ * host engine's queue, not the speaker's, so a host several people share
282
+ * shows their queue together.
283
+ */
284
+ spool: {
285
+ type: "object",
286
+ additionalProperties: false,
287
+ required: ["depth"],
288
+ properties: { depth: { type: "integer", minimum: 0 }, oldest: line(SPOOL_TIME_CHARS) },
289
+ },
185
290
  space,
186
291
  counts: {
187
292
  type: "object",
@@ -219,6 +324,10 @@ const recentInput = viewInput({
219
324
  offset: { type: "integer", minimum: 0, maximum: RECENT_MAX_OFFSET, multipleOf: RECENT_PAGE },
220
325
  /** A space the person chose from `spaces.list`; omitted, every space they can read. */
221
326
  space: id,
327
+ /** Only what this agent wrote, as the records service names it; a trailing `*` matches every agent that starts with it. */
328
+ agent: line(200),
329
+ /** Only what was written for this task key ("checkout-v3"). */
330
+ task: line(200),
222
331
  })
223
332
 
224
333
  /** The space a row came from. */
@@ -229,6 +338,9 @@ const rowSpace = {
229
338
  properties: { id, name: line(200) },
230
339
  }
231
340
 
341
+ /** A count, the views' own: never negative. */
342
+ const integer = { type: "integer", minimum: 0 }
343
+
232
344
  const recentOutput = {
233
345
  type: "object",
234
346
  additionalProperties: false,
@@ -255,7 +367,7 @@ const recentOutput = {
255
367
  items: {
256
368
  type: "object",
257
369
  additionalProperties: false,
258
- required: ["id", "text", "type", "at", "space", "status"],
370
+ required: ["id", "text", "type", "at", "space", "status", "version", "copies"],
259
371
  properties: {
260
372
  id,
261
373
  text: line(MEMORY_TEXT_CHARS),
@@ -269,6 +381,21 @@ const recentOutput = {
269
381
  stated_by: { type: "string", enum: ["person", "agent", "inferred", "external"] },
270
382
  /** Where it came from, as "event evt_…", "turn msg-…", "routine daily@v1" and so on, where the record says. */
271
383
  source: line(SOURCE_CHARS),
384
+ /** The agent that wrote it, where the record names one. */
385
+ agent: line(AGENT_CHARS),
386
+ /** The task key it was written for, where the record names one. */
387
+ task: line(TASK_CHARS),
388
+ /** The record's version; 0 when the store gave none. */
389
+ version: integer,
390
+ /** The copies it stands for: the ids it supersedes, and the id that superseded it. Both only where they exist. */
391
+ copies: {
392
+ type: "object",
393
+ additionalProperties: false,
394
+ properties: {
395
+ supersedes: { type: "array", maxItems: COPIES_MAX, items: id },
396
+ supersededBy: id,
397
+ },
398
+ },
272
399
  },
273
400
  },
274
401
  },
@@ -362,7 +489,6 @@ const commitmentsOutput = {
362
489
 
363
490
  /* ---------------------------------------------------------------- records (0.9) */
364
491
 
365
- const integer = { type: "integer", minimum: 0 }
366
492
  const flag = { type: "boolean" }
367
493
  const list = (items, max) => ({ type: "array", maxItems: max, items })
368
494
  const object = (properties, required = Object.keys(properties)) => ({
@@ -373,6 +499,8 @@ const object = (properties, required = Object.keys(properties)) => ({
373
499
  })
374
500
  /** A space the person chose from `spaces.list`; omitted, their personal space. */
375
501
  const spaceInput = { space: id }
502
+ /** A page's owning person in its space: the record's own owner, named by the space's roster; absent when no one can be named. */
503
+ const pageOwner = object({ id: line(OWNER_ID_CHARS), name: line(OWNER_NAME_CHARS) }, ["id", "name"])
376
504
  const period = { type: "string", enum: ["day", "week", "month"] }
377
505
 
378
506
  const journalListInput = viewInput({ ...spaceInput, period })
@@ -450,6 +578,17 @@ const reviewListOutput = object({
450
578
  stated_by: { type: "string", enum: ["person", "agent", "inferred", "external", "unknown"] },
451
579
  /** Where it came from, as "event evt_…" or "routine daily@v1", where the record says. */
452
580
  source: line(SOURCE_CHARS),
581
+ /** The session that made it, where the record names one: a held write records its own. */
582
+ session: line(200),
583
+ /** The turn (the assistant message) that made it, where the record names one. */
584
+ turn: line(200),
585
+ /** Whether Memory is holding a write for this person to approve (a `team_write`), not proposing a record. */
586
+ held: flag,
587
+ /**
588
+ * A held write's own target space: where its records would be saved, which
589
+ * is not the space this review was read from. Absent for a proposed record.
590
+ */
591
+ space: rowSpace,
453
592
  /** Whether the words came from someone other than the person: the page labels it. */
454
593
  external: flag,
455
594
  evidence: list(
@@ -460,8 +599,16 @@ const reviewListOutput = object({
460
599
  proposed: line(600),
461
600
  expires: line(40),
462
601
  created: line(40),
602
+ /** #55: what accepting it would make, when the payload is a record (a share names none). */
603
+ payload: object(
604
+ {
605
+ kind: { type: "string", enum: ["memory", "page", "commitment"] },
606
+ type: line(40),
607
+ },
608
+ ["kind"],
609
+ ),
463
610
  },
464
- ["id", "status", "action", "title", "target", "reason", "stated_by", "external", "evidence", "proposed", "expires", "created"],
611
+ ["id", "status", "action", "title", "target", "reason", "stated_by", "external", "evidence", "proposed", "expires", "created", "held"],
465
612
  ),
466
613
  REVIEW_MAX,
467
614
  ),
@@ -476,14 +623,22 @@ const inboxOutput = object({
476
623
  * each and updated in place from day to day. An item that is no longer true
477
624
  * is left out, and the host drops it.
478
625
  */
479
- items: list(object({
480
- key: line(200),
481
- category: { type: "string", enum: ["request", OVERDUE_CATEGORY] },
482
- label: line(40),
483
- name: line(120),
484
- line: line(120),
485
- at: line(40),
486
- }), INBOX_MAX),
626
+ items: list(object(
627
+ {
628
+ key: line(200),
629
+ category: { type: "string", enum: ["request", OVERDUE_CATEGORY] },
630
+ label: line(40),
631
+ name: line(120),
632
+ line: line(120),
633
+ at: line(40),
634
+ /** A proposal's own type (`create`, `team_write`, `share`, …), where it has one: Jelly's `kind?` takes it. */
635
+ kind: line(40),
636
+ ...(INBOX_ITEM_SESSION
637
+ ? { session: line(200) }
638
+ : {}),
639
+ },
640
+ ["key", "category", "label", "name", "line", "at"],
641
+ ), INBOX_MAX),
487
642
  })
488
643
 
489
644
  const pagesListOutput = object({
@@ -491,9 +646,33 @@ const pagesListOutput = object({
491
646
  /** The folder listed, "" for the top. */
492
647
  folder: line(64),
493
648
  folders: list(object({ name: line(64), count: integer }), FOLDERS_MAX),
494
- pages: list(object({ path: id, title: line(200), type: line(40), updated: line(40) }), PAGES_MAX),
649
+ pages: list(
650
+ object(
651
+ {
652
+ path: id,
653
+ title: line(200),
654
+ type: line(40),
655
+ updated: line(40),
656
+ /** The page's owning person, where the page names one. */
657
+ owner: pageOwner,
658
+ /** How many pages link to this one, at most `BACKLINKS_MAX`; absent when the count could not be read. */
659
+ backlinks: integer,
660
+ /** Whether there are more backlinks than `backlinks` counts. */
661
+ backlinksMore: flag,
662
+ },
663
+ ["path", "title", "type", "updated"],
664
+ ),
665
+ PAGES_MAX,
666
+ ),
495
667
  more: flag,
496
- })
668
+ /**
669
+ * Where the next page starts, when a folder has more pages than one answer
670
+ * lists: pass it back as `cursor`. Absent when this is the last page, and when
671
+ * the answer was cut for size (then `more` is true and the rest is not read
672
+ * further: a listing that big is read folder by folder).
673
+ */
674
+ cursor: line(CURSOR_CHARS),
675
+ }, ["space", "folder", "folders", "pages", "more"])
497
676
 
498
677
  const pageRef = { ...spaceInput, path: id, id }
499
678
 
@@ -508,6 +687,22 @@ const pagesReadOutput = object({
508
687
  stated_by: line(20),
509
688
  updated: line(40),
510
689
  version: integer,
690
+ /**
691
+ * The page's owning person, where Memory can name them: the record's owner, and
692
+ * the name the space's member roster gives that id. Left out when the roster
693
+ * cannot name the person (a reader with only a page grant cannot list members),
694
+ * and for the routines' own user: an id is not a name, and Jelly's `readPage`
695
+ * draws whatever `name` says.
696
+ */
697
+ owner: pageOwner,
698
+ /** When the page was last reviewed, from its own `fields.reviewed` (a date or date-time); absent when it says none. */
699
+ reviewed: line(40),
700
+ /**
701
+ * Whether a review is due: true when the page's own `fields.review_due` (a
702
+ * date) is today or earlier. A boolean because that is what Jelly's `readPage`
703
+ * draws ("Review due"); a page that names no due date says nothing.
704
+ */
705
+ reviewDue: flag,
511
706
  fields: list(object({ name: line(40), value: line(300) }), FIELDS_MAX),
512
707
  body: line(RECORD_BODY_CHARS),
513
708
  clipped: flag,
@@ -515,7 +710,7 @@ const pagesReadOutput = object({
515
710
  outlinks: list(object({ target: line(200), title: line(200), exists: flag }), LINKS_MAX),
516
711
  backlinks: list(object({ id, path: line(200), title: line(200), type: line(40) }), LINKS_MAX),
517
712
  backlinksMore: flag,
518
- })
713
+ }, ["space", "id", "path", "kind", "type", "title", "status", "stated_by", "updated", "version", "fields", "body", "clipped", "outlinks", "backlinks", "backlinksMore"])
519
714
 
520
715
  const lineageItem = object({ id, title: line(200), status: line(20) })
521
716
 
@@ -529,8 +724,44 @@ const pagesHistoryOutput = object({
529
724
  supersededBy: list(lineageItem, LINEAGE_MAX),
530
725
  })
531
726
 
727
+ const termsInput = viewInput({
728
+ /** A space the person chose from `spaces.list`; omitted, every space they can read. */
729
+ space: id,
730
+ /** The kinds of term to list; omitted, all of `TERM_TYPES`. */
731
+ types: { type: "array", maxItems: TERM_TYPES.length, items: { type: "string", enum: [...TERM_TYPES] } },
732
+ /** The most terms to list, 10 to `TERMS_MAX`; omitted, `TERMS_DEFAULT`. */
733
+ max: { type: "integer", minimum: 10, maximum: TERMS_MAX },
734
+ })
735
+
736
+ const termsOutput = object({
737
+ /** The people and names Memory knows, in space order and then by text. */
738
+ terms: list(
739
+ object(
740
+ {
741
+ text: line(TERM_TEXT_CHARS),
742
+ /** The page type the name came from: person, project, team, or a glossary entry. */
743
+ kind: line(40),
744
+ space: rowSpace,
745
+ /** The page it is written on, for a reader that wants to open it. */
746
+ path: id,
747
+ },
748
+ ["text", "kind", "space"],
749
+ ),
750
+ TERMS_MAX,
751
+ ),
752
+ /** Whether more names are held than this answer lists. */
753
+ more: flag,
754
+ /** A space that could not be read, or was not read, and why: named, never dropped. */
755
+ incomplete: list(
756
+ object({ id, name: line(200), reason: line(200) }, ["id", "name", "reason"]),
757
+ LIST_MAX,
758
+ ),
759
+ })
760
+
532
761
  const graphInput = viewInput({
533
762
  ...pageRef,
763
+ /** A folder (a wiki): every page in it and the links between them, in one read. One of `path`, `id` or `folder`. */
764
+ folder: line(64),
534
765
  depth: { type: "integer", minimum: 1, maximum: 2 },
535
766
  max: { type: "integer", minimum: 10, maximum: GRAPH_NODES_MAX },
536
767
  /** Record types to keep (person, project, decision, …); empty keeps every type. */
@@ -665,7 +896,7 @@ export const VIEW_METHODS = Object.freeze([
665
896
  name: "pages.list",
666
897
  label: "list your pages by folder",
667
898
  permission: "mem_page",
668
- input: viewInput({ ...spaceInput, folder: line(64) }),
899
+ input: viewInput({ ...spaceInput, folder: line(64), cursor: line(CURSOR_CHARS) }),
669
900
  output: pagesListOutput,
670
901
  },
671
902
  {
@@ -696,6 +927,13 @@ export const VIEW_METHODS = Object.freeze([
696
927
  input: empty,
697
928
  output: profileReadOutput,
698
929
  },
930
+ {
931
+ name: "terms.list",
932
+ label: "list the people and names Memory knows",
933
+ permission: "mem_page",
934
+ input: termsInput,
935
+ output: termsOutput,
936
+ },
699
937
  ])
700
938
 
701
939
  // TODO(#49): no snooze action, and no other act, is declared here yet. Snoozing
@@ -118,7 +118,7 @@ export function overdueInboxItems(items, { now, zone, max = OVERDUE_MAX }) {
118
118
  if (key.length > 200) continue
119
119
  const tail = ` · ${ownerWords(found.owner)} · overdue ${found.days} ${found.days === 1 ? "day" : "days"}, due ${formatDay(found.day)}`
120
120
  const title = oneLinePlain(found.what, Math.max(10, 120 - tail.length)) || "A commitment"
121
- out.push({ key, category: OVERDUE_CATEGORY, label: OVERDUE_LABEL, name: "Memory", line: `${title}${tail}`, at })
121
+ out.push({ key, kind: "commitment", category: OVERDUE_CATEGORY, label: OVERDUE_LABEL, name: "Memory", line: `${title}${tail}`, at })
122
122
  if (out.length >= max) break
123
123
  }
124
124
  return out
@@ -34,9 +34,8 @@ const LEFT_OUT = "Some of what Memory holds about you is not shown here, to keep
34
34
  * `notes` and `incomplete` is set; only when nothing could be read at all is
35
35
  * the call a refusal, never an empty profile that looks like "nothing held".
36
36
  *
37
- * It only reads. Erasing waits for the verified-caller grant (#49): until then
38
- * `mem_forget` (a phrase, with a preview) erases from the persona and the
39
- * scenarios under the person's own permission ask.
37
+ * It only reads. Erasing a phrase, with a preview, is the console's Profile
38
+ * page (deploy/auth/console/profile-area.mjs).
40
39
  *
41
40
  * @param {{ runtime: any, personalScopes: () => Promise<Array<{ context: any, scope: any }>>, available: () => Promise<void>, describe: (error: unknown) => string }} input
42
41
  */
@@ -0,0 +1,81 @@
1
+ import { idOf, SPACE_KINDS } from "./shape.js"
2
+
3
+ /**
4
+ * The bounded metadata a write's result carries (`metadata.memoryReceipt`),
5
+ * built the way `recallResultView` builds `metadata.memoryRecall`: what a call
6
+ * saved or changed, and nothing else, so a host can count a turn's receipts
7
+ * and the `remembered` tool-result view can draw one.
8
+ *
9
+ * It names the record the call wrote (its id) and the three space fields the
10
+ * views declare, and it shows the record's title in one short line: display
11
+ * metadata for the person who made the write, never a second copy of what the
12
+ * store holds. A call that stored or changed one record answers a receipt; a
13
+ * call that changed several, or that refused before writing, answers none.
14
+ */
15
+
16
+ /** The writes that answer a receipt, in the view's own words. */
17
+ export const RECEIPT_ACTIONS = Object.freeze(["remembered", "corrected", "confirmed", "retired", "restored", "committed"])
18
+
19
+ /** The tool verb of each receipt (`mem_remember`, `mem_revise`'s actions, `mem_commitments add`). */
20
+ const VERB_ACTIONS = Object.freeze({ remember: "remembered", correct: "corrected", confirm: "confirmed", retire: "retired", restore: "restored", commit: "committed" })
21
+
22
+ /**
23
+ * The receipt for one write, named by the tool's own verb: the tools call this
24
+ * rather than building the object, so the approval-action reader
25
+ * (`scripts/approval-actions.mjs`) never mistakes a receipt's action for an
26
+ * ask.
27
+ *
28
+ * @param {string} verb remember, correct, confirm, retire, restore or commit
29
+ * @param {{ record?: any, space?: any }} write
30
+ */
31
+ export function writeReceipt(verb, { record, space } = {}) {
32
+ return receiptView({ action: VERB_ACTIONS[verb], record, space })
33
+ }
34
+
35
+ /** Characters of a receipt's title. */
36
+ export const RECEIPT_TITLE_CHARS = 200
37
+
38
+ /** One line, at most `max` characters, with no control character left in it. */
39
+ const line = (value, max) =>
40
+ String(value ?? "")
41
+ .replace(/[\u0000-\u001f\u007f]/g, " ")
42
+ .replace(/\s+/g, " ")
43
+ .trim()
44
+ .slice(0, max)
45
+
46
+ /**
47
+ * The receipt a result carries, or undefined when the call has nothing to
48
+ * report as saved (no record id, or an action the view does not know).
49
+ *
50
+ * @param {{ action?: string, record?: any, space?: { id?: string, name?: string, kind?: string } }} input
51
+ * @returns {{ v: 1, action: string, id: string, kind: string, type: string, status: string, space: { id: string, name: string, kind: string }, title: string } | undefined}
52
+ */
53
+ export function receiptView({ action, record, space } = {}) {
54
+ if (!RECEIPT_ACTIONS.includes(action)) return undefined
55
+ const id = idOf(record?.id)
56
+ if (!id) return undefined
57
+ return {
58
+ v: 1,
59
+ action,
60
+ id,
61
+ kind: line(record?.kind, 20),
62
+ type: line(record?.type, 40),
63
+ status: line(record?.status, 20),
64
+ space: {
65
+ id: idOf(space?.id) || "unknown",
66
+ name: line(space?.name, 200),
67
+ kind: SPACE_KINDS.has(space?.kind) ? space.kind : "unknown",
68
+ },
69
+ title: line(record?.title, RECEIPT_TITLE_CHARS),
70
+ }
71
+ }
72
+
73
+ /**
74
+ * A tool result with its receipt beside its text, or the result exactly as it
75
+ * is when the call has nothing to report as saved. `metadata` is the one place
76
+ * a host reads a result's display data (`memoryRecall` uses the same).
77
+ *
78
+ * @param {{ content: string, metadata?: object }} result
79
+ * @param {ReturnType<typeof receiptView>} receipt
80
+ */
81
+ export const withReceipt = (result, receipt) => (receipt ? { ...result, metadata: { ...(result.metadata ?? {}), memoryReceipt: receipt } } : result)