@mossbear/protocol 0.1.0-alpha.52 → 0.1.0-alpha.54

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.
package/dist/schemas.js CHANGED
@@ -9,7 +9,7 @@
9
9
  */
10
10
  import * as v from 'valibot';
11
11
  import { DISPLAY_NAME_REFUSED_CHARACTERS } from './bundleSlug.js';
12
- import { BUNDLE_MEMBER_TYPES, CONTEXT_ITEM_TYPES, INBOX_CONTENT_TYPES, PUSH_CONTENT_TYPES, } from './contextKinds.js';
12
+ import { BUNDLE_MEMBER_TYPES, CONTEXT_ITEM_TYPES, CONTEXT_ITEM_TYPE_FILTER_VALUES, INBOX_CONTENT_TYPES, PUSH_CONTENT_TYPES, } from './contextKinds.js';
13
13
  // ---------------------------------------------------------------------------
14
14
  // Core enum schemas
15
15
  // ---------------------------------------------------------------------------
@@ -792,7 +792,7 @@ export const CreateBundleResponseSchema = v.object({
792
792
  // part of identity, so detach must carry it too — an itemId alone cannot
793
793
  // address a `guide` membership.
794
794
  //
795
- // A membership kind is not a `content_type` narrowing — it says which table
795
+ // A membership kind is not a content-kind narrowing — it says which table
796
796
  // `item_id` points at — so it derives from `BUNDLE_MEMBER_TYPES` rather than
797
797
  // from the content-kind table beside it. See that constant for why the two axes
798
798
  // stay named apart.
@@ -846,12 +846,21 @@ export const DeleteBundleResponseSchema = v.object({
846
846
  // Context item + inbox schemas (context-layer-mcp-inbox-plan.md — Phase 1a)
847
847
  // ---------------------------------------------------------------------------
848
848
  // The `type` of an item returned to an agent. A `guide` is a canonical guide
849
- // row; the rest are guide_files rows (documents, references, assets).
849
+ // row; the rest are guide_files rows (plain content items and assets).
850
850
  //
851
851
  // Derived, like the two narrowings below, from `contextKinds.ts` — the one
852
852
  // table that says which kinds exist and what each may do. The values and their
853
853
  // order are unchanged; `contextKinds.test.ts` pins that.
854
854
  export const ContextItemTypeSchema = v.picklist(CONTEXT_ITEM_TYPES);
855
+ /**
856
+ * What a `?types=` filter parses.
857
+ *
858
+ * Equal to {@link ContextItemTypeSchema}'s values again: it was briefly wider
859
+ * so a filter written against the pre-rename vocabulary returned the kind
860
+ * those rows became rather than an empty page, and that window closed with
861
+ * the release that moved the CLI's own vocabulary onto `content`.
862
+ */
863
+ export const ContextItemTypeFilterSchema = v.picklist(CONTEXT_ITEM_TYPE_FILTER_VALUES);
855
864
  // The contentType a caller may *create* through the context layer. `guide` is
856
865
  // deliberately absent, and stays absent after slice 2b-B made guides pushable:
857
866
  // this schema is reached only by POST (create) and the MCP `push_context`
@@ -894,11 +903,158 @@ export const GuideAliasSchema = v.object({
894
903
  root: GuideDiscoveryRootSchema,
895
904
  path: SafeRelativePosixPathSchema,
896
905
  });
906
+ /**
907
+ * The markers every untrusted block in a response is wrapped in, plus a
908
+ * statement of what they mean.
909
+ *
910
+ * Generated per response from the content itself, so no marker-like text
911
+ * inside a block can end it early — a property `deriveDelimiterToken` checks
912
+ * rather than assumes.
913
+ *
914
+ * Named for the guide-history response it was written for and shared by every
915
+ * payload that places somebody else's words in front of an agent: a grade's
916
+ * reasoning, and now an item's notes. One marker scheme, not one per payload —
917
+ * a second scheme is a second thing a reader has to be taught to respect.
918
+ * Declared here, above its first user, rather than beside that response.
919
+ */
920
+ export const GuideHistoryUntrustedSchema = v.object({
921
+ token: NonEmptyStringSchema,
922
+ startMarker: NonEmptyStringSchema,
923
+ endMarker: NonEmptyStringSchema,
924
+ note: v.string(),
925
+ });
926
+ /**
927
+ * How many open notes one item carries on the wire, newest first.
928
+ *
929
+ * A wire bound, not a product limit: the write side refuses the note that
930
+ * would exceed it *by name* (see the dashboard's note mutator), so this cap is
931
+ * never the thing that silently drops a request a person left.
932
+ */
933
+ export const MAX_ITEM_NOTES_ON_WIRE = 20;
934
+ /**
935
+ * One note a **person** left about a context item, riding the item it is about.
936
+ *
937
+ * A note is not an item: it is not a member, not projected, not versioned and
938
+ * not capturable. It travels on the item so that it inherits every delivery
939
+ * decision the item already went through — workspace scope, the archived drop,
940
+ * the response limit, the subscriber's mute — rather than restating them.
941
+ *
942
+ * **Every `body` here is already wrapped in the response's untrusted markers**
943
+ * (`ContextItemsResponseSchema.untrusted`). A reader emits the bytes as it
944
+ * received them and never re-wraps them: the markers are derived against the
945
+ * bodies the server sent, so a second wrapping cannot claim the same guarantee.
946
+ */
947
+ export const ContextItemNoteSchema = v.object({
948
+ id: NonEmptyStringSchema,
949
+ /** The note's text, already wrapped in the response's untrusted markers. */
950
+ body: v.string(),
951
+ /** The author's display name as the workspace shows it, or null. Never an email. */
952
+ authorName: v.nullable(v.string()),
953
+ /** ISO timestamp, machine format. */
954
+ createdAt: v.string(),
955
+ /** The item's content version the note was written against. */
956
+ itemVersion: v.number(),
957
+ /** True when the item's current version is greater than `itemVersion`. */
958
+ itemChangedSince: v.boolean(),
959
+ /**
960
+ * How many agent reads were handed this note **before** this one — so a
961
+ * note reaching an agent for the first time reports `0`.
962
+ *
963
+ * It is the stored count as it read at the moment the response was built;
964
+ * the serve this response *is* has not been counted yet. Excluded rather
965
+ * than included because the count is recorded best-effort: a response that
966
+ * claimed to include itself would be wrong whenever that record failed, and
967
+ * a number that is sometimes off by one is worse than one that is
968
+ * consistently the prior total.
969
+ *
970
+ * So `deliveredCount > 0` means an earlier read was handed this note, and
971
+ * `0` means this read is the first. Neither says a model took it in — only
972
+ * that the server handed it over.
973
+ */
974
+ deliveredCount: v.number(),
975
+ /**
976
+ * This note's thread root — its own id for every note written today, since
977
+ * no reply exists yet. Ignorable now; load-bearing once a reply is a second
978
+ * row with a different id here. It is on the wire from the first response
979
+ * because the wire contract is consumed by installed CLI versions: reshaping
980
+ * a flat `notes` array into threads-of-notes later would be a breaking
981
+ * change, while a field today's readers ignore costs them nothing.
982
+ */
983
+ threadId: NonEmptyStringSchema,
984
+ /**
985
+ * Always `null` today — no reply exists to point at. Present now so an older
986
+ * reader meeting a future response that carries real replies degrades to
987
+ * "a flat list of notes" rather than failing to parse.
988
+ */
989
+ replyToId: v.nullable(NonEmptyStringSchema),
990
+ });
991
+ const MAX_SOURCE_BRANCH_LENGTH = 255;
992
+ /**
993
+ * The revision published bytes were read from — 40 hex characters for a sha1
994
+ * repository, 64 for a sha256 one. Lowercase only, because that is what
995
+ * `git rev-parse` emits and accepting both spellings would make two rows naming
996
+ * one commit compare unequal.
997
+ *
998
+ * Deliberately not an abbreviation: a short sha is ambiguous by construction and
999
+ * this is the field a subscriber uses to answer "what did I get".
1000
+ */
1001
+ export const CommitShaSchema = v.pipe(v.string(), v.regex(/^[0-9a-f]{40}$|^[0-9a-f]{64}$/, 'commitSha must be 40 or 64 lowercase hex characters'));
1002
+ /**
1003
+ * Where a **git-owned** artifact comes from (`artifact-ownership-and-delivery-plan.md`
1004
+ * → slice 1). Its presence is what says git owns the artifact: the working copy
1005
+ * and the commit are the authority, and Mossbear distributes the committed
1006
+ * revision rather than a second independently editable copy.
1007
+ *
1008
+ * **One object rather than three sibling keys on the item**, because the legal
1009
+ * states are "all of it" or "none of it" and a nested object makes the absent
1010
+ * state a single missing key instead of three that a writer could half-fill.
1011
+ * The two fields here are the two that cannot be half-filled: `branch` is the
1012
+ * one optional member, so an object with a repo and a revision is always a
1013
+ * complete source.
1014
+ *
1015
+ * **The source path is not here.** The item's own `path` is the repo-relative
1016
+ * path, and it is a required member of the subset — but the requirement is held
1017
+ * by the database, not restated here; see `gitSource` on `ContextItemSchema`
1018
+ * below for why a wire rule that looked identical would not be. What matters at
1019
+ * this layer is that there is only ever one path, never a source path beside a
1020
+ * projection path that publication and delivery could disagree about.
1021
+ */
1022
+ export const GitSourceSchema = v.object({
1023
+ /**
1024
+ * The committed `project.id` of the source repository — the same id space as
1025
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
1026
+ * says which repo an item is materialized into and is stamped onto
1027
+ * Mossbear-owned rows too, this one says who may edit it.
1028
+ */
1029
+ projectId: ProjectIdSchema,
1030
+ commitSha: CommitShaSchema,
1031
+ /**
1032
+ * The branch the publishing commit was on. **The one optional member**:
1033
+ * publication is not restricted by branch, so this is recorded so a subscriber
1034
+ * can see what they got, and a detached HEAD has none to record.
1035
+ */
1036
+ branch: v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(MAX_SOURCE_BRANCH_LENGTH))),
1037
+ });
897
1038
  export const ContextItemSchema = v.object({
898
1039
  id: v.string(),
899
1040
  type: ContextItemTypeSchema,
900
1041
  name: v.string(),
901
- contentType: v.string(),
1042
+ /**
1043
+ * The stored `(role, format)` pair, as two bare nullable strings.
1044
+ *
1045
+ * **Both are deliberately unenumerated.** A client switches on one value it
1046
+ * cares about — `role === 'criteria'` is how a rubric is told from ordinary
1047
+ * prose, which `type` cannot say because a rubric serializes as a `document` —
1048
+ * and a server that adds a fourth role or a fifth format must not break a
1049
+ * client that has never heard of it. Narrowing them here would make every such
1050
+ * addition a breaking wire change for no reader's benefit.
1051
+ *
1052
+ * Null on exactly the rows that carry no content: a tombstone, and an alias.
1053
+ * A `guide` item has no pair at all — it is a different table — and reports
1054
+ * both as null.
1055
+ */
1056
+ role: v.nullable(v.string()),
1057
+ format: v.nullable(v.string()),
902
1058
  content: v.nullable(v.string()),
903
1059
  origin: v.optional(v.nullable(v.string())),
904
1060
  // Monotonic content version of the underlying doc (guide_files), surfaced so a
@@ -974,10 +1130,190 @@ export const ContextItemSchema = v.object({
974
1130
  // a server predating this field says and what an unaliased guide says. Both
975
1131
  // read the same way — derive nothing — so the CLI needs no third case.
976
1132
  aliases: v.optional(v.pipe(v.array(GuideAliasSchema), v.maxLength(MAX_GUIDE_ALIASES))),
1133
+ /**
1134
+ * Open notes a person left about this item, newest first.
1135
+ *
1136
+ * Optional, and absent rather than empty when there are none — the same rule
1137
+ * `aliases` and `projectId` follow above, and for the same reason: an older
1138
+ * reader against a newer server ignores the key, and a newer reader against
1139
+ * an older server reads "no notes" instead of failing.
1140
+ *
1141
+ * **Absence is not a verdict.** No notes here means none were served on this
1142
+ * item in this response — not that nobody has anything to say about it.
1143
+ */
1144
+ notes: v.optional(v.pipe(v.array(ContextItemNoteSchema), v.maxLength(MAX_ITEM_NOTES_ON_WIRE))),
977
1145
  updatedAt: v.string(),
1146
+ /**
1147
+ * Present iff this artifact is owned by git. Absent means Mossbear owns it
1148
+ * and it is editable in the dashboard.
1149
+ *
1150
+ * **Optional, and absence is not yet a verdict.** Nothing writes this before
1151
+ * `publish` ships, so today every item omits it, and the existing bundle-home
1152
+ * rule — a bundle may name one repo as its only writer, and the server
1153
+ * refuses every other writer by name — is what still protects items a repo
1154
+ * already owns. A reader must not treat an absent `gitSource` as permission
1155
+ * to publish back.
1156
+ *
1157
+ * **Optional *and* nullable, like every other late-added column on this item.**
1158
+ * A serializer that maps the columns straight through emits `null` for a
1159
+ * Mossbear-owned row, and a key that only accepted `undefined` would throw on
1160
+ * the whole response rather than on the one item — `parseContextItemsResponse`
1161
+ * parses a pull as a batch. Both spellings read the same way: no git source.
1162
+ *
1163
+ * **`path` is the third required member of the subset and is not re-checked
1164
+ * here.** The database holds that invariant
1165
+ * (`guide_files_git_source_subset`), and a wire rule that looked identical
1166
+ * would in fact be stricter: `path` is serialized through a scope helper that
1167
+ * emits `null` for a path this schema cannot parse, so a single such row would
1168
+ * fail every other item in the same pull. A git-owned item that arrives
1169
+ * without a usable path is a broken item, not a broken response.
1170
+ */
1171
+ gitSource: v.optional(v.nullable(GitSourceSchema)),
1172
+ /**
1173
+ * This artifact is a **tombstone**: the repository that publishes it deleted
1174
+ * the file, so what the item still carries is the last revision rather than a
1175
+ * current one (`artifact-ownership-and-delivery-plan.md` → D28).
1176
+ *
1177
+ * **It is still delivered, and that is deliberate.** Dropping the item from
1178
+ * the response would say the same thing more quietly and cost two things
1179
+ * worth more than the byte: the publishing repo would lose the id it needs to
1180
+ * republish the path in place — re-adding a deleted file would create a
1181
+ * second artifact at the same path rather than a new revision of the one
1182
+ * that is there — and a reader would be left unable to tell a removal from
1183
+ * a bundle it has stopped being able to see. What the flag asks of a client
1184
+ * is one thing: do not materialize it. A file left at a discovery root keeps
1185
+ * feeding deleted guidance into every agent that reads that repo, which is
1186
+ * the failure the decision exists to stop.
1187
+ *
1188
+ * **Optional, and absent means an ordinary artifact.** A client that has
1189
+ * never heard of it behaves as it always did — it keeps the last published
1190
+ * revision on disk, which is the retain behaviour this replaces rather than a
1191
+ * new failure. That is what makes the server safe to ship first.
1192
+ *
1193
+ * `literal(true)` rather than a boolean: `removed: false` would be a second
1194
+ * spelling of absence, and an artifact that came back is content again rather
1195
+ * than a tombstone that says no.
1196
+ */
1197
+ removed: v.optional(v.literal(true)),
978
1198
  });
979
1199
  export const ContextItemsResponseSchema = v.object({
980
1200
  items: v.array(ContextItemSchema),
1201
+ /**
1202
+ * The markers every note `body` in this response is wrapped in, plus a
1203
+ * statement of what they mean. Present exactly when at least one item
1204
+ * carries a note — there is nothing to delimit otherwise.
1205
+ */
1206
+ untrusted: v.optional(v.nullable(GuideHistoryUntrustedSchema)),
1207
+ });
1208
+ /**
1209
+ * How many bundles one notes read may name.
1210
+ *
1211
+ * A repo's delivery set is the union of its committed subscriptions and the
1212
+ * reader's account ones, so this bounds a request, not a product limit: a
1213
+ * reader subscribing to more bundles than this asks in two calls rather than
1214
+ * losing the tail silently.
1215
+ */
1216
+ export const MAX_NOTE_BUNDLE_IDS = 100;
1217
+ /**
1218
+ * How many times one subscriber is told, in one repo, that a given note is
1219
+ * waiting before the hook falls silent about it.
1220
+ *
1221
+ * **A cap on the interruption, never on the note.** After it is reached the
1222
+ * note is still open, still on the item page, and still returned in full by
1223
+ * the on-demand read — it simply stops being announced in front of the first
1224
+ * turn of every session. So silence here means "nothing new to interrupt you
1225
+ * about", never "nobody left anything".
1226
+ *
1227
+ * Three rather than one, for the reason the announcement exists: the first
1228
+ * session in a repo is often doing unrelated work, so a one-shot announcement
1229
+ * would routinely spend itself on the session least likely to act. Three is a
1230
+ * judgement, named so replacing it is one edit — the same discipline the live
1231
+ * session window is held to.
1232
+ */
1233
+ export const MAX_NOTE_ANNOUNCEMENTS_PER_REPO = 3;
1234
+ /**
1235
+ * Ask which notes are waiting for this reader in this repo, and be counted as
1236
+ * told.
1237
+ *
1238
+ * **A write, because being told is a fact the server has to keep.** The count
1239
+ * cannot be `item_notes.delivered_count` — that is one global number across
1240
+ * every subscriber and every repo, so one reader's fill of a note would
1241
+ * silence it for everyone — and it cannot live in the checkout, because the
1242
+ * disposable environments this exists for rebuild the clone every session and
1243
+ * a counter there resets with it, announcing every unresolved note as new
1244
+ * forever.
1245
+ */
1246
+ export const AnnounceItemNotesRequestSchema = v.object({
1247
+ /**
1248
+ * The repo, as its committed config declares it. Required: it is the scope
1249
+ * the count is kept under, and a request with nothing to key on could only
1250
+ * be answered by an uncapped announcement — which is the repeating broadcast
1251
+ * this route exists to end.
1252
+ */
1253
+ projectId: ProjectIdSchema,
1254
+ /**
1255
+ * The bundles this repo receives — the union the caller already resolved.
1256
+ *
1257
+ * Sent rather than derived, because only half of it is the server's to know:
1258
+ * a repo-scoped subscription lives in the committed config and travels by
1259
+ * `git clone`. Declaring a bundle grants nothing: every one of them is still
1260
+ * filtered by the caller's own workspace membership.
1261
+ */
1262
+ bundleIds: v.pipe(v.array(NonEmptyStringSchema), v.maxLength(MAX_NOTE_BUNDLE_IDS)),
1263
+ });
1264
+ /**
1265
+ * What an announcement answers: how many notes are waiting, and how many of
1266
+ * them this call was counted as announcing.
1267
+ *
1268
+ * **Two numbers because they answer two questions and a reader needs both.**
1269
+ * `open` is the true state of this repo's notes and is what a caller shows a
1270
+ * person — a number that is sometimes a subset of the truth would be worse
1271
+ * than the silence it replaced. `announced` is how many of those were still
1272
+ * under the cap, and it is the one that decides whether to speak at all: zero
1273
+ * means this reader has already been told about every one of them as often as
1274
+ * the cap allows.
1275
+ */
1276
+ export const AnnounceItemNotesResponseSchema = v.object({
1277
+ /** Open, unmuted notes about the items these bundles deliver to this reader. */
1278
+ open: v.pipe(v.number(), v.integer(), v.minValue(0)),
1279
+ /** How many of those were under the cap and have now been counted as announced. */
1280
+ announced: v.pipe(v.number(), v.integer(), v.minValue(0)),
1281
+ });
1282
+ /**
1283
+ * One note on the on-demand read, with the item it is about named on the note.
1284
+ *
1285
+ * The item is named here rather than the notes riding an item, because this
1286
+ * read answers "what has been left for me" rather than "what is in this
1287
+ * bundle": there is no item payload to hang them off, and an agent that has to
1288
+ * ask for every item to find out whether one carries a note is the round trip
1289
+ * the announcement exists to avoid.
1290
+ */
1291
+ export const ItemNoteWithSubjectSchema = v.object({
1292
+ ...ContextItemNoteSchema.entries,
1293
+ /** The item the note is about, as the wire names it. */
1294
+ itemName: v.string(),
1295
+ /** The item's declared repo-relative path, or null when it has none. */
1296
+ itemPath: v.nullable(v.string()),
1297
+ });
1298
+ /**
1299
+ * Every open note waiting for this reader across the bundles they named.
1300
+ *
1301
+ * **This read is a delivery and is counted as one**, exactly as notes riding
1302
+ * an item are: a body reached an agent. What it is *not* is an announcement —
1303
+ * nothing here touches the per-repo announcement count, so asking to read your
1304
+ * notes never spends the interruptions the hook is allowed.
1305
+ *
1306
+ * **Never capped.** The announcement cap governs whether a hook speaks; a
1307
+ * reader who asked is owed every open note, and hiding one here would retire a
1308
+ * person's request without anybody deciding to.
1309
+ */
1310
+ export const ItemNotesResponseSchema = v.object({
1311
+ notes: v.array(ItemNoteWithSubjectSchema),
1312
+ /**
1313
+ * The markers every `body` above is wrapped in, plus a statement of what
1314
+ * they mean. Present exactly when at least one note came back.
1315
+ */
1316
+ untrusted: v.optional(v.nullable(GuideHistoryUntrustedSchema)),
981
1317
  });
982
1318
  /** Max number of context item ids a push may cite as its transform sources. */
983
1319
  export const MAX_TRANSFORM_SOURCE_IDS = 100;
@@ -1049,6 +1385,28 @@ export const PushContextRequestSchema = v.object({
1049
1385
  * a member of the bundle's workspace to reach this route at all.
1050
1386
  */
1051
1387
  projectId: v.optional(v.string()),
1388
+ /**
1389
+ * Where the committed bytes in `content` came from, when this write is a
1390
+ * publication (`artifact-ownership-and-delivery-plan.md` → slice 3). Present
1391
+ * means git owns the resulting artifact: the commit is the authority and
1392
+ * Mossbear distributes the revision rather than keeping a second editable
1393
+ * copy.
1394
+ *
1395
+ * **Sending it is a claim about provenance, not an authorization.** The
1396
+ * server still answers who may write here from bundle membership and the
1397
+ * bundle's declared home, exactly as it does for `projectId` above; what this
1398
+ * adds is the revision the bytes were read from, so a subscriber can answer
1399
+ * "what did I get".
1400
+ *
1401
+ * **`path` is required alongside it and the route enforces that**, because
1402
+ * the database will: `guide_files_git_source_subset` admits only "repo id +
1403
+ * path + sha all present" or the whole group absent, so a publication that
1404
+ * named no path would fail at insert time with a constraint error instead of
1405
+ * a sentence. Refused in the route rather than restated as a wire rule, for
1406
+ * the reason `ContextItemSchema.gitSource` gives — a path this schema cannot
1407
+ * parse is one item's problem, not the response's.
1408
+ */
1409
+ gitSource: v.optional(GitSourceSchema),
1052
1410
  });
1053
1411
  export const PushContextResponseSchema = v.object({
1054
1412
  item: ContextItemSchema,
@@ -1101,6 +1459,43 @@ export const UpdateContextItemRequestSchema = v.object({
1101
1459
  // nothing to clear on a create, so `[]` there would only be a second way to
1102
1460
  // say "no sources" alongside omitting the field.
1103
1461
  sourceItemIds: v.optional(UpdatableSourceItemIdsSchema),
1462
+ /**
1463
+ * The revision this update's bytes were read from — same meaning as on
1464
+ * `PushContextRequestSchema` above, and the field that makes a republication
1465
+ * advance an artifact's provenance rather than leave it pointing at the
1466
+ * commit it was first published from.
1467
+ *
1468
+ * **Omitted leaves the stored group alone; it never clears it.** An update
1469
+ * that says nothing about provenance is a name or body edit, not a claim that
1470
+ * the artifact stopped being git-owned — and an absent key that silently
1471
+ * un-owned a row would hand a subscriber write access by omission, which is
1472
+ * the failure the whole ownership model exists to prevent. Ownership is given
1473
+ * up by promotion, not by a missing field.
1474
+ */
1475
+ gitSource: v.optional(GitSourceSchema),
1476
+ /**
1477
+ * Tombstone this artifact: the commit that published it has since deleted the
1478
+ * file, so the revision stops being delivered while the row and its version
1479
+ * history stay where they are.
1480
+ *
1481
+ * **A verb, not a column state**, the same shape the dashboard's own removal
1482
+ * takes (`~/zero/mutators.ts` → `guideFiles.update`'s `removed`). There is no
1483
+ * writable field here that a removal and an ordinary edit could disagree
1484
+ * about, and `literal(true)` is what keeps `removed: false` from reading as a
1485
+ * request to bring something back — un-removing is republishing, which is an
1486
+ * ordinary content write.
1487
+ *
1488
+ * **`gitSource` is required alongside it and the route enforces that.** A
1489
+ * tombstone's whole claim is *which revision removed the file*: without one
1490
+ * the row would say an artifact stopped being delivered and be unable to say
1491
+ * why, which is the silent withdrawal this field exists to replace. That also
1492
+ * keeps the only writer of a removal here the publication path — this is not
1493
+ * a general delete verb for the context layer.
1494
+ *
1495
+ * **Never sent with `content`.** A removal has no bytes; a body carrying both
1496
+ * is two answers to one question and the route refuses it rather than picking.
1497
+ */
1498
+ removed: v.optional(v.literal(true)),
1104
1499
  });
1105
1500
  export const UpdateContextItemResponseSchema = v.object({
1106
1501
  item: ContextItemSchema,
@@ -1170,6 +1565,9 @@ export const InboxCaptureRequestSchema = v.object({
1170
1565
  * from it. The one in-repo caller is the dashboard composer.)
1171
1566
  */
1172
1567
  id: v.optional(CaptureIdSchema),
1568
+ // Optional for v1 compatibility. Missing and null both mean Inbox; a string
1569
+ // names the bundle the original request must remain tied to on every retry.
1570
+ bundleId: v.optional(v.nullable(v.string())),
1173
1571
  contentType: InboxContentTypeSchema,
1174
1572
  content: ContextContentSchema,
1175
1573
  name: v.optional(ContextItemNameSchema),
@@ -1181,7 +1579,9 @@ export const InboxItemSchema = v.object({
1181
1579
  id: v.string(),
1182
1580
  type: ContextItemTypeSchema,
1183
1581
  name: v.string(),
1184
- contentType: v.string(),
1582
+ /** The stored pair, as {@link ContextItemSchema} carries it. */
1583
+ role: v.nullable(v.string()),
1584
+ format: v.nullable(v.string()),
1185
1585
  content: v.nullable(v.string()),
1186
1586
  source: v.optional(v.nullable(v.string())),
1187
1587
  // Monotonic content version of the underlying doc, mirroring
@@ -1634,7 +2034,7 @@ export const MAX_SYNC_AUX_BATCH = 100;
1634
2034
  */
1635
2035
  export const MAX_RULE_MANIFEST_FILES = 500;
1636
2036
  /**
1637
- * A rule file observed on disk in the repo `mossbear sync` ran from.
2037
+ * A rule file observed on disk in the repo `mossbear report` ran from.
1638
2038
  *
1639
2039
  * `path` is relative to that repo root, in exactly the form `payloadPath`
1640
2040
  * takes at import time (`packages/cli/src/rules/discover.ts`), so
@@ -1768,18 +2168,18 @@ export const SessionSelfReportSchema = v.object({
1768
2168
  /**
1769
2169
  * The CLI entry point a sync came from, when that entry point is a hook.
1770
2170
  *
1771
- * **One member on purpose.** `mossbear session-start` is the command
2171
+ * **One member on purpose.** `mossbear refresh` is the command
1772
2172
  * `mossbear init` registers as the `SessionStart` hook, and nothing else runs
1773
2173
  * it — so a request carrying this value is proof that the hooks a project was
1774
2174
  * set up with are firing, which is the one onboarding fact the dashboard could
1775
2175
  * not previously observe. The other two hooks (`Stop`, `SessionEnd`) both run
1776
- * `mossbear sync`, which is also the command a person types by hand; their
2176
+ * `mossbear report`, which is also the command a person types by hand; their
1777
2177
  * requests are therefore indistinguishable from a manual sync and are
1778
2178
  * deliberately not named here rather than guessed at.
1779
2179
  *
1780
2180
  * Optional on the envelope, and its absence means only "not known to be a
1781
2181
  * session-start sync" — never "no hooks". A CLI predating this field sends
1782
- * none, and so does every ordinary `mossbear sync`.
2182
+ * none, and so does every ordinary `mossbear report`.
1783
2183
  *
1784
2184
  * A user can pass the flag that sets this by hand. That is not a privilege
1785
2185
  * boundary: the value is scoped to the caller's own account and the only thing
@@ -1806,12 +2206,12 @@ export const DashboardSyncRequestSchema = v.object({
1806
2206
  cliVersion: v.optional(CliVersionSchema),
1807
2207
  /**
1808
2208
  * Sessions whose agent context has ended, named by the CLI's `SessionEnd`
1809
- * hook (`mossbear sync --session-complete`) — never by its per-turn `Stop` hook.
2209
+ * hook (`mossbear complete`) — never by its per-turn `Stop` hook.
1810
2210
  * The server closes those sessions' runs; every other session in the payload
1811
2211
  * stays open.
1812
2212
  *
1813
2213
  * Session-keyed rather than a single envelope-level boolean, because one
1814
- * `mossbear sync` uploads every session with pending actions and chunks them
2214
+ * `mossbear report` uploads every session with pending actions and chunks them
1815
2215
  * across several requests. A boolean would close sessions that merely had a
1816
2216
  * backlog, and would close a session before the batches carrying the rest of
1817
2217
  * its actions had arrived. The CLI therefore names a session here only on the
@@ -1953,7 +2353,7 @@ export const ActionEntrySchema = v.object({
1953
2353
  * This is what makes a skill load ride the action stream instead of the
1954
2354
  * transcript. `skill_usage` — the other place a loaded skill name is
1955
2355
  * recorded — is populated by `extractSessionUsage`, which returns empty unless
1956
- * `mossbear sync` is given `--transcripts-dir`, and the hook `mossbear init`
2356
+ * `mossbear report` is given `--transcripts-dir`, and the hook `mossbear init`
1957
2357
  * installs never passes one. So the transcript path has no data in a normal
1958
2358
  * session, while an action definitionally syncs.
1959
2359
  */
@@ -1966,7 +2366,7 @@ export const ActionEntrySchema = v.object({
1966
2366
  * (`packages/cli/src/action-queue.ts`) builds the wire payload field by
1967
2367
  * field and does not include this one; transcripts are disclosed as
1968
2368
  * local-only in the dashboard's own privacy disclosure, and a path is still
1969
- * a fact about the user's filesystem. It exists so `mossbear sync` can find
2369
+ * a fact about the user's filesystem. It exists so `mossbear report` can find
1970
2370
  * the transcript for a session it is already uploading without searching for
1971
2371
  * it.
1972
2372
  *
@@ -2326,20 +2726,6 @@ export const GuideHistoryGuideSchema = v.object({
2326
2726
  path: v.nullable(SafeRelativePosixPathSchema),
2327
2727
  root: v.nullable(GuideDiscoveryRootSchema),
2328
2728
  });
2329
- /**
2330
- * The markers every `reasoning` block in this response is wrapped in, plus a
2331
- * statement of what they mean.
2332
- *
2333
- * Generated per response from the content itself, so no marker-like text inside
2334
- * a block can end it early — a property `deriveDelimiterToken` checks rather
2335
- * than assumes.
2336
- */
2337
- export const GuideHistoryUntrustedSchema = v.object({
2338
- token: NonEmptyStringSchema,
2339
- startMarker: NonEmptyStringSchema,
2340
- endMarker: NonEmptyStringSchema,
2341
- note: v.string(),
2342
- });
2343
2729
  export const GuideHistoryResponseSchema = v.object({
2344
2730
  guide: GuideHistoryGuideSchema,
2345
2731
  /** The wording the window is about, or null when the guide has no revision identity. */
@@ -2369,7 +2755,7 @@ export const GuideHistoryResponseSchema = v.object({
2369
2755
  // ---------------------------------------------------------------------------
2370
2756
  /**
2371
2757
  * One run's grade, read by `mossbear sessions` and by the one line
2372
- * `mossbear session-start` prints when the previous session violated a guide.
2758
+ * `mossbear sessions last` prints when the previous session violated a guide.
2373
2759
  *
2374
2760
  * The loop this closes: a session ends with "synced N item(s) to the
2375
2761
  * dashboard." and the verdict exists only in the dashboard. This is the read
@@ -2383,7 +2769,7 @@ export const GuideHistoryResponseSchema = v.object({
2383
2769
  * How the caller names the run. Exactly one of the two.
2384
2770
  *
2385
2771
  * The CLI only ever knows an *agent session* id — the `SessionEnd` hook
2386
- * payload's `session_id`, which `mossbear sync --session-complete` reports — so
2772
+ * payload's `session_id`, which `mossbear complete` reports — so
2387
2773
  * the `agent_session` form is the one it uses. The session id is for a caller
2388
2774
  * that already has one, from a dashboard URL say. Both are opaque and both
2389
2775
  * reach a SQL predicate, so they are bounded and shape-checked here.
@@ -2476,65 +2862,6 @@ export const SessionGradeResponseSchema = v.object({
2476
2862
  untrusted: v.nullable(GuideHistoryUntrustedSchema),
2477
2863
  });
2478
2864
  // ---------------------------------------------------------------------------
2479
- // GET /api/v1/runs/residue — compatibility stub, kept for CLIs already
2480
- // published against it. The extractor that used to populate this response
2481
- // was removed (session-residue-extraction — a post-mortem of the removal
2482
- // lives in the dashboard repo's docs) and this build's own CLI no longer
2483
- // calls the route. The server now always
2484
- // answers `{ items: [], untrusted: null }`; these schemas stay only because
2485
- // the response still has to validate against what an already-installed CLI
2486
- // parses.
2487
- // ---------------------------------------------------------------------------
2488
- /**
2489
- * The five kinds of session residue the server used to extract on session
2490
- * close. No longer produced by anything — kept so an already-installed CLI's
2491
- * parse of the (now always-empty) response still type-checks against the
2492
- * same shape it always has.
2493
- */
2494
- export const SessionResidueKindSchema = v.picklist([
2495
- 'decision',
2496
- 'deferral',
2497
- 'assumption',
2498
- 'question',
2499
- 'found_not_fixed',
2500
- ]);
2501
- /**
2502
- * How many residue items one read returns at most — the same cap the
2503
- * extractor applies per session, applied again across sessions: the handoff a
2504
- * session reads at start is a glance, not a log.
2505
- */
2506
- export const MAX_SESSION_RESIDUE_ITEMS = 5;
2507
- /** `?project=` — the committed project id whose recent sessions to read. */
2508
- export const SessionResidueRequestSchema = v.object({
2509
- project: ProjectIdSchema,
2510
- });
2511
- /** One item a recent session in the project left behind. */
2512
- export const SessionResidueItemSchema = v.object({
2513
- kind: SessionResidueKindSchema,
2514
- /**
2515
- * The item's text, **already wrapped in the response's untrusted markers**
2516
- * — model-authored, transcript-derived, and about to be placed in front of
2517
- * an agent, so delimited at the source exactly as a grade's reasoning is.
2518
- */
2519
- text: v.string(),
2520
- /** The run the item came from; what `mossbear sessions <id>` takes. */
2521
- sessionId: NonEmptyStringSchema,
2522
- agentSessionId: NonEmptyStringSchema,
2523
- /** ISO timestamp of the session's close; null while it is still open. */
2524
- endedAt: v.nullable(v.string()),
2525
- });
2526
- export const SessionResidueResponseSchema = v.object({
2527
- project: ProjectIdSchema,
2528
- /**
2529
- * Newest session first, then in the order the session recorded them; at
2530
- * most {@link MAX_SESSION_RESIDUE_ITEMS}. Empty is the ordinary answer and
2531
- * says "nothing on record", never "nothing happened".
2532
- */
2533
- items: v.pipe(v.array(SessionResidueItemSchema), v.maxLength(MAX_SESSION_RESIDUE_ITEMS)),
2534
- /** The markers every `text` is wrapped in; present exactly when `items` is non-empty. */
2535
- untrusted: v.nullable(GuideHistoryUntrustedSchema),
2536
- });
2537
- // ---------------------------------------------------------------------------
2538
2865
  // Parse wrappers (throw ValiError on invalid input)
2539
2866
  // ---------------------------------------------------------------------------
2540
2867
  export function parseAgentConfig(data) {
@@ -2703,13 +3030,19 @@ export function parseGuideHistoryRequest(data) {
2703
3030
  export function parseGuideHistoryResponse(data) {
2704
3031
  return v.parse(GuideHistoryResponseSchema, data);
2705
3032
  }
3033
+ export function parseAnnounceItemNotesRequest(data) {
3034
+ return v.parse(AnnounceItemNotesRequestSchema, data);
3035
+ }
3036
+ export function parseAnnounceItemNotesResponse(data) {
3037
+ return v.parse(AnnounceItemNotesResponseSchema, data);
3038
+ }
3039
+ export function parseItemNotesResponse(data) {
3040
+ return v.parse(ItemNotesResponseSchema, data);
3041
+ }
2706
3042
  export function parseRunGradeRequest(data) {
2707
3043
  return v.parse(SessionGradeRequestSchema, data);
2708
3044
  }
2709
3045
  export function parseSessionGradeResponse(data) {
2710
3046
  return v.parse(SessionGradeResponseSchema, data);
2711
3047
  }
2712
- export function parseSessionResidueResponse(data) {
2713
- return v.parse(SessionResidueResponseSchema, data);
2714
- }
2715
3048
  //# sourceMappingURL=schemas.js.map