@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/agentGuidancePaths.d.ts +1 -1
- package/dist/agentGuidancePaths.js +1 -1
- package/dist/contextKinds.d.ts +93 -74
- package/dist/contextKinds.d.ts.map +1 -1
- package/dist/contextKinds.js +78 -52
- package/dist/contextKinds.js.map +1 -1
- package/dist/contextKinds.test.js +95 -95
- package/dist/contextKinds.test.js.map +1 -1
- package/dist/schemas.d.ts +1668 -134
- package/dist/schemas.d.ts.map +1 -1
- package/dist/schemas.js +424 -91
- package/dist/schemas.js.map +1 -1
- package/dist/schemas.test.js +117 -19
- package/dist/schemas.test.js.map +1 -1
- package/dist/types.d.ts +3 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/dist/whatSyncs.d.ts +1 -1
- package/package.json +1 -1
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
|
|
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 (
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|