@mossbear/protocol 0.1.0-alpha.100

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 (143) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +7 -0
  3. package/dist/agentGuidancePaths.d.ts +101 -0
  4. package/dist/agentGuidancePaths.d.ts.map +1 -0
  5. package/dist/agentGuidancePaths.js +185 -0
  6. package/dist/agentGuidancePaths.js.map +1 -0
  7. package/dist/agentGuidancePaths.test.d.ts +2 -0
  8. package/dist/agentGuidancePaths.test.d.ts.map +1 -0
  9. package/dist/agentGuidancePaths.test.js +91 -0
  10. package/dist/agentGuidancePaths.test.js.map +1 -0
  11. package/dist/aliasPaths.d.ts +100 -0
  12. package/dist/aliasPaths.d.ts.map +1 -0
  13. package/dist/aliasPaths.js +148 -0
  14. package/dist/aliasPaths.js.map +1 -0
  15. package/dist/aliasPaths.test.d.ts +2 -0
  16. package/dist/aliasPaths.test.d.ts.map +1 -0
  17. package/dist/aliasPaths.test.js +80 -0
  18. package/dist/aliasPaths.test.js.map +1 -0
  19. package/dist/artifact.test.d.ts +2 -0
  20. package/dist/artifact.test.d.ts.map +1 -0
  21. package/dist/artifact.test.js +374 -0
  22. package/dist/artifact.test.js.map +1 -0
  23. package/dist/bundleSlug.d.ts +177 -0
  24. package/dist/bundleSlug.d.ts.map +1 -0
  25. package/dist/bundleSlug.js +233 -0
  26. package/dist/bundleSlug.js.map +1 -0
  27. package/dist/bundleSlug.test.d.ts +2 -0
  28. package/dist/bundleSlug.test.d.ts.map +1 -0
  29. package/dist/bundleSlug.test.js +197 -0
  30. package/dist/bundleSlug.test.js.map +1 -0
  31. package/dist/commentAnchor.d.ts +34 -0
  32. package/dist/commentAnchor.d.ts.map +1 -0
  33. package/dist/commentAnchor.js +122 -0
  34. package/dist/commentAnchor.js.map +1 -0
  35. package/dist/commentAnchor.test.d.ts +2 -0
  36. package/dist/commentAnchor.test.d.ts.map +1 -0
  37. package/dist/commentAnchor.test.js +48 -0
  38. package/dist/commentAnchor.test.js.map +1 -0
  39. package/dist/contextKinds.d.ts +165 -0
  40. package/dist/contextKinds.d.ts.map +1 -0
  41. package/dist/contextKinds.js +148 -0
  42. package/dist/contextKinds.js.map +1 -0
  43. package/dist/contextKinds.test.d.ts +2 -0
  44. package/dist/contextKinds.test.d.ts.map +1 -0
  45. package/dist/contextKinds.test.js +137 -0
  46. package/dist/contextKinds.test.js.map +1 -0
  47. package/dist/frameDocument.d.ts +71 -0
  48. package/dist/frameDocument.d.ts.map +1 -0
  49. package/dist/frameDocument.js +140 -0
  50. package/dist/frameDocument.js.map +1 -0
  51. package/dist/frameDocument.test.d.ts +2 -0
  52. package/dist/frameDocument.test.d.ts.map +1 -0
  53. package/dist/frameDocument.test.js +84 -0
  54. package/dist/frameDocument.test.js.map +1 -0
  55. package/dist/frameProtocol.d.ts +11 -0
  56. package/dist/frameProtocol.d.ts.map +1 -0
  57. package/dist/frameProtocol.js +11 -0
  58. package/dist/frameProtocol.js.map +1 -0
  59. package/dist/index.d.ts +24 -0
  60. package/dist/index.d.ts.map +1 -0
  61. package/dist/index.js +24 -0
  62. package/dist/index.js.map +1 -0
  63. package/dist/limits.d.ts +19 -0
  64. package/dist/limits.d.ts.map +1 -0
  65. package/dist/limits.js +19 -0
  66. package/dist/limits.js.map +1 -0
  67. package/dist/markdownSections.d.ts +58 -0
  68. package/dist/markdownSections.d.ts.map +1 -0
  69. package/dist/markdownSections.js +102 -0
  70. package/dist/markdownSections.js.map +1 -0
  71. package/dist/markdownSections.test.d.ts +2 -0
  72. package/dist/markdownSections.test.d.ts.map +1 -0
  73. package/dist/markdownSections.test.js +95 -0
  74. package/dist/markdownSections.test.js.map +1 -0
  75. package/dist/pairing.d.ts +183 -0
  76. package/dist/pairing.d.ts.map +1 -0
  77. package/dist/pairing.js +175 -0
  78. package/dist/pairing.js.map +1 -0
  79. package/dist/pairing.test.d.ts +2 -0
  80. package/dist/pairing.test.d.ts.map +1 -0
  81. package/dist/pairing.test.js +105 -0
  82. package/dist/pairing.test.js.map +1 -0
  83. package/dist/photos.d.ts +146 -0
  84. package/dist/photos.d.ts.map +1 -0
  85. package/dist/photos.js +127 -0
  86. package/dist/photos.js.map +1 -0
  87. package/dist/publicModelCatalog.d.ts +19 -0
  88. package/dist/publicModelCatalog.d.ts.map +1 -0
  89. package/dist/publicModelCatalog.generated.d.ts +2 -0
  90. package/dist/publicModelCatalog.generated.d.ts.map +1 -0
  91. package/dist/publicModelCatalog.generated.js +489 -0
  92. package/dist/publicModelCatalog.generated.js.map +1 -0
  93. package/dist/publicModelCatalog.js +68 -0
  94. package/dist/publicModelCatalog.js.map +1 -0
  95. package/dist/publicModelCatalog.test.d.ts +2 -0
  96. package/dist/publicModelCatalog.test.d.ts.map +1 -0
  97. package/dist/publicModelCatalog.test.js +88 -0
  98. package/dist/publicModelCatalog.test.js.map +1 -0
  99. package/dist/publicModelNativeAliases.d.ts +5 -0
  100. package/dist/publicModelNativeAliases.d.ts.map +1 -0
  101. package/dist/publicModelNativeAliases.js +8 -0
  102. package/dist/publicModelNativeAliases.js.map +1 -0
  103. package/dist/schemas.d.ts +10745 -0
  104. package/dist/schemas.d.ts.map +1 -0
  105. package/dist/schemas.js +4572 -0
  106. package/dist/schemas.js.map +1 -0
  107. package/dist/schemas.test.d.ts +2 -0
  108. package/dist/schemas.test.d.ts.map +1 -0
  109. package/dist/schemas.test.js +1617 -0
  110. package/dist/schemas.test.js.map +1 -0
  111. package/dist/steeringOverTime.d.ts +30 -0
  112. package/dist/steeringOverTime.d.ts.map +1 -0
  113. package/dist/steeringOverTime.js +19 -0
  114. package/dist/steeringOverTime.js.map +1 -0
  115. package/dist/types.d.ts +109 -0
  116. package/dist/types.d.ts.map +1 -0
  117. package/dist/types.js +12 -0
  118. package/dist/types.js.map +1 -0
  119. package/dist/usageOnly.d.ts +190 -0
  120. package/dist/usageOnly.d.ts.map +1 -0
  121. package/dist/usageOnly.js +53 -0
  122. package/dist/usageOnly.js.map +1 -0
  123. package/dist/usageOnly.test.d.ts +2 -0
  124. package/dist/usageOnly.test.d.ts.map +1 -0
  125. package/dist/usageOnly.test.js +203 -0
  126. package/dist/usageOnly.test.js.map +1 -0
  127. package/dist/version.d.ts +47 -0
  128. package/dist/version.d.ts.map +1 -0
  129. package/dist/version.js +125 -0
  130. package/dist/version.js.map +1 -0
  131. package/dist/version.test.d.ts +2 -0
  132. package/dist/version.test.d.ts.map +1 -0
  133. package/dist/version.test.js +86 -0
  134. package/dist/version.test.js.map +1 -0
  135. package/dist/whatSyncs.d.ts +62 -0
  136. package/dist/whatSyncs.d.ts.map +1 -0
  137. package/dist/whatSyncs.js +228 -0
  138. package/dist/whatSyncs.js.map +1 -0
  139. package/dist/whatSyncs.test.d.ts +2 -0
  140. package/dist/whatSyncs.test.d.ts.map +1 -0
  141. package/dist/whatSyncs.test.js +113 -0
  142. package/dist/whatSyncs.test.js.map +1 -0
  143. package/package.json +52 -0
@@ -0,0 +1,4572 @@
1
+ /**
2
+ * Runtime validation schemas using Valibot.
3
+ *
4
+ * Schemas are the single source of truth — TypeScript types in types.ts are
5
+ * derived from these via `v.InferOutput<typeof Schema>`.
6
+ *
7
+ * Callers can use the exported `parse*` wrappers (throw ValiError on invalid
8
+ * input) or call `v.safeParse(Schema, data)` directly for non-throwing checks.
9
+ */
10
+ import * as v from 'valibot';
11
+ import { DISPLAY_NAME_REFUSED_CHARACTERS } from './bundleSlug.js';
12
+ import { isBundleSlug } from './bundleSlug.js';
13
+ import { CONTEXT_CONTENT_KINDS, CONTEXT_ITEM_TYPES, CONTEXT_ITEM_TYPE_FILTER_VALUES, contextItemTypeOf, CAPTURE_CONTENT_TYPES, } from './contextKinds.js';
14
+ import { MAX_ARTIFACT_DESCRIPTION_CHARS, MAX_ARTIFACT_NAME_CHARS, MAX_CONTEXT_CONTENT_BYTES, MAX_RAW_GUIDE_CONTENT_BYTES, } from './limits.js';
15
+ import { PhotoAssetSchema } from './photos.js';
16
+ // ---------------------------------------------------------------------------
17
+ // Core enum schemas
18
+ // ---------------------------------------------------------------------------
19
+ export const VerdictSchema = v.picklist(['aligned', 'unguided', 'misaligned']);
20
+ export const GuidingTierSchema = v.picklist(['pattern_match', 'cached', 'llm', 'batch']);
21
+ /**
22
+ * Compatibility vocabulary for the source of legacy extracted suggestions.
23
+ * These values describe suggestion provenance rather than run-harness identity.
24
+ */
25
+ export const PlatformKindSchema = v.picklist([
26
+ 'claude_code',
27
+ 'codex',
28
+ 'opencode',
29
+ 'cursor',
30
+ 'copilot',
31
+ 'other',
32
+ ]);
33
+ /**
34
+ * Which agent harness produced a run — the CLI's harness registry, on the wire.
35
+ *
36
+ * **Deliberately not {@link PlatformKindSchema}, and not a widening of it.**
37
+ * That picklist answers a different question — which transcript format a
38
+ * *suggestion* was extracted from — over a set that includes harnesses
39
+ * `mossbear init` cannot wire (`cursor`, `copilot`) and excludes one it can
40
+ * (`antigravity`). Two questions, two sets; collapsing them would need both a
41
+ * new member and an overloaded meaning.
42
+ *
43
+ * Declared here rather than in the CLI so there is exactly one list: the CLI's
44
+ * `HarnessId` is `v.InferOutput` of this, imported as a type, so a manifest for
45
+ * a harness this schema does not name fails typecheck instead of failing at the
46
+ * sync boundary. The import is type-only on purpose — `mossbear-hook` runs once
47
+ * per agent tool call, and nothing here may enter its runtime import graph.
48
+ *
49
+ * Rides `metadata.harness` on each action (see {@link ActionMetadataSchema});
50
+ * the server reduces a session's actions to one value and writes `runs.harness`.
51
+ */
52
+ export const HarnessIdSchema = v.picklist([
53
+ 'claude_code',
54
+ 'codex',
55
+ 'antigravity',
56
+ 'opencode',
57
+ ]);
58
+ /**
59
+ * Where a session ran, recorded only when the hook can see it ran in a cloud
60
+ * container: a claude.ai/code session, a Codespace, a CI runner.
61
+ *
62
+ * **There is no `local`.** Nothing positively marks a laptop. "Not one of the
63
+ * clouds we recognize" is only an inference, and it would mislabel any cloud
64
+ * platform the CLI has no marker for yet. So the stamp is either present and
65
+ * `cloud`, or absent, and absent means "not known to be cloud". It never means
66
+ * "local".
67
+ *
68
+ * A picklist rather than a boolean, so a later member (a specific platform)
69
+ * widens a vocabulary instead of replacing a field. Widening follows the
70
+ * `harness` rule: the server is deployed first.
71
+ *
72
+ * Rides `metadata.environment` on each action (see {@link ActionMetadataSchema}).
73
+ * The server writes `cloud` onto a session when any of its actions carry it.
74
+ */
75
+ export const SessionEnvironmentSchema = v.picklist(['cloud']);
76
+ export const GuideFileFormatSchema = v.picklist([
77
+ 'agents-md',
78
+ 'agents-dir',
79
+ 'claude-md',
80
+ 'claude-rules',
81
+ 'cursorrules',
82
+ 'cursor-rules',
83
+ 'skill-md',
84
+ ]);
85
+ const NonEmptyStringSchema = v.pipe(v.string(), v.minLength(1));
86
+ const Sha256HexSchema = v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/i));
87
+ // No eval-provider schemas here. They described the LLM credentials the CLI
88
+ // needed to grade on-device; grading is server-side and the CLI holds no
89
+ // provider config. The server's own provider settings are environment
90
+ // variables it reads at startup, not a wire contract.
91
+ // Auth wire schemas used to live here (ValidateTokenRequest/Response,
92
+ // CliTokenMetadata). The validate-token route never adopted them — it checks
93
+ // `typeof body.token === 'string'` by hand — and nothing else imported them.
94
+ // Deleted rather than kept as a parallel contract that had already drifted
95
+ // from the route's `{ valid }` response.
96
+ // The guide snapshot schemas live further down, after
97
+ // `SafeRelativePosixPathSchema` and `GuideDiscoveryRootSchema`: the bundle now
98
+ // carries the same `(root, path)` pair the import payload does, and a `const`
99
+ // cannot be referenced above its own declaration.
100
+ export { MAX_ARTIFACT_DESCRIPTION_CHARS, MAX_ARTIFACT_NAME_CHARS, MAX_RAW_GUIDE_CONTENT_BYTES, };
101
+ /** Max member files a single skill-md payload may carry. */
102
+ export const MAX_SKILL_MEMBER_FILES = 64;
103
+ const BoundedRawContentSchema = v.pipe(v.string(), v.check((value) => new TextEncoder().encode(value).length <= MAX_RAW_GUIDE_CONTENT_BYTES, `rawContent must be at most ${MAX_RAW_GUIDE_CONTENT_BYTES} bytes`));
104
+ // A path that is safe to re-create on disk and safe to store as identity:
105
+ // forward slashes only, never absolute (POSIX or Windows drive-letter form),
106
+ // no empty / `.` / `..` segments, no control characters. Every path this
107
+ // protocol carries is eventually written into a project tree by the export
108
+ // round-trip, so the rule belongs at the schema boundary rather than in each
109
+ // consumer, at the boundary where untrusted data crosses in.
110
+ //
111
+ // Exported so the member-files read path (server response filtering, CLI
112
+ // defense-in-depth before writing to disk) enforces the identical rule.
113
+ //
114
+ // The check messages each name the one edit that fixes the path, so they are
115
+ // written for the reader and exported for a server boundary to pass through.
116
+ export const PATH_ISSUE_MESSAGES = {
117
+ backslash: 'path must use forward slashes',
118
+ absolute: 'path must be relative',
119
+ control: 'path must not contain control characters',
120
+ segments: 'path must not contain empty, "." or ".." segments',
121
+ skillMd: 'path must not shadow the skill’s own SKILL.md',
122
+ };
123
+ export const SafeRelativePosixPathSchema = v.pipe(v.string(), v.minLength(1), v.maxLength(512), v.check((path) => !path.includes('\\'), PATH_ISSUE_MESSAGES.backslash), v.check((path) => !path.startsWith('/') && !/^[a-zA-Z]:/.test(path), PATH_ISSUE_MESSAGES.absolute), v.check(
124
+ // eslint-disable-next-line no-control-regex
125
+ (path) => !/[\u0000-\u001f\u007f]/.test(path), PATH_ISSUE_MESSAGES.control), v.check((path) => path
126
+ .split('/')
127
+ .every((segment) => segment !== '' && segment !== '.' && segment !== '..'), PATH_ISSUE_MESSAGES.segments));
128
+ // Member paths are relative to the skill directory, and additionally may never
129
+ // name the skill's own SKILL.md (the payload itself).
130
+ export const SkillMemberPathSchema = v.pipe(SafeRelativePosixPathSchema, v.check((path) => path.toLowerCase() !== 'skill.md', PATH_ISSUE_MESSAGES.skillMd));
131
+ // A sibling file of a skill's SKILL.md (scripts/, references/, assets/,
132
+ // supporting docs), imported alongside it as a guide_file row.
133
+ export const RawSkillMemberFileSchema = v.object({
134
+ path: SkillMemberPathSchema,
135
+ rawContent: BoundedRawContentSchema,
136
+ lastModified: v.pipe(v.number(), v.integer(), v.minValue(0)),
137
+ content_hash: Sha256HexSchema,
138
+ });
139
+ /** Max skipped-member paths a skill-md payload may report alongside `members`. */
140
+ export const MAX_SKILL_SKIPPED_MEMBER_PATHS = 256;
141
+ // Paths (relative to the skill directory) that discovery found but could not
142
+ // import this run — binary/non-UTF-8, oversized, unreadable, or beyond the
143
+ // member cap. Deliberately looser than SkillMemberPathSchema: these describe
144
+ // what is on the user's disk and are only ever string-matched against stored
145
+ // member paths server-side (never re-created as files), so an odd on-disk
146
+ // filename must not fail the whole payload.
147
+ const SkippedMemberPathSchema = v.pipe(v.string(), v.minLength(1), v.maxLength(512));
148
+ /**
149
+ * Which root a discovered guide file's `path` is relative to: the repo checkout
150
+ * (`project`) or the user's homedir (`global`, e.g. `.claude/CLAUDE.md`).
151
+ * Part of the import resolution key — see `RawGuideFilePayloadSchema.root`.
152
+ */
153
+ export const GuideDiscoveryRootSchema = v.picklist(['project', 'global']);
154
+ // ---------------------------------------------------------------------------
155
+ // Guide snapshot schemas
156
+ // ---------------------------------------------------------------------------
157
+ export const GuideSnapshotSchema = v.object({
158
+ id: v.string(),
159
+ title: v.string(),
160
+ content: v.string(),
161
+ enabled: v.boolean(),
162
+ updatedAt: v.string(),
163
+ // origin is `file:{format}:{path}` for imported guides, null/absent
164
+ // otherwise. contentHash is the SHA-256 of the canonical bytes; the CLI uses
165
+ // the pair to round-trip imported files back to disk without re-encoding.
166
+ //
167
+ // **`origin` is not superseded by `(root, path)`.** Nothing on the write side
168
+ // reconciles on it after this slice, but `resolveRuleFileDelivery` still
169
+ // matches delivery evidence on `(origin, contentHash)`, so dropping it
170
+ // would make every guide read as undelivered — silently, since runs still
171
+ // grade and verdicts still appear. It stays as provenance.
172
+ origin: v.optional(v.nullable(v.string())),
173
+ contentHash: v.optional(v.nullable(Sha256HexSchema)),
174
+ // Which scope root `path` is relative to, and the path itself — the write
175
+ // side's half of the identity the read side already stores on
176
+ // `guide_files.root` / `guide_files.path`
177
+ // (`guide-write-side-identity-plan.md` → "Carry `root` on every write path").
178
+ //
179
+ // Without them the bundle could not express "global": `origin` is
180
+ // `file:{format}:{path}` with no root component, so every writer resolved it
181
+ // against the repo and a guide imported from `~/.claude/CLAUDE.md` came back
182
+ // down as `<repo>/.claude/CLAUDE.md`.
183
+ //
184
+ // **Both optional and nullable, and their absence is not an error.** A guide
185
+ // authored in the dashboard has no path; a row imported before the columns
186
+ // existed has neither. Such a guide keeps resolving from `origin` alone —
187
+ // today's behaviour — rather than becoming undeliverable. A missing `root` is
188
+ // read as `project`, which is what every pre-existing row meant.
189
+ root: v.optional(v.nullable(GuideDiscoveryRootSchema)),
190
+ path: v.optional(v.nullable(SafeRelativePosixPathSchema)),
191
+ });
192
+ export const GuideBundleResponseSchema = v.object({
193
+ guides: v.array(GuideSnapshotSchema),
194
+ pulledAt: v.string(),
195
+ });
196
+ export const RawGuideFilePayloadSchema = v.pipe(v.object({
197
+ // Relative to the discovery root the CLI walked (`payloadPath`,
198
+ // `packages/cli/src/rules/discover.ts:29-30`). Two things depend on it
199
+ // being a safe relative path, which is why it is parsed here rather than
200
+ // guarded downstream:
201
+ //
202
+ // - it is embedded verbatim in the guide's `origin` (`file:{format}:{path}`)
203
+ // and parsed back out to place the file on disk. The writer that does so
204
+ // is now the docs phase's projection resolver
205
+ // (`packages/cli/src/artifacts/guide-projection.ts`), which rejects anything
206
+ // absolute, traversing or uncontained — so an unsafe path stores a guide
207
+ // that can never round-trip. (`mossbear guides export` was the original
208
+ // writer and skipped such a path *silently*; it was deleted by
209
+ // `unified-item-sync` Slice 5.);
210
+ // - it is stored as `guide_files.path`, the column import reconciles on
211
+ // (`guide-versioned-identity-plan.md` → Decision 4), and identity must
212
+ // not be keyable on a value the exporter refuses to honour.
213
+ path: SafeRelativePosixPathSchema,
214
+ // Which discovery root `path` is relative to — `guide-versioned-identity-plan.md`
215
+ // → Decision 6. Without it, `(repoId, path)` collapses a project skill onto
216
+ // its `~/.claude/skills` twin: `.claude/skills` is in both of the CLI's root
217
+ // lists and both scans emit the same relative string, while `repoId` is
218
+ // envelope-level so both files carry the same one.
219
+ //
220
+ // **Optional, and its absence is not an error** — a CLI predating this field
221
+ // sends none, exactly as it may send no `repoId`. A payload missing either
222
+ // does not participate in reconciliation and keeps the content-hash insert
223
+ // behaviour it was created under, rather than being defaulted to `'project'`:
224
+ // guessing would let an old client's `--global` file adopt a project row.
225
+ root: v.optional(GuideDiscoveryRootSchema),
226
+ format: GuideFileFormatSchema,
227
+ rawContent: BoundedRawContentSchema,
228
+ lastModified: v.pipe(v.number(), v.integer(), v.minValue(0)),
229
+ content_hash: Sha256HexSchema,
230
+ // Only meaningful on `skill-md` payloads. `[]` asserts the skill has no
231
+ // member files (stale synced rows are removed server-side); omitting the
232
+ // field means "no member information" and leaves member rows untouched.
233
+ // No CLI caller omits it today — every sender reaches this schema through
234
+ // a directory scan that populates it — but the distinction is load-bearing
235
+ // on the wire and must not collapse: reading an absent `members` as an
236
+ // empty skill would hard-delete a client's member rows.
237
+ members: v.optional(v.pipe(v.array(RawSkillMemberFileSchema), v.maxLength(MAX_SKILL_MEMBER_FILES))),
238
+ /**
239
+ * The body-item version this machine last agreed with the server about for
240
+ * this `(scope, root, path)` — the machine-local baseline
241
+ * (`guide-versioned-identity-plan.md` → slice 2b-B, D10 in
242
+ * `context-bundle-authoring-plan.md`).
243
+ *
244
+ * It is the *client* half of the reconcile precondition, and it exists to
245
+ * answer a question the server cannot: whether the bytes on this disk were
246
+ * edited **from** the version the server currently holds, or from an older
247
+ * one. The server-only guard shipped in 2b-A can see that a dashboard edit
248
+ * exists, never that this machine has already seen it — so a guide the
249
+ * dashboard edited and the user then re-synced to disk forks forever.
250
+ *
251
+ * **Optional, and its absence is not an error.** A CLI predating the
252
+ * baseline store, a fresh machine, or a deleted `~/.mossbear/state/` sends
253
+ * none, and the payload falls back to the server-only guard exactly as it
254
+ * behaves today. Absence therefore degrades to "decline and fork", never to
255
+ * an overwrite; a *stale* value degrades to a reported conflict.
256
+ */
257
+ expectedVersion: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
258
+ // Only alongside `members`: member paths present on disk but not imported
259
+ // this run. The server must NOT treat their absence from `members` as
260
+ // removal — a transiently unreadable or newly-oversized file would
261
+ // otherwise hard-delete its previously synced row.
262
+ skippedMemberPaths: v.optional(v.pipe(v.array(SkippedMemberPathSchema), v.maxLength(MAX_SKILL_SKIPPED_MEMBER_PATHS))),
263
+ }), v.check((payload) => payload.members === undefined || payload.format === 'skill-md', 'members are only supported on skill-md payloads'), v.check((payload) => payload.skippedMemberPaths === undefined || payload.members !== undefined, 'skippedMemberPaths requires members'),
264
+ // Case-insensitive uniqueness: the export round-trip re-creates these files
265
+ // on disk, where the default macOS/Windows filesystems fold case — two
266
+ // members differing only by case would silently overwrite each other.
267
+ v.check((payload) => payload.members === undefined ||
268
+ new Set(payload.members.map((member) => member.path.toLowerCase())).size ===
269
+ payload.members.length, 'member paths must be unique (case-insensitive)'));
270
+ // A skill guide's member file as served by GET /api/v1/guides/:id/member-files
271
+ // — the export round-trip's read side. Lean by design: member bodies are NOT
272
+ // part of the guide bundle (the eval hot path pulls that every session), they
273
+ // are fetched lazily per skill guide at export time.
274
+ export const GuideMemberFileSchema = v.object({
275
+ path: SkillMemberPathSchema,
276
+ content: BoundedRawContentSchema,
277
+ contentHash: Sha256HexSchema,
278
+ });
279
+ export const GuideMemberFilesResponseSchema = v.pipe(v.object({
280
+ memberFiles: v.pipe(v.array(GuideMemberFileSchema), v.maxLength(MAX_SKILL_MEMBER_FILES)),
281
+ }),
282
+ // Mirrors the import payload's rule: on case-folding filesystems two
283
+ // entries differing only by case resolve to one file, and both planning as
284
+ // NEW would let the second silently clobber the first without the
285
+ // OVERWRITE diff prompt. A response that case-collides is malformed.
286
+ v.check((response) => new Set(response.memberFiles.map((file) => file.path.toLowerCase())).size ===
287
+ response.memberFiles.length, 'member file paths must be unique (case-insensitive)'));
288
+ /** Max number of rules accepted in a single `POST /api/rules/import` request. */
289
+ export const MAX_RULES_IMPORT_BATCH = 100;
290
+ /** Opaque checkout digest shared by run logs, manifests, and `runs.repo_id`. */
291
+ export const RepoIdSchema = v.pipe(v.string(), v.regex(/^repo_[0-9a-f]{32}$/, 'repoId must be repo_ followed by 32 hex chars'));
292
+ /** Longest accepted `projectId`. Generated ids are far shorter; this bounds a hand-declared one. */
293
+ const MAX_PROJECT_ID_LENGTH = 128;
294
+ /**
295
+ * A repo's declared portable identity. See `RulesImportRequestSchema.projectId`
296
+ * for why this is looser than {@link RepoIdSchema} — a declared id is
297
+ * human-authored and predates any prefix rule.
298
+ */
299
+ export const ProjectIdSchema = v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(MAX_PROJECT_ID_LENGTH), v.regex(/^[A-Za-z0-9_.-]+$/, 'projectId must contain only letters, digits, underscore, dot or hyphen'));
300
+ /**
301
+ * A checkout's committed `project.id` as a context write declares it: trimmed
302
+ * and non-empty, exactly the rule the CLI's config reader applies — and no
303
+ * stricter. {@link ProjectIdSchema}'s character set is deliberately not
304
+ * applied, because the reader accepts hand-authored ids outside it and a
305
+ * checkout it serves must not start failing every push.
306
+ *
307
+ * Trimmed and non-empty because the value is **stored** as a document's home:
308
+ * an empty or padded id is one no checkout can ever match, so a document homed
309
+ * on it would read as foreign in every repo.
310
+ */
311
+ export const DeclaredProjectIdSchema = v.pipe(v.string(), v.trim(), v.minLength(1));
312
+ /** Longest accepted `workspaceId`. Server-minted ids are `nanoid()`; this bounds a hand-edited one. */
313
+ const MAX_WORKSPACE_ID_LENGTH = 128;
314
+ /**
315
+ * The workspace a repo declares its project-scoped guidance belongs to. See
316
+ * `RulesImportRequestSchema.workspaceId`.
317
+ *
318
+ * Same shape as {@link ProjectIdSchema}, and for the same reason: the id is
319
+ * minted by the server (`nanoid()`, whose alphabet this character class covers)
320
+ * but it reaches us out of a **committed, hand-editable** file, so it is
321
+ * constrained only as far as it must be to serve as a lookup key — no
322
+ * whitespace, no path separators, no control characters, bounded length.
323
+ * Whether it names a workspace this caller may reach is a membership question,
324
+ * answered against the database, not a question a regex can answer.
325
+ */
326
+ export const WorkspaceIdSchema = v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(MAX_WORKSPACE_ID_LENGTH), v.regex(/^[A-Za-z0-9_.-]+$/, 'workspaceId must contain only letters, digits, underscore, dot or hyphen'));
327
+ // Envelope-only schema: caps request shape/size before the per-item
328
+ // parseRawGuideFilePayload loop validates each rule in detail, which is what
329
+ // preserves the import route's index-aware error reporting.
330
+ export const RulesImportRequestSchema = v.object({
331
+ rules: v.pipe(v.array(v.unknown()), v.maxLength(MAX_RULES_IMPORT_BATCH)),
332
+ /**
333
+ * Which checkout these files came from — the same opaque digest the hook and
334
+ * the rule manifest already carry (`packages/cli/src/repo-id.ts`,
335
+ * `RuleManifestSchema.repoId`). Envelope-level, not per-file: every file in
336
+ * one import comes from one repo, and the per-file payload stays lean (the
337
+ * "Import endpoint payload" resolved decision).
338
+ *
339
+ * It is what lets the server reconcile an edited file back onto the guide it
340
+ * already created instead of inserting a second one. `origin` alone cannot:
341
+ * it is `file:{format}:{path}` with no repo component, so two checkouts
342
+ * sharing `.agents/code-style.md` would collide.
343
+ *
344
+ * **Optional, and its absence is not an error.** A CLI predating this field
345
+ * sends none, and the server falls back to the content-hash dedupe it always
346
+ * used. Never send a repo id derived anywhere but `repoIdFromRoot` — the
347
+ * digest is keyed by a machine-local secret precisely so the server never
348
+ * learns a path.
349
+ *
350
+ * Shaped by the canonical `RepoIdSchema` (shared with run logs and manifests)
351
+ * rather than a looser local check: a row storing anything but
352
+ * a real digest could never match one, so a malformed identity has to be
353
+ * rejected at the boundary instead of persisted as a permanent orphan.
354
+ */
355
+ repoId: v.optional(RepoIdSchema),
356
+ /**
357
+ * The repo's **portable** identity — `project.id` from the committed
358
+ * `<repo>/.mossbear/config.json` (`guide-write-side-identity` slice 1, shipped in
359
+ * #540). This is what makes `(scope, path)` reconciliation portable, and it is
360
+ * the field `unified-item-sync` slice 2 exists to put on the wire.
361
+ *
362
+ * **Why `repoId` is not enough, even though it is already here.**
363
+ * `repoIdFromRoot` is an HMAC keyed by a machine-local secret
364
+ * (`packages/cli/src/repo-id.ts`), so the same checkout on two machines — or
365
+ * one teammate's clone versus another's — produces two different digests. A
366
+ * guide reconciled on it therefore forks the moment anyone else edits the
367
+ * file, which is the one-way trip this item is closing. `projectId` is
368
+ * declared in a committed file, so every clone agrees on it.
369
+ *
370
+ * **Optional, and its absence is not an error.** A CLI predating this field
371
+ * sends none and the server falls back to `repoId` scoping, which is exactly
372
+ * the behaviour those clients already have. A repo that has never run
373
+ * `mossbear init` also has no declaration, and must keep importing.
374
+ *
375
+ * Deliberately looser than `RepoIdSchema`: a generated id is
376
+ * `proj_`+hex, but a *declared* one is whatever a human committed —
377
+ * `readRepoProjectId` accepts any non-empty trimmed string
378
+ * (`packages/cli/src/artifacts/repo-config.ts`), and rejecting those here would
379
+ * break a shipped contract. Constrained only as far as it must be to serve as
380
+ * a storage key: no whitespace, no path separators, no control characters,
381
+ * bounded length.
382
+ */
383
+ projectId: v.optional(ProjectIdSchema),
384
+ /**
385
+ * The workspace this repo declares its project-scoped guidance belongs to —
386
+ * `workspace.id` from the committed `<repo>/.mossbear/config.json`
387
+ * (`workspace-declaration` slice 1).
388
+ *
389
+ * **What it changes: which of the caller's workspaces a project path resolves
390
+ * in.** Import identity is already scoped by workspace *membership* rather
391
+ * than authorship, so a caller in several workspaces has several candidate
392
+ * rows at one `(project, root, path)` and the resolver picked between them by
393
+ * row age. The declaration is the narrower lookup that removes the guess, and
394
+ * it is committed so every clone of the repo narrows the same way.
395
+ *
396
+ * **Membership stays the boundary; this only narrows inside it.** The
397
+ * declaration cannot widen what a caller may reach: a workspace they are not a
398
+ * member of is refused by name rather than resolved, and never quietly
399
+ * replaced by their personal one — falling back would recreate the fork the
400
+ * declaration exists to close.
401
+ *
402
+ * **Envelope-level, and never sent on a global batch.** It is the *repo's*
403
+ * declaration, so it travels with the same batch that carries `repoId` and
404
+ * `projectId`; a `root: 'global'` file belongs to no checkout and to no
405
+ * project, and by the same rule to no repo-declared workspace.
406
+ *
407
+ * **Optional, and its absence is not an error.** A CLI predating this field
408
+ * sends none, and a repo that has never declared one has none to send; both
409
+ * keep the resolution they have today.
410
+ */
411
+ workspaceId: v.optional(WorkspaceIdSchema),
412
+ });
413
+ /**
414
+ * What the server did with one payload, reported per file so the CLI can update
415
+ * its machine-local baseline (`guide-versioned-identity-plan.md` → slice 2b-B).
416
+ *
417
+ * The distinction that matters is not "did something change" but **do disk and
418
+ * server now agree**: `imported`, `updated` and `skipped` all mean they do, and
419
+ * only those license recording a new baseline. `conflict` means the disk bytes
420
+ * did *not* land — recording the server's version for one would hand the next
421
+ * import a matching `expectedVersion` and turn a refused overwrite into an
422
+ * automatic one on the following run, which is the failure this whole precondition
423
+ * exists to prevent.
424
+ */
425
+ export const GuideImportOutcomeSchema = v.picklist([
426
+ 'imported',
427
+ 'updated',
428
+ 'skipped',
429
+ 'conflict',
430
+ ]);
431
+ /**
432
+ * Per-payload import outcome, addressed by the same `(root, path)` pair the
433
+ * server reconciles on so the CLI can key its baseline identically without
434
+ * re-deriving anything.
435
+ *
436
+ * `version` is the body item's version **as the server holds it after this
437
+ * request** — the value a later import should send as `expectedVersion` once
438
+ * disk and server agree. It is reported for a `conflict` too, deliberately: the
439
+ * conflict report needs it to offer explicit resolution, and reporting it is not
440
+ * the same as recording it.
441
+ *
442
+ * Entries are omitted for a payload the server could not address at all (no
443
+ * `root`, or a pre-R0 row): there is no identity to key a baseline on, and
444
+ * inventing one would let a later import claim a precondition it never observed.
445
+ */
446
+ export const GuideImportResultSchema = v.object({
447
+ /** Canonical guide identity for review links; absent on older servers. */
448
+ guideId: v.optional(NonEmptyStringSchema),
449
+ root: GuideDiscoveryRootSchema,
450
+ path: SafeRelativePosixPathSchema,
451
+ outcome: GuideImportOutcomeSchema,
452
+ version: v.pipe(v.number(), v.integer(), v.minValue(1)),
453
+ });
454
+ /** Max alias sets one import response reports as divergent. */
455
+ export const MAX_GUIDE_IMPORT_DIVERGENCES = 64;
456
+ /**
457
+ * An alias set the server found in one import but **did not** collapse, because
458
+ * the files do not hold the same rules
459
+ * (`alias-instruction-file-identity-plan.md` → second addendum,
460
+ * 2026-09-03).
461
+ *
462
+ * Reporting rather than refusing is the whole point. An identical
463
+ * `AGENTS.md`/`.cursorrules` pair becomes one guide; a divergent one imports as
464
+ * two guides exactly as it does today, and this names the paths so the user can
465
+ * see the drift the product would otherwise have kept silent. Nothing about the
466
+ * import fails, and nothing the user does today stops working.
467
+ *
468
+ * `paths` carries every path in the set this request saw, in the order the
469
+ * server ranks them — so the first is the one that would have kept the body had
470
+ * they matched.
471
+ */
472
+ export const GuideImportDivergenceSchema = v.object({
473
+ root: GuideDiscoveryRootSchema,
474
+ paths: v.pipe(v.array(SafeRelativePosixPathSchema), v.minLength(2)),
475
+ });
476
+ /**
477
+ * An alias pair one import left as **two guides**, because a guide was already
478
+ * stored at the incoming file's alias partner path and the pair could not be
479
+ * collapsed onto it (`skill-alias-collapse-managed-file-plan.md` →
480
+ * *Reporting*).
481
+ *
482
+ * Distinct from {@link GuideImportDivergenceSchema}, which says the files
483
+ * differ. This one says only that the fork happened — the reasons are several
484
+ * (the bodies differ, the skill directories around them could not be proven to
485
+ * match, the partner path already answers to a second guide) and the import
486
+ * cannot always tell them apart, so it names the pair and leaves the reading to
487
+ * whoever wrote the files. Reported only when a guide was *created* at the
488
+ * incoming path, so a repo re-importing a pair that forked long ago stays
489
+ * quiet.
490
+ *
491
+ * `paths` is the incoming file first, then the partner already stored.
492
+ */
493
+ export const GuideImportAliasForkSchema = v.object({
494
+ root: GuideDiscoveryRootSchema,
495
+ paths: v.pipe(v.array(SafeRelativePosixPathSchema), v.minLength(2)),
496
+ });
497
+ // ---------------------------------------------------------------------------
498
+ // `mossbear unlink` — un-enrol a guide from the default bundle
499
+ // ---------------------------------------------------------------------------
500
+ /**
501
+ * One guide to stop delivering, addressed the way the **import** route already
502
+ * resolves an existing guide: `(root, path)` plus the envelope's checkout and
503
+ * project identity.
504
+ *
505
+ * **Deliberately not `origin`.** `file:{format}:{path}` is not unique — every
506
+ * repo has an `AGENTS.md`, so an origin-keyed request disables the matching
507
+ * guide in every repo in the workspace. That is the defect that sank the first
508
+ * implementation of this verb. `(root, path)` scoped by `repoId`/`projectId`
509
+ * is the key the import route reconciles on, so unlink addresses exactly the
510
+ * row link created and no other.
511
+ */
512
+ export const RawGuideUnlinkSchema = v.object({
513
+ root: GuideDiscoveryRootSchema,
514
+ /**
515
+ * The canonical guide-path validator, not a fresh `v.string()`: it already
516
+ * rejects absolute paths, control characters and `..` traversal, and a second
517
+ * hand-rolled constraint here would be a place for the two to disagree.
518
+ */
519
+ path: SafeRelativePosixPathSchema,
520
+ });
521
+ /** Max guides accepted in a single `POST /api/rules/unlink` request. */
522
+ export const MAX_RULE_UNLINK_BATCH = 500;
523
+ export const RuleUnlinkRequestSchema = v.object({
524
+ unlinks: v.pipe(v.array(RawGuideUnlinkSchema), v.maxLength(MAX_RULE_UNLINK_BATCH)),
525
+ /** Same envelope identity the import route carries, and for the same reason. */
526
+ repoId: v.optional(v.string()),
527
+ projectId: v.optional(v.string()),
528
+ });
529
+ /**
530
+ * `unlinked` counts guides removed from the default bundle; `skipped` counts
531
+ * requested paths that resolved to nothing, or were already out of it.
532
+ *
533
+ * `stillDelivered` names guides that remain in *other* bundles the caller can
534
+ * reach — including a teammate's, since a bundle shared into a workspace they
535
+ * belong to keeps arriving whoever owns it. Unlink is the exact inverse of what
536
+ * link does — it removes the default-bundle membership link created — so a
537
+ * guide someone deliberately added to a curated bundle stays there, and saying
538
+ * so is the difference between a true report and a reassuring one.
539
+ *
540
+ * `released` names the requested paths whose guide is now in **no** bundle the
541
+ * caller can reach, so nothing delivers it any more. It exists because the
542
+ * caller holds a fact the server does not: the local placement record that
543
+ * marks a path as managed by a bundle. A path taken out of every bundle and
544
+ * still recorded as bundle-managed is two answers to one question, and only the
545
+ * server can tell which paths genuinely stopped being delivered. Note this is
546
+ * not on its own enough to make a re-link restore delivery — the import route
547
+ * enrols only the guide rows its insert creates — so a caller acting on this
548
+ * should not report the path as re-adoptable.
549
+ *
550
+ * Optional with an empty default, so a client on this version still parses a
551
+ * response from a deployment that predates the field.
552
+ */
553
+ export const RuleUnlinkResponseSchema = v.object({
554
+ unlinked: v.number(),
555
+ skipped: v.number(),
556
+ stillDelivered: v.array(v.string()),
557
+ released: v.optional(v.array(RawGuideUnlinkSchema), []),
558
+ });
559
+ export function parseRuleUnlinkRequest(data) {
560
+ return v.parse(RuleUnlinkRequestSchema, data);
561
+ }
562
+ // ---------------------------------------------------------------------------
563
+ // Display names
564
+ // ---------------------------------------------------------------------------
565
+ /**
566
+ * The sentence a caller gets back when a display name carries a character that
567
+ * cannot be seen. It is written for the person who typed the name, not for the
568
+ * developer reading the schema. This repo's error-message rules put the
569
+ * reader first, keep the blame off them, and ask a refusal to leave them
570
+ * something to do — so the action leads and "control character",
571
+ * which is not a phrase most people can act on, never appears.
572
+ *
573
+ * "often" is doing real work in the second clause. This branch cannot tell a
574
+ * pasted name from a typed one, so it does not claim to; it names
575
+ * where such characters usually come from, which is what makes the advice
576
+ * actionable without overclaiming.
577
+ */
578
+ export const DISPLAY_NAME_CONTROL_CHARACTER_MESSAGE = 'Remove the invisible characters from this name — copying text from another app often brings them along.';
579
+ /**
580
+ * A user-typed display name that is safe to print into a terminal line.
581
+ *
582
+ * Refuses every character in {@link DISPLAY_NAME_REFUSED_CHARACTERS}
583
+ * (`bundleSlug.ts`, where the class is defined once and explained): the control
584
+ * characters, where ESC and CR live — a CR can overwrite the line a user is
585
+ * reading, which in a tool whose job is reporting what reached their agents
586
+ * means the sentence on screen can be made to say something other than what
587
+ * happened — and the explicit bidi controls, which reorder a rendered line
588
+ * without changing a byte of it. The rest of `\p{Cf}` is admitted: the
589
+ * zero-width joiners Persian, Hindi and Bengali need, the join inside a
590
+ * multi-person emoji, a soft hyphen. Sharing the class with `displayable` is
591
+ * what keeps the boundary and the derivation saying the same thing.
592
+ *
593
+ * **Refuse, never strip.** A user typing a name is present and can be told;
594
+ * rewriting their input silently is what those same rules argue against. The
595
+ * one strip in the codebase — `displayable`, reached through
596
+ * `defaultGuidesBundleFor` in `bundleSlug.ts` — is a *derivation* with no user
597
+ * to report to, which is the exception that fixes the rule rather than a
598
+ * precedent for a second one.
599
+ *
600
+ * **Then requires one character outside `\p{Cf}`.** Admitting the joiners
601
+ * admits a name made of nothing but them, which `v.trim()` cannot see and
602
+ * `minLength(1)` counts. Such a name is refused as empty, with the same
603
+ * sentence — to the person typing it, it is a name of invisible characters
604
+ * either way.
605
+ *
606
+ * **A factory, because the max length is per-field** (64 for a workspace name,
607
+ * 200 for a bundle name) while the character rule is not. Exported rather than
608
+ * inlined so a fourth display-name field meets the rule while reading its
609
+ * neighbours — nothing enforces that it is called.
610
+ */
611
+ export function displayNameSchema(maxLength) {
612
+ return v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(maxLength), v.check((name) => !DISPLAY_NAME_REFUSED_CHARACTERS.test(name), DISPLAY_NAME_CONTROL_CHARACTER_MESSAGE), v.regex(/\P{Cf}/u, DISPLAY_NAME_CONTROL_CHARACTER_MESSAGE));
613
+ }
614
+ /** A bundle's display name. Bundles are addressed by slug; this is the label. */
615
+ export const BUNDLE_NAME_MAX_LENGTH = 200;
616
+ // ---------------------------------------------------------------------------
617
+ // Context bundle schemas
618
+ // ---------------------------------------------------------------------------
619
+ // url-safe slug, unique per user. Lowercase alphanumerics + hyphens, must start
620
+ // with an alphanumeric so it reads cleanly in a URL/path.
621
+ export const BundleSlugSchema = v.pipe(v.string(), v.check(isBundleSlug, 'slug must be lowercase alphanumeric with hyphens, at most 64 characters'));
622
+ export const BundleSchema = v.object({
623
+ id: v.string(),
624
+ slug: BundleSlugSchema,
625
+ name: v.string(),
626
+ createdAt: v.string(),
627
+ /**
628
+ * The project id of the repo that owns this bundle's items, when one claims it
629
+ * (`subscription-delivery-target-plan.md` → slice 3). Absent is the ordinary
630
+ * case: a bundle with no home is edited wherever its owner likes.
631
+ *
632
+ * A home makes the named checkout the only writer — a PR there is the review
633
+ * — and every other writer, the dashboard included, is refused by name.
634
+ *
635
+ * Optional rather than nullable so a CLI built before this field parses a new
636
+ * server's listing unchanged.
637
+ */
638
+ home: v.optional(v.string()),
639
+ });
640
+ export const BundleListResponseSchema = v.object({
641
+ bundles: v.array(BundleSchema),
642
+ });
643
+ /**
644
+ * One workspace the caller belongs to, as `GET /api/v1/workspaces` returns it.
645
+ *
646
+ * `role` is a bare string rather than an enum: the CLI only labels the row it
647
+ * offers, and a server that adds a fourth role must not break a client that
648
+ * merely prints it (`workspace-declaration` slice 1).
649
+ */
650
+ export const WorkspaceSummarySchema = v.object({
651
+ id: v.string(),
652
+ name: v.string(),
653
+ slug: v.string(),
654
+ role: v.string(),
655
+ /** The caller's personal workspace — where their rows land when nothing narrows. */
656
+ isDefault: v.boolean(),
657
+ });
658
+ export const WorkspaceListResponseSchema = v.object({
659
+ workspaces: v.array(WorkspaceSummarySchema),
660
+ });
661
+ /**
662
+ * How a bundle reaches a repo. Two scopes and no third:
663
+ *
664
+ * - `repo` — named by the committed `.mossbear/config.json`, shared with
665
+ * teammates by `git clone`.
666
+ * - `user` — recorded against the account, private, and on every machine.
667
+ *
668
+ * A bundle both scopes name carries **both** labels. An earlier shape reported a
669
+ * single winning `scope`, which made `status` and `doctor` — both of which count
670
+ * the account's subscriptions by filtering for `user` — report zero for a bundle
671
+ * that is genuinely subscribed at the account level and will keep delivering to
672
+ * every other repo. The scopes are not mutually exclusive, so the wire shape
673
+ * must not say they are. Raised by Codex on #735.
674
+ */
675
+ export const SubscriptionScopeSchema = v.picklist(['repo', 'user']);
676
+ /**
677
+ * Where a subscription's items are delivered, independent of where their source
678
+ * lives (`subscription-delivery-target-plan.md` → slice 2).
679
+ *
680
+ * - `repo` — land at the item's path in the checkout doing the sync, under the
681
+ * same git-owned write rule every project item obeys.
682
+ * - `global` — land in the machine-global namespace, unattended.
683
+ *
684
+ * **Absent is not a third value.** A subscription that names no target routes on
685
+ * the item's own `root`, which is what every subscription meant before this
686
+ * field existed — so the column and the config key are both nullable and the
687
+ * default bundle keeps behaving exactly as it does today.
688
+ */
689
+ export const DeliverTargetSchema = v.picklist(['repo', 'global']);
690
+ export const ResolvedSubscriptionSchema = v.object({
691
+ id: v.string(),
692
+ slug: BundleSlugSchema,
693
+ name: v.string(),
694
+ /** Every scope that names this bundle. Never empty; may hold both. */
695
+ scopes: v.pipe(v.array(SubscriptionScopeSchema), v.minLength(1)),
696
+ /**
697
+ * The **account** subscription's delivery target, when there is an account
698
+ * subscription and it names one.
699
+ *
700
+ * Only the account side, and deliberately so: the repo side's target lives in
701
+ * the committed `.mossbear/config.json` on the caller's own disk, which the
702
+ * server cannot read — the same asymmetry that makes this endpoint a round
703
+ * trip at all. Echoing a value the caller just sent would make the server look
704
+ * like the authority on a fact it does not hold. The caller pairs this with
705
+ * its own committed `deliver` to build the per-scope target set
706
+ * (`packages/cli/src/artifacts/delivery.ts` → `deliveryBundles`).
707
+ *
708
+ * Optional rather than nullable so a CLI built before this field parses a new
709
+ * server's response unchanged, and a new CLI reads an old server's response as
710
+ * "names no target" — which is the absent-field default either way.
711
+ */
712
+ deliver: v.optional(DeliverTargetSchema),
713
+ /**
714
+ * The bundle's home repo, when one claims it. Sent on every resolved
715
+ * subscription regardless of scope, because it is a property of the *bundle*
716
+ * rather than of either subscription — unlike `deliver`, which each scope
717
+ * answers for itself.
718
+ */
719
+ home: v.optional(v.string()),
720
+ /**
721
+ * Guide ids the **account** subscription has switched off for this subscriber
722
+ * (`subscription-delivery-target-plan.md` → slice 4).
723
+ *
724
+ * Account-scoped and nowhere else: a repo subscription is a committed file
725
+ * shared by everyone who clones it, so a mute there would be one member
726
+ * deciding for the team. A muted guide leaves the desired delivery list, and
727
+ * the global namespace prunes it once no repo still refers to it — repo by
728
+ * repo, as each syncs, because the referrer record is machine-local repo ids.
729
+ */
730
+ muted: v.optional(v.array(v.string())),
731
+ });
732
+ /**
733
+ * The ids a repo's committed config names. Sent rather than looked up, because
734
+ * the committed file is on the caller's disk and the server has no way to read
735
+ * it — that asymmetry is the whole reason delivery used to be written back into
736
+ * the repo.
737
+ */
738
+ /**
739
+ * Capped, like the other batch endpoints. The route expands this into
740
+ * `inArray(bundles.id, …)`, one Postgres bind parameter per id, and the wire
741
+ * protocol tops out at 65,535 of them — so an uncapped array lets a body well
742
+ * under the request-size limit reach the database and fail as a 500 rather than
743
+ * being refused as bad input. Raised by Codex on #735.
744
+ */
745
+ export const MAX_REPO_BUNDLE_IDS = 500;
746
+ export const ResolveSubscriptionsRequestSchema = v.object({
747
+ repoBundleIds: v.pipe(v.array(v.string()), v.maxLength(MAX_REPO_BUNDLE_IDS)),
748
+ });
749
+ export const ResolveSubscriptionsResponseSchema = v.object({
750
+ /** The effective delivery set, de-duplicated by bundle id. */
751
+ bundles: v.array(ResolvedSubscriptionSchema),
752
+ /**
753
+ * Committed ids the caller cannot see. **Reported, never dropped** — the line
754
+ * was put in the config deliberately by whoever owns the repo, so a non-member
755
+ * gets a named failure rather than deletion advice.
756
+ */
757
+ unresolved: v.array(v.object({ id: v.string() })),
758
+ /**
759
+ * Account-level settings the sync needs, carried on the response every sync
760
+ * already fetches rather than on a request of their own.
761
+ *
762
+ * `deliverGlobalSkills` is the account's "Deliver my global skills" switch:
763
+ * whether guides scoped to every repo may be written to the global skills
764
+ * directories of every machine and cloud session this account syncs. Only a
765
+ * signed-in browser session can change it; it is reported here, never
766
+ * accepted. **Optional**, so a response from a server that predates it parses,
767
+ * and the CLI reads its absence as "the server did not say", which delivers
768
+ * nothing and removes nothing.
769
+ */
770
+ account: v.optional(v.object({
771
+ deliverGlobalSkills: v.boolean(),
772
+ })),
773
+ /**
774
+ * True when the caller's token is limited to certain bundles. Such a token
775
+ * resolves only what it was granted, so an id in `unresolved` may be a bundle
776
+ * the account can reach and the token cannot. Said once for the response,
777
+ * never per id, so it confirms nothing about any one bundle. Optional: absent
778
+ * means an ordinary token, and a server that predates it never sends it.
779
+ */
780
+ limitedToken: v.optional(v.boolean()),
781
+ });
782
+ /**
783
+ * Subscribe the calling account to a bundle it can see, or change the delivery
784
+ * target of a subscription it already has.
785
+ *
786
+ * **The product path to a non-default bundle** (`subscription-delivery-target-plan.md`
787
+ * → slice 2). Before this, the only insert into `user_bundle_subscriptions` was
788
+ * the one that mints an account's own capture bundle, so an account could not
789
+ * subscribe to anything else without a hand-written row.
790
+ *
791
+ * Idempotent by the table's composite key: subscribing twice is one
792
+ * subscription, and a second call carrying a different `deliver` updates it
793
+ * rather than failing.
794
+ */
795
+ /** No account should be able to make one sync unboundedly expensive. */
796
+ export const MAX_MUTED_GUIDE_IDS = 1000;
797
+ export const SubscribeBundleRequestSchema = v.object({
798
+ bundleId: v.string(),
799
+ /**
800
+ * Where this account's subscription delivers. **Three states, and all three
801
+ * are reachable**: a value sets the target, an explicit `null` clears it back
802
+ * to "route on the item's root", and omitting the field leaves whatever is
803
+ * stored.
804
+ *
805
+ * The first shipped version made omission clear the target, so that "route on
806
+ * the item's root" would stay reachable. It made a bare re-subscribe — the
807
+ * commonest call there is — silently reset routing the caller never mentioned:
808
+ * `mossbear pull <bundle> --account` a second time would wipe a target set the
809
+ * first time, and print a success line saying nothing about it. Found by the
810
+ * automated reviewer on #1246. A nullable field reaches the same state without
811
+ * making silence mean a write.
812
+ */
813
+ deliver: v.optional(v.nullable(DeliverTargetSchema)),
814
+ /**
815
+ * The guide ids to switch off for this subscriber — the whole set, replacing
816
+ * whatever is stored. `[]` unmutes everything, and omitting the field leaves
817
+ * the stored set alone.
818
+ *
819
+ * The same three states as `deliver` above, reached the same way: an explicit
820
+ * empty clears, and silence never means a write. So changing a delivery target
821
+ * cannot unmute anything, and muting cannot move a target.
822
+ */
823
+ muted: v.optional(v.pipe(v.array(v.string()), v.maxLength(MAX_MUTED_GUIDE_IDS))),
824
+ });
825
+ export const SubscribeBundleResponseSchema = v.object({
826
+ bundleId: v.string(),
827
+ /** False when the subscription was already there and only its target moved. */
828
+ created: v.boolean(),
829
+ deliver: v.optional(DeliverTargetSchema),
830
+ /** The stored mute set after this write. Omitted when nothing is muted. */
831
+ muted: v.optional(v.array(v.string())),
832
+ });
833
+ export const CreateBundleRequestSchema = v.object({
834
+ slug: BundleSlugSchema,
835
+ name: displayNameSchema(BUNDLE_NAME_MAX_LENGTH),
836
+ // The workspace to create the bundle in. Omitted means the caller's default
837
+ // workspace; a workspace the caller is not a member of is refused.
838
+ workspaceId: v.optional(v.pipe(v.string(), v.minLength(1))),
839
+ });
840
+ export const CreateBundleResponseSchema = v.object({
841
+ bundle: BundleSchema,
842
+ });
843
+ // Scoped tokens: a CLI key limited to chosen bundles, read or write on each.
844
+ // The server enforces the limit; a key with no grants listed here is refused.
845
+ export const SCOPED_TOKEN_MAX_GRANTS = 200;
846
+ // The label becomes the API key's name, and better-auth's api-key plugin
847
+ // refuses a name longer than 32 characters — the same limit the dashboard's
848
+ // ordinary CLI-token label carries. A longer label here would pass this schema
849
+ // and then fail inside the key plugin as a server error.
850
+ export const SCOPED_TOKEN_LABEL_MAX_LENGTH = 32;
851
+ // A cap on live scoped tokens per account, so the listing stays bounded.
852
+ export const SCOPED_TOKEN_MAX_PER_ACCOUNT = 50;
853
+ export const GrantAccessSchema = v.picklist(['read', 'write']);
854
+ export const BundleGrantSchema = v.object({
855
+ bundleId: NonEmptyStringSchema,
856
+ access: GrantAccessSchema,
857
+ });
858
+ export const CreateScopedTokenRequestSchema = v.object({
859
+ label: displayNameSchema(SCOPED_TOKEN_LABEL_MAX_LENGTH),
860
+ grants: v.pipe(v.array(BundleGrantSchema), v.minLength(1), v.maxLength(SCOPED_TOKEN_MAX_GRANTS), v.check((grants) => new Set(grants.map((g) => g.bundleId)).size === grants.length, 'each bundle may be granted once')),
861
+ });
862
+ export const ScopedTokenSchema = v.object({
863
+ id: v.string(),
864
+ label: v.string(),
865
+ grants: v.array(BundleGrantSchema),
866
+ createdAt: v.string(),
867
+ /** When the key last authenticated a request; null if it never has. */
868
+ lastUsedAt: v.nullable(v.string()),
869
+ });
870
+ export const CreateScopedTokenResponseSchema = v.object({
871
+ ...ScopedTokenSchema.entries,
872
+ /** The key itself. Returned once, here, and never again. */
873
+ token: v.string(),
874
+ });
875
+ export const ListScopedTokensResponseSchema = v.object({
876
+ tokens: v.array(ScopedTokenSchema),
877
+ });
878
+ export const RevokeScopedTokenRequestSchema = v.object({
879
+ id: NonEmptyStringSchema,
880
+ });
881
+ // A membership is addressed by the artifact id alone: a guide and its body are
882
+ // one id, so no membership kind travels the wire. An older client may still send
883
+ // `itemType` on attach (or `?itemType=` on detach); this schema is not strict, so
884
+ // the field is dropped on parse rather than refused.
885
+ /**
886
+ * The member to attach, by its artifact id. `itemId` is the name a CLI from before
887
+ * release step 2 sends; both are read, and the parsed value is always `artifactId`.
888
+ * Drop `itemId` once no such CLI is left to send it.
889
+ */
890
+ /** The most artifacts one attach request may name. */
891
+ export const MAX_BUNDLE_MEMBERS_PER_ATTACH = 200;
892
+ export const AttachBundleMemberRequestSchema = v.pipe(v.object({
893
+ artifactId: v.optional(v.pipe(v.string(), v.minLength(1))),
894
+ itemId: v.optional(v.pipe(v.string(), v.minLength(1))),
895
+ // A list files them in one request and is answered per id, once for a
896
+ // repeated id (match results by `artifactId`, not by position)
897
+ // (`AttachBundleMembersResponseSchema`). The single-id forms keep their
898
+ // body and their `{ attached }` answer for CLIs that predate the list.
899
+ artifactIds: v.optional(v.pipe(v.array(v.pipe(v.string(), v.minLength(1))),
900
+ // Before the cap, so the cap counts distinct artifacts.
901
+ v.transform((ids) => [...new Set(ids)]), v.minLength(1), v.maxLength(MAX_BUNDLE_MEMBERS_PER_ATTACH))),
902
+ }), v.check((request) => request.artifactIds === undefined
903
+ ? request.artifactId !== undefined || request.itemId !== undefined
904
+ : request.artifactId === undefined && request.itemId === undefined, 'A member needs an artifactId, or a list of artifactIds on its own.'), v.transform((request) => request.artifactIds
905
+ ? { artifactIds: request.artifactIds }
906
+ : { artifactId: (request.artifactId ?? request.itemId) }));
907
+ export const AttachBundleMemberResponseSchema = v.object({
908
+ // False when the item was already a member — attach is idempotent, and the
909
+ // caller (multi-select menu applying a diff) treats both as success.
910
+ attached: v.boolean(),
911
+ });
912
+ /**
913
+ * One id's outcome in a list attach. `unavailable` is every refusal that is not
914
+ * a path collision, and reads the same whether the artifact is missing, not the
915
+ * caller's to file or in another workspace, so a list cannot probe which ids
916
+ * exist.
917
+ */
918
+ export const AttachBundleMembersResultSchema = v.object({
919
+ artifactId: v.string(),
920
+ status: v.picklist(['added', 'already_there', 'unavailable', 'path_taken']),
921
+ });
922
+ export const AttachBundleMembersResponseSchema = v.object({
923
+ results: v.array(AttachBundleMembersResultSchema),
924
+ });
925
+ export const DetachBundleMemberResponseSchema = v.object({
926
+ detached: v.boolean(),
927
+ });
928
+ /**
929
+ * The most field keys a bundle's shared column list may hold, and the longest
930
+ * one. A key is a frontmatter key as written, so the bound is on what a
931
+ * dashboard could ever show as a column rather than on any real key's length;
932
+ * both are generous enough that a refusal means a client bug.
933
+ */
934
+ export const BUNDLE_COLUMNS_MAX_COUNT = 100;
935
+ export const BUNDLE_COLUMN_KEY_MAX_LENGTH = 200;
936
+ /**
937
+ * A bundle's shared column list: field keys in display order, no key twice.
938
+ * An array that repeats a key is refused rather than deduplicated, since the
939
+ * order is the content and a client that sent one has lost track of its own
940
+ * list.
941
+ */
942
+ export const BundleColumnsSchema = v.pipe(v.array(v.pipe(v.string(), v.minLength(1), v.maxLength(BUNDLE_COLUMN_KEY_MAX_LENGTH))), v.maxLength(BUNDLE_COLUMNS_MAX_COUNT), v.check((keys) => new Set(keys).size === keys.length, 'columns must not repeat a key'));
943
+ // Rename changes the display name only. The slug is the bundle's identity —
944
+ // repos subscribe by slug in `.mossbear/config.json` → `bundles`, and
945
+ // `mossbear pull <slug>` addresses it — so a slug change would silently break
946
+ // every subscribed repo (context-bundle-authoring-plan.md → D14).
947
+ /**
948
+ * What `PATCH /api/v1/context/bundles/:id` may change: the display name, the
949
+ * home repo, the shared column list, or any of them. The slug stays immutable
950
+ * — repos address a bundle by id and name it by slug, so a slug change would
951
+ * rename a folder in every subscriber's checkout.
952
+ *
953
+ * Every field optional, with a check that at least one is present: a body that
954
+ * changes nothing is a request the caller did not mean to send, and answering it
955
+ * 200 would hide a client bug. `home: null` clears the claim, which is how a
956
+ * repo hands a bundle back — distinct from omitting the field, which leaves it.
957
+ * `columns: null` is the same for the column list: it returns the bundle to
958
+ * "not chosen", where every shared field shows.
959
+ */
960
+ export const UpdateBundleRequestSchema = v.pipe(v.object({
961
+ name: v.optional(displayNameSchema(BUNDLE_NAME_MAX_LENGTH)),
962
+ home: v.optional(v.nullable(v.pipe(v.string(), v.minLength(1), v.maxLength(200)))),
963
+ columns: v.optional(v.nullable(BundleColumnsSchema)),
964
+ }), v.check((value) => value.name !== undefined || value.home !== undefined || value.columns !== undefined, 'name, home or columns is required'));
965
+ export const UpdateBundleResponseSchema = v.object({
966
+ bundle: BundleSchema,
967
+ });
968
+ export const DeleteBundleResponseSchema = v.object({
969
+ deleted: v.boolean(),
970
+ // `movedToInbox` was removed in `inbox-as-view` slice 2. Deleting a bundle no
971
+ // longer re-parents anything: an item that loses its last membership is
972
+ // unfiled, which is what the inbox view shows, rather than stranded. The
973
+ // field could only ever have reported 0 afterwards, and a number that can
974
+ // never be non-zero is a discriminator carrying no decision. Nothing on the
975
+ // CLI wire parsed it — `parseDeleteBundleResponse` has one caller, the
976
+ // dashboard's own bundles client.
977
+ });
978
+ // ---------------------------------------------------------------------------
979
+ // Context item + inbox schemas (context-layer-mcp-inbox-plan.md — Phase 1a)
980
+ // ---------------------------------------------------------------------------
981
+ // The `type` of an item returned to an agent. A `guide` is a canonical guide
982
+ // row; the rest are guide_files rows (plain content items and assets).
983
+ //
984
+ // Derived, like the two narrowings below, from `contextKinds.ts` — the one
985
+ // table that says which kinds exist and what each may do. The values and their
986
+ // order are unchanged; `contextKinds.test.ts` pins that.
987
+ export const ContextItemTypeSchema = v.picklist(CONTEXT_ITEM_TYPES);
988
+ /**
989
+ * What a `?types=` filter parses.
990
+ *
991
+ * Equal to {@link ContextItemTypeSchema}'s values again: it was briefly wider
992
+ * so a filter written against the pre-rename vocabulary returned the kind
993
+ * those rows became rather than an empty page, and that window closed with
994
+ * the release that moved the CLI's own vocabulary onto `content`.
995
+ */
996
+ export const ContextItemTypeFilterSchema = v.picklist(CONTEXT_ITEM_TYPE_FILTER_VALUES);
997
+ // Inbox capture is text or an image today (image upload lands in Phase 2b) —
998
+ // the `capturable` column of `CONTEXT_CONTENT_KINDS`.
999
+ export const CaptureContentTypeSchema = v.picklist(CAPTURE_CONTENT_TYPES);
1000
+ export { MAX_CONTEXT_CONTENT_BYTES };
1001
+ const ContextContentSchema = v.pipe(v.string(), v.check((value) => new TextEncoder().encode(value).length <= MAX_CONTEXT_CONTENT_BYTES, `content must be at most ${MAX_CONTEXT_CONTENT_BYTES} bytes`));
1002
+ const ArtifactNameSchema = v.pipe(v.string(), v.minLength(1), v.maxLength(MAX_ARTIFACT_NAME_CHARS));
1003
+ /**
1004
+ * An artifact's description as a writer sends it: one paragraph of plain text,
1005
+ * with no line breaks or other control characters, so it saves on Enter like a
1006
+ * title, prints safely in a terminal, and stays a plain YAML
1007
+ * scalar in a Markdown artifact's frontmatter. Blank text is refused rather than
1008
+ * stored: `null` is how a description is cleared, so "none" has one shape.
1009
+ */
1010
+ export const ArtifactDescriptionSchema = v.pipe(v.string(),
1011
+ // Blank includes text made only of invisible format characters, which
1012
+ // `trim` cannot see, as `displayNameSchema` refuses a name of them.
1013
+ v.regex(/[^\s\p{Cf}]/u, 'description must not be blank'), v.maxLength(MAX_ARTIFACT_DESCRIPTION_CHARS, `description must be at most ${MAX_ARTIFACT_DESCRIPTION_CHARS} characters`),
1014
+ // The display-name class (control characters and the bidi controls, which
1015
+ // reorder a printed line), plus the two Unicode line breaks: one line, and
1016
+ // nothing a terminal printing it would act on.
1017
+ v.check((value) => !DISPLAY_NAME_REFUSED_CHARACTERS.test(value) && !/[\u2028\u2029]/.test(value), 'description must be one line of text, with no control characters'));
1018
+ // The wire ceiling for an in-place update — see UpdateContextItemRequestSchema
1019
+ // for why it is the guide bound rather than the context bound.
1020
+ const UpdatableContentSchema = v.pipe(v.string(), v.check((value) => new TextEncoder().encode(value).length <= MAX_RAW_GUIDE_CONTENT_BYTES, `content must be at most ${MAX_RAW_GUIDE_CONTENT_BYTES} bytes`));
1021
+ // The item shape returned to agents. `content` is nullable because an asset
1022
+ // stores an object key elsewhere (Phase 2b), not inline text.
1023
+ /**
1024
+ * Max alias paths one guide reports. Three root instruction files and two
1025
+ * skills directories are the whole population today
1026
+ * (`packages/protocol/src/aliasPaths.ts`); the cap is a wire bound, not a
1027
+ * product limit, and exists so a corrupt row cannot make one item unbounded.
1028
+ */
1029
+ export const MAX_GUIDE_ALIASES = 8;
1030
+ /**
1031
+ * One `(root, path)` a guide is *also* held at. Same two fields, same
1032
+ * narrowing, as the item's own scope pair — an alias is a projection target,
1033
+ * not a second kind of location.
1034
+ */
1035
+ export const GuideAliasSchema = v.object({
1036
+ root: GuideDiscoveryRootSchema,
1037
+ path: SafeRelativePosixPathSchema,
1038
+ });
1039
+ /**
1040
+ * The markers every untrusted block in a response is wrapped in, plus a
1041
+ * statement of what they mean.
1042
+ *
1043
+ * Generated per response from the content itself, so no marker-like text
1044
+ * inside a block can end it early — a property `deriveDelimiterToken` checks
1045
+ * rather than assumes.
1046
+ *
1047
+ * Named for the guide-history response it was written for and shared by every
1048
+ * payload that places somebody else's words in front of an agent: a grade's
1049
+ * reasoning, and now an item's comments. One marker scheme, not one per payload —
1050
+ * a second scheme is a second thing a reader has to be taught to respect.
1051
+ * Declared here, above its first user, rather than beside that response.
1052
+ */
1053
+ export const GuideHistoryUntrustedSchema = v.object({
1054
+ token: NonEmptyStringSchema,
1055
+ startMarker: NonEmptyStringSchema,
1056
+ endMarker: NonEmptyStringSchema,
1057
+ note: v.string(),
1058
+ });
1059
+ /**
1060
+ * How many open comments one item carries on the wire, newest first.
1061
+ *
1062
+ * A wire bound, not a product limit: the write side refuses the comment that
1063
+ * would exceed it *by name* (see the dashboard's note mutator), so this cap is
1064
+ * never the thing that silently drops a comment a person left.
1065
+ */
1066
+ export const MAX_ITEM_COMMENTS_ON_WIRE = 20;
1067
+ /**
1068
+ * How many replies one delivered thread carries, the newest kept. A thread past
1069
+ * it says how many it held back (`repliesWithheld`), so a cut is never silent.
1070
+ */
1071
+ export const MAX_REPLIES_PER_THREAD_ON_WIRE = 10;
1072
+ /**
1073
+ * The most entries one item's `comments` can hold once threads ride it: a
1074
+ * person's allowance of roots plus an agent's own, each followed by its replies.
1075
+ * A client that does not render threads is sent roots alone, which stay within
1076
+ * `MAX_ITEM_COMMENTS_ON_WIRE`.
1077
+ */
1078
+ export const MAX_ITEM_THREAD_ENTRIES_ON_WIRE = 2 * MAX_ITEM_COMMENTS_ON_WIRE * (1 + MAX_REPLIES_PER_THREAD_ON_WIRE);
1079
+ /**
1080
+ * Who wrote a comment. An agent writes under its person's account, so the
1081
+ * author's name alone cannot tell a person's answer from an agent's message.
1082
+ */
1083
+ export const CommentAuthorKindSchema = v.picklist(['person', 'agent', 'mossbear']);
1084
+ /** What a finding rests on: graded sessions, how loads read a skill, or the rubric alone. */
1085
+ export const FindingTierSchema = v.picklist(['observed', 'usage', 'practice']);
1086
+ /**
1087
+ * What a Mossbear finding carries on the comment read, besides its claim.
1088
+ *
1089
+ * `tierLine` and `blindSpot` are written by the server from data it holds —
1090
+ * the cited sessions, the load counts, the rubric check — never by a model, so
1091
+ * they sit outside the response's untrusted markers. `prediction` is
1092
+ * model-authored and arrives inside them. A finding never carries replacement
1093
+ * text: the reader's agent has the repository and writes the fix.
1094
+ */
1095
+ export const CommentFindingSchema = v.object({
1096
+ tier: FindingTierSchema,
1097
+ /** How the finding is known, in one line: "Seen in 3 sessions (2026-09-15 – 2026-10-03)". */
1098
+ tierLine: v.pipe(v.string(), v.maxLength(300)),
1099
+ /** What the drafter did not read, fixed per tier. */
1100
+ blindSpot: v.pipe(v.string(), v.maxLength(300)),
1101
+ /** What should change in later sessions if the finding is fixed, wrapped in the untrusted markers. */
1102
+ prediction: v.nullable(v.string()),
1103
+ });
1104
+ /**
1105
+ * One comment a **person** left about a context item, riding the item it is about.
1106
+ *
1107
+ * A comment is not an item: it is not a member, not projected, not versioned and
1108
+ * not capturable. It travels on the item so that it inherits every delivery
1109
+ * decision the item already went through — workspace scope, the archived drop,
1110
+ * the response limit, the subscriber's mute — rather than restating them.
1111
+ *
1112
+ * **Every `body` here is already wrapped in the response's untrusted markers**
1113
+ * (`ContextItemsResponseSchema.untrusted`). A reader emits the bytes as it
1114
+ * received them and never re-wraps them: the markers are derived against the
1115
+ * bodies the server sent, so a second wrapping cannot claim the same guarantee.
1116
+ */
1117
+ export const ArtifactCommentSchema = v.object({
1118
+ id: NonEmptyStringSchema,
1119
+ state: v.optional(v.picklist(['open', 'resolved'])),
1120
+ /** Current source location of an anchored passage, or its lost quote. */
1121
+ passage: v.optional(v.object({
1122
+ quote: v.string(),
1123
+ status: v.picklist(['located', 'changed', 'orphaned']),
1124
+ lines: v.nullable(v.object({ start: v.number(), end: v.number() })),
1125
+ })),
1126
+ /** The comment's text, already wrapped in the response's untrusted markers. */
1127
+ body: v.string(),
1128
+ /**
1129
+ * What a comment Mossbear wrote is: a finding about the item, never an edit.
1130
+ * Present only on a Mossbear comment. The comment's `body` begins with the
1131
+ * claim (what goes wrong); this carries what the claim rests on.
1132
+ */
1133
+ finding: v.optional(CommentFindingSchema),
1134
+ /**
1135
+ * Whether the person approved a comment Mossbear drafted. Present on every
1136
+ * Mossbear comment and absent on a person's or an agent's, which are
1137
+ * requests as written. `false` is a draft nobody has read yet: a reader shows
1138
+ * it to the user and acts only on their go-ahead. Only a client that reports
1139
+ * a version able to mark drafts is ever listed one, so an older reader that
1140
+ * strips this field never receives a draft it would print as a request.
1141
+ */
1142
+ approved: v.optional(v.boolean()),
1143
+ /** The author's display name as the workspace shows it, or null. Never an email. */
1144
+ authorName: v.nullable(v.string()),
1145
+ /**
1146
+ * Who wrote it. Optional because a server that predates the field omits it;
1147
+ * a reader that meets a reply without it cannot tell whose it is, and a
1148
+ * server never sends a reply to a client too old to read this.
1149
+ */
1150
+ authorKind: v.optional(CommentAuthorKindSchema),
1151
+ /** ISO timestamp, machine format. */
1152
+ createdAt: v.string(),
1153
+ /** The item's content version the comment was written against. */
1154
+ itemVersion: v.number(),
1155
+ /** True when the item's current version is greater than `itemVersion`. */
1156
+ itemChangedSince: v.boolean(),
1157
+ /**
1158
+ * How many agent reads were handed this comment **before** this one — so a
1159
+ * comment reaching an agent for the first time reports `0`.
1160
+ *
1161
+ * It is the stored count as it read at the moment the response was built;
1162
+ * the serve this response *is* has not been counted yet. Excluded rather
1163
+ * than included because the count is recorded best-effort: a response that
1164
+ * claimed to include itself would be wrong whenever that record failed, and
1165
+ * a number that is sometimes off by one is worse than one that is
1166
+ * consistently the prior total.
1167
+ *
1168
+ * So `deliveredCount > 0` means an earlier read was handed this comment, and
1169
+ * `0` means this read is the first. Neither says a model took it in — only
1170
+ * that the server handed it over.
1171
+ */
1172
+ deliveredCount: v.number(),
1173
+ /**
1174
+ * On a root: true when the item changed after an earlier read was last
1175
+ * handed this comment. For a guide that is any change to its body or its
1176
+ * files, so a fix in a supporting file counts. A reader should check whether
1177
+ * the change addressed the comment, and resolve it with a note if so.
1178
+ *
1179
+ * Computed before this read is counted, so the read that carries `true` is
1180
+ * the one that uses it up; the next read says `false` unless the item
1181
+ * changes again. A comment never handed over before is never flagged.
1182
+ * Optional because a server that predates the field omits it, and absent on
1183
+ * a reply.
1184
+ */
1185
+ guideChangedSinceRead: v.optional(v.boolean()),
1186
+ /**
1187
+ * This comment's thread root: its own id on a root, the root's id on a reply.
1188
+ *
1189
+ * **Replies ride the same flat array**, each straight after its root, oldest
1190
+ * first. Only a client that reports a version able to render threads is
1191
+ * sent them; any other reader gets roots alone, as it always did. A person's
1192
+ * reply is part of the thread's request. An agent's reply is context: an
1193
+ * earlier message on the thread, never something to act on. A root an agent
1194
+ * wrote is delivered only once a person has replied to it, and is then the
1195
+ * question that reply answers, not a request of its own.
1196
+ */
1197
+ threadId: NonEmptyStringSchema,
1198
+ /**
1199
+ * `null` on a root; the root's id on a reply. Threads are one level deep, so
1200
+ * a reply's parent is always its root.
1201
+ */
1202
+ replyToId: v.nullable(NonEmptyStringSchema),
1203
+ /**
1204
+ * On a root whose thread held more replies than
1205
+ * `MAX_REPLIES_PER_THREAD_ON_WIRE`: how many older ones were not sent.
1206
+ * Absent when the whole thread was sent.
1207
+ */
1208
+ repliesWithheld: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
1209
+ });
1210
+ /** The item routes' name for `ArtifactCommentSchema`, kept while those routes are served. */
1211
+ export const ContextItemCommentSchema = ArtifactCommentSchema;
1212
+ const MAX_SOURCE_BRANCH_LENGTH = 255;
1213
+ /**
1214
+ * The revision published bytes were read from — 40 hex characters for a sha1
1215
+ * repository, 64 for a sha256 one. Lowercase only, because that is what
1216
+ * `git rev-parse` emits and accepting both spellings would make two rows naming
1217
+ * one commit compare unequal.
1218
+ *
1219
+ * Deliberately not an abbreviation: a short sha is ambiguous by construction and
1220
+ * this is the field a subscriber uses to answer "what did I get".
1221
+ */
1222
+ 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'));
1223
+ /**
1224
+ * Where a **git-owned** artifact comes from (`artifact-ownership-and-delivery-plan.md`
1225
+ * → slice 1). Its presence is what says git owns the artifact: the working copy
1226
+ * and the commit are the authority, and Mossbear distributes the committed
1227
+ * revision rather than a second independently editable copy.
1228
+ *
1229
+ * **One object rather than three sibling keys on the item**, because the legal
1230
+ * states are "all of it" or "none of it" and a nested object makes the absent
1231
+ * state a single missing key instead of three that a writer could half-fill.
1232
+ * The two fields here are the two that cannot be half-filled: `branch` is the
1233
+ * one optional member, so an object with a repo and a revision is always a
1234
+ * complete source.
1235
+ *
1236
+ * **The source path is not here.** The item's own `path` is the repo-relative
1237
+ * path, and it is a required member of the subset — but the requirement is held
1238
+ * by the database, not restated here; see `gitSource` on `ContextItemSchema`
1239
+ * below for why a wire rule that looked identical would not be. What matters at
1240
+ * this layer is that there is only ever one path, never a source path beside a
1241
+ * projection path that publication and delivery could disagree about.
1242
+ */
1243
+ export const GitSourceSchema = v.object({
1244
+ /**
1245
+ * The committed `project.id` of the source repository — the same id space as
1246
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
1247
+ * says which repo an item is materialized into and is stamped onto
1248
+ * Mossbear-owned rows too, this one says who may edit it.
1249
+ */
1250
+ projectId: ProjectIdSchema,
1251
+ commitSha: CommitShaSchema,
1252
+ /**
1253
+ * The branch the publishing commit was on. **The one optional member**: a
1254
+ * detached HEAD has none to record. Publishers read it back to tell a copy
1255
+ * from another branch, whose commit a squash merge may have discarded, from
1256
+ * one of the published branch itself.
1257
+ */
1258
+ branch: v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(MAX_SOURCE_BRANCH_LENGTH))),
1259
+ });
1260
+ const ContextItemObjectSchema = v.object({
1261
+ id: v.string(),
1262
+ /**
1263
+ * The id every artifact route addresses: the body file's id for a guide
1264
+ * (null only for a guide with no body yet), the item's own id otherwise.
1265
+ * Optional so a client tolerates a server that predates it, and one that
1266
+ * stops sending it (the item id is the artifact id).
1267
+ */
1268
+ artifactId: v.optional(v.nullable(v.string())),
1269
+ /**
1270
+ * Leaving the wire: a reader tells a guide from content by `role` and the
1271
+ * guide fields, not by this. Optional so a client parses a server that no
1272
+ * longer sends it.
1273
+ */
1274
+ type: v.optional(ContextItemTypeSchema),
1275
+ name: v.string(),
1276
+ /**
1277
+ * The stored `(role, format)` pair, as two bare nullable strings.
1278
+ *
1279
+ * **Both are deliberately unenumerated.** A client switches on one value it
1280
+ * cares about — `role === 'criteria'` is how a rubric is told from ordinary
1281
+ * prose, which `type` cannot say because a rubric serializes as a `document` —
1282
+ * and a server that adds a fourth role or a fifth format must not break a
1283
+ * client that has never heard of it. Narrowing them here would make every such
1284
+ * addition a breaking wire change for no reader's benefit.
1285
+ *
1286
+ * Null on exactly the rows that carry no content: a tombstone, and an alias.
1287
+ * A `guide` item has no pair at all — it is a different table — and reports
1288
+ * both as null.
1289
+ */
1290
+ role: v.nullable(v.string()),
1291
+ format: v.nullable(v.string()),
1292
+ content: v.nullable(v.string()),
1293
+ /**
1294
+ * What a person or their agent says about the artifact, as plain text: for
1295
+ * Markdown its frontmatter `description`, repeated from `content`, and for
1296
+ * any other kind (a photo) the one place it is. Data, never instructions.
1297
+ * Absent when there is none, and from a server that predates it.
1298
+ */
1299
+ description: v.optional(v.nullable(v.string())),
1300
+ /** Set when the item is a photo: its stored parts, never their bytes. */
1301
+ asset: v.optional(v.nullable(PhotoAssetSchema)),
1302
+ origin: v.optional(v.nullable(v.string())),
1303
+ // Monotonic content version of the underlying doc (guide_files), surfaced so a
1304
+ // caller can echo it back as an expected-version precondition. See
1305
+ // doc-version-history-plan.md.
1306
+ //
1307
+ // A `guide` item reports the version of its **body item** — the guide_files
1308
+ // row holding its content, which shares the guide's id
1309
+ // (`guide-versioned-identity-plan.md` → Decision 1). That is the row a guide
1310
+ // push updates, so the precondition a caller echoes back is checked against
1311
+ // the same counter it read. Guides carried no version until slice 2b-B, which
1312
+ // is why this stays optional: an item reported without one has no version to
1313
+ // echo, and the CLI declines to push it rather than falling back to
1314
+ // last-write-wins.
1315
+ version: v.optional(v.number()),
1316
+ // Scope root and path, mirroring `GuideSnapshotSchema` — the docs phase
1317
+ // projects an item onto disk, and without a root it resolved every one of
1318
+ // them against the repo checkout. Every member kind carries the pair: a
1319
+ // `guide` since #543, and a `guide_file` member — documents included — since
1320
+ // `unified-item-sync` put the columns on the wire and `docs-in-place` slice 0
1321
+ // made the docs phase land a document at its own declared path rather than in
1322
+ // the bundle directory. The same optional/nullable rule applies throughout:
1323
+ // absent means "no declared path", which degrades to the origin-derived
1324
+ // projection (guides) or the bundle-directory default (documents) rather than
1325
+ // failing.
1326
+ /**
1327
+ * The guide a **derived** item belongs to — its evaluation criteria, or a
1328
+ * skill's member files (`subscription-delivery-target-plan.md` → slice 4).
1329
+ *
1330
+ * Absent on everything else, including a guide itself: a guide member is
1331
+ * addressed by the guide's own id, so `id` already answers this for it.
1332
+ *
1333
+ * It exists because derived items have no bundle membership and no id of their
1334
+ * guide's — they are `guide_files` rows attached by `guide_id` — so a rule
1335
+ * expressed over guide ids (a subscriber's mute) cannot reach them from the
1336
+ * item alone. Muting a skill and still delivering its `scripts/` would leave a
1337
+ * broken half-skill on disk, which is worse than not muting at all.
1338
+ */
1339
+ guideId: v.optional(v.nullable(v.string())),
1340
+ root: v.optional(v.nullable(GuideDiscoveryRootSchema)),
1341
+ path: v.optional(v.nullable(SafeRelativePosixPathSchema)),
1342
+ // The portable identity of the project this item belongs to — the `project.id`
1343
+ // a repo commits to `.mossbear/config.json` (`packages/cli/src/artifacts/repo-config.ts:302-315`).
1344
+ // A project-scoped item carrying one belongs to *that* repo and nowhere else,
1345
+ // which is what lets the docs phase stop materializing a guide from repo X
1346
+ // into repo Z (`project-scope-git-owned-plan.md` → Approach 1).
1347
+ //
1348
+ // Optional and nullable, and both nulls mean the same thing: **no declaration
1349
+ // to compare against**, never "belongs to no project". The server's guide
1350
+ // table gained its project column late, so every guide imported before it
1351
+ // carries NULL, and a `guide_file` member has no project column at all. The
1352
+ // import contract closes that gap without a backfill: reconcile stamps the id
1353
+ // onto any row it resolves — including one it found through the older,
1354
+ // machine-local checkout scope — and only ever sets it, never clears it, so a
1355
+ // repo converges onto the portable key one edited file at a time. That is why
1356
+ // a reader treats an absent id as "deliver as before" rather than as a
1357
+ // mismatch: the state is transient by construction, and refusing on it would
1358
+ // stop delivering guides the user has been getting all along.
1359
+ projectId: v.optional(v.nullable(v.string())),
1360
+ /**
1361
+ * The repo a **document's** declared `path` is placed in — its home — as the
1362
+ * `project.id` of the checkout that last set the path. Documents only.
1363
+ *
1364
+ * Deliberately not `projectId` above: a reader takes a mismatch there as "this
1365
+ * item belongs to another repo, do not materialize it", so a home echoed on it
1366
+ * would stop every other subscriber receiving the document at all. A home says
1367
+ * only *where* the path is literal. Only the repo whose `project.id` matches
1368
+ * writes the document at `path`; every other repo mirrors it under the
1369
+ * bundle folder (`bundleMirrorPath` in `@mossbear/projections`).
1370
+ *
1371
+ * Absent and null read the same — **no home**, so no repo takes the path
1372
+ * literally for a new placement. A server predating the field says the same,
1373
+ * which is the safe direction: the file lands inside the bundle folder
1374
+ * instead of at a repo path it may not belong in.
1375
+ */
1376
+ pathProjectId: v.optional(v.nullable(v.string())),
1377
+ // Every **other** path this guide is held at in the repo it came from — the
1378
+ // alias rows on one guide (`alias-instruction-file-identity-plan.md` →
1379
+ // Decision 1, and the 2026-09-03 addendum's "the planner has to be told which
1380
+ // paths to derive").
1381
+ //
1382
+ // The body item's own `(root, path)` above is the source; these are the
1383
+ // mirrors derived from it locally. The pair is on the wire because local
1384
+ // discovery cannot supply it: which paths a guide is aliased at is a fact
1385
+ // about the merge the server performed, not about what this checkout happens
1386
+ // to hold — a repo that has not yet created its `CLAUDE.md` still gets told
1387
+ // the guide is aliased there.
1388
+ //
1389
+ // Optional and empty-able: absent means "no aliases reported", which is what
1390
+ // a server predating this field says and what an unaliased guide says. Both
1391
+ // read the same way — derive nothing — so the CLI needs no third case.
1392
+ aliases: v.optional(v.pipe(v.array(GuideAliasSchema), v.maxLength(MAX_GUIDE_ALIASES))),
1393
+ /**
1394
+ * Open comments a person left about this item, newest first.
1395
+ *
1396
+ * Optional, and absent rather than empty when there are none — the same rule
1397
+ * `aliases` and `projectId` follow above, and for the same reason: an older
1398
+ * reader against a newer server ignores the key, and a newer reader against
1399
+ * an older server reads "no comments" instead of failing.
1400
+ *
1401
+ * **Absence is not a verdict.** No comments here means none were served on this
1402
+ * item in this response — not that nobody has anything to say about it.
1403
+ */
1404
+ comments: v.optional(v.pipe(v.array(ArtifactCommentSchema), v.maxLength(MAX_ITEM_THREAD_ENTRIES_ON_WIRE))),
1405
+ updatedAt: v.string(),
1406
+ /**
1407
+ * Present iff this artifact is owned by git. Absent means Mossbear owns it
1408
+ * and it is editable in the dashboard.
1409
+ *
1410
+ * **Optional, and absence is not yet a verdict.** Nothing writes this before
1411
+ * `publish` ships, so today every item omits it, and the existing bundle-home
1412
+ * rule — a bundle may name one repo as its only writer, and the server
1413
+ * refuses every other writer by name — is what still protects items a repo
1414
+ * already owns. A reader must not treat an absent `gitSource` as permission
1415
+ * to publish back.
1416
+ *
1417
+ * **Optional *and* nullable, like every other late-added column on this item.**
1418
+ * A serializer that maps the columns straight through emits `null` for a
1419
+ * Mossbear-owned row, and a key that only accepted `undefined` would throw on
1420
+ * the whole response rather than on the one item — `parseContextItemsResponse`
1421
+ * parses a pull as a batch. Both spellings read the same way: no git source.
1422
+ *
1423
+ * **`path` is the third required member of the subset and is not re-checked
1424
+ * here.** The database holds that invariant
1425
+ * (`guide_files_git_source_subset`), and a wire rule that looked identical
1426
+ * would in fact be stricter: `path` is serialized through a scope helper that
1427
+ * emits `null` for a path this schema cannot parse, so a single such row would
1428
+ * fail every other item in the same pull. A git-owned item that arrives
1429
+ * without a usable path is a broken item, not a broken response.
1430
+ */
1431
+ gitSource: v.optional(v.nullable(GitSourceSchema)),
1432
+ /**
1433
+ * This artifact is a **tombstone**: the repository that publishes it deleted
1434
+ * the file, so what the item still carries is the last revision rather than a
1435
+ * current one (`artifact-ownership-and-delivery-plan.md` → D28).
1436
+ *
1437
+ * **It is still delivered, and that is deliberate.** Dropping the item from
1438
+ * the response would say the same thing more quietly and cost two things
1439
+ * worth more than the byte: the publishing repo would lose the id it needs to
1440
+ * republish the path in place — re-adding a deleted file would create a
1441
+ * second artifact at the same path rather than a new revision of the one
1442
+ * that is there — and a reader would be left unable to tell a removal from
1443
+ * a bundle it has stopped being able to see. What the flag asks of a client
1444
+ * is one thing: do not materialize it. A file left at a discovery root keeps
1445
+ * feeding deleted guidance into every agent that reads that repo, which is
1446
+ * the failure the decision exists to stop.
1447
+ *
1448
+ * **Optional, and absent means an ordinary artifact.** A client that has
1449
+ * never heard of it behaves as it always did — it keeps the last published
1450
+ * revision on disk, which is the retain behaviour this replaces rather than a
1451
+ * new failure. That is what makes the server safe to ship first.
1452
+ *
1453
+ * `literal(true)` rather than a boolean: `removed: false` would be a second
1454
+ * spelling of absence, and an artifact that came back is content again rather
1455
+ * than a tombstone that says no.
1456
+ */
1457
+ removed: v.optional(v.literal(true)),
1458
+ /**
1459
+ * This guide is switched off. Served only to a read that asked for the
1460
+ * bundle's inventory (`inactive=include`), which the publishers make so a
1461
+ * switched-off guide is updated in place rather than created again. Every
1462
+ * other read omits switched-off guides, so a reader that ignores this key is
1463
+ * never handed one.
1464
+ */
1465
+ inactive: v.optional(v.literal(true)),
1466
+ /**
1467
+ * Beside `inactive` only: publication switched this guide off because the
1468
+ * published branch deleted its file, so publishing that file again switches
1469
+ * it back on. A switched-off guide without it was switched off by a person,
1470
+ * and publication leaves it off — re-sending its unchanged bytes would be a
1471
+ * write with nothing to do.
1472
+ */
1473
+ retiredByPublication: v.optional(v.literal(true)),
1474
+ });
1475
+ /**
1476
+ * A bundle read's item. `type` is filled in from the rest of the item when the
1477
+ * server no longer sends it (`contextItemTypeOf`), so every reader keeps one
1478
+ * answer to "is this a guide" whichever server it is talking to.
1479
+ */
1480
+ export const ContextItemSchema = v.pipe(ContextItemObjectSchema, v.transform((item) => ({ ...item, type: contextItemTypeOf(item) })));
1481
+ export const ContextItemsResponseSchema = v.object({
1482
+ items: v.array(ContextItemSchema),
1483
+ /**
1484
+ * The markers every comment `body` in this response is wrapped in, plus a
1485
+ * statement of what they mean. Present exactly when at least one item
1486
+ * carries a comment — there is nothing to delimit otherwise.
1487
+ */
1488
+ untrusted: v.optional(v.nullable(GuideHistoryUntrustedSchema)),
1489
+ });
1490
+ /**
1491
+ * The bundle pull under its artifact name: the same members and comments as
1492
+ * {@link ContextItemsResponseSchema}, under `artifacts`.
1493
+ */
1494
+ export const BundleArtifactsResponseSchema = v.object({
1495
+ artifacts: v.array(ContextItemSchema),
1496
+ untrusted: v.optional(v.nullable(GuideHistoryUntrustedSchema)),
1497
+ });
1498
+ /**
1499
+ * How many bundles one comments read may name.
1500
+ *
1501
+ * A repo's delivery set is the union of its committed subscriptions and the
1502
+ * reader's account ones, so this bounds a request, not a product limit: a
1503
+ * reader subscribing to more bundles than this asks in two calls rather than
1504
+ * losing the tail silently.
1505
+ */
1506
+ export const MAX_COMMENT_BUNDLE_IDS = 100;
1507
+ /**
1508
+ * `POST /api/v1/context/comments/resolve`: close one open comment and leave the
1509
+ * agent's note as a reply in its thread.
1510
+ *
1511
+ * **Two ways to find the comment, never both at once.** Without `artifactId`,
1512
+ * the id is looked up among the comments the named bundles deliver, which is
1513
+ * what `list_comments` listed. With it, the id is looked up among that one
1514
+ * artifact's open comments, which is what its feedback read listed, after the
1515
+ * same read check that read makes. A request with `artifactId` does not fall
1516
+ * back to the bundles when the id is not on that artifact.
1517
+ */
1518
+ export const ResolveItemCommentRequestSchema = v.object({
1519
+ /** The comment's id, or a unique prefix of it as a read printed it. */
1520
+ id: v.pipe(v.string(), v.minLength(1), v.maxLength(128)),
1521
+ /** One line, kept in the thread as the agent's reply. */
1522
+ note: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(500), v.regex(/^[^\r\n]+$/)),
1523
+ /** The bundles this repo receives. Ignored when `artifactId` is sent. */
1524
+ bundleIds: v.optional(v.pipe(v.array(NonEmptyStringSchema), v.maxLength(MAX_COMMENT_BUNDLE_IDS)), []),
1525
+ /** The artifact the comment is on, as its feedback read was asked for it. */
1526
+ artifactId: v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(128))),
1527
+ /**
1528
+ * The reader's repo, as its committed `project.id`. A comment drafted from
1529
+ * one repo's corrections is listed only to a read that declares that repo,
1530
+ * so it is resolvable only by one that declares it too.
1531
+ */
1532
+ projectId: v.optional(ProjectIdSchema),
1533
+ /** The CLI's version, so a draft resolves only for a client that marks drafts. */
1534
+ cliVersion: v.optional(v.pipe(v.string(), v.maxLength(64))),
1535
+ });
1536
+ /** A resolve the server carried out. Every refusal is an error response instead. */
1537
+ export const ResolveItemCommentResponseSchema = v.object({
1538
+ resolved: v.literal(true),
1539
+ });
1540
+ /**
1541
+ * How many times one subscriber is told, in one repo, that a given comment is
1542
+ * waiting before the hook falls silent about it.
1543
+ *
1544
+ * **A cap on the interruption, never on the comment.** After it is reached the
1545
+ * comment is still open, still on the item page, and still returned in full by
1546
+ * the on-demand read — it simply stops being announced in front of the first
1547
+ * turn of every session. So silence here means "nothing new to interrupt you
1548
+ * about", never "nobody left anything".
1549
+ *
1550
+ * Three rather than one, for the reason the announcement exists: the first
1551
+ * session in a repo is often doing unrelated work, so a one-shot announcement
1552
+ * would routinely spend itself on the session least likely to act. Three is a
1553
+ * judgement, named so replacing it is one edit — the same discipline the live
1554
+ * session window is held to.
1555
+ */
1556
+ export const MAX_COMMENT_ANNOUNCEMENTS_PER_REPO = 3;
1557
+ /**
1558
+ * Ask which comments are waiting for this reader in this repo, and be counted as
1559
+ * told.
1560
+ *
1561
+ * **A write, because being told is a fact the server has to keep.** The count
1562
+ * cannot be `item_comments.delivered_count` — that is one global number across
1563
+ * every subscriber and every repo, so one reader's fill of a comment would
1564
+ * silence it for everyone — and it cannot live in the checkout, because the
1565
+ * disposable environments this exists for rebuild the clone every session and
1566
+ * a counter there resets with it, announcing every unresolved comment as new
1567
+ * forever.
1568
+ */
1569
+ export const AnnounceItemCommentsRequestSchema = v.object({
1570
+ /**
1571
+ * The repo, as its committed config declares it. Required: it is the scope
1572
+ * the count is kept under, and a request with nothing to key on could only
1573
+ * be answered by an uncapped announcement — which is the repeating broadcast
1574
+ * this route exists to end.
1575
+ */
1576
+ projectId: ProjectIdSchema,
1577
+ /**
1578
+ * The bundles this repo receives — the union the caller already resolved.
1579
+ *
1580
+ * Sent rather than derived, because only half of it is the server's to know:
1581
+ * a repo-scoped subscription lives in the committed config and travels by
1582
+ * `git clone`. Declaring a bundle grants nothing: every one of them is still
1583
+ * filtered by the caller's own workspace membership.
1584
+ */
1585
+ bundleIds: v.pipe(v.array(NonEmptyStringSchema), v.maxLength(MAX_COMMENT_BUNDLE_IDS)),
1586
+ /**
1587
+ * The release asking. A person's reply on a thread counts as waiting only
1588
+ * for a release that renders threads; without it the answer is the roots-only
1589
+ * count every older release was given.
1590
+ */
1591
+ cliVersion: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(64))),
1592
+ });
1593
+ /**
1594
+ * What an announcement answers: how many comments are waiting, and how many of
1595
+ * them this call was counted as announcing.
1596
+ *
1597
+ * **Two numbers because they answer two questions and a reader needs both.**
1598
+ * `open` is the true state of this repo's comments and is what a caller shows a
1599
+ * person — a number that is sometimes a subset of the truth would be worse
1600
+ * than the silence it replaced. `announced` is how many of those were still
1601
+ * under the cap, and it is the one that decides whether to speak at all: zero
1602
+ * means this reader has already been told about every one of them as often as
1603
+ * the cap allows.
1604
+ */
1605
+ export const AnnounceItemCommentsResponseSchema = v.object({
1606
+ /** Open, unmuted comments about the items these bundles deliver to this reader. */
1607
+ open: v.pipe(v.number(), v.integer(), v.minValue(0)),
1608
+ /** How many of those were under the cap and have now been counted as announced. */
1609
+ announced: v.pipe(v.number(), v.integer(), v.minValue(0)),
1610
+ });
1611
+ /**
1612
+ * How many comments one agent session may leave on one subject, not counting its
1613
+ * whole-subject comment. Anchored comments and replies share it.
1614
+ */
1615
+ export const MAX_AGENT_COMMENTS_PER_SUBJECT = 50;
1616
+ /** The longest an agent comment's text may be, in characters. */
1617
+ export const MAX_AGENT_COMMENT_BODY_CHARS = 4000;
1618
+ /**
1619
+ * Why an agent comment was refused, as the `code` on the error body. A caller
1620
+ * branches on these; the message beside one is for a person.
1621
+ */
1622
+ export const AGENT_COMMENT_ERROR_CODES = [
1623
+ /** The request named no agent session. The CLI never makes one up. */
1624
+ 'agent_session_required',
1625
+ /** This agent session has used its comments on the subject. */
1626
+ 'agent_comment_limit_reached',
1627
+ /** An agent comment is text only: it may not carry replacement text. */
1628
+ 'agent_comment_text_only',
1629
+ /** The subject or comment is not one this account can comment on. */
1630
+ 'agent_comment_target_missing',
1631
+ /** A comment names a passage that is not whole lines of the item as it is now. */
1632
+ 'agent_comment_passage_not_found',
1633
+ /** The passage appears more than once, so which one is meant is unknown. */
1634
+ 'agent_comment_passage_ambiguous',
1635
+ /** The item already carries as many open comments as it may. */
1636
+ 'item_comment_limit_reached',
1637
+ ];
1638
+ export const AgentCommentErrorCodeSchema = v.picklist(AGENT_COMMENT_ERROR_CODES);
1639
+ const AgentCommentTargetIdSchema = v.pipe(v.string(), v.minLength(1), v.maxLength(128));
1640
+ /**
1641
+ * Leave a comment, or reply to one, as an agent (`POST /api/v1/context/comments`).
1642
+ *
1643
+ * **`target` names what the comment is about, one way.** `artifact` is the id
1644
+ * a bundle read gave for a guide or document, and `item` is its older name for
1645
+ * the same thing, accepted until every client sends `artifact`. `session` is an
1646
+ * agent session id of the caller's own (the key a search hit and the session digest hand out), and
1647
+ * `reply` is the id of a comment to answer. A reply joins that comment's thread
1648
+ * and the subject it is about.
1649
+ *
1650
+ * **Who the agent is comes from `agent`, and `sessionId` is the harness's own
1651
+ * id as the CLI read it.** A request without one is refused with
1652
+ * `agent_session_required`, and the CLI and tool offer no way to type one. The
1653
+ * server cannot check it against the harness, so it is a claim by the holder of
1654
+ * the token: the comment is always written under that token's account, and the
1655
+ * handle shown for it names a session only as far as the claim is true.
1656
+ *
1657
+ * **Text only.** There is no replacement-text field, and a request that carries
1658
+ * one is refused with `agent_comment_text_only` rather than having it dropped.
1659
+ */
1660
+ export const AgentCommentRequestSchema = v.object({
1661
+ target: v.variant('kind', [
1662
+ v.object({ kind: v.literal('artifact'), id: AgentCommentTargetIdSchema }),
1663
+ v.object({ kind: v.literal('session'), id: AgentCommentTargetIdSchema }),
1664
+ v.object({ kind: v.literal('reply'), id: AgentCommentTargetIdSchema }),
1665
+ ]),
1666
+ body: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(MAX_AGENT_COMMENT_BODY_CHARS)),
1667
+ /**
1668
+ * The passage an item comment is about, as the exact text of one or more whole
1669
+ * lines of the item (a paragraph, a heading, a list). None means the item as a
1670
+ * whole. The server finds the lines; a passage that is not in the item as it is
1671
+ * now is refused with `agent_comment_passage_not_found`.
1672
+ */
1673
+ passage: v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(8000))),
1674
+ agent: v.object({
1675
+ sessionId: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(128)),
1676
+ harness: HarnessIdSchema,
1677
+ /** The agent's own statement of its model, when it knows it. */
1678
+ model: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(100))),
1679
+ cliVersion: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(64))),
1680
+ }),
1681
+ /**
1682
+ * The reader's repo, as its committed `project.id`. A reply may name a
1683
+ * comment by the unique id prefix `list_comments` printed, and a comment
1684
+ * drafted from one repo's corrections is listed only to a read that declares
1685
+ * that repo, so it is matched only by a reply that declares it too.
1686
+ */
1687
+ projectId: v.optional(ProjectIdSchema),
1688
+ /**
1689
+ * The bundles the reader's `list_comments` was scoped to, so an id prefix
1690
+ * printed there is matched among exactly those bundles. Without it the prefix
1691
+ * is matched among every bundle the caller can reach.
1692
+ */
1693
+ bundleIds: v.optional(v.pipe(v.array(NonEmptyStringSchema), v.maxLength(MAX_COMMENT_BUNDLE_IDS))),
1694
+ });
1695
+ /**
1696
+ * The comment a create settled on. `created` is false when this agent session
1697
+ * already had a whole-subject comment on the subject: that comment comes back
1698
+ * unchanged and nothing was written.
1699
+ */
1700
+ export const AgentCommentResponseSchema = v.object({
1701
+ created: v.boolean(),
1702
+ comment: v.object({
1703
+ id: v.string(),
1704
+ threadId: v.string(),
1705
+ subject: v.object({
1706
+ kind: v.picklist(['artifact', 'session']),
1707
+ id: v.string(),
1708
+ }),
1709
+ body: v.string(),
1710
+ createdAt: v.string(),
1711
+ }),
1712
+ });
1713
+ /**
1714
+ * One comment on the on-demand read, with the item it is about named on the comment.
1715
+ *
1716
+ * The item is named here rather than the comments riding an item, because this
1717
+ * read answers "what has been left for me" rather than "what is in this
1718
+ * bundle": there is no item payload to hang them off, and an agent that has to
1719
+ * ask for every item to find out whether one carries a comment is the round trip
1720
+ * the announcement exists to avoid.
1721
+ */
1722
+ export const ItemCommentWithSubjectSchema = v.object({
1723
+ ...ContextItemCommentSchema.entries,
1724
+ /** The item the comment is about, as the wire names it. */
1725
+ itemName: v.string(),
1726
+ /** The item's declared repo-relative path, or null when it has none. */
1727
+ itemPath: v.nullable(v.string()),
1728
+ });
1729
+ /**
1730
+ * Every open comment waiting for this reader across the bundles they named.
1731
+ *
1732
+ * **This read is a delivery and is counted as one**, exactly as comments riding
1733
+ * an item are: a body reached an agent. What it is *not* is an announcement —
1734
+ * nothing here touches the per-repo announcement count, so asking to read your
1735
+ * comments never spends the interruptions the hook is allowed.
1736
+ *
1737
+ * **Never capped.** The announcement cap governs whether a hook speaks; a
1738
+ * reader who asked is owed every open comment, and hiding one here would retire a
1739
+ * person's request without anybody deciding to.
1740
+ */
1741
+ export const ItemCommentsResponseSchema = v.object({
1742
+ comments: v.array(ItemCommentWithSubjectSchema),
1743
+ cursor: v.optional(v.string()),
1744
+ /**
1745
+ * The markers every `body` above is wrapped in, plus a statement of what
1746
+ * they mean. Present exactly when at least one comment came back.
1747
+ */
1748
+ untrusted: v.optional(v.nullable(GuideHistoryUntrustedSchema)),
1749
+ });
1750
+ /**
1751
+ * The evidence behind one Mossbear finding an agent was handed
1752
+ * (`GET /api/v1/context/comments/evidence`).
1753
+ *
1754
+ * `list_comments` carries the claim and a one-line tier; this is the finding
1755
+ * in full: the claim, the change it predicts in future sessions, what the
1756
+ * drafter did not read, and the evidence for its tier. Readable only through a
1757
+ * comment the comment read itself would deliver to this reader, so another
1758
+ * person's finding, one drafted from another repo, or a draft listed only to a
1759
+ * newer client has no evidence here either. A draft the reader was listed
1760
+ * does: an agent can say why it was raised before the person approves it.
1761
+ *
1762
+ * Citations (observed and usage findings) are reduced to what the reader may
1763
+ * see: their own sessions, with a date and a short excerpt of the grader's
1764
+ * reasoning or of their own redacted correction turn. A `navigation` citation
1765
+ * has an empty excerpt: it is dated evidence that a session loaded the skill,
1766
+ * and nothing more. `citationsWithheld` counts any that were dropped, so a
1767
+ * short list is never mistaken for the whole of it.
1768
+ */
1769
+ export const CommentEvidenceCitationSchema = v.object({
1770
+ /**
1771
+ * `navigation` is a skill load counted when a finding was drafted from how
1772
+ * the skill's files were read: evidence of how a skill was used, not of a
1773
+ * failure. `action` is a recorded step of a workflow repeated across
1774
+ * sessions. `discrepancy` is a grader's note that a session's closing report
1775
+ * contradicted its recorded actions; its excerpt is the agent's quoted claim
1776
+ * and the record. A server sends `action` and `discrepancy` only to a client
1777
+ * that names a version new enough to parse them.
1778
+ */
1779
+ kind: v.picklist(['verdict', 'turn', 'navigation', 'action', 'discrepancy']),
1780
+ sessionId: NonEmptyStringSchema,
1781
+ /** ISO, when the verdict was graded, the turn was said, the skill loaded, or the action was recorded. */
1782
+ at: v.string(),
1783
+ /** Wrapped in the response's untrusted markers. */
1784
+ excerpt: v.string(),
1785
+ });
1786
+ /** What a usage finding adds to its citations: the counts for one reference file. */
1787
+ export const CommentEvidenceUsageSchema = v.object({
1788
+ /** The reference's skill-relative path, wrapped in the response's untrusted markers. */
1789
+ path: v.string(),
1790
+ /** Eligible loads of the skill. */
1791
+ loads: v.pipe(v.number(), v.integer()),
1792
+ /** Distinct sessions those loads span. */
1793
+ sessions: v.pipe(v.number(), v.integer()),
1794
+ /** Loads followed by a successful read of the reference. */
1795
+ loadsWithRead: v.pipe(v.number(), v.integer()),
1796
+ });
1797
+ /**
1798
+ * What a practice finding adds: the rubric check it answers and the rubric's
1799
+ * version, the practice lines it weighs with their sources, the facts measured
1800
+ * from the file, and the answer to each item of evidence the check asks for.
1801
+ * `answers[].answer` is model-written, so it travels wrapped in the response's
1802
+ * untrusted markers.
1803
+ */
1804
+ export const CommentEvidencePracticeSchema = v.object({
1805
+ check: v.object({ id: v.string(), name: v.string() }),
1806
+ rubricVersion: v.pipe(v.number(), v.integer()),
1807
+ // Optional, so a CLI reads a dashboard that has not shipped these fields yet:
1808
+ // the two release independently.
1809
+ practices: v.optional(v.array(v.object({
1810
+ text: v.string(),
1811
+ source: v.object({ title: v.string(), url: v.string() }),
1812
+ })), []),
1813
+ facts: v.optional(v.array(v.string()), []),
1814
+ answers: v.optional(v.array(v.object({ item: v.string(), answer: v.string() })), []),
1815
+ });
1816
+ /**
1817
+ * A comment the person (or Mossbear) left on one of the sessions a finding
1818
+ * cites — the person's own account of what the agent should have known, set
1819
+ * beside the grader's excerpt (`guide-findings-plan.md` → Your note on a
1820
+ * session).
1821
+ *
1822
+ * **Reachable only here.** A comment about a session is never listed by
1823
+ * `list_comments` or announced at session start: it is context for a finding,
1824
+ * found by following the finding's citation, not a request.
1825
+ */
1826
+ export const CommentEvidenceSessionCommentSchema = v.object({
1827
+ sessionId: NonEmptyStringSchema,
1828
+ /** Only the person's own notes are sent today; `mossbear` is reserved. */
1829
+ authorKind: v.picklist(['person', 'mossbear']),
1830
+ /** ISO, when the comment was written. */
1831
+ at: v.string(),
1832
+ /** Wrapped in the response's untrusted markers. */
1833
+ body: v.string(),
1834
+ });
1835
+ export const CommentEvidenceResponseSchema = v.object({
1836
+ /** The comment's full id, even when the request named a prefix. */
1837
+ commentId: NonEmptyStringSchema,
1838
+ itemName: v.string(),
1839
+ itemPath: v.nullable(v.string()),
1840
+ tier: FindingTierSchema,
1841
+ /** One line saying how the finding is known; server-written, outside the markers. */
1842
+ tierLine: v.string(),
1843
+ /** What the drafter did not read; server-written, outside the markers. */
1844
+ blindSpot: v.string(),
1845
+ /** What goes wrong, wrapped in the response's untrusted markers. */
1846
+ claim: v.string(),
1847
+ /** What future sessions should show if the finding is fixed, wrapped; null if none. */
1848
+ prediction: v.nullable(v.string()),
1849
+ /** A usage finding's counts; null on every other tier. */
1850
+ usage: v.nullable(CommentEvidenceUsageSchema),
1851
+ /** A practice finding's rubric check; null on every other tier. */
1852
+ practice: v.nullable(CommentEvidencePracticeSchema),
1853
+ citations: v.array(CommentEvidenceCitationSchema),
1854
+ citationsWithheld: v.pipe(v.number(), v.integer()),
1855
+ /**
1856
+ * Comments on the cited sessions, newest first, wrapped in the untrusted
1857
+ * markers. Defaulted so a response from a server that predates the field
1858
+ * still parses.
1859
+ */
1860
+ sessionComments: v.optional(v.array(CommentEvidenceSessionCommentSchema), []),
1861
+ /**
1862
+ * Comments on the cited sessions that were left out to keep the response
1863
+ * bounded (the newest few per session are sent), so a short list is never
1864
+ * mistaken for the whole of it. Zero when none were.
1865
+ */
1866
+ sessionCommentsWithheld: v.optional(v.pipe(v.number(), v.integer()), 0),
1867
+ untrusted: GuideHistoryUntrustedSchema,
1868
+ });
1869
+ // A capture id the *client* minted, so a capture has a name before it has a
1870
+ // server — `offline-doc-editing-plan.md` → slice 4.
1871
+ //
1872
+ // The whole point is that the id survives a request the client never saw the
1873
+ // answer to: an outbox entry replayed after a reconnect carries the id it was
1874
+ // created with, so the server can tell a retry from a second capture. That makes
1875
+ // this a client-supplied primary key, which is why it is validated tightly
1876
+ // rather than passed through — the value reaches `guide_files.id` and comes
1877
+ // back out in URLs and log fields.
1878
+ //
1879
+ // The bound is deliberately wider than `nanoid()`'s 21 characters. Existing
1880
+ // rows carry `crypto.randomUUID()` values (36), the CLI and MCP callers may
1881
+ // mint their own, and a ceiling that only fits one generator is a rule every
1882
+ // future caller has to discover by getting a 400.
1883
+ const MAX_CAPTURE_ID_LENGTH = 128;
1884
+ export const CaptureIdSchema = v.pipe(v.string(),
1885
+ // **No `v.trim()`, deliberately.** Trimming is a *transform*: it would strip
1886
+ // the padding before the regex ran, so `" abc12345 "` would be accepted and
1887
+ // silently become `abc12345`. For an idempotency key that is the wrong
1888
+ // answer twice over — the caller's retry would address a different key than
1889
+ // the one it sent, and two callers whose ids differ only in padding would
1890
+ // collide on one row. The alphabet below excludes whitespace, so the
1891
+ // untrimmed value is refused instead. (Codex review on #1314.)
1892
+ v.minLength(8, 'id must be at least 8 characters'), v.maxLength(MAX_CAPTURE_ID_LENGTH),
1893
+ // `nanoid()`'s alphabet plus the dot and the UUID hyphen. No whitespace, no
1894
+ // control characters, nothing that changes meaning in a path segment.
1895
+ v.regex(/^[A-Za-z0-9_.-]+$/, 'id must contain only letters, digits, underscore, dot or hyphen'));
1896
+ export const CaptureRequestSchema = v.object({
1897
+ /**
1898
+ * Optional, and it stays optional.
1899
+ *
1900
+ * This is a token-authenticated `v1` endpoint, so its callers are not only
1901
+ * the ones in this repo — adding a *required* field to it breaks every
1902
+ * external one for a field only the offline outbox needs. A caller that
1903
+ * sends an id is asking for idempotency; a caller that does not is asking
1904
+ * for a new capture every time.
1905
+ *
1906
+ * The CLI and MCP server do not capture; the one in-repo caller is the
1907
+ * dashboard composer.
1908
+ */
1909
+ id: v.optional(CaptureIdSchema),
1910
+ // Optional for v1 compatibility. Missing and null both mean Inbox; a string
1911
+ // names the bundle the original request must remain tied to on every retry.
1912
+ bundleId: v.optional(v.nullable(v.string())),
1913
+ contentType: CaptureContentTypeSchema,
1914
+ content: ContextContentSchema,
1915
+ name: v.optional(ArtifactNameSchema),
1916
+ source: v.optional(v.string()),
1917
+ });
1918
+ /**
1919
+ * `POST /api/v1/artifacts/captures`: what a capture wrote, with its provenance.
1920
+ * `capturedAt` is the row's createdAt. The artifact listing serves the same row
1921
+ * as an {@link ArtifactSchema}; this is the composer's receipt.
1922
+ */
1923
+ export const CapturedItemSchema = v.object({
1924
+ id: v.string(),
1925
+ type: ContextItemTypeSchema,
1926
+ name: v.string(),
1927
+ /** The stored pair, as {@link ContextItemSchema} carries it. */
1928
+ role: v.nullable(v.string()),
1929
+ format: v.nullable(v.string()),
1930
+ content: v.nullable(v.string()),
1931
+ /** Set when the item is a photo: its stored parts, never their bytes. */
1932
+ asset: v.optional(v.nullable(PhotoAssetSchema)),
1933
+ source: v.optional(v.nullable(v.string())),
1934
+ // Monotonic content version of the underlying doc, mirroring
1935
+ // `ContextItemSchema.version` — a capture is a guide_file too, so a caller
1936
+ // that edits it via PUT can echo this back as an expected-version precondition.
1937
+ version: v.optional(v.number()),
1938
+ capturedAt: v.string(),
1939
+ updatedAt: v.string(),
1940
+ });
1941
+ export const CaptureResponseSchema = v.object({
1942
+ item: CapturedItemSchema,
1943
+ });
1944
+ /**
1945
+ * `POST /api/v1/artifacts/captures/photos`: the attempt to stage parts into, or —
1946
+ * for a begin replayed after the capture committed — the item it became.
1947
+ */
1948
+ export const BeginPhotoUploadResponseSchema = v.variant('state', [
1949
+ v.object({
1950
+ state: v.literal('reserved'),
1951
+ attemptId: v.string(),
1952
+ expiresAt: v.string(),
1953
+ }),
1954
+ v.object({ state: v.literal('committed'), item: CapturedItemSchema }),
1955
+ ]);
1956
+ // ---------------------------------------------------------------------------
1957
+ // Doc version history (read API)
1958
+ // ---------------------------------------------------------------------------
1959
+ // One append-only saved version of a context doc (guide_file). Rows are served
1960
+ // lazily over REST and never sync through Zero — syncing them would grow every
1961
+ // client's initial-sync payload forever. See doc-version-history-plan.md.
1962
+ //
1963
+ // `authorType` is intentionally an open string, not a picklist: the server owns
1964
+ // the closed set ('user' | 'agent' | 'cli'), but a deployed client parses this
1965
+ // response strictly, and a picklist would turn any future author kind into a
1966
+ // hard parse error on an otherwise valid history read.
1967
+ export const ArtifactVersionSchema = v.object({
1968
+ id: v.string(),
1969
+ // Monotonic checkpoint number. Autosave may advance the current item token
1970
+ // beyond its latest checkpoint, and saved numbers can have gaps.
1971
+ version: v.pipe(v.number(), v.integer(), v.minValue(1)),
1972
+ contentHash: v.string(),
1973
+ authorType: v.string(),
1974
+ // Non-secret provenance the write path recorded (e.g. bundle slug, capture
1975
+ // source). Never a bearer secret — these rows outlive tokens and ride export.
1976
+ metadata: v.optional(v.nullable(v.record(v.string(), v.unknown()))),
1977
+ createdAt: v.string(),
1978
+ });
1979
+ // The full version including the snapshotted body, returned by the per-version
1980
+ // content fetch. `content` is nullable to stay blob-tier compatible: a future
1981
+ // encrypted/blob version stores a hash pointer, not inline text.
1982
+ export const ArtifactVersionDetailSchema = v.object({
1983
+ id: v.string(),
1984
+ version: v.pipe(v.number(), v.integer(), v.minValue(1)),
1985
+ content: v.nullable(v.string()),
1986
+ contentHash: v.string(),
1987
+ authorType: v.string(),
1988
+ metadata: v.optional(v.nullable(v.record(v.string(), v.unknown()))),
1989
+ createdAt: v.string(),
1990
+ });
1991
+ /** The item routes' names for the version schemas, kept while those routes are served. */
1992
+ // Newest-first page of a doc's version summaries. `nextCursor` is the version
1993
+ // number to pass back as `?before=` for the following (older) page, or null
1994
+ // once the oldest version has been returned.
1995
+ export const BundleArtifactVersionsResponseSchema = v.object({
1996
+ versions: v.array(ArtifactVersionSchema),
1997
+ nextCursor: v.nullable(v.number()),
1998
+ });
1999
+ /** Default and max page size for the version-history list endpoint. */
2000
+ export const DEFAULT_VERSIONS_LIMIT = 50;
2001
+ export const MAX_VERSIONS_LIMIT = 200;
2002
+ // ---------------------------------------------------------------------------
2003
+ // Artifact wire contract
2004
+ // ---------------------------------------------------------------------------
2005
+ //
2006
+ // One durable content object, one identity, one set of operations. These
2007
+ // schemas are the shared contract for the artifact HTTP routes, the CLI and the
2008
+ // MCP tools. They sit beside the older context-item schemas and change none of
2009
+ // them; the old contract is removed in a later step, not here.
2010
+ /**
2011
+ * What part an artifact plays. The stored `role` vocabulary, enumerated.
2012
+ *
2013
+ * Unlike the older item schema, which leaves role a bare string so an old client
2014
+ * survives a new value, the artifact contract names the set: a client that
2015
+ * meets a role it has never heard of should fail loudly on the parse rather than
2016
+ * guess at what it may do with the bytes. Adding a role is a deliberate wire
2017
+ * change.
2018
+ */
2019
+ export const ArtifactRoleSchema = v.picklist(['guidance', 'criteria', 'content']);
2020
+ /**
2021
+ * What shape an artifact's bytes are. Not {@link GuideFileFormatSchema}, which
2022
+ * names agent-instruction file layouts; this is the stored content format.
2023
+ */
2024
+ export const ArtifactFormatSchema = v.picklist(['markdown', 'html', 'binary', 'code']);
2025
+ /**
2026
+ * The formats a caller may create, derived from the content-kind table so a
2027
+ * kind that is not pushable cannot become creatable here. Binary is excluded:
2028
+ * a create stores text `content`, and a binary artifact reads back with
2029
+ * `content: null`, so it could not round-trip. Creation is always
2030
+ * `role: 'content'`; guidance and criteria arrive through import.
2031
+ *
2032
+ * `html` is the one addition outside the table: an HTML page the dashboard
2033
+ * renders live in a sandboxed frame. It is deliberately not a row there,
2034
+ * because a row would give it an item type of its own, and a client that
2035
+ * predates that type would reject every listing carrying one. An `html`
2036
+ * artifact serializes as an ordinary `content` item and reports its format on
2037
+ * `ArtifactSchema.format`.
2038
+ */
2039
+ export const CreatableArtifactFormatSchema = v.picklist([
2040
+ ...CONTEXT_CONTENT_KINDS.filter((k) => k.pushable && k.format !== 'binary').map((k) => k.format),
2041
+ 'html',
2042
+ ]);
2043
+ /** Largest version an artifact can carry: the version column is a 32-bit integer. */
2044
+ export const MAX_ARTIFACT_VERSION = 2147483647;
2045
+ /**
2046
+ * Lifecycle state of an artifact. `deleted` is in the Trash: hidden and
2047
+ * restorable for the workspace's retention period. `removed` is a tombstone: the publishing
2048
+ * repository deleted the file, and the artifact still reports its last revision.
2049
+ * Aliases and anything else that is not content are not artifacts and never
2050
+ * appear here.
2051
+ */
2052
+ export const ArtifactStateSchema = v.picklist(['live', 'deleted', 'removed']);
2053
+ /** Most source references one saved revision may pin. */
2054
+ export const MAX_ARTIFACT_SOURCE_REFS = 50;
2055
+ /**
2056
+ * A byte range inside a pinned source revision, `[start, end)` over the UTF-8
2057
+ * bytes the revision's content hash covers. Resolved against the pinned bytes,
2058
+ * never the source's current head.
2059
+ */
2060
+ export const ArtifactPassageSelectorSchema = v.pipe(v.object({
2061
+ start: v.pipe(v.number(), v.integer(), v.minValue(0)),
2062
+ end: v.pipe(v.number(), v.integer(), v.minValue(1)),
2063
+ }), v.check((p) => p.end > p.start, 'passage end must be greater than start'));
2064
+ /**
2065
+ * A reference from a derived revision to the source revision it was written
2066
+ * from. Stored on the derived revision, so editing the source later does not
2067
+ * rewrite it.
2068
+ *
2069
+ * **`version` is optional, and absence means unpinned.** A legacy id-only
2070
+ * citation, or a source that was never saved, carries no version; a reader must
2071
+ * not substitute the source's current version. `contentHash` is set only when
2072
+ * known and is never invented. A reference is the writer's assertion about what
2073
+ * it read, not proof that the cited text supports the derived content.
2074
+ */
2075
+ const ArtifactSourceRefEntries = {
2076
+ artifactId: v.pipe(v.string(), v.minLength(1)),
2077
+ version: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(MAX_ARTIFACT_VERSION))),
2078
+ contentHash: v.optional(Sha256HexSchema),
2079
+ passage: v.optional(ArtifactPassageSelectorSchema),
2080
+ gitCommit: v.optional(CommitShaSchema),
2081
+ };
2082
+ const PASSAGE_NEEDS_VERSION = 'a passage requires version: it selects bytes of a pinned revision';
2083
+ export const ArtifactSourceRefSchema = v.pipe(v.object(ArtifactSourceRefEntries),
2084
+ // A passage is a byte range of one pinned revision, so it needs `version`.
2085
+ v.check((ref) => ref.passage === undefined || ref.version !== undefined, PASSAGE_NEEDS_VERSION));
2086
+ /** The bounded source list a write may attach to the revision it creates. */
2087
+ export const ArtifactSourceRefsSchema = v.pipe(v.array(ArtifactSourceRefSchema), v.maxLength(MAX_ARTIFACT_SOURCE_REFS));
2088
+ /**
2089
+ * A source reference as a saved revision reports it: the writer's reference plus
2090
+ * the `basis` the server recorded. `verified` means the writer pinned a revision
2091
+ * and a hash and both matched the server's copy; `asserted` is everything else.
2092
+ * Output only: request schemas do not accept `basis`, so a client cannot claim it.
2093
+ */
2094
+ export const ArtifactRecordedSourceRefSchema = v.pipe(v.object({
2095
+ ...ArtifactSourceRefEntries,
2096
+ basis: v.picklist(['verified', 'asserted']),
2097
+ }), v.check((ref) => ref.passage === undefined || ref.version !== undefined, PASSAGE_NEEDS_VERSION));
2098
+ export const ArtifactRecordedSourceRefsSchema = v.pipe(v.array(ArtifactRecordedSourceRefSchema), v.maxLength(MAX_ARTIFACT_SOURCE_REFS));
2099
+ /**
2100
+ * What an artifact is, in the words a reader uses: a guide, or content that is
2101
+ * Markdown, HTML, code, a photo or some other file. One value per artifact,
2102
+ * derived from its stored role and format by {@link artifactKindOf}, and the
2103
+ * vocabulary the artifact listing filters on.
2104
+ */
2105
+ export const ARTIFACT_KINDS = [
2106
+ 'markdown',
2107
+ 'html',
2108
+ 'code',
2109
+ 'photo',
2110
+ 'file',
2111
+ 'guide',
2112
+ ];
2113
+ export const ArtifactKindSchema = v.picklist(ARTIFACT_KINDS);
2114
+ /**
2115
+ * The kind of an artifact with this role and format.
2116
+ *
2117
+ * Guidance and criteria are a guide's. Binary content is a photo when it
2118
+ * carries the photo parts a capture records, and any other file otherwise,
2119
+ * such as an image a skill ships.
2120
+ */
2121
+ export function artifactKindOf(artifact) {
2122
+ if (artifact.role !== 'content')
2123
+ return 'guide';
2124
+ switch (artifact.format) {
2125
+ case 'markdown':
2126
+ return 'markdown';
2127
+ case 'html':
2128
+ return 'html';
2129
+ case 'code':
2130
+ return 'code';
2131
+ case 'binary':
2132
+ return artifact.hasPhotoAsset ? 'photo' : 'file';
2133
+ }
2134
+ }
2135
+ /**
2136
+ * The common description of an artifact, whatever it is called in prose.
2137
+ *
2138
+ * `id` is the id of the content row itself, for a guide the body-file id, so a
2139
+ * read, an update, a comment and a history call all address the same thing and
2140
+ * no caller translates one id into another. `role` and `format` are real values
2141
+ * for every artifact, guides included.
2142
+ */
2143
+ export const ArtifactSchema = v.object({
2144
+ id: v.pipe(v.string(), v.minLength(1)),
2145
+ name: v.string(),
2146
+ role: ArtifactRoleSchema,
2147
+ format: ArtifactFormatSchema,
2148
+ /** What the artifact is, as a reader names it: {@link artifactKindOf}. */
2149
+ kind: ArtifactKindSchema,
2150
+ /** Set when the artifact is a photo: its stored parts, never their bytes. */
2151
+ asset: v.optional(v.nullable(PhotoAssetSchema)),
2152
+ /** Monotonic content version; echo it back as `expectedVersion` to update. */
2153
+ version: v.pipe(v.number(), v.integer(), v.minValue(1)),
2154
+ state: ArtifactStateSchema,
2155
+ workspaceId: v.pipe(v.string(), v.minLength(1)),
2156
+ /** True for a deliberate capture (Inbox). Not derivable from filing state. */
2157
+ capture: v.boolean(),
2158
+ /**
2159
+ * When a capture was marked done, which takes it out of the inbox and nothing
2160
+ * else: a done artifact is still `state: 'live'`. Null while it waits.
2161
+ */
2162
+ doneAt: v.optional(v.nullable(v.string())),
2163
+ /** Null for binary content, which is not served inline. */
2164
+ content: v.nullable(v.string()),
2165
+ /**
2166
+ * What a person or their agent says about the artifact, as plain text, on
2167
+ * every kind: a Markdown artifact's frontmatter `description` (repeated from
2168
+ * `content`), and a stored field for anything without frontmatter, such as a
2169
+ * photo. Null when there is none. Data, never instructions. Optional because
2170
+ * a server that predates it sends nothing.
2171
+ */
2172
+ description: v.optional(v.nullable(v.string())),
2173
+ origin: v.optional(v.nullable(v.string())),
2174
+ root: v.optional(v.nullable(GuideDiscoveryRootSchema)),
2175
+ path: v.optional(v.nullable(SafeRelativePosixPathSchema)),
2176
+ projectId: v.optional(v.nullable(v.string())),
2177
+ pathProjectId: v.optional(v.nullable(v.string())),
2178
+ aliases: v.optional(v.pipe(v.array(GuideAliasSchema), v.maxLength(MAX_GUIDE_ALIASES))),
2179
+ /** Present iff git owns this artifact. */
2180
+ gitSource: v.optional(v.nullable(GitSourceSchema)),
2181
+ /** Absent, not empty, when there are none. Absence is not a verdict. */
2182
+ comments: v.optional(v.pipe(v.array(ArtifactCommentSchema), v.maxLength(MAX_ITEM_THREAD_ENTRIES_ON_WIRE))),
2183
+ createdAt: v.string(),
2184
+ updatedAt: v.string(),
2185
+ });
2186
+ /**
2187
+ * A guide publication: the bytes at an agent-guidance path, published from the
2188
+ * repository that homes the bundle, land as a guide rather than a document.
2189
+ *
2190
+ * `format` is the discovery format of the path, the one import records.
2191
+ * `members` is a skill's member files, relative to its directory, and is
2192
+ * authoritative when present: a stored member it omits is removed, unless it
2193
+ * is listed in `skippedPaths` (present at the ref, but not sendable). Only a
2194
+ * `skill-md` publication carries members.
2195
+ */
2196
+ export const GuidePublishSchema = v.pipe(v.strictObject({
2197
+ format: GuideFileFormatSchema,
2198
+ members: v.optional(v.pipe(v.array(v.strictObject({
2199
+ path: SkillMemberPathSchema,
2200
+ content: BoundedRawContentSchema,
2201
+ })), v.maxLength(MAX_SKILL_MEMBER_FILES),
2202
+ // Case-insensitive, as an import's members are: a checkout on a
2203
+ // case-folding filesystem can hold only one of `Run.sh` and `run.sh`.
2204
+ v.check((members) => new Set(members.map((member) => member.path.toLowerCase())).size ===
2205
+ members.length, 'member paths must be unique (case-insensitive)'))),
2206
+ skippedPaths: v.optional(v.pipe(v.array(SkippedMemberPathSchema), v.maxLength(MAX_SKILL_SKIPPED_MEMBER_PATHS))),
2207
+ /**
2208
+ * The repository's other copies of this file, such as a skill's twin in
2209
+ * the other skills folder, each published as an alias of this guide rather
2210
+ * than a guide of its own. Each must be an alias path of the published one
2211
+ * (`aliasPathSiblings`). Additive: an alias it omits is kept.
2212
+ */
2213
+ aliases: v.optional(v.pipe(v.array(SafeRelativePosixPathSchema), v.maxLength(MAX_GUIDE_ALIASES))),
2214
+ }), v.check((guide) => guide.format === 'skill-md' ||
2215
+ (guide.members === undefined && guide.skippedPaths === undefined), 'only a skill-md guide carries members'));
2216
+ /**
2217
+ * Create an artifact. Always a create: it takes no id, and an update is a
2218
+ * separate request. `bundle` is optional for an unrestricted caller, who files
2219
+ * later; a scoped credential must name a bundle it may write, and the server
2220
+ * refuses a scoped create without one.
2221
+ */
2222
+ export const CreateArtifactRequestSchema = v.strictObject({
2223
+ name: ArtifactNameSchema,
2224
+ content: ContextContentSchema,
2225
+ /** Defaults to markdown. Creation is always `role: 'content'`. */
2226
+ format: v.optional(CreatableArtifactFormatSchema),
2227
+ /** Destination bundle slug. */
2228
+ bundle: v.optional(BundleSlugSchema),
2229
+ origin: v.optional(v.nullable(v.string())),
2230
+ /** Sources pinned on the first revision. */
2231
+ sources: v.optional(ArtifactSourceRefsSchema),
2232
+ /**
2233
+ * Where the artifact sits in the tree of the repo that declared it. Same
2234
+ * schema as the read side's `path`. The route refuses agent guidance,
2235
+ * Mossbear's state directory and git's, and requires `bundle` beside it.
2236
+ */
2237
+ path: v.optional(SafeRelativePosixPathSchema),
2238
+ /**
2239
+ * The writer's checkout, as the `project.id` it commits. Declaring it grants
2240
+ * nothing: a home-claiming bundle accepts a create only from its home, and it
2241
+ * is stored as the repo `path` is placed in. Same meaning and parsing as
2242
+ * `UpdateArtifactRequestSchema.projectId`.
2243
+ */
2244
+ projectId: v.optional(DeclaredProjectIdSchema),
2245
+ /**
2246
+ * The commit the bytes were read from, when this create is a publication from
2247
+ * a git home. Its presence makes the artifact git-owned. The route requires
2248
+ * `path` and `bundle` beside it.
2249
+ */
2250
+ gitSource: v.optional(GitSourceSchema),
2251
+ /**
2252
+ * The agent session that wrote this revision, as its harness names it (the id
2253
+ * `create_comment` resolves). Recorded in the saved version's `metadata`, and
2254
+ * absent when the writer could not tell. Provenance only: it grants nothing
2255
+ * and is not shown as authorship.
2256
+ */
2257
+ agentSessionId: v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(256))),
2258
+ /**
2259
+ * Publish this path as a guide ({@link GuidePublishSchema}). The one way an
2260
+ * agent-guidance `path` is accepted: the route also requires `gitSource` and
2261
+ * a `bundle` whose home is `projectId`.
2262
+ */
2263
+ guide: v.optional(GuidePublishSchema),
2264
+ });
2265
+ /**
2266
+ * Update an existing artifact: its content, its name, its description, or a
2267
+ * mix. The id is in the route. The version the caller read is required: there
2268
+ * is no last-write-wins update. `sources` describe the revision this write
2269
+ * creates and are not inherited, so omitting them records none.
2270
+ *
2271
+ * At least one of `content`, `name` and `description` is required. A Markdown
2272
+ * artifact's description is its frontmatter key, so `description` there
2273
+ * rewrites that key as a content edit, and is refused beside `content`, which
2274
+ * would say something else about the same key. On any other kind, `name` and
2275
+ * `description` are fields: they advance `version` and save no revision.
2276
+ */
2277
+ export const UpdateArtifactRequestFieldsSchema = v.strictObject({
2278
+ /** Dashboard autosave boundary; omitted retains every ordinary edit. */
2279
+ checkpoint: v.optional(v.boolean()),
2280
+ content: v.optional(UpdatableContentSchema),
2281
+ /** A new name. Refused on a guide, which is named from its body. */
2282
+ name: v.optional(ArtifactNameSchema),
2283
+ /** A new description, or `null` to clear it. */
2284
+ description: v.optional(v.nullable(ArtifactDescriptionSchema)),
2285
+ expectedVersion: v.pipe(v.number(), v.integer(), v.minValue(1)),
2286
+ sources: v.optional(ArtifactSourceRefsSchema),
2287
+ /**
2288
+ * An ordinary edit preserves the owner read under the write lock. Its
2289
+ * checkout gitSource advances an existing owner's commit, but cannot make
2290
+ * an unowned artifact git-owned. Omit for deliberate publication.
2291
+ */
2292
+ preserveOwnership: v.optional(v.literal(true)),
2293
+ /**
2294
+ * The writer's checkout, as the `project.id` it commits. Declaring it grants
2295
+ * nothing; it says which checkout this write comes from, so the home
2296
+ * repository of a git-owned artifact or home-claiming bundle is not refused.
2297
+ */
2298
+ projectId: v.optional(DeclaredProjectIdSchema),
2299
+ /**
2300
+ * The commit the new content was read from, for a git-owned artifact. It
2301
+ * advances the artifact's recorded provenance with its content. A git-owned artifact
2302
+ * updated without one is refused (409). For any other artifact it is a
2303
+ * publication claim unless preserveOwnership is true: for an artifact with
2304
+ * a path, it makes git the owner from that revision on; for an artifact
2305
+ * with no path it is refused (400).
2306
+ */
2307
+ gitSource: v.optional(GitSourceSchema),
2308
+ /**
2309
+ * The agent session that wrote this revision, as its harness names it (the id
2310
+ * `create_comment` resolves). Recorded in the saved version's `metadata`, and
2311
+ * absent when the writer could not tell. Provenance only: it grants nothing
2312
+ * and is not shown as authorship.
2313
+ */
2314
+ agentSessionId: v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(256))),
2315
+ /**
2316
+ * A guide publication's members ({@link GuidePublishSchema}), written after
2317
+ * the body. Accepted only on a guide's body, beside a `gitSource`.
2318
+ */
2319
+ guide: v.optional(GuidePublishSchema),
2320
+ });
2321
+ /**
2322
+ * Whether an update names something to change. Shared with the MCP tool, which
2323
+ * validates its own arguments before it builds this request.
2324
+ */
2325
+ export const artifactUpdateChangesSomething = (request) => request.content !== undefined ||
2326
+ request.name !== undefined ||
2327
+ request.description !== undefined;
2328
+ /** The `PUT` body: {@link UpdateArtifactRequestFieldsSchema}, carrying at least one change. */
2329
+ export const UpdateArtifactRequestSchema = v.pipe(UpdateArtifactRequestFieldsSchema, v.check((request) => artifactUpdateChangesSomething(request), 'send at least one of content, name and description'));
2330
+ /**
2331
+ * Tombstone an artifact: the commit that published it has since deleted the
2332
+ * file. The row and its history are kept, marked removed, and it is no longer
2333
+ * delivered. That is withdrawal, not Delete, which moves the artifact to the
2334
+ * Trash and out of every bundle.
2335
+ *
2336
+ * `gitSource` is required because a tombstone's whole claim is which revision
2337
+ * removed the file. `expectedVersion` is the optional precondition the caller
2338
+ * last read.
2339
+ */
2340
+ export const WithdrawArtifactRequestSchema = v.strictObject({
2341
+ gitSource: GitSourceSchema,
2342
+ /**
2343
+ * The writer's checkout, as on update. Required: a git-owned artifact is
2344
+ * read-only outside its source repo, so a removal that does not say which
2345
+ * checkout it comes from is refused by name for every real target.
2346
+ */
2347
+ projectId: DeclaredProjectIdSchema,
2348
+ expectedVersion: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
2349
+ /**
2350
+ * The one bundle this removal is for — a withdrawal, where a declaration
2351
+ * stopped covering the path for that bundle while the file is still there.
2352
+ * A tombstone stops delivery everywhere, so the server refuses with a 409
2353
+ * tagged `shared-artifact` when the artifact belongs to any other bundle,
2354
+ * checked under the same lock an attach takes. Absent for a committed
2355
+ * deletion, which removes the artifact from every bundle.
2356
+ */
2357
+ onlyMemberOf: v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(128))),
2358
+ });
2359
+ /**
2360
+ * Delete an artifact: move it to the Trash, restorable for the workspace's
2361
+ * retention period. The body is optional; `projectId` is the same checkout
2362
+ * claim as on update.
2363
+ */
2364
+ export const DeleteArtifactRequestSchema = v.strictObject({
2365
+ projectId: v.optional(DeclaredProjectIdSchema),
2366
+ });
2367
+ /**
2368
+ * Restore an artifact from the Trash. The same optional checkout claim as Delete:
2369
+ * an artifact a repository publishes, or one held by a bundle a repository
2370
+ * homes, is restored only from that checkout. The claim identifies the
2371
+ * checkout and grants no access of its own.
2372
+ */
2373
+ export const RestoreArtifactRequestSchema = DeleteArtifactRequestSchema;
2374
+ /**
2375
+ * `GET .../history` query. Integer strings only: `2abc` is not 2. `limit` is
2376
+ * bounded and `before` is a positive safe integer version cursor.
2377
+ */
2378
+ export const ArtifactHistoryQuerySchema = v.object({
2379
+ limit: v.optional(v.pipe(v.string(), v.regex(/^[1-9][0-9]{0,8}$/, 'limit must be a positive integer'), v.transform(Number), v.maxValue(MAX_VERSIONS_LIMIT))),
2380
+ before: v.optional(v.pipe(v.string(), v.regex(/^[1-9][0-9]{0,15}$/, 'before must be a positive integer'), v.transform(Number), v.safeInteger(), v.maxValue(MAX_ARTIFACT_VERSION))),
2381
+ });
2382
+ /**
2383
+ * Optional revision selector for a read (`?version=n`). Omitted reads the
2384
+ * current content. When given, the response `artifact.content` is that saved
2385
+ * revision's bytes while `artifact.version` stays the current version, so the
2386
+ * value to send back as `expectedVersion` never depends on what was selected.
2387
+ * A version that was never saved is a 404, not the nearest one.
2388
+ */
2389
+ export const ReadArtifactQuerySchema = v.object({
2390
+ version: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(MAX_ARTIFACT_VERSION))),
2391
+ });
2392
+ /** Which revision the content in a read response is. */
2393
+ export const ArtifactSelectedRevisionSchema = v.object({
2394
+ version: v.pipe(v.number(), v.integer(), v.minValue(1)),
2395
+ /** True when this is the current version. */
2396
+ current: v.boolean(),
2397
+ contentHash: v.nullable(Sha256HexSchema),
2398
+ });
2399
+ export const ReadArtifactResponseSchema = v.object({
2400
+ artifact: ArtifactSchema,
2401
+ revision: ArtifactSelectedRevisionSchema,
2402
+ /** Delimiters for comment bodies, present when any comment is returned. */
2403
+ untrusted: v.optional(v.nullable(GuideHistoryUntrustedSchema)),
2404
+ });
2405
+ export const CreateArtifactResponseSchema = v.object({
2406
+ artifact: ArtifactSchema,
2407
+ });
2408
+ export const UpdateArtifactResponseSchema = v.object({
2409
+ artifact: ArtifactSchema,
2410
+ });
2411
+ /** Most artifacts one page of `GET /api/v1/artifacts` returns, and the default. */
2412
+ export const MAX_LIST_ARTIFACTS_LIMIT = 500;
2413
+ export const DEFAULT_LIST_ARTIFACTS_LIMIT = 100;
2414
+ /** The longest cursor the listing hands out, with room to spare. */
2415
+ const MAX_LIST_ARTIFACTS_CURSOR_LENGTH = 512;
2416
+ /**
2417
+ * `GET /api/v1/artifacts`: the query string, as an object of its values.
2418
+ *
2419
+ * Every filter narrows; none is required. `inbox=true` is the Inbox: the
2420
+ * caller's own captures that are not done, not deleted and not filed, so it
2421
+ * cannot be combined with `bundle`. `bundle` is a bundle id. `kind` is a
2422
+ * comma-separated list of {@link ARTIFACT_KINDS}. `since` is an ISO timestamp
2423
+ * compared with when the artifact was created, which is also the order: newest
2424
+ * first. `cursor` is the previous page's `nextCursor`, opaque to the caller.
2425
+ *
2426
+ * There is no text query: finding by text is `GET /api/v1/search`.
2427
+ *
2428
+ * `comments=none` asks to be handed no comments, and not to be counted as
2429
+ * having received any, for a caller that will not show them.
2430
+ */
2431
+ export const ListArtifactsQuerySchema = v.pipe(v.object({
2432
+ inbox: v.optional(v.picklist(['true', 'false'], 'inbox must be true or false')),
2433
+ bundle: v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(128))),
2434
+ kind: v.optional(v.pipe(v.string(), v.transform((raw) => raw.split(',').map((part) => part.trim())), v.array(v.picklist(ARTIFACT_KINDS, `kind must be one of ${ARTIFACT_KINDS.join(', ')}`)), v.minLength(1))),
2435
+ since: v.optional(v.pipe(v.string(), v.check((raw) => !Number.isNaN(Date.parse(raw)), 'since must be an ISO timestamp'))),
2436
+ limit: v.optional(v.pipe(v.string(), v.regex(/^\d+$/, `limit must be a whole number from 1 to ${MAX_LIST_ARTIFACTS_LIMIT}`), v.transform(Number), v.minValue(1, `limit must be a whole number from 1 to ${MAX_LIST_ARTIFACTS_LIMIT}`), v.maxValue(MAX_LIST_ARTIFACTS_LIMIT, `limit must be a whole number from 1 to ${MAX_LIST_ARTIFACTS_LIMIT}`)), String(DEFAULT_LIST_ARTIFACTS_LIMIT)),
2437
+ cursor: v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(MAX_LIST_ARTIFACTS_CURSOR_LENGTH))),
2438
+ comments: v.optional(v.literal('none')),
2439
+ /** The CLI release asking, so thread replies reach only one that renders them. */
2440
+ cli: v.optional(v.pipe(v.string(), v.maxLength(64))),
2441
+ }), v.check((query) => !(query.inbox === 'true' && query.bundle !== undefined), 'The inbox holds only unfiled captures, so inbox and bundle cannot be combined.'), v.transform(({ inbox, ...rest }) => ({ ...rest, inbox: inbox === 'true' })));
2442
+ /**
2443
+ * One page of the artifact listing, newest first. `nextCursor` is null on the
2444
+ * last page. `untrusted` delimits comment bodies, as on a read.
2445
+ */
2446
+ export const ListArtifactsResponseSchema = v.object({
2447
+ artifacts: v.array(ArtifactSchema),
2448
+ nextCursor: v.nullable(v.pipe(v.string(), v.minLength(1))),
2449
+ untrusted: v.optional(v.nullable(GuideHistoryUntrustedSchema)),
2450
+ });
2451
+ /**
2452
+ * `POST /api/v1/artifacts/:id/done`: `true` marks a capture done, which takes it
2453
+ * out of the inbox and nothing else; `false` moves it back to the inbox.
2454
+ */
2455
+ export const MarkDoneRequestSchema = v.strictObject({
2456
+ done: v.boolean(),
2457
+ });
2458
+ /** The capture after the change; `doneAt` is null once it is back in the inbox. */
2459
+ export const MarkDoneResponseSchema = v.object({
2460
+ artifact: ArtifactSchema,
2461
+ });
2462
+ /** The artifact after Delete, `state: 'deleted'`. */
2463
+ export const DeleteArtifactResponseSchema = v.object({
2464
+ deleted: v.literal(true),
2465
+ artifact: ArtifactSchema,
2466
+ });
2467
+ /** The tombstoned artifact, `state: 'removed'`. */
2468
+ export const WithdrawArtifactResponseSchema = v.object({
2469
+ artifact: ArtifactSchema,
2470
+ });
2471
+ /**
2472
+ * A saved revision: the shared version summary plus the sources it was derived
2473
+ * from, when any were recorded.
2474
+ */
2475
+ export const ArtifactRevisionSchema = v.object({
2476
+ ...ArtifactVersionSchema.entries,
2477
+ sources: v.optional(ArtifactRecordedSourceRefsSchema),
2478
+ });
2479
+ export const ArtifactRevisionDetailSchema = v.object({
2480
+ ...ArtifactVersionDetailSchema.entries,
2481
+ sources: v.optional(ArtifactRecordedSourceRefsSchema),
2482
+ });
2483
+ /** Newest-first page of saved revisions; `nextCursor` as in the older history. */
2484
+ export const ArtifactHistoryResponseSchema = v.object({
2485
+ versions: v.array(ArtifactRevisionSchema),
2486
+ nextCursor: v.nullable(v.number()),
2487
+ });
2488
+ /**
2489
+ * The one refused-stale-write shape, for a direct update and a bundle-scoped one
2490
+ * alike. The `code` is what separates a retryable conflict from the other 409s
2491
+ * (a read-only artifact is permanent). Nothing was written.
2492
+ */
2493
+ export const ArtifactVersionConflictSchema = v.object({
2494
+ error: v.string(),
2495
+ code: v.literal('version-conflict'),
2496
+ currentVersion: v.pipe(v.number(), v.integer(), v.minValue(1)),
2497
+ expectedVersion: v.pipe(v.number(), v.integer(), v.minValue(1)),
2498
+ requestId: v.optional(v.string()),
2499
+ });
2500
+ // ---------------------------------------------------------------------------
2501
+ // Drafts: a revision its author can see and nobody else has received
2502
+ // ---------------------------------------------------------------------------
2503
+ const DraftBranchSchema = v.pipe(v.string(), v.minLength(1), v.maxLength(MAX_SOURCE_BRANCH_LENGTH));
2504
+ /**
2505
+ * Save a draft of an artifact from a git branch. One draft per artifact,
2506
+ * author and branch, so a second upload from the same branch replaces the
2507
+ * first. `baseVersion` is the artifact version the branch's bytes were
2508
+ * compared with; publishing the draft later sends it as `expectedVersion`.
2509
+ * Content equal to the artifact's current content stores nothing and removes
2510
+ * any draft from that branch, because it has landed.
2511
+ */
2512
+ export const UpsertArtifactDraftRequestSchema = v.strictObject({
2513
+ branch: DraftBranchSchema,
2514
+ content: UpdatableContentSchema,
2515
+ baseVersion: v.pipe(v.number(), v.integer(), v.minValue(1)),
2516
+ gitCommit: v.optional(CommitShaSchema),
2517
+ });
2518
+ /**
2519
+ * One of the caller's drafts. `branch` is null for a draft written in the
2520
+ * dashboard or by an agent rather than uploaded from git.
2521
+ */
2522
+ export const ArtifactDraftSchema = v.object({
2523
+ id: v.string(),
2524
+ artifactId: v.string(),
2525
+ branch: v.nullable(v.string()),
2526
+ gitCommit: v.nullable(v.string()),
2527
+ content: v.string(),
2528
+ contentHash: v.string(),
2529
+ baseVersion: v.pipe(v.number(), v.integer(), v.minValue(1)),
2530
+ createdAt: v.string(),
2531
+ updatedAt: v.string(),
2532
+ });
2533
+ /** `draft` is null when the content had already landed and nothing was kept. */
2534
+ export const UpsertArtifactDraftResponseSchema = v.object({
2535
+ draft: v.nullable(ArtifactDraftSchema),
2536
+ });
2537
+ /** The caller's own drafts of one artifact, most recently updated first. */
2538
+ export const ListArtifactDraftsResponseSchema = v.object({
2539
+ drafts: v.array(ArtifactDraftSchema),
2540
+ });
2541
+ // ---------------------------------------------------------------------------
2542
+ // Sync payload schemas
2543
+ // ---------------------------------------------------------------------------
2544
+ // The guiding tiers plus `unguided`. Spread from GuidingTierSchema so the four
2545
+ // tier names exist once; `unguided` is a deliberate extra on the wire, and the
2546
+ // accepted set is unchanged by this line.
2547
+ const DashboardSyncTierSchema = v.picklist([...GuidingTierSchema.options, 'unguided']);
2548
+ const DashboardGuideSuggestionStatusSchema = v.picklist([
2549
+ 'pending',
2550
+ 'accepted',
2551
+ 'dismissed',
2552
+ ]);
2553
+ export const ProposalCitationSchema = v.object({
2554
+ agentSessionId: v.string(),
2555
+ timestamp: v.optional(v.string()),
2556
+ summary: v.string(),
2557
+ });
2558
+ /** Max serialized size of an action's `metadata` field — bounds storage bloat. */
2559
+ export const MAX_ACTION_METADATA_BYTES = 16 * 1024;
2560
+ /**
2561
+ * Longest accepted CLI version string. Releases are `x.y.z` /
2562
+ * `x.y.z-<channel>.<n>`, so this is generous — it exists because the value is
2563
+ * client-supplied and lands on every action row, not to constrain the format
2564
+ * (ordering already fails closed on anything unparseable).
2565
+ */
2566
+ const MAX_CLI_VERSION_LENGTH = 64;
2567
+ const CliVersionSchema = v.pipe(v.string(), v.nonEmpty(), v.maxLength(MAX_CLI_VERSION_LENGTH));
2568
+ /**
2569
+ * Identity of the skill an agent loaded, captured by the logger hook from a
2570
+ * `Skill` tool call.
2571
+ *
2572
+ * Two fields because the hook can only ever be sure of one of them:
2573
+ *
2574
+ * - `name` is `tool_input.skill` verbatim — always present, never qualified.
2575
+ * Two skills that share a directory name (`.claude/skills/review` and
2576
+ * `.agents/skills/review`) are indistinguishable by it, which is review
2577
+ * finding 5 on PR #387.
2578
+ * - `path` is the skill's *directory*, relative to the discovery root the
2579
+ * guide import walks and in the same posix form its `origin` carries
2580
+ * (`.claude/skills/review`). This is the qualified identity: it is exactly
2581
+ * `guides.origin`'s path with the trailing `/SKILL.md` removed, so the two
2582
+ * sides of the join are the same string rather than two derivations of it.
2583
+ * Optional because the hook resolves it by probing the filesystem: a skill
2584
+ * that lives somewhere the probe does not look (a plugin skill, a
2585
+ * `~/.claude/skills` skill, a session whose cwd is not the repo root) has a
2586
+ * name and no path, and matching falls back to the name.
2587
+ */
2588
+ export const ActionSkillLoadSchema = v.object({
2589
+ name: NonEmptyStringSchema,
2590
+ path: v.optional(NonEmptyStringSchema),
2591
+ });
2592
+ /**
2593
+ * The `actions.action_type` a skill load is stored under.
2594
+ *
2595
+ * Deliberately **not** a member of `KNOWN_ACTION_TYPES` below, even though the
2596
+ * CLI emits it on purpose. A skill load is evidence about what was in the
2597
+ * agent's *context*, not a piece of work anyone should grade — it is an input to
2598
+ * `inContextGuides`, never a row the grader judges — the dashboard's
2599
+ * gradeable-action filter excludes it. Keeping it out of the known-vocabulary
2600
+ * list is what stops it being treated as gradeable work by anything that
2601
+ * enumerates that list.
2602
+ */
2603
+ export const SKILL_LOAD_ACTION_TYPE = 'skill_load';
2604
+ /**
2605
+ * The `actions.action_type` of a skill's member file a shell command read, in a
2606
+ * harness that reads through the shell. The command is already an action of
2607
+ * its own and is what gets graded; this row only records which file it opened,
2608
+ * so navigation can be told. Like a skill load it is context, not work: kept
2609
+ * out of `KNOWN_ACTION_TYPES` and excluded from grading, so one `cat` is never
2610
+ * two gradeable actions.
2611
+ */
2612
+ export const SKILL_MEMBER_READ_ACTION_TYPE = 'skill_member_read';
2613
+ /**
2614
+ * A machine-shaped label for *why* a tool call failed — `ENOENT`, `TimeoutError`,
2615
+ * `permission_denied`.
2616
+ *
2617
+ * Deliberately not free text. An error *message* is content: it quotes file
2618
+ * contents, stderr and third-party data, which is exactly the class
2619
+ * `content-sync-privacy` gates and `sanitizeCommand` cannot redact (it targets
2620
+ * shell syntax, not prose). A class is metadata, so it rides the same
2621
+ * unblocked path as the exit code. The character set admits identifiers and
2622
+ * dotted/namespaced codes and nothing else; anything failing it is dropped
2623
+ * rather than truncated, because half an error class is not a smaller fact, it
2624
+ * is a different one.
2625
+ */
2626
+ export const ActionErrorClassSchema = v.pipe(v.string(), v.regex(/^[A-Za-z0-9_.:-]{1,32}$/, 'errorClass must be 1-32 chars of [A-Za-z0-9_.:-]'));
2627
+ /**
2628
+ * Whether a logged tool call actually succeeded.
2629
+ *
2630
+ * The logger hook parsed `tool_input` and dropped the `tool_response` beside
2631
+ * it, so every action reached the grader looking like it had happened. A failed
2632
+ * edit and a successful one rendered identically, and the run grader has no
2633
+ * other way to tell them apart.
2634
+ *
2635
+ * **Absent means unknown, never success.** The hook emits this only from a
2636
+ * response shape it recognizes (`extractActionOutcome`), and agent tool
2637
+ * responses vary per tool and per platform; a guess here would be worse than
2638
+ * silence, because the grader would weigh it. `status` is therefore the only
2639
+ * required field, and the whole object is optional everywhere it appears.
2640
+ */
2641
+ export const ActionOutcomeSchema = v.object({
2642
+ status: v.picklist(['ok', 'error']),
2643
+ errorClass: v.optional(ActionErrorClassSchema),
2644
+ /**
2645
+ * Bounded to a signed 16-bit range, which covers every real exit status
2646
+ * (0-255, 128+signal, and Node's -1) with room to spare. The bound is a line
2647
+ * length bound as much as a validity one: this renders into the grading
2648
+ * prompt, where every field is capped.
2649
+ */
2650
+ exitCode: v.optional(v.pipe(v.number(), v.integer(), v.minValue(-32_768), v.maxValue(32_767))),
2651
+ });
2652
+ /**
2653
+ * {@link ActionOutcomeSchema} with unknown keys refused rather than ignored.
2654
+ *
2655
+ * Used only by `ActionMetadataSchema`'s boundary check, where the difference
2656
+ * matters: see the comment there. Readers parse with the permissive schema,
2657
+ * which strips unknown keys on output the way `v.object` always has.
2658
+ */
2659
+ const StrictActionOutcomeSchema = v.strictObject(ActionOutcomeSchema.entries);
2660
+ /**
2661
+ * Longest narration field accepted on the wire.
2662
+ *
2663
+ * Matches `MAX_PROSE_CHARS` in `@mossbear/eval-core`, which is the cap the
2664
+ * client-side redactor already applies. Duplicated as a literal rather than
2665
+ * imported because the dependency runs the other way — `@mossbear/eval-core`
2666
+ * depends on this package — and inverting it to share one constant would make
2667
+ * the wire contract depend on the evaluation package. The number is a bound, so
2668
+ * a drift between them fails safe in the direction that matters: the server
2669
+ * refusing something the client would have sent, never the reverse.
2670
+ */
2671
+ export const MAX_ACTION_NARRATION_CHARS = 2000;
2672
+ /**
2673
+ * A code fence at the start of a line, allowing Markdown container prefixes.
2674
+ *
2675
+ * Reject surviving fence openers, including list and quote prefixes. A client
2676
+ * running structural stripping removes these before upload. Inline `code`
2677
+ * spans and a mid-sentence "wrap it in ```" are untouched, because neither
2678
+ * begins a line.
2679
+ *
2680
+ * **What this does and does not buy.** It catches the realistic failure — a
2681
+ * client whose stripping broke, or one built against the wire schema without
2682
+ * reading the class table — before its output lands in a column. It is not a
2683
+ * defense against a determined client, which would simply send the same source
2684
+ * with no fence around it; the server cannot tell prose from code in general,
2685
+ * which is exactly why the class table strips whole *structures* rather than
2686
+ * asking a scrubber to recognize code. Claiming more than this would be the
2687
+ * "alignment theater" the charter's fourth commitment names.
2688
+ */
2689
+ const LINE_INITIAL_FENCE = /^[ \t]*(?:>[ \t]*|(?:[-+*]|\d{1,9}[.)])[ \t]+)*(?:`{3,}|~{3,})/m;
2690
+ const NarrationTextSchema = v.pipe(v.string(), v.maxLength(MAX_ACTION_NARRATION_CHARS), v.check((value) => !LINE_INITIAL_FENCE.test(value), 'narration must not contain a code block — code is stripped structurally on the client before upload'));
2691
+ /**
2692
+ * Transcript evidence attached to an action.
2693
+ *
2694
+ * **Two fields, and the omissions are the specification.** The class table
2695
+ * decides that user turns and assistant *prose* sync prose-redacted, assistant
2696
+ * code blocks are stripped to a language-and-line-count placeholder, and
2697
+ * tool-result bodies **never** sync. There is therefore no field here for a
2698
+ * tool result, no field for a code-block body, and no field for a diff.
2699
+ *
2700
+ * **`strictObject`, so a body that carries one is rejected rather than
2701
+ * trimmed.** This is the same decision `StrictActionOutcomeSchema` above makes
2702
+ * and for a sharper version of the same reason. A permissive `v.object` strips
2703
+ * unknown keys on output, which would turn a client sending
2704
+ * `narration.toolResult` into a *silently accepted* request: the sender is told
2705
+ * it worked, learns nothing, and keeps sending. Trimming is a policy that fails
2706
+ * open — it makes an over-sharing client indistinguishable from a correct one.
2707
+ * Rejecting makes the class table enforceable against a client the server does
2708
+ * not control, which is the only kind of enforcement worth having here; the
2709
+ * CLI's own choke point (`packages/cli/src/transcript/narration.ts`) is the
2710
+ * first line, not the last.
2711
+ *
2712
+ * The forward-compatibility cost is the same as `outcome`'s, and so is the
2713
+ * ordering that pays it: widen this schema and deploy the server before any
2714
+ * CLI starts sending a new narration field.
2715
+ */
2716
+ export const ActionNarrationSchema = v.strictObject({
2717
+ /**
2718
+ * The user turn this action followed — prose-redacted on the user's machine.
2719
+ *
2720
+ * **Not every message with `role: 'user'`.** A tool result is delivered as a
2721
+ * user-role message whose content is a `tool_result` block, so the client
2722
+ * selects on content-block type rather than role
2723
+ * (`packages/cli/src/transcript/messages.ts`). Nothing on this side can tell
2724
+ * the difference after the fact, which is why the client selects
2725
+ * structurally and this schema constrains the shape rather than the content.
2726
+ */
2727
+ userText: v.optional(NarrationTextSchema),
2728
+ /**
2729
+ * Assistant prose adjacent to the tool call — code blocks structurally
2730
+ * removed, then prose-redacted, then windowed, all on the user's machine.
2731
+ */
2732
+ assistantText: v.optional(NarrationTextSchema),
2733
+ });
2734
+ const ActionMetadataSchema = v.pipe(v.record(v.string(), v.unknown()), v.check((value) => new TextEncoder().encode(JSON.stringify(value)).length <= MAX_ACTION_METADATA_BYTES, `metadata must serialize to at most ${MAX_ACTION_METADATA_BYTES} bytes`),
2735
+ // `metadata` is an open record by design (platform-specific context), but the
2736
+ // one key the server *reads* has to be trustworthy: `skill` is what resolves
2737
+ // a run's loaded skills, so a malformed one must be rejected at the boundary
2738
+ // rather than silently ignored downstream.
2739
+ v.check((value) => value.skill === undefined || v.is(ActionSkillLoadSchema, value.skill), 'metadata.skill must be { name: string, path?: string }'), v.check((value) => value.repoId === undefined || v.is(RepoIdSchema, value.repoId), 'metadata.repoId must be repo_ followed by 32 hex chars'),
2740
+ // The committed project id, stamped beside `repoId` by the logger hook and
2741
+ // reduced onto the run the same way (`ActionEntrySchema.projectId`). Checked
2742
+ // here for the same reason `repoId` is: the server reads it, and a malformed
2743
+ // one would be stored rather than refused.
2744
+ v.check((value) => value.projectId === undefined || v.is(ProjectIdSchema, value.projectId), 'metadata.projectId must be a project id (letters, digits, underscore, dot or hyphen)'),
2745
+ // Which harness produced this action, stamped by the logger hook from the
2746
+ // `--harness` flag its own entry carries (`run-source-linking` slice 1).
2747
+ //
2748
+ // Here rather than as a top-level field on `DashboardSyncAction`, for the
2749
+ // reason `repoId` above is: the server does not read it from the request. It
2750
+ // re-reads the session's stored actions and reduces them, so the only
2751
+ // per-action channel that survives to that reducer is this column. A
2752
+ // top-level field would validate, then be dropped on insert.
2753
+ //
2754
+ // Checked here for the same reason `skill` and `outcome` are — the server
2755
+ // reads it — and absent is the ordinary state: an action logged by a hook
2756
+ // entry that names no harness carries no key at all, and absence means
2757
+ // "unrecorded", never `claude_code`.
2758
+ //
2759
+ // The same forward-compatibility cost `outcome` below spells out, and the
2760
+ // same ordering pays it: **widen this picklist, server deployed first, before
2761
+ // any CLI ships a new harness id.** An id this server does not know rejects
2762
+ // the whole request — not just the field — so a CLI released ahead of the
2763
+ // deploy would stop that user's actions uploading altogether. A harness is
2764
+ // added far more often than an outcome field, so the note belongs here too.
2765
+ v.check((value) => value.harness === undefined || v.is(HarnessIdSchema, value.harness), 'metadata.harness must be a known harness id'),
2766
+ // Where the session ran (`cloud`, or no key), stamped by the logger hook.
2767
+ // Checked for the reason `harness` is: the server reads it.
2768
+ v.check((value) => value.environment === undefined ||
2769
+ v.is(SessionEnvironmentSchema, value.environment), 'metadata.environment must be cloud'),
2770
+ // Same reasoning as `skill` above: the server reads this one, so a malformed
2771
+ // outcome is rejected at the boundary rather than reaching the grader as a
2772
+ // half-parsed fact about whether the action succeeded.
2773
+ //
2774
+ // `v.is` only answers yes/no — it does not substitute the schema's stripped
2775
+ // output — and the surrounding `metadata` is an open record that keeps what
2776
+ // it was given. A permissive object check would therefore *store* an
2777
+ // unrecognized `outcome.message`, which is exactly the free-text error prose
2778
+ // this field exists to keep off the wire. `strictObject` is what makes the
2779
+ // check mean what it says.
2780
+ //
2781
+ // The forward-compatibility cost is real and the ordering that pays it:
2782
+ // widen this schema (server, deployed first) before any CLI starts sending a
2783
+ // new outcome field, or an un-upgraded server rejects the whole action.
2784
+ v.check((value) => value.outcome === undefined || v.is(StrictActionOutcomeSchema, value.outcome), 'metadata.outcome must be { status: "ok" | "error", errorClass?: string, exitCode?: number } with no other keys'));
2785
+ // Token usage extracted from an agent's own transcript (e.g. Claude Code
2786
+ // JSONL), keyed by model. Raw token counts only — cost is derived server-side.
2787
+ export const TokenUsageSchema = v.object({
2788
+ model: NonEmptyStringSchema,
2789
+ provider: v.optional(v.string()),
2790
+ // Response occurrence time in Unix milliseconds; absent on legacy totals.
2791
+ occurredAt: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(8_640_000_000_000_000))),
2792
+ inputTokens: v.pipe(v.number(), v.integer(), v.minValue(0)),
2793
+ outputTokens: v.pipe(v.number(), v.integer(), v.minValue(0)),
2794
+ cacheReadTokens: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
2795
+ cacheWriteTokens: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
2796
+ });
2797
+ /** Identity of a model's usage at an instant, or its undated legacy total. */
2798
+ export function usageRowKey(row) {
2799
+ return JSON.stringify([row.model, row.occurredAt ?? null]);
2800
+ }
2801
+ /** Preserve legacy model ordering so saved numerical proofs remain verifiable. */
2802
+ export function compareUsageRows(a, b) {
2803
+ return ((a.model < b.model ? -1 : a.model > b.model ? 1 : 0) ||
2804
+ (a.occurredAt ?? -1) - (b.occurredAt ?? -1));
2805
+ }
2806
+ // Whole-session replacement must fit one request; splitting it would erase
2807
+ // earlier pieces. Leave envelope space beneath the transport body ceiling.
2808
+ export const MAX_HOSTED_USAGE_ROWS = 50_000;
2809
+ export const MAX_HOSTED_USAGE_BYTES = 8 * 1024 * 1024;
2810
+ export const MAX_SYNC_REQUEST_BYTES = 9 * 1024 * 1024;
2811
+ export const DashboardSessionUsageSchema = v.object({
2812
+ sessionId: v.optional(v.string()),
2813
+ agentSessionId: NonEmptyStringSchema,
2814
+ usage: v.pipe(v.array(TokenUsageSchema), v.maxLength(MAX_HOSTED_USAGE_ROWS), v.check((rows) => new TextEncoder().encode(JSON.stringify(rows)).byteLength <=
2815
+ MAX_HOSTED_USAGE_BYTES, 'Usage snapshot exceeds the single-session upload capacity')),
2816
+ });
2817
+ // Per-skill Tier-1 "load overhead" token usage extracted from an agent's own
2818
+ // transcript — the precise part
2819
+ // of skill-cost attribution: the tokens billed to load a Skill/SKILL.md into
2820
+ // context, approximated in v1 as the first-load message's usage. Tier 2
2821
+ // (heuristic guided-work spans) is not implemented yet.
2822
+ export const SkillUsageEntrySchema = v.object({
2823
+ skillName: NonEmptyStringSchema,
2824
+ model: NonEmptyStringSchema,
2825
+ inputTokens: v.pipe(v.number(), v.integer(), v.minValue(0)),
2826
+ cacheWriteTokens: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
2827
+ });
2828
+ export const DashboardSkillUsageSchema = v.object({
2829
+ sessionId: v.optional(v.string()),
2830
+ agentSessionId: NonEmptyStringSchema,
2831
+ usage: v.array(SkillUsageEntrySchema),
2832
+ });
2833
+ /**
2834
+ * Bounds on the action fields that reach an LLM prompt verbatim.
2835
+ *
2836
+ * Every one of these is interpolated verbatim into the run grader's action log,
2837
+ * so an unbounded value is not just storage bloat: it is an authenticated client
2838
+ * deciding how much context one nominally-capped action consumes, or making the
2839
+ * provider call fail on length over and over while the run stays retryable. The prompt caps
2840
+ * them again on the way out — these stop the oversized value being *stored*,
2841
+ * which is the only place a cap holds for rows the prompt never renders.
2842
+ *
2843
+ * Sized well above anything the CLI produces: summaries are capped at 200
2844
+ * characters before they leave the machine (`MAX_SUMMARY_CHARS`,
2845
+ * `packages/cli/src/action-queue.ts:31`), action types are derived from tool
2846
+ * names, and `filePaths` carries at most one entry per action
2847
+ * (`toSyncAction`, `packages/cli/src/action-queue.ts:135-147`).
2848
+ */
2849
+ const MAX_ACTION_ID_LENGTH = 128;
2850
+ const MAX_ACTION_TYPE_LENGTH = 128;
2851
+ const MAX_ACTION_SUMMARY_LENGTH = 4_000;
2852
+ const MAX_ACTION_FILE_PATHS = 100;
2853
+ export const MAX_ACTION_FILE_PATH_LENGTH = 1_024;
2854
+ /**
2855
+ * An action id as it may appear in a prompt: bounded, and free of the control
2856
+ * characters that would let it break out of the line it is rendered on. Ids are
2857
+ * the one field the grader reads back and cites, so they cannot be truncated or
2858
+ * sanitized after the fact without silently detaching every citation that used
2859
+ * them — the boundary is the only place to reject a bad one.
2860
+ */
2861
+ const ActionIdSchema = v.pipe(v.string(), v.maxLength(MAX_ACTION_ID_LENGTH), v.regex(/^[^\p{Cc}\p{Cf}\s]*$/u, 'id must not contain whitespace or control characters'));
2862
+ export const DashboardSyncActionSchema = v.object({
2863
+ id: v.optional(ActionIdSchema),
2864
+ sessionId: v.optional(v.string()),
2865
+ /**
2866
+ * Optional on the wire, but **required to be graded**: runs are the only
2867
+ * grading unit, and an action with no session joins no run.
2868
+ * The field stays optional because
2869
+ * tightening it would 400 a whole batch — a poison pill for any queue file
2870
+ * carrying one — and no shipped CLI omits it: the hook always writes a
2871
+ * session id, falling back to the literal `'unknown'`
2872
+ * (`packages/cli/src/hook-logger.ts:364`), which groups into a run like any
2873
+ * other. A direct API caller that omits it gets its actions stored and
2874
+ * ungraded, and the server logs `sync.actions_without_session` so the case is
2875
+ * visible rather than silent.
2876
+ */
2877
+ agentSessionId: v.optional(v.string()),
2878
+ actionType: v.pipe(v.string(), v.maxLength(MAX_ACTION_TYPE_LENGTH)),
2879
+ summary: v.pipe(v.string(), v.maxLength(MAX_ACTION_SUMMARY_LENGTH)),
2880
+ filePaths: v.optional(v.pipe(v.array(v.pipe(v.string(), v.maxLength(MAX_ACTION_FILE_PATH_LENGTH))), v.maxLength(MAX_ACTION_FILE_PATHS))),
2881
+ verdict: v.optional(VerdictSchema),
2882
+ gradingTier: v.optional(DashboardSyncTierSchema),
2883
+ guideIds: v.optional(v.array(v.string())),
2884
+ violatedGuideId: v.optional(v.nullable(v.string())),
2885
+ evalReasoning: v.optional(v.nullable(v.string())),
2886
+ metadata: v.optional(v.nullable(ActionMetadataSchema)),
2887
+ /**
2888
+ * Transcript evidence for this action. See {@link ActionNarrationSchema}.
2889
+ *
2890
+ * A top-level field rather than a `metadata` key, and that is a decision
2891
+ * rather than a style choice (design review, 2026-08-15): `metadata` is an
2892
+ * open record holding *metadata* under one shared 16 KB budget, and this is
2893
+ * content — the first content an action carries. It lands in its own column
2894
+ * server-side for the same reason.
2895
+ *
2896
+ * **No shipped CLI sends this yet.** Slice 2 builds the extraction and both
2897
+ * halves of the enforcement; Slice 3 adds the column and the disclosure
2898
+ * surface and is what turns it on, so nothing begins leaving a user's machine
2899
+ * a release before the panel describing it.
2900
+ */
2901
+ narration: v.optional(ActionNarrationSchema),
2902
+ });
2903
+ export const DashboardGuideSuggestionSchema = v.object({
2904
+ id: v.optional(v.string()),
2905
+ content: v.string(),
2906
+ reasoning: v.optional(v.string()),
2907
+ triggerType: v.picklist([
2908
+ 'uncovered',
2909
+ 'ambiguous',
2910
+ 'performance_pattern',
2911
+ 'conversational_feedback',
2912
+ ]),
2913
+ sourceActionIds: v.optional(v.array(v.union([v.string(), ProposalCitationSchema]))),
2914
+ status: v.optional(DashboardGuideSuggestionStatusSchema),
2915
+ });
2916
+ /** Max number of actions accepted in a single `POST /api/sync` request. */
2917
+ export const MAX_SYNC_ACTIONS_BATCH = 500;
2918
+ /** Max number of guideSuggestions/runUsage entries per sync request. */
2919
+ export const MAX_SYNC_AUX_BATCH = 100;
2920
+ /**
2921
+ * Max rule files one delivery manifest enumerates. Well above what a real repo
2922
+ * carries (this one: ~20), and bounded because the manifest rides every
2923
+ * action-carrying batch: an unbounded list would multiply across a chunked
2924
+ * sync. Overflow sets `truncated` rather than being dropped silently.
2925
+ */
2926
+ export const MAX_RULE_MANIFEST_FILES = 500;
2927
+ /**
2928
+ * A rule file observed on disk in the repo `mossbear report` ran from.
2929
+ *
2930
+ * `path` is relative to that repo root, in exactly the form `payloadPath`
2931
+ * takes at import time (`packages/cli/src/rules/discover.ts`), so
2932
+ * `file:{format}:{path}` reconstructs the `origin` the dashboard stored for
2933
+ * the guide this file produced. That reconstruction is the whole join; nothing
2934
+ * else about the file is needed and nothing else is sent.
2935
+ *
2936
+ * **Never any content.** `contentHash` is the same sha256 the import payload
2937
+ * carries, present so a later slice can tell "delivered" from "delivered but
2938
+ * edited since import" without shipping the bytes again.
2939
+ */
2940
+ export const RuleManifestFileSchema = v.object({
2941
+ path: v.pipe(v.string(), v.minLength(1), v.maxLength(512)),
2942
+ format: GuideFileFormatSchema,
2943
+ contentHash: Sha256HexSchema,
2944
+ });
2945
+ /**
2946
+ * Which rule files were actually on disk in the repo this sync ran from —
2947
+ * observed delivery, replacing the assumption that every non-skill active
2948
+ * guide reached the agent. Without it, an account with several repos, or a
2949
+ * dashboard-authored guide never exported anywhere, is graded against
2950
+ * instructions the agent never received.
2951
+ *
2952
+ * `repoId` is an opaque, machine-local digest — deliberately not a path, a
2953
+ * remote URL, or a repo name. Its only job is to keep two checkouts on the
2954
+ * same account distinguishable, which is the half of review finding 5 that
2955
+ * repo-root-relative origins cannot express: two repos each holding
2956
+ * `.claude/skills/review` produce byte-identical origins by construction. See
2957
+ * `repoIdFromRoot` (`packages/cli/src/rules/manifest.ts`) for how it is
2958
+ * derived and why that derivation is privacy-safe.
2959
+ */
2960
+ export const RuleFileManifestSchema = v.object({
2961
+ repoId: RepoIdSchema,
2962
+ files: v.pipe(v.array(RuleManifestFileSchema), v.maxLength(MAX_RULE_MANIFEST_FILES)),
2963
+ /**
2964
+ * The repo held more rule files than the cap, so `files` is a prefix. Set
2965
+ * rather than silently trimmed: a manifest read as complete would mark the
2966
+ * omitted files' guides undelivered, which is the exact wrong-verdict
2967
+ * failure this field exists to prevent.
2968
+ */
2969
+ truncated: v.optional(v.boolean()),
2970
+ });
2971
+ /**
2972
+ * Where the checkout stood when a run closed — the git head the `SessionEnd`
2973
+ * hook observed, and the branch it was on.
2974
+ *
2975
+ * The join the ledger has never had. Every existing query walks run → what
2976
+ * happened; nothing walks commit → which run, because until this field no
2977
+ * commit, branch or PR identifier existed anywhere in the pipeline.
2978
+ * An anchor also cannot be backfilled:
2979
+ * a run that closes without one is unanchorable forever, which is why it is
2980
+ * captured before its first reader exists.
2981
+ *
2982
+ * Absence is an ordinary answer rather than a failure to report. A session runs
2983
+ * outside a git repo; git is missing, or slow enough that the capture's own
2984
+ * timeout fires — the field is then simply not sent, and the run's columns stay
2985
+ * null. A checkout on a detached head sends an anchor with a null `branch`.
2986
+ * None of it says anything to the user: a run that produced no identifiable
2987
+ * commit is a normal run, and the CLI has nothing to offer them about it.
2988
+ *
2989
+ * There is deliberately no `prNumber` here. It is the one part of the anchor
2990
+ * that is not free: no environment variable in a real cloud agent session names
2991
+ * a PR (checked 2026-08-22 — see the spec's Open questions), so a wire field
2992
+ * for it would be protocol surface no producer ever fills. `runs.pr_number`
2993
+ * exists as a reserved column; the wire waits for a mechanism.
2994
+ *
2995
+ * Not a per-action field and not a per-session map: it describes the machine
2996
+ * and the checkout at one instant, the way `RuleFileManifestSchema` does, and
2997
+ * applies to whichever runs the request closes.
2998
+ */
2999
+ export const CommitAnchorSchema = v.object({
3000
+ /**
3001
+ * `git rev-parse HEAD`. Full 40-hex only — an abbreviated sha is ambiguous
3002
+ * across repos and would make the reverse index it feeds silently lossy.
3003
+ *
3004
+ * Required *within* the object, while the object itself is optional. The two
3005
+ * together say the one thing worth saying: an anchor exists exactly when a
3006
+ * head was observed. A nullable `headSha` would add a third state — "an
3007
+ * anchor, but of nothing" — that no caller can produce (the only checkout
3008
+ * with a branch and no head is one with no commits, where both probes fail)
3009
+ * and every reader would still have to handle.
3010
+ */
3011
+ headSha: v.pipe(v.string(), v.regex(/^[0-9a-f]{40}$/)),
3012
+ /**
3013
+ * The branch name, or null on a detached head — which is a real state a
3014
+ * bisect or a CI checkout sits in, not an error. Capped so a pathological
3015
+ * ref name cannot widen the payload.
3016
+ */
3017
+ branch: v.nullable(v.pipe(v.string(), v.minLength(1), v.maxLength(255))),
3018
+ });
3019
+ /**
3020
+ * The agent's closing account of the run — the prose of the session's final
3021
+ * assistant message.
3022
+ *
3023
+ * **The same content class as narration, so it is literally the same schema**
3024
+ * rather than a twin of it: produced by the same client-side pipeline (text
3025
+ * blocks only → strip code structurally → redact prose → bound), carrying the
3026
+ * same guarantees, capped at the same `MAX_ACTION_NARRATION_CHARS`, and
3027
+ * rejected on the same line-initial fence. A separate declaration with the same
3028
+ * body would be two homes for one rule and would drift the first time either
3029
+ * moved. What differs is *which* prose and how much of it — the client's
3030
+ * concern, decided in `extractSessionSelfReport`, not the wire's.
3031
+ *
3032
+ * `minLength(1)` because absence has exactly one representation here: a run
3033
+ * with nothing to report omits the field. An empty string would be a second
3034
+ * spelling of null that every reader would then have to handle.
3035
+ *
3036
+ * **It names its session, and that is not decoration.** This is where the
3037
+ * report parts company with `CommitAnchorSchema`, which carries no session id
3038
+ * and is right not to: an anchor describes the *checkout*, so it applies to
3039
+ * whichever runs a request closes. A self-report describes the work of exactly
3040
+ * one session. A request can close more than one — `buildSyncBatches` marks
3041
+ * every session in the upload's actions completed when `sessionComplete` is set
3042
+ * (`packages/cli/src/sync-batches.ts:118-126`), which a `SessionEnd` sync hits
3043
+ * whenever an earlier session's `Stop` sync failed and left a backlog. Without
3044
+ * the id the server would write one session's closing summary onto the other
3045
+ * session's run, and slice 2 would then grade a run's actions against a report
3046
+ * of different work: a confidently wrong finding, which this pipeline ranks
3047
+ * below having none at all (`packages/cli/src/transcript/narration.ts:1-20`).
3048
+ *
3049
+ * The id makes the server the enforcement point rather than the client. A CLI
3050
+ * that attaches the report to the wrong batch cannot misattribute it, because
3051
+ * the writer matches on this field instead of trusting placement.
3052
+ */
3053
+ export const SessionSelfReportSchema = v.object({
3054
+ /** The session whose closing message this is. Must be one the request closes. */
3055
+ agentSessionId: NonEmptyStringSchema,
3056
+ /** The report itself — same content class and cap as narration. */
3057
+ text: v.pipe(NarrationTextSchema, v.minLength(1)),
3058
+ });
3059
+ /** One prose-redacted user turn, captured independently of tool actions. */
3060
+ export const DashboardSyncTurnSchema = v.strictObject({
3061
+ agentSessionId: NonEmptyStringSchema,
3062
+ ordinal: v.pipe(v.number(), v.integer(), v.minValue(1)),
3063
+ text: v.pipe(NarrationTextSchema, v.minLength(1)),
3064
+ });
3065
+ /**
3066
+ * The CLI entry point a sync came from, when that entry point is a hook.
3067
+ *
3068
+ * **One member on purpose.** `mossbear refresh` is the command
3069
+ * `mossbear init` registers as the `SessionStart` hook, and nothing else runs
3070
+ * it — so a request carrying this value is proof that the hooks a project was
3071
+ * set up with are firing, which is the one onboarding fact the dashboard could
3072
+ * not previously observe. The other two hooks (`Stop`, `SessionEnd`) both run
3073
+ * `mossbear report`, which is also the command a person types by hand; their
3074
+ * requests are therefore indistinguishable from a manual sync and are
3075
+ * deliberately not named here rather than guessed at.
3076
+ *
3077
+ * Optional on the envelope, and its absence means only "not known to be a
3078
+ * session-start sync" — never "no hooks". A CLI predating this field sends
3079
+ * none, and so does every ordinary `mossbear report`.
3080
+ *
3081
+ * A user can pass the flag that sets this by hand. That is not a privilege
3082
+ * boundary: the value is scoped to the caller's own account and the only thing
3083
+ * it can buy them is a more optimistic sentence on their own onboarding
3084
+ * screen.
3085
+ */
3086
+ export const SyncOriginSchema = v.picklist(['session-start']);
3087
+ export const DashboardSyncRequestSchema = v.object({
3088
+ actions: v.optional(v.pipe(v.array(DashboardSyncActionSchema), v.maxLength(MAX_SYNC_ACTIONS_BATCH))),
3089
+ guideSuggestions: v.optional(v.pipe(v.array(DashboardGuideSuggestionSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
3090
+ runUsage: v.optional(v.pipe(v.array(DashboardSessionUsageSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
3091
+ skillUsage: v.optional(v.pipe(v.array(DashboardSkillUsageSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
3092
+ turns: v.optional(v.pipe(v.array(DashboardSyncTurnSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
3093
+ /**
3094
+ * Version of the CLI making *this request* — the only `cliVersion` on the
3095
+ * wire. (A per-action one existed until `action-cli-version-column-drop`; it
3096
+ * attributed a verdict to the CLI that produced it, which no CLI does any
3097
+ * more.) It sits on the envelope because the server reads it before touching
3098
+ * any row, to
3099
+ * compare against its version floor and reject an incompatible client with
3100
+ * 426 rather than half-ingesting the batch. Optional: clients predating this
3101
+ * field send none, and are never blocked for it.
3102
+ */
3103
+ cliVersion: v.optional(CliVersionSchema),
3104
+ /**
3105
+ * Sessions whose agent context has ended, named by the CLI's `SessionEnd`
3106
+ * hook (`mossbear complete`) — never by its per-turn `Stop` hook.
3107
+ * The server closes those sessions' runs; every other session in the payload
3108
+ * stays open.
3109
+ *
3110
+ * Session-keyed rather than a single envelope-level boolean, because one
3111
+ * `mossbear report` uploads every session with pending actions and chunks them
3112
+ * across several requests. A boolean would close sessions that merely had a
3113
+ * backlog, and would close a session before the batches carrying the rest of
3114
+ * its actions had arrived. The CLI therefore names a session here only on the
3115
+ * final batch that carries that session's actions.
3116
+ *
3117
+ * Deliberately an assertion, not a fact: `SessionEnd` also fires on
3118
+ * `/clear`, `--resume` and `logout`, and a reclaimed cloud container may fire
3119
+ * nothing at all. Closing is therefore reversible — later actions for a
3120
+ * closed run reopen it — and the server's idle sweep, not this field, is what
3121
+ * runs actually depend on being closed by.
3122
+ */
3123
+ completedSessionIds: v.optional(v.pipe(v.array(NonEmptyStringSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
3124
+ /**
3125
+ * The rule files present in the repo this sync ran from — see
3126
+ * {@link RuleFileManifestSchema}.
3127
+ *
3128
+ * Envelope-level rather than per-action because it describes the machine and
3129
+ * the checkout, not any one tool call; the server attaches it to the runs it
3130
+ * materializes from this request. Present on every batch that carries
3131
+ * actions, so a session chunked across several requests has the manifest
3132
+ * available wherever its run is touched.
3133
+ *
3134
+ * Optional: a CLI predating this sends none, and the server must read its
3135
+ * absence as "delivery unobserved", never as "nothing was delivered".
3136
+ */
3137
+ ruleManifest: v.optional(RuleFileManifestSchema),
3138
+ /**
3139
+ * Where the checkout stood when this request's `completedSessionIds` closed —
3140
+ * see {@link CommitAnchorSchema}.
3141
+ *
3142
+ * Rides only the batches that name a completed session, which is the opposite
3143
+ * of `ruleManifest`'s placement rule and deliberately so. The ordinary
3144
+ * `SessionEnd` request carries **no actions at all** — the preceding `Stop`
3145
+ * hook synced and advanced the run-log cursor — so a field attached to
3146
+ * action-carrying batches would be absent from exactly the request that
3147
+ * exists to report the close.
3148
+ *
3149
+ * Optional, and an absent anchor is never an error: a CLI predating this
3150
+ * sends none, and the server must read its absence as "no head observed"
3151
+ * rather than refusing the close.
3152
+ */
3153
+ commitAnchor: v.optional(CommitAnchorSchema),
3154
+ /**
3155
+ * What the agent said it did, as its own closing message — see
3156
+ * {@link SessionSelfReportSchema}.
3157
+ *
3158
+ * Rides the same batches as `commitAnchor` and for the same reason: it
3159
+ * describes the *session that just ended*, and the ordinary `SessionEnd`
3160
+ * request carries no actions to attach it to. The server writes it onto the
3161
+ * runs this request closes.
3162
+ *
3163
+ * Optional, and its absence is never an error or a finding. A CLI predating
3164
+ * this sends none; so does a session with no transcript, one whose repo has
3165
+ * narration switched off, and one that ended without the agent speaking. All
3166
+ * of them are ordinary runs, and nothing downstream distinguishes them —
3167
+ * "could not compare" is not a verdict and renders nothing.
3168
+ */
3169
+ selfReport: v.optional(SessionSelfReportSchema),
3170
+ /**
3171
+ * Which of the CLI's entry points sent this request, named only when the
3172
+ * entry point is one an agent harness invokes rather than one a person types
3173
+ * — see {@link SyncOriginSchema}.
3174
+ */
3175
+ origin: v.optional(SyncOriginSchema),
3176
+ });
3177
+ export const ExtractedSkillSuggestionSchema = v.object({
3178
+ id: v.string(),
3179
+ signal: v.string(),
3180
+ confidence: v.pipe(v.number(), v.minValue(0), v.maxValue(1)),
3181
+ occurrences: v.pipe(v.number(), v.integer(), v.minValue(1)),
3182
+ citations: v.array(ProposalCitationSchema),
3183
+ source: PlatformKindSchema,
3184
+ });
3185
+ export const ExtractedFeedbackBatchSchema = v.object({
3186
+ skillSuggestions: v.array(ExtractedSkillSuggestionSchema),
3187
+ });
3188
+ // ---------------------------------------------------------------------------
3189
+ // Agent config schema
3190
+ // ---------------------------------------------------------------------------
3191
+ // AgentConfig was the input shape of `packages/projections`' renderers, which
3192
+ // were deleted with `projections-compat-renderers-dead`.
3193
+ // EvalRequest/EvalResult/Finding and ProjectionRequest/ProjectionResult used
3194
+ // to wrap it for the CLI's on-device grader and a projection wire envelope;
3195
+ // both are gone, and had zero consumers outside this package's own tests.
3196
+ //
3197
+ // The CLI command that produced these — `mossbear guides project` — is gone
3198
+ // too (`guides-project-removal`). The schema stays only because it is a
3199
+ // published export: nothing in the repo reads it since the renderers were
3200
+ // removed, and dropping it is a semver judgment, not a cleanup.
3201
+ export const AgentConfigSchema = v.object({
3202
+ id: v.string(),
3203
+ name: v.string(),
3204
+ description: v.string(),
3205
+ capabilities: v.array(v.string()),
3206
+ meta: v.optional(v.record(v.string(), v.unknown())),
3207
+ });
3208
+ // ---------------------------------------------------------------------------
3209
+ // Action log schemas
3210
+ // ---------------------------------------------------------------------------
3211
+ export const ActionEntrySchema = v.object({
3212
+ /**
3213
+ * Stable identity, assigned by the logger hook when the action happens.
3214
+ *
3215
+ * Serves two jobs at once: it is
3216
+ * the `actions.id` a sync sends, so re-syncing the same append-only run log
3217
+ * is a no-op against the server's `onConflictDoNothing`; and it is the
3218
+ * correlation key for joining transcript evidence to an action, which
3219
+ * adjacency cannot do once one assistant message emits several tool calls.
3220
+ *
3221
+ * Optional because run logs written before this field existed must stay
3222
+ * readable. Sync derives an id for those from `(agentSessionId, line index)`; see
3223
+ * `deriveLegacyActionId`.
3224
+ */
3225
+ id: v.optional(v.string()),
3226
+ timestamp: v.string(),
3227
+ agentSessionId: v.string(),
3228
+ toolName: v.string(),
3229
+ filePath: v.optional(v.string()),
3230
+ command: v.optional(v.string()),
3231
+ /**
3232
+ * Set only for a `Skill` tool call: which skill the agent loaded.
3233
+ *
3234
+ * This is what makes a skill load ride the action stream instead of the
3235
+ * transcript. `skill_usage` — the other place a loaded skill name is
3236
+ * recorded — is populated by `extractSessionUsage`, which returns empty unless
3237
+ * `mossbear report` is given `--transcripts-dir`, and the hook `mossbear init`
3238
+ * installs never passes one. So the transcript path has no data in a normal
3239
+ * session, while an action definitionally syncs.
3240
+ */
3241
+ skill: v.optional(ActionSkillLoadSchema),
3242
+ /**
3243
+ * Skills a shell call loaded by reading their `SKILL.md`, in a harness whose
3244
+ * manifest says that read is the load (Codex). A list because one command can
3245
+ * read several; kept apart from `skill`, which only a `Skill` call sets.
3246
+ * Local-to-upload like the rest of the entry: each becomes its own
3247
+ * `skill_load` action beside the shell call.
3248
+ */
3249
+ skillReads: v.optional(v.array(ActionSkillLoadSchema)),
3250
+ /**
3251
+ * Files inside a skill's directory (not its `SKILL.md`) a shell call read, as
3252
+ * paths relative to the working directory, in a harness that reads through
3253
+ * the shell. Each becomes its own `file_read` action beside the call, the
3254
+ * action a read tool would have produced.
3255
+ */
3256
+ memberReads: v.optional(v.array(v.string())),
3257
+ /**
3258
+ * Where this session's transcript lives on *this machine*, as the agent
3259
+ * itself reported it.
3260
+ *
3261
+ * **Local-only, and it must stay that way.** `toSyncAction`
3262
+ * (`packages/cli/src/action-queue.ts`) builds the wire payload field by
3263
+ * field and does not include this one; transcripts are disclosed as
3264
+ * local-only in the dashboard's own privacy disclosure, and a path is still
3265
+ * a fact about the user's filesystem. It exists so `mossbear report` can find
3266
+ * the transcript for a session it is already uploading without searching for
3267
+ * it.
3268
+ *
3269
+ * Optional three times over: run logs written before this field existed must
3270
+ * stay readable, a hook protocol other than Claude Code's may not send it,
3271
+ * and resolution falls back to the `<agentSessionId>.jsonl` filename convention
3272
+ * when it is absent or stale.
3273
+ */
3274
+ transcriptPath: v.optional(v.string()),
3275
+ /**
3276
+ * Which checkout produced this action — the same digest as
3277
+ * {@link RuleFileManifestSchema}'s `repoId`, stamped by the logger hook from
3278
+ * the event's `cwd` so a sync in repo A does not attach A's manifest to
3279
+ * sessions that ran in repo B (`run-repo-attribution`).
3280
+ */
3281
+ repoId: v.optional(RepoIdSchema),
3282
+ /**
3283
+ * Which *project* produced this action — the portable `project.id` a repo
3284
+ * commits in `.mossbear/config.json` (`ProjectIdSchema`), read by the logger
3285
+ * hook from the event's `cwd` beside `repoId`.
3286
+ *
3287
+ * The two answer different questions and both are needed. `repoId` is a
3288
+ * digest keyed by a machine-local secret, so it separates two checkouts on
3289
+ * one machine and matches nothing anywhere else — a fresh cloud container
3290
+ * mints a new key and so a new digest for the same repo. The handoff a
3291
+ * session reads at start (`session-handoff-context`) has to find *this
3292
+ * repo's* previous sessions from any machine, and the committed id is the
3293
+ * only key every clone agrees on.
3294
+ *
3295
+ * Optional: run logs written before this field existed must stay readable,
3296
+ * and a repo that has never run `mossbear init` declares no id.
3297
+ */
3298
+ projectId: v.optional(ProjectIdSchema),
3299
+ /**
3300
+ * Which harness produced this action, stamped by the logger hook from the
3301
+ * `--harness` flag on its own hook entry (`run-source-linking` slice 1).
3302
+ *
3303
+ * Optional twice over, and the second reading is the one that matters: run
3304
+ * logs written before this field existed must stay readable, **and a hook
3305
+ * entry that names no harness stamps nothing**. A bare `mossbear-hook` entry
3306
+ * resolves to the Claude Code *field map* — which is what it has always
3307
+ * meant, and is correct, because Codex and OpenCode send that same payload —
3308
+ * but it is not evidence of *which* of those harnesses invoked it. Writing
3309
+ * `claude_code` there would label every pre-upgrade Codex run as Claude Code,
3310
+ * silently, for exactly the multi-harness user this field exists for.
3311
+ */
3312
+ harness: v.optional(HarnessIdSchema),
3313
+ /**
3314
+ * `cloud` when the hook saw a cloud marker in its own process environment;
3315
+ * see {@link SessionEnvironmentSchema}. Absent otherwise, and absent never
3316
+ * means local.
3317
+ */
3318
+ environment: v.optional(SessionEnvironmentSchema),
3319
+ /**
3320
+ * Whether the tool call succeeded, when the hook could tell.
3321
+ *
3322
+ * Optional twice over: run logs written before this field existed must stay
3323
+ * readable, and a recognized response shape is not guaranteed even now. See
3324
+ * {@link ActionOutcomeSchema} — absent is "unknown", not "fine".
3325
+ */
3326
+ outcome: v.optional(ActionOutcomeSchema),
3327
+ });
3328
+ /**
3329
+ * Action types the CLI maps agent tool calls onto.
3330
+ *
3331
+ * Deliberately **not** a closed schema. `DashboardSyncAction.actionType` stays
3332
+ * an open string so a tool the CLI has never seen still syncs as itself
3333
+ * (`packages/cli/src/action-queue.ts` normalizes an unknown tool name rather
3334
+ * than collapsing it into a catch-all) — a closed picklist would silently drop
3335
+ * those. This list is the *known* vocabulary: what the CLI produces on purpose.
3336
+ *
3337
+ * It lives here because it is a contract between two packages that never import
3338
+ * each other. It used to also be the vocabulary the guide-trigger picker
3339
+ * offered; that picker is gone
3340
+ * and nothing matches against this list any more — relevance is observed from
3341
+ * what was in the agent's context, not asserted against an action type.
3342
+ *
3343
+ * `SKILL_LOAD_ACTION_TYPE` is the one type the CLI emits on purpose that is
3344
+ * deliberately absent here; see its own comment for why.
3345
+ */
3346
+ const KNOWN_ACTION_TYPES = [
3347
+ 'file_edit',
3348
+ 'file_read',
3349
+ 'shell_command',
3350
+ 'search',
3351
+ 'web_access',
3352
+ ];
3353
+ /** True when `value` is one of the action types the CLI produces on purpose. */
3354
+ export function isKnownActionType(value) {
3355
+ return KNOWN_ACTION_TYPES.includes(value);
3356
+ }
3357
+ // No run-eval result schema here. It was the contract for the CLI's on-device
3358
+ // grader, which is gone. The only grader left runs on the server and owns its
3359
+ // own output contract there — one shape of that fact, not two packages holding
3360
+ // copies that a comment has to keep in step.
3361
+ // ---------------------------------------------------------------------------
3362
+ // Guide verdict history (guide-history-for-agents)
3363
+ // ---------------------------------------------------------------------------
3364
+ /**
3365
+ * The read an agent makes of a guide's own grading record, so the improvement
3366
+ * loop the user already runs in-conversation ("what could be improved in this
3367
+ * skill?") has the evidence Mossbear holds and the agent does not.
3368
+ *
3369
+ * **Evidence out, never instructions out.** Nothing in this contract carries a
3370
+ * directive to change anything, and nothing on the server writes as a result of
3371
+ * it. It is a read, and the decision stays in the user's conversation.
3372
+ */
3373
+ /**
3374
+ * How the agent names the guide.
3375
+ *
3376
+ * Either a repo-relative path exactly as the guide file declares it
3377
+ * (`.claude/skills/reviewer/SKILL.md`, `AGENTS.md`), or the bare name of a
3378
+ * skill (`reviewer`), which the server expands to the skill layouts it knows.
3379
+ * Both resolve through the `(root, path)` identity import already reconciles
3380
+ * on, rather than a second one invented here.
3381
+ *
3382
+ * Bounded and shape-checked at the boundary rather than at the query string: it
3383
+ * reaches a SQL predicate, and an identifier is not free text.
3384
+ */
3385
+ export const GuideHistoryIdentifierSchema = v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(512), v.check((value) => !/[\u0000-\u001f\u007f]/.test(value), 'guide must not contain control characters'));
3386
+ /**
3387
+ * The request an agent sends.
3388
+ *
3389
+ * `root` is optional and is the disambiguator, not decoration: `.claude/skills`
3390
+ * is scanned under **both** discovery roots
3391
+ * (`packages/cli/src/rules/discover.ts:101,105`), so a project skill and its
3392
+ * `~/.claude/skills` twin declare the same path string. When the identifier
3393
+ * reaches guides under more than one root and no root was given, the server
3394
+ * refuses and names both rather than picking one — answering a question about
3395
+ * the wrong file's history is worse than not answering it.
3396
+ */
3397
+ export const GuideHistoryRequestSchema = v.object({
3398
+ guide: GuideHistoryIdentifierSchema,
3399
+ root: v.optional(GuideDiscoveryRootSchema),
3400
+ /**
3401
+ * Which repo's copy — **the axis import itself reconciles on**, and the one
3402
+ * that actually resolves the common collision.
3403
+ *
3404
+ * `root` alone does not, and assuming it did was the first version's defect:
3405
+ * import's resolution key is `(userId, repoId, root, path)` and two files at
3406
+ * one path under different repos deliberately stay two rows. So any
3407
+ * user with two repos has two guides at `(project, AGENTS.md)`, and a refusal
3408
+ * telling them to pass `root` names the one field that cannot separate those.
3409
+ *
3410
+ * `projectId` is the portable identity a repo commits and every clone agrees
3411
+ * on; `repoId` is the machine-local digest. Both are optional and both are
3412
+ * what the caller already sends at import time, so an agent running inside a
3413
+ * repo supplies them without being asked.
3414
+ */
3415
+ projectId: v.optional(NonEmptyStringSchema),
3416
+ repoId: v.optional(NonEmptyStringSchema),
3417
+ /**
3418
+ * The exact guide, when the caller has already been shown the candidates.
3419
+ *
3420
+ * The escape hatch that makes the refusal always satisfiable: two repos can
3421
+ * be indistinguishable to a caller that knows neither id (a guide imported
3422
+ * before repo identity was recorded carries neither), and an error whose
3423
+ * remedy cannot be carried out is worse than no remedy at all. The 409 names
3424
+ * this id for every candidate.
3425
+ */
3426
+ guideId: v.optional(NonEmptyStringSchema),
3427
+ });
3428
+ /**
3429
+ * One revision of a guide's wording: the body file and the version it stood at.
3430
+ *
3431
+ * The pair, never a bare version number — `guide_files.version` restarts at 1
3432
+ * per row, so a number alone compares equal across two different files.
3433
+ */
3434
+ export const GuideHistoryRevisionSchema = v.object({
3435
+ bodyItemId: NonEmptyStringSchema,
3436
+ version: v.pipe(v.number(), v.integer()),
3437
+ });
3438
+ /**
3439
+ * Which of three states the guide's record is in — a required field rather than
3440
+ * something a reader infers from empty arrays.
3441
+ *
3442
+ * The distinction is the whole point of returning it: `unevaluated` means no
3443
+ * graded run has ever produced a verdict, while `awaiting_current_revision`
3444
+ * means the guide has a real record that is entirely about wording the user has
3445
+ * since rewritten. Collapsing those two onto "no data" is exactly the claim the
3446
+ * dashboard stopped making with its awaiting-current-revision check, and an
3447
+ * agent reading an absence as a verdict is the same error one screen further
3448
+ * out.
3449
+ */
3450
+ export const GuideHistoryStateSchema = v.picklist([
3451
+ 'evaluated',
3452
+ 'awaiting_current_revision',
3453
+ 'unevaluated',
3454
+ ]);
3455
+ /**
3456
+ * The verdict window, scoped to the revision named beside it.
3457
+ *
3458
+ * Both denominators travel: `applicable` is the rate's own denominator
3459
+ * (`aligned + misaligned`), `total` is the window's row count including the runs
3460
+ * that never engaged the guide. Rendering one as the other is the defect
3461
+ * `alignment-rate-sample-disclosure` was filed for, and a payload carrying only
3462
+ * one of them would hand an agent the same mistake.
3463
+ */
3464
+ export const GuideHistoryWindowSchema = v.object({
3465
+ /** Rows summarized, after the revision narrow. */
3466
+ total: v.pipe(v.number(), v.integer()),
3467
+ aligned: v.pipe(v.number(), v.integer()),
3468
+ misaligned: v.pipe(v.number(), v.integer()),
3469
+ /** In context, never engaged. Neither a pass nor a failure. */
3470
+ notApplicable: v.pipe(v.number(), v.integer()),
3471
+ /** `aligned + misaligned` — the rate's own denominator. */
3472
+ applicable: v.pipe(v.number(), v.integer()),
3473
+ /** `aligned / applicable`, or **null when no run engaged the guide**. */
3474
+ alignmentRate: v.nullable(v.number()),
3475
+ /** The rows hit the per-guide cap: a bounded window, never a lifetime total. */
3476
+ isWindowed: v.boolean(),
3477
+ /** The cap the rows were fetched under, so a reader can say what "windowed" means. */
3478
+ windowSize: v.pipe(v.number(), v.integer()),
3479
+ /**
3480
+ * Verdicts fetched and then dropped by the revision narrow — about wording
3481
+ * that is no longer current, or citing no revision at all. A **floor** rather
3482
+ * than a total whenever `isWindowed`, because rows past the cap were never
3483
+ * fetched.
3484
+ */
3485
+ olderRevisionRows: v.pipe(v.number(), v.integer()),
3486
+ /**
3487
+ * `applicable` is too small for the percentage to mean anything — threshold
3488
+ * `applicable < 3` (founder, 2026-08-22). Read the counts, not the rate.
3489
+ */
3490
+ isLowConfidence: v.boolean(),
3491
+ });
3492
+ /**
3493
+ * One side of a guide edit's before/after pair — the wording, and what the runs
3494
+ * that engaged it did.
3495
+ *
3496
+ * Structurally a window like `GuideHistoryWindow` and deliberately not that
3497
+ * schema: these two sides are bounded **per revision** by a different
3498
+ * server-side query, so `isSaturated` is
3499
+ * the server's own measurement of its partition rather than the client-side
3500
+ * `isWindowed` inference, and the span each side covers is part of what makes
3501
+ * the pair readable.
3502
+ *
3503
+ * Both denominators travel here for the same reason they travel on the window:
3504
+ * a delta between two undisclosed denominators is worse than no number at all.
3505
+ */
3506
+ export const GuideHistoryChangeSideSchema = v.object({
3507
+ /** The wording this side judges. */
3508
+ revision: GuideHistoryRevisionSchema,
3509
+ /** Rows in this side's window, including the runs that never engaged it. */
3510
+ total: v.pipe(v.number(), v.integer()),
3511
+ aligned: v.pipe(v.number(), v.integer()),
3512
+ misaligned: v.pipe(v.number(), v.integer()),
3513
+ notApplicable: v.pipe(v.number(), v.integer()),
3514
+ /** `aligned + misaligned` — this side's own denominator. */
3515
+ applicable: v.pipe(v.number(), v.integer()),
3516
+ /** `aligned / applicable`, or null when no run engaged this wording. */
3517
+ alignmentRate: v.nullable(v.number()),
3518
+ /** This side is below the sample floor, so read its counts and not its rate. */
3519
+ isLowConfidence: v.boolean(),
3520
+ /**
3521
+ * This side is a bounded sample of its revision rather than the whole record.
3522
+ * A saturated side beside an unsaturated one is two different kinds of
3523
+ * number, and comparing them without saying so is the defect the flag exists
3524
+ * to stop.
3525
+ */
3526
+ isSaturated: v.boolean(),
3527
+ /** The span this side covers, ISO. Both null on a side with no rows. */
3528
+ newestAt: v.nullable(v.string()),
3529
+ oldestAt: v.nullable(v.string()),
3530
+ });
3531
+ /**
3532
+ * Which side is too thin for a delta to mean anything.
3533
+ *
3534
+ * Named rather than a boolean because the two take different sentences: too few
3535
+ * runs *since* the change is the ordinary state right after an edit, while too
3536
+ * few *before* it means there was never a baseline to compare against.
3537
+ */
3538
+ export const GuideHistoryChangeSuppressionSchema = v.picklist(['since', 'before', 'both']);
3539
+ /**
3540
+ * Which way the pair points, or null while the delta is withheld.
3541
+ *
3542
+ * A reading of a *set* of runs, never a verdict on one — the vocabulary
3543
+ * `aligned | misaligned | not_applicable` is untouched, and nothing derived
3544
+ * here is written back to a row.
3545
+ */
3546
+ export const GuideHistoryChangeDirectionSchema = v.picklist([
3547
+ 'improved',
3548
+ 'regressed',
3549
+ 'unchanged',
3550
+ ]);
3551
+ /**
3552
+ * The guide's last edit, read as two windows
3553
+ * (`insight-to-proven-change` §A, surfaced by `guide-history-for-agents`
3554
+ * deliverable 3).
3555
+ *
3556
+ * > Changed 12 Aug. Before: misaligned in 6 of 8 runs that engaged it.
3557
+ * > Since: 0 of 11.
3558
+ *
3559
+ * **Null on the response is a state, not a missing field.** It means this guide
3560
+ * has no earlier wording that produced evidence — a guide on its first
3561
+ * revision, which is the normal state and not an error.
3562
+ *
3563
+ * **Paired, never merged**, and **never causal**: this states two windows and
3564
+ * their denominators and stops. The model changed, the task mix changed and the
3565
+ * codebase changed too, so "since" is the strongest word the evidence supports.
3566
+ */
3567
+ export const GuideHistoryChangeSchema = v.object({
3568
+ /** The revision that preceded the change. */
3569
+ before: GuideHistoryChangeSideSchema,
3570
+ /** The wording the guide stands at now. */
3571
+ since: GuideHistoryChangeSideSchema,
3572
+ /**
3573
+ * `since` minus `before`, in `[-1, 1]`, or **null whenever the pair is
3574
+ * suppressed** or either side never engaged the guide. Null is not zero: one
3575
+ * says the evidence does not support a number, the other would be a claim.
3576
+ */
3577
+ alignmentRateDelta: v.nullable(v.number()),
3578
+ /**
3579
+ * Which side is below the sample floor, or null when neither is and the delta
3580
+ * stands. `'since'` is the ordinary post-edit state — *not enough runs since
3581
+ * this change* — and is reported rather than omitted.
3582
+ */
3583
+ suppressedBy: v.nullable(GuideHistoryChangeSuppressionSchema),
3584
+ /** The delta's sign, or null while it is withheld. `unchanged` is exactly zero. */
3585
+ direction: v.nullable(GuideHistoryChangeDirectionSchema),
3586
+ /** Either side is a bounded sample, so neither is a lifetime total. */
3587
+ isWindowed: v.boolean(),
3588
+ /** The per-revision cap each side was bounded by, so "sample" has a size. */
3589
+ windowSize: v.pipe(v.number(), v.integer()),
3590
+ /**
3591
+ * When the current wording was recorded, ISO — the boundary between the two
3592
+ * windows, and null when no version row carries it.
3593
+ *
3594
+ * A date, never an attribution: it says when the window opened, not that the
3595
+ * edit caused what happened inside it.
3596
+ */
3597
+ changedAt: v.nullable(v.string()),
3598
+ });
3599
+ /** Findings returned per response, and the character bound on each reasoning. */
3600
+ export const MAX_GUIDE_HISTORY_FINDINGS = 5;
3601
+ export const MAX_GUIDE_HISTORY_REASONING_CHARS = 1200;
3602
+ /**
3603
+ * One recorded finding: a run that judged this guide misaligned, and why.
3604
+ *
3605
+ * `reasoning` arrives **already wrapped in the response's untrusted markers**
3606
+ * rather than raw. It is model-authored text derived from a transcript, so the
3607
+ * discipline the run grader applies to such text on the way in applies on the
3608
+ * way out; wrapping it at the source is what makes the boundary
3609
+ * unforgeable, since a consumer handed raw text plus separate markers can
3610
+ * simply not use them.
3611
+ *
3612
+ * `isCurrentRevision` is not optional detail. A payload that scopes its *rate*
3613
+ * to the current wording and then hands over reasoning about deleted sentences,
3614
+ * unlabelled, reproduces inside one response the conflation
3615
+ * `pattern-evidence-guide-revision` removed from the dashboard.
3616
+ */
3617
+ export const GuideHistoryFindingSchema = v.object({
3618
+ sessionId: NonEmptyStringSchema,
3619
+ occurredAt: v.string(),
3620
+ revision: v.nullable(GuideHistoryRevisionSchema),
3621
+ isCurrentRevision: v.boolean(),
3622
+ reasoning: v.string(),
3623
+ });
3624
+ /** The guide the identifier resolved to, echoed so the agent can check itself. */
3625
+ export const GuideHistoryGuideSchema = v.object({
3626
+ id: NonEmptyStringSchema,
3627
+ title: v.string(),
3628
+ path: v.nullable(SafeRelativePosixPathSchema),
3629
+ root: v.nullable(GuideDiscoveryRootSchema),
3630
+ });
3631
+ /**
3632
+ * The newest stored failure-pattern analysis of the guide, as the reader's own
3633
+ * dashboard shows it (`drafted-guide-suggestions` slice 7).
3634
+ *
3635
+ * **The caller's own analysis only.** An analysis reads the caller's verdicts,
3636
+ * so a workspace-mate's is never returned, the same rule the verdicts follow.
3637
+ *
3638
+ * **Staleness is derived on read**, exactly as the dashboard derives it: the
3639
+ * guide's wording changed since (`revision_changed`), or failures of the same
3640
+ * wording arrived that it has not read (`new_failures`, with how many). A stale
3641
+ * analysis is still what it found; it is reported, never withheld.
3642
+ *
3643
+ * `summary` arrives wrapped in the response's untrusted markers. It is
3644
+ * model-authored text derived from session transcripts. On `no_pattern` it may
3645
+ * be empty between them, because the dashboard supplies that sentence itself.
3646
+ */
3647
+ export const GuideHistoryAnalysisSchema = v.object({
3648
+ id: NonEmptyStringSchema,
3649
+ /** When it was written, ISO. */
3650
+ createdAt: v.string(),
3651
+ outcome: v.picklist(['pattern', 'no_pattern']),
3652
+ summary: v.string(),
3653
+ /** Failed sessions the analysis read. */
3654
+ sessionsAnalysed: v.pipe(v.number(), v.integer()),
3655
+ /** Failed sessions it left out to stay within its prompt's cap. */
3656
+ sessionsOmitted: v.pipe(v.number(), v.integer()),
3657
+ stale: v.boolean(),
3658
+ /** Why it is out of date, or null while it is current. */
3659
+ staleReason: v.nullable(v.picklist(['revision_changed', 'new_failures'])),
3660
+ /** Failures it has not read, when `staleReason` is `new_failures`; else null. */
3661
+ newFailures: v.nullable(v.pipe(v.number(), v.integer())),
3662
+ });
3663
+ export const GuideHistoryResponseSchema = v.object({
3664
+ guide: GuideHistoryGuideSchema,
3665
+ /** The wording the window is about, or null when the guide has no revision identity. */
3666
+ currentRevision: v.nullable(GuideHistoryRevisionSchema),
3667
+ state: GuideHistoryStateSchema,
3668
+ window: GuideHistoryWindowSchema,
3669
+ /**
3670
+ * The last edit's two windows, or **null when there is no earlier wording to
3671
+ * compare against**.
3672
+ *
3673
+ * Present-and-null rather than omitted: a guide on its first revision has no
3674
+ * delta, and that is an answer. An absent key would leave a reader unable to
3675
+ * tell "no edit to measure" from "this server does not report deltas".
3676
+ */
3677
+ change: v.nullable(GuideHistoryChangeSchema),
3678
+ findings: v.array(GuideHistoryFindingSchema),
3679
+ /**
3680
+ * Misaligned rows in the window beyond the `MAX_GUIDE_HISTORY_FINDINGS`
3681
+ * returned. Reported rather than silently truncated: a caller reading five
3682
+ * findings has no other way to know it is reading five of forty.
3683
+ */
3684
+ findingsOmitted: v.pipe(v.number(), v.integer()),
3685
+ /**
3686
+ * The caller's newest stored failure-pattern analysis of this guide, or
3687
+ * **null when they have never asked for one**. Optional because a server
3688
+ * that predates it sends no key; a reader must not take absence for "never
3689
+ * analysed".
3690
+ */
3691
+ analysis: v.optional(v.nullable(GuideHistoryAnalysisSchema)),
3692
+ untrusted: GuideHistoryUntrustedSchema,
3693
+ });
3694
+ // ---------------------------------------------------------------------------
3695
+ // Artifact feedback — open comments and grading for one artifact
3696
+ // (`GET /api/v1/artifacts/:id/feedback`)
3697
+ // ---------------------------------------------------------------------------
3698
+ /**
3699
+ * `GET .../feedback` query. `cursor` is the `nextCursor` of the previous page,
3700
+ * opaque to callers; a malformed one is a 400, never a restart from page one.
3701
+ */
3702
+ export const ArtifactFeedbackQuerySchema = v.object({
3703
+ cursor: v.optional(v.pipe(v.string(), v.regex(/^[0-9]{1,16}:[A-Za-z0-9_-]{1,128}$/, 'cursor is not a feedback cursor'))),
3704
+ /**
3705
+ * The reader's checkout, as its committed `project.id`. Without it, a Mossbear
3706
+ * correction drafted for one repo is withheld, as on the comments read.
3707
+ */
3708
+ project: v.optional(DeclaredProjectIdSchema),
3709
+ /**
3710
+ * The release asking. Replies on a thread are sent only to one that renders
3711
+ * threads; without it the page is roots only, as it was.
3712
+ */
3713
+ cli: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(64))),
3714
+ });
3715
+ /**
3716
+ * Why `grading` is null. Closed vocabulary, so a reader branches on `code`
3717
+ * rather than on wording.
3718
+ *
3719
+ * - `not-graded`: this artifact is not a guide, so nothing grades it.
3720
+ * - `not-available-to-credential`: the credential is limited to bundles, and
3721
+ * grading is not offered to those. It is the only reason a limited credential
3722
+ * ever sees, whatever the artifact is, so it says nothing about whether
3723
+ * grading data exists.
3724
+ */
3725
+ export const ArtifactGradingUnavailableSchema = v.object({
3726
+ code: v.picklist(['not-graded', 'not-available-to-credential']),
3727
+ reason: v.string(),
3728
+ });
3729
+ /**
3730
+ * What people, agents and grading have said about one artifact.
3731
+ *
3732
+ * `grading` is the guide's grading record for the same caller (the guide history route's payload), or
3733
+ * null with `gradingUnavailable` saying why. It is never a zeroed record:
3734
+ * absence is not a verdict. Comment evidence is never inlined.
3735
+ */
3736
+ export const ArtifactFeedbackResponseSchema = v.object({
3737
+ artifactId: v.pipe(v.string(), v.minLength(1)),
3738
+ /** The artifact's current version, as `read` reports it. */
3739
+ version: v.pipe(v.number(), v.integer(), v.minValue(1)),
3740
+ /** Open comments, oldest first by `(createdAt, id)`. */
3741
+ comments: v.array(ArtifactCommentSchema),
3742
+ /** Absent on the last page; pass it back as `cursor` for the next. */
3743
+ nextCursor: v.optional(v.string()),
3744
+ /** The markers every comment `body` is wrapped in; present when any comment came back. */
3745
+ untrusted: v.optional(v.nullable(GuideHistoryUntrustedSchema)),
3746
+ grading: v.nullable(GuideHistoryResponseSchema),
3747
+ /** Present exactly when `grading` is null. */
3748
+ gradingUnavailable: v.optional(ArtifactGradingUnavailableSchema),
3749
+ });
3750
+ /** Most artifacts one batch feedback read may name. */
3751
+ export const MAX_ARTIFACT_FEEDBACK_BATCH = 25;
3752
+ /**
3753
+ * `POST /api/v1/artifacts/feedback` body: several artifacts read at once, each
3754
+ * paged as `GET .../:id/feedback` pages it (`cursor` is that artifact's own
3755
+ * `nextCursor`). `project` and `cli` mean what they mean on the single read.
3756
+ */
3757
+ export const ArtifactFeedbackBatchRequestSchema = v.object({
3758
+ artifacts: v.pipe(v.array(v.object({
3759
+ id: v.pipe(v.string(), v.minLength(1), v.maxLength(512)),
3760
+ cursor: ArtifactFeedbackQuerySchema.entries.cursor,
3761
+ })), v.minLength(1), v.maxLength(MAX_ARTIFACT_FEEDBACK_BATCH)),
3762
+ project: ArtifactFeedbackQuerySchema.entries.project,
3763
+ cli: ArtifactFeedbackQuerySchema.entries.cli,
3764
+ });
3765
+ /**
3766
+ * One entry per requested id, in request order. `feedback` is null for an id
3767
+ * the caller cannot read, missing or out of scope alike, and carries nothing
3768
+ * else about it; the other entries are unaffected. A read that failed is
3769
+ * `unavailable: true` instead, and nothing of it was counted as delivered.
3770
+ */
3771
+ export const ArtifactFeedbackBatchResponseSchema = v.object({
3772
+ artifacts: v.array(v.object({
3773
+ id: v.string(),
3774
+ feedback: v.nullable(ArtifactFeedbackResponseSchema),
3775
+ /** Set on a null `feedback` that is a failed read, not an unreadable id: ask again. */
3776
+ unavailable: v.optional(v.literal(true)),
3777
+ })),
3778
+ });
3779
+ // ---------------------------------------------------------------------------
3780
+ // Run grade — one run's verdict, for the terminal (`GET /api/v1/runs/grade`)
3781
+ // ---------------------------------------------------------------------------
3782
+ /**
3783
+ * One session's grade, read by the MCP `session_digest` tool.
3784
+ *
3785
+ * The loop this closes: a session ends with "synced N item(s) to the
3786
+ * dashboard." and the verdict exists only in the dashboard. This is the read
3787
+ * that brings it back to the terminal the work happened in.
3788
+ *
3789
+ * **Evidence out, never instructions out** — the same contract as the guide
3790
+ * history read above. It returns data and never a directive; nothing on the
3791
+ * server writes as a result of it.
3792
+ */
3793
+ /**
3794
+ * How the caller names the run. Exactly one of the two.
3795
+ *
3796
+ * The CLI only ever knows an *agent session* id — the `SessionEnd` hook
3797
+ * payload's `session_id`, which `mossbear complete` reports — so
3798
+ * the `agent_session` form is the one it uses. The session id is for a caller
3799
+ * that already has one, from a dashboard URL say. Both are opaque and both
3800
+ * reach a SQL predicate, so they are bounded and shape-checked here.
3801
+ */
3802
+ const SessionGradeIdentifierSchema = v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(256), v.check((value) => !/[\u0000-\u001f\u007f]/.test(value), 'identifier must not contain control characters'));
3803
+ export const SessionGradeRequestSchema = v.pipe(v.object({
3804
+ session: v.optional(SessionGradeIdentifierSchema),
3805
+ agent_session: v.optional(SessionGradeIdentifierSchema),
3806
+ /**
3807
+ * Opt in to the session digest: the grade plus the turns, self-report and
3808
+ * git position of the session. Omitted, the small grade payload is
3809
+ * returned unchanged.
3810
+ */
3811
+ detail: v.optional(v.literal('digest')),
3812
+ }), v.check((request) => (request.session !== undefined) !== (request.agent_session !== undefined), 'Pass exactly one of session or agent_session'));
3813
+ /**
3814
+ * Which of four states the run's grade is in — a required field rather than
3815
+ * something a reader infers from a null `grade`.
3816
+ *
3817
+ * These states need different sentences, and the absence of a grade is never
3818
+ * one of them on its own:
3819
+ *
3820
+ * - `pending` — no grade yet, and the grading sweep can still pick the run
3821
+ * up (it is open, or closed inside the grading window). "Not graded yet"
3822
+ * is honest here and only here — unless `gradeFailedAttempts` is above
3823
+ * zero, when grading has been tried and has not finished.
3824
+ * - `graded` — a grader judged it; `grade` carries what it said.
3825
+ * - `nothing_to_grade` — a grader ran and found nothing to judge: no
3826
+ * gradeable actions, or no guides in the agent's context. The record
3827
+ * cannot tell those two apart, so neither can the sentence.
3828
+ * - `expired` — no grade, and the run closed too long ago for the sweep to
3829
+ * select it. It will never be graded, and telling a reader to wait would
3830
+ * promise work the system does not do.
3831
+ * - `grading_off` — only usage was synced; no behavioral grade is requested.
3832
+ */
3833
+ export const SessionGradeStateSchema = v.picklist([
3834
+ 'pending',
3835
+ 'graded',
3836
+ 'nothing_to_grade',
3837
+ 'expired',
3838
+ 'grading_off',
3839
+ ]);
3840
+ /**
3841
+ * The run-level verdict vocabulary — `aligned | misaligned | not_applicable`.
3842
+ * `not_applicable` is a guide that was in the agent's context and that the
3843
+ * session never engaged. It is not `unguided`, which is an action-level word,
3844
+ * and neither is ever restated in terms of the other.
3845
+ */
3846
+ export const SESSION_GUIDE_VERDICTS = ['aligned', 'misaligned', 'not_applicable'];
3847
+ export const SessionGuideVerdictValueSchema = v.picklist(SESSION_GUIDE_VERDICTS);
3848
+ /** One guide's verdict for the run, with the grader's reasoning wrapped. */
3849
+ export const SessionGradeGuideSchema = v.object({
3850
+ guideId: NonEmptyStringSchema,
3851
+ title: v.string(),
3852
+ verdict: SessionGuideVerdictValueSchema,
3853
+ /**
3854
+ * The grader's reasoning, **already wrapped in the response's untrusted
3855
+ * markers** — model-authored text derived from a transcript, delimited at the
3856
+ * source so a consumer cannot skip the markers. Empty between the markers
3857
+ * when the row recorded none.
3858
+ */
3859
+ reasoning: v.string(),
3860
+ });
3861
+ export const SessionGradeSchema = v.object({
3862
+ /** The grader's one-paragraph judgment of the run, wrapped like `reasoning`; null when the record carries none. */
3863
+ summary: v.nullable(v.string()),
3864
+ /** ISO timestamp, machine format — display formatting is the reader's job. */
3865
+ gradedAt: v.string(),
3866
+ /** The model that produced the judgment, or null when the record does not say. */
3867
+ model: v.nullable(v.string()),
3868
+ /**
3869
+ * True when the run grew after this grade was written — a later sync
3870
+ * attached more actions — so the judgment describes a smaller run than the
3871
+ * one on record. A superseded grade is real and is still reported; it is
3872
+ * labelled rather than hidden.
3873
+ */
3874
+ superseded: v.boolean(),
3875
+ guides: v.array(SessionGradeGuideSchema),
3876
+ });
3877
+ export const GradedSessionSchema = v.object({
3878
+ id: NonEmptyStringSchema,
3879
+ agentSessionId: NonEmptyStringSchema,
3880
+ startedAt: v.string(),
3881
+ endedAt: v.nullable(v.string()),
3882
+ status: v.picklist(['open', 'closed']),
3883
+ });
3884
+ /**
3885
+ * Grading passes on the run's current content that ended without a grade:
3886
+ * a provider error, quota spent, a response that did not parse. It sits
3887
+ * beside `state` rather than adding one, because the sweep keeps retrying
3888
+ * such a run, so it is still `pending` (or `expired` once the window closes),
3889
+ * and a new `state` value would fail every installed client's parse. Above
3890
+ * zero beside `pending`, "not graded yet" is no longer the whole answer:
3891
+ * grading was tried, did not finish, and is still being retried. Beside a
3892
+ * superseded `graded`, it counts failed re-grades of the newer content.
3893
+ * Absent from a server that predates it, which means "not reported", never 0.
3894
+ */
3895
+ const GradeFailedAttemptsSchema = v.optional(v.pipe(v.number(), v.integer(), v.minValue(0)));
3896
+ export const SessionGradeResponseSchema = v.object({
3897
+ run: GradedSessionSchema,
3898
+ state: SessionGradeStateSchema,
3899
+ gradeFailedAttempts: GradeFailedAttemptsSchema,
3900
+ /** Present exactly when `state` is `graded`. */
3901
+ grade: v.nullable(SessionGradeSchema),
3902
+ /**
3903
+ * The markers every `summary` and `reasoning` in this response is wrapped in.
3904
+ * Present exactly when `grade` is — there is nothing to delimit otherwise.
3905
+ */
3906
+ untrusted: v.nullable(GuideHistoryUntrustedSchema),
3907
+ });
3908
+ // ---------------------------------------------------------------------------
3909
+ // Session digest — `GET /api/v1/runs/grade?detail=digest`
3910
+ // ---------------------------------------------------------------------------
3911
+ /** Most turns one digest returns; `turnsTotal` says how many the session has. */
3912
+ export const SESSION_DIGEST_MAX_TURNS = 50;
3913
+ /** What the digest cannot carry yet, named so an absence is never read as "none". */
3914
+ export const SESSION_DIGEST_UNAVAILABLE = [
3915
+ 'comments',
3916
+ 'resumeCommand',
3917
+ 'cloudUrl',
3918
+ ];
3919
+ export const SessionDigestUnavailableSchema = v.picklist(SESSION_DIGEST_UNAVAILABLE);
3920
+ export const SessionDigestTurnSchema = v.object({
3921
+ ordinal: v.number(),
3922
+ /** What the user said, **wrapped in the response's untrusted markers** and bounded. */
3923
+ text: v.string(),
3924
+ /** The steering classifier's label, or null when the turn was never classified. */
3925
+ steeringLabel: v.nullable(v.string()),
3926
+ });
3927
+ export const SessionDigestSchema = v.object({
3928
+ /** The agent's own closing account of the session, wrapped and bounded; null when it gave none. */
3929
+ selfReport: v.nullable(v.string()),
3930
+ /** The user's turns in order, at most `SESSION_DIGEST_MAX_TURNS`. */
3931
+ turns: v.array(SessionDigestTurnSchema),
3932
+ /** Every turn the session recorded, so a cut list is not read as the whole. */
3933
+ turnsTotal: v.number(),
3934
+ /** The repository's identity digest, or null when the session recorded none. */
3935
+ repoId: v.nullable(v.string()),
3936
+ /** The branch observed at close, wrapped like any text taken from the repo; null when unrecorded. */
3937
+ branch: v.nullable(v.string()),
3938
+ /** The head commit observed at close, or null. A commit made mid-session is not it. */
3939
+ headSha: v.nullable(v.string()),
3940
+ /** The session's page on the dashboard, as a path; the client prefixes the dashboard address. */
3941
+ dashboardPath: v.string(),
3942
+ /** Absolute dashboard link, added by the client that knows the address. */
3943
+ dashboardUrl: v.optional(v.string()),
3944
+ /** Comments on this session, wrapped; empty until sessions can be commented on. */
3945
+ comments: v.array(v.string()),
3946
+ /** The parts of a digest no session carries yet. */
3947
+ notYetAvailable: v.array(SessionDigestUnavailableSchema),
3948
+ });
3949
+ export const SessionDigestResponseSchema = v.object({
3950
+ run: GradedSessionSchema,
3951
+ state: SessionGradeStateSchema,
3952
+ gradeFailedAttempts: GradeFailedAttemptsSchema,
3953
+ grade: v.nullable(SessionGradeSchema),
3954
+ digest: SessionDigestSchema,
3955
+ /** One marker pair over every wrapped block in the response, present always. */
3956
+ untrusted: GuideHistoryUntrustedSchema,
3957
+ });
3958
+ // ---------------------------------------------------------------------------
3959
+ // Search — one term across the caller's evidence (`GET /api/v1/search`)
3960
+ // ---------------------------------------------------------------------------
3961
+ /**
3962
+ * The corpora a search can reach today.
3963
+ *
3964
+ * `guides` is guide bodies and their author-written eval criteria; `verdicts`
3965
+ * is the grader's reasoning for why a session did or did not follow a guide;
3966
+ * `content` is the name and body of the documents saved in bundles; `comments`
3967
+ * is the text of comments left on guides and documents and, for a caller that
3968
+ * reads them (`SearchRequest.sessionComments`), on its own sessions; `turns` is what the
3969
+ * caller themself said to their agents, redacted; `sessions` is the grader's
3970
+ * summary of the caller's own sessions and the agent's closing report. One
3971
+ * registry on the server declares how each is matched and scoped; this list is
3972
+ * only what a caller may name.
3973
+ */
3974
+ export const SEARCH_CORPUS_IDS = [
3975
+ 'guides',
3976
+ 'verdicts',
3977
+ 'content',
3978
+ 'comments',
3979
+ 'turns',
3980
+ 'sessions',
3981
+ ];
3982
+ export const SearchCorpusIdSchema = v.picklist(SEARCH_CORPUS_IDS);
3983
+ /**
3984
+ * Every stored text no search reaches yet — the actions and their narration.
3985
+ * Every response names them, so "nothing found" can never be read as covering
3986
+ * them. (Earlier wordings of a guide are deliberately never searched, which is a
3987
+ * different thing from not yet.)
3988
+ */
3989
+ export const SEARCH_UNIMPLEMENTED_CORPORA = ['actions'];
3990
+ /**
3991
+ * What a response still names as not searched for a caller that did not say it
3992
+ * reads session comments (`SearchRequest.sessionComments`): they were left out
3993
+ * of its `comments`, so saying otherwise would read a zero as covering them.
3994
+ */
3995
+ export const SEARCH_SESSION_COMMENTS_UNSEARCHED = 'session-comments';
3996
+ export const SearchUnimplementedCorpusSchema = v.picklist(SEARCH_UNIMPLEMENTED_CORPORA);
3997
+ /** Hits returned per corpus when the caller does not say. */
3998
+ export const SEARCH_DEFAULT_LIMIT = 10;
3999
+ /** The most hits one corpus returns. Totals are counted past it. */
4000
+ export const SEARCH_MAX_LIMIT = 25;
4001
+ /**
4002
+ * The term. Literal, case-insensitive, with `*` and `?` as the only wildcards —
4003
+ * not a regex, which an unindexed shared database cannot afford.
4004
+ *
4005
+ * At least two characters after trimming, not counting wildcards: every row
4006
+ * matches one character (or `**`), so a shorter term is a scan with no question
4007
+ * behind it.
4008
+ */
4009
+ export const SearchTermSchema = v.pipe(v.string(), v.trim(), v.minLength(2, 'q must be at least 2 characters'), v.maxLength(200, 'q must be at most 200 characters'), v.check((value) => !/[\u0000-\u001f\u007f]/.test(value), 'q must not contain control characters'),
4010
+ // Wildcards do not count toward the two: `**` is a pattern that matches
4011
+ // every row, which is the scan the minimum exists to refuse.
4012
+ v.check((value) => value.replace(/[*?]/g, '').length >= 2, 'q must contain at least 2 characters besides * and ?'));
4013
+ /**
4014
+ * How much of each guide hit to return — progressive disclosure, so a search
4015
+ * costs an agent little context until it asks for more.
4016
+ *
4017
+ * - `excerpt` (the default): a short window around the match, kept inside the
4018
+ * match's Markdown section, plus the section's heading path. A short section
4019
+ * comes back whole, and a longer one says how long it is (`sectionChars`).
4020
+ * - `section`: the whole section that holds the match, capped. Meant for one
4021
+ * hit at a time — pass the hit's `fileId` in `fileIds`.
4022
+ */
4023
+ export const SEARCH_DETAILS = ['excerpt', 'section'];
4024
+ export const SearchDetailSchema = v.picklist(SEARCH_DETAILS);
4025
+ /** Frontmatter filters a `content` search accepts at once. */
4026
+ export const SEARCH_MAX_FRONTMATTER_FILTERS = 3;
4027
+ /**
4028
+ * One top-level frontmatter field a `content` item must carry, by exact scalar
4029
+ * value (`type: recipe`). The key is a plain YAML key so it can be matched
4030
+ * without being interpreted; the value is literal text, compared
4031
+ * case-insensitively.
4032
+ */
4033
+ export const SearchFrontmatterSchema = v.pipe(v.record(v.pipe(v.string(), v.regex(/^[A-Za-z][\w-]{0,39}$/, 'frontmatter keys are plain names')), v.pipe(v.string(), v.trim(), v.minLength(1, 'a frontmatter value must not be empty'), v.maxLength(100, 'a frontmatter value must be at most 100 characters'), v.check((value) => !/[\u0000-\u001f\u007f]/.test(value), 'a frontmatter value must not contain control characters'))), v.check((fields) => {
4034
+ const count = Object.keys(fields).length;
4035
+ return count >= 1 && count <= SEARCH_MAX_FRONTMATTER_FILTERS;
4036
+ }, `frontmatter takes between 1 and ${SEARCH_MAX_FRONTMATTER_FILTERS} fields`));
4037
+ /** Who wrote a comment: a person, an agent, or Mossbear itself. */
4038
+ export const SEARCH_COMMENT_AUTHOR_KINDS = CommentAuthorKindSchema.options;
4039
+ export const SearchCommentAuthorKindSchema = CommentAuthorKindSchema;
4040
+ /**
4041
+ * What a comment is attached to. `artifact` is a guide or a document; `session`
4042
+ * is a run the caller made. Session comments are the caller's own and never reach
4043
+ * a workspace-mate.
4044
+ */
4045
+ /**
4046
+ * The subject kinds a client names in a search: `artifact`, never its older
4047
+ * name `item`.
4048
+ */
4049
+ export const SEARCH_COMMENT_SUBJECT_KIND_NAMES = ['artifact', 'session'];
4050
+ export const SearchCommentSubjectKindFilterSchema = v.picklist(SEARCH_COMMENT_SUBJECT_KIND_NAMES);
4051
+ /**
4052
+ * What a user turn was, as the session classifier labels it. The same
4053
+ * vocabulary the classifier writes; a `turns` search may keep only some.
4054
+ */
4055
+ export const SEARCH_STEERING_LABELS = [
4056
+ 'correction',
4057
+ 'steering',
4058
+ 'new request',
4059
+ 'acknowledgement',
4060
+ 'insufficient evidence',
4061
+ ];
4062
+ export const SearchSteeringLabelSchema = v.picklist(SEARCH_STEERING_LABELS);
4063
+ /**
4064
+ * One exact value a `sessions` search filters on — a head sha, a branch name or
4065
+ * a repo digest. Compared as written, so it is trimmed and bounded but never
4066
+ * case-folded or treated as a pattern.
4067
+ */
4068
+ export const SearchSessionFilterValueSchema = v.pipe(v.string(), v.trim(), v.minLength(1, 'a session filter must not be empty'), v.maxLength(200, 'a session filter must be at most 200 characters'), v.check((value) => !/[\u0000-\u001f\u007f]/.test(value), 'a session filter must not contain control characters'));
4069
+ export const SearchRequestObjectSchema = v.object({
4070
+ /**
4071
+ * The term. Optional only for a `sessions` search that names a filter (`headSha`,
4072
+ * `branch` or `repoId`): "which session ended at this commit" has no words to match.
4073
+ */
4074
+ q: v.optional(SearchTermSchema),
4075
+ /** Which corpora to search; every one when absent. */
4076
+ corpora: v.optional(v.pipe(v.array(SearchCorpusIdSchema), v.minLength(1))),
4077
+ /**
4078
+ * The bundles a scoped caller may read content from — `mossbear mcp
4079
+ * --bundles` resolved to ids by the CLI, since the server never sees that
4080
+ * flag. **Present means narrowed**, even when empty: an allowlist that
4081
+ * reaches no bundle narrows the content corpora to nothing, never to
4082
+ * everything. Absent means the caller is not bundle-scoped.
4083
+ */
4084
+ bundleIds: v.optional(v.pipe(v.array(NonEmptyStringSchema), v.maxLength(200))),
4085
+ limit: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(SEARCH_MAX_LIMIT))),
4086
+ /** How much of each guide hit to return; `excerpt` when absent. */
4087
+ detail: v.optional(SearchDetailSchema),
4088
+ /**
4089
+ * Restrict the guides corpus to these guide files — the `fileId`s of earlier
4090
+ * hits, to expand them. Narrows within the caller's scope, never past it: an
4091
+ * id the caller cannot read matches nothing. Does not touch other corpora.
4092
+ */
4093
+ fileIds: v.optional(v.pipe(v.array(NonEmptyStringSchema), v.minLength(1), v.maxLength(SEARCH_MAX_LIMIT))),
4094
+ /**
4095
+ * Restrict the `content` corpus to items whose frontmatter carries every one
4096
+ * of these fields. Does not touch other corpora.
4097
+ */
4098
+ frontmatter: v.optional(SearchFrontmatterSchema),
4099
+ /**
4100
+ * Restrict the `comments` corpus to comments written by these kinds of
4101
+ * author. Does not touch other corpora.
4102
+ */
4103
+ authorKinds: v.optional(v.pipe(v.array(SearchCommentAuthorKindSchema), v.minLength(1))),
4104
+ /**
4105
+ * Restrict the `comments` corpus to comments on these kinds of subject. Does
4106
+ * not touch other corpora.
4107
+ */
4108
+ subjectKinds: v.optional(v.pipe(v.array(SearchCommentSubjectKindFilterSchema), v.minLength(1))),
4109
+ /**
4110
+ * Restrict the `turns` corpus to turns the classifier gave one of these
4111
+ * labels. A turn with no label never matches. Does not touch other corpora.
4112
+ */
4113
+ steeringLabels: v.optional(v.pipe(v.array(SearchSteeringLabelSchema), v.minLength(1))),
4114
+ /**
4115
+ * Restrict the `sessions` corpus to sessions whose recorded head was exactly
4116
+ * this commit when they closed. A commit made mid-session matches nothing:
4117
+ * the head is the one observed at close. Does not touch other corpora.
4118
+ */
4119
+ headSha: v.optional(SearchSessionFilterValueSchema),
4120
+ /** Restrict the `sessions` corpus to sessions that closed on exactly this branch. Does not touch other corpora. */
4121
+ branch: v.optional(SearchSessionFilterValueSchema),
4122
+ /** Restrict the `sessions` corpus to sessions recorded under exactly this repo id. Does not touch other corpora. */
4123
+ repoId: v.optional(SearchSessionFilterValueSchema),
4124
+ /**
4125
+ * Whether the caller can read a `comments` hit on a session. A client from
4126
+ * before session comments were searchable validates the whole response
4127
+ * strictly and would reject one, so the server returns them only to a caller
4128
+ * that says it can, and tells every other caller they were not searched.
4129
+ * Absent means it cannot.
4130
+ */
4131
+ sessionComments: v.optional(v.boolean()),
4132
+ });
4133
+ /**
4134
+ * A request with no term searches the caller's sessions by filter alone, so it
4135
+ * must name one, and must not name another corpus (which has nothing to match).
4136
+ */
4137
+ export const SearchRequestSchema = v.pipe(SearchRequestObjectSchema, v.forward(v.check((request) => request.q !== undefined ||
4138
+ request.headSha !== undefined ||
4139
+ request.branch !== undefined ||
4140
+ request.repoId !== undefined, 'q must be at least 2 characters (or filter sessions by headSha, branch or repoId)'), ['q']), v.forward(v.check((request) => request.q !== undefined ||
4141
+ request.corpora === undefined ||
4142
+ request.corpora.every((id) => id === 'sessions'), 'without q only the sessions corpus can be searched'), ['corpora']));
4143
+ /**
4144
+ * Why a corpus was not searched. Codes, never prose: each caller writes its own
4145
+ * sentence, and the dashboard's has to be a translatable one.
4146
+ */
4147
+ export const SearchSkipReasonSchema = v.picklist([
4148
+ 'excluded-by-caller',
4149
+ 'timed-out',
4150
+ // The caller's token is limited to certain bundles, and grading results, the
4151
+ // caller's turns and sessions, and comments on their sessions are never among
4152
+ // what such a token reaches.
4153
+ 'not-granted',
4154
+ // A filter named only kinds of subject this caller cannot be given: `session`
4155
+ // from a client that did not say it reads session comments, which is also what
4156
+ // a server from before they were searchable said to every caller.
4157
+ 'not-yet-searchable',
4158
+ ]);
4159
+ /** Why a searched corpus covered less than the caller's whole scope. */
4160
+ export const SearchNarrowingSchema = v.picklist(['narrowed-by-bundle-allowlist']);
4161
+ /** A guide file whose text matched. The excerpt is wrapped in `untrusted`'s markers. */
4162
+ export const SearchGuideHitSchema = v.object({
4163
+ guideId: NonEmptyStringSchema,
4164
+ /** Wrapped in `untrusted`'s markers; null when nothing names the guide. */
4165
+ guideTitle: v.nullable(v.string()),
4166
+ fileId: NonEmptyStringSchema,
4167
+ path: v.nullable(v.string()),
4168
+ /** The guide's own body, or its author-written eval criteria. */
4169
+ part: v.picklist(['body', 'criteria']),
4170
+ /**
4171
+ * The heading path of the Markdown section that holds the match, joined with
4172
+ * `SECTION_PATH_SEPARATOR` and wrapped in `untrusted`'s markers — a heading is
4173
+ * file text. Null when the match sits above the first heading. Optional
4174
+ * because a server that predates sections does not send it.
4175
+ */
4176
+ section: v.optional(v.nullable(v.string())),
4177
+ /**
4178
+ * The whole section's length in characters, present only when `excerpt` is
4179
+ * less than all of it — what expanding the hit would add. Null when the
4180
+ * excerpt is the whole section. Optional for the same reason as `section`.
4181
+ */
4182
+ sectionChars: v.optional(v.nullable(v.pipe(v.number(), v.integer(), v.minValue(0)))),
4183
+ /**
4184
+ * Around the match, cut with `…`, never past its section. By default a short
4185
+ * window, or the whole section when that is short too; for `detail:
4186
+ * 'section'`, the whole section, capped.
4187
+ */
4188
+ excerpt: v.string(),
4189
+ });
4190
+ /** One session's verdict on one guide whose reasoning matched, wrapped in markers. */
4191
+ export const SearchVerdictHitSchema = v.object({
4192
+ sessionId: NonEmptyStringSchema,
4193
+ guideId: NonEmptyStringSchema,
4194
+ /**
4195
+ * Wrapped in `untrusted`'s markers. Null when the guide is no longer one the
4196
+ * caller can read, or nothing names it.
4197
+ */
4198
+ guideTitle: v.nullable(v.string()),
4199
+ verdict: SessionGuideVerdictValueSchema,
4200
+ occurredAt: v.string(),
4201
+ reasoning: v.string(),
4202
+ });
4203
+ /**
4204
+ * A saved document whose name or body matched — an artifact `read_artifact`
4205
+ * reads by its `itemId`. The name, workspace name and excerpt are wrapped in
4206
+ * `untrusted`'s markers.
4207
+ */
4208
+ export const SearchContentHitSchema = v.object({
4209
+ itemId: NonEmptyStringSchema,
4210
+ /** Wrapped in `untrusted`'s markers; null when the item has no name. */
4211
+ name: v.nullable(v.string()),
4212
+ workspaceId: NonEmptyStringSchema,
4213
+ /** Wrapped in `untrusted`'s markers. */
4214
+ workspaceName: v.string(),
4215
+ /**
4216
+ * Slugs of the bundles that hold the item and that the caller may read — the
4217
+ * `bundle` argument `pull_artifacts` takes to read the bundle. Never more than
4218
+ * a scoped caller's allowlist reaches.
4219
+ */
4220
+ bundles: v.array(v.string()),
4221
+ updatedAt: v.string(),
4222
+ /**
4223
+ * Where the item opens on the dashboard. Added by the CLI, which knows the
4224
+ * dashboard's address; the server does not send it.
4225
+ */
4226
+ url: v.optional(v.string()),
4227
+ /** A window around the match, wrapped in `untrusted`'s markers. */
4228
+ excerpt: v.string(),
4229
+ });
4230
+ /** What every matched comment carries, whatever it is attached to. */
4231
+ const searchCommentHitFields = {
4232
+ commentId: NonEmptyStringSchema,
4233
+ /** The thread's root; equal to `commentId` for a root comment. */
4234
+ threadId: NonEmptyStringSchema,
4235
+ authorKind: SearchCommentAuthorKindSchema,
4236
+ /** Whether the thread has been resolved — a resolved thread is answered, not open. */
4237
+ resolved: v.boolean(),
4238
+ createdAt: v.string(),
4239
+ /**
4240
+ * Where the comment's subject opens on the dashboard. Added by the CLI, which
4241
+ * knows the dashboard's address; the server does not send it.
4242
+ */
4243
+ url: v.optional(v.string()),
4244
+ /** A window around the match, wrapped in `untrusted`'s markers. */
4245
+ excerpt: v.string(),
4246
+ };
4247
+ /**
4248
+ * A comment on a guide or document that matched. `body` and `itemName` and
4249
+ * `workspaceName` are wrapped in `untrusted`'s markers.
4250
+ */
4251
+ export const SearchArtifactCommentHitSchema = v.object({
4252
+ ...searchCommentHitFields,
4253
+ subjectKind: v.literal('artifact'),
4254
+ itemId: NonEmptyStringSchema,
4255
+ /**
4256
+ * The guide the item belongs to, or null for a standalone document. A comment
4257
+ * on a guide sits on its body file, so this is the id the dashboard's guide
4258
+ * page takes; `itemId` is the one a document page takes.
4259
+ */
4260
+ guideId: v.nullable(NonEmptyStringSchema),
4261
+ /** Wrapped in `untrusted`'s markers; null when the item has no name. */
4262
+ itemName: v.nullable(v.string()),
4263
+ workspaceId: NonEmptyStringSchema,
4264
+ /** Wrapped in `untrusted`'s markers. */
4265
+ workspaceName: v.string(),
4266
+ /** Whether the item has been edited since the comment was written. */
4267
+ itemChangedSince: v.boolean(),
4268
+ /**
4269
+ * Where the match is. A current server always says `body`; `suggestion` is
4270
+ * what an older one said for a match in a comment's suggested edit, accepted
4271
+ * so a CLI talking to one mid-rollout still parses the report. Nothing reads
4272
+ * the difference.
4273
+ */
4274
+ matchedIn: v.picklist(['body', 'suggestion']),
4275
+ /**
4276
+ * A Mossbear suggestion's draft state: whether its owner has handed it to
4277
+ * their agents. Absent on a person's or an agent's comment and on a reply.
4278
+ */
4279
+ approved: v.optional(v.boolean()),
4280
+ });
4281
+ /**
4282
+ * A comment on one of the caller's own sessions that matched. It has no
4283
+ * workspace and no item: `sessionId` is the id the dashboard's session page
4284
+ * takes. The excerpt is wrapped in `untrusted`'s markers.
4285
+ */
4286
+ export const SearchSessionCommentHitSchema = v.object({
4287
+ ...searchCommentHitFields,
4288
+ subjectKind: v.literal('session'),
4289
+ sessionId: NonEmptyStringSchema,
4290
+ matchedIn: v.literal('body'),
4291
+ });
4292
+ export const SearchCommentHitSchema = v.variant('subjectKind', [
4293
+ SearchArtifactCommentHitSchema,
4294
+ SearchSessionCommentHitSchema,
4295
+ ]);
4296
+ /**
4297
+ * One thing the caller said to an agent, redacted at the source. `excerpt` and
4298
+ * `projectId` and `branch` are wrapped in `untrusted`'s markers: a turn is text a
4299
+ * person typed (or pasted) and a branch name is whatever git was told.
4300
+ */
4301
+ export const SearchTurnHitSchema = v.object({
4302
+ /** The agent's own session id — the key a session digest takes. */
4303
+ agentSessionId: NonEmptyStringSchema,
4304
+ /**
4305
+ * The dashboard's id for the session, which its session page takes. Null when
4306
+ * the session has not been recorded as a run yet.
4307
+ */
4308
+ sessionId: v.nullable(NonEmptyStringSchema),
4309
+ /** Which turn of the session this was, counting from 1. */
4310
+ ordinal: v.pipe(v.number(), v.integer(), v.minValue(1)),
4311
+ /** Null when the classifier has not labelled the turn. */
4312
+ steeringLabel: v.nullable(SearchSteeringLabelSchema),
4313
+ /** Wrapped in `untrusted`'s markers; null where the session recorded none. */
4314
+ projectId: v.nullable(v.string()),
4315
+ /** Wrapped in `untrusted`'s markers; null where the session recorded none. */
4316
+ branch: v.nullable(v.string()),
4317
+ createdAt: v.string(),
4318
+ /**
4319
+ * Where the session opens on the dashboard. Added by the CLI, which knows the
4320
+ * dashboard's address; the server does not send it.
4321
+ */
4322
+ url: v.optional(v.string()),
4323
+ /** A window around the match, wrapped in `untrusted`'s markers. */
4324
+ excerpt: v.string(),
4325
+ });
4326
+ /** Which of a session's stored texts a `sessions` hit matched. */
4327
+ export const SEARCH_SESSION_MATCH_FIELDS = ['grade', 'self_report'];
4328
+ export const SearchSessionMatchFieldSchema = v.picklist(SEARCH_SESSION_MATCH_FIELDS);
4329
+ /**
4330
+ * One of the caller's own sessions, found by what the grader said about it or
4331
+ * what the agent reported at the end. `repoId`, `projectId`, `branch`,
4332
+ * `headSha` and `excerpt` are wrapped in `untrusted`'s markers: the first four
4333
+ * are whatever a checkout reported, and the excerpt is model-authored or
4334
+ * written by an agent.
4335
+ */
4336
+ export const SearchSessionHitSchema = v.object({
4337
+ /** The agent's own session id — the key a session digest takes. */
4338
+ agentSessionId: NonEmptyStringSchema,
4339
+ /** The dashboard's id for the session, which its session page takes. */
4340
+ sessionId: NonEmptyStringSchema,
4341
+ /** Wrapped in `untrusted`'s markers; null where the session recorded none. */
4342
+ repoId: v.nullable(v.string()),
4343
+ /** Wrapped in `untrusted`'s markers; null where the session recorded none. */
4344
+ projectId: v.nullable(v.string()),
4345
+ /** Wrapped in `untrusted`'s markers; null where the session recorded none. */
4346
+ branch: v.nullable(v.string()),
4347
+ /**
4348
+ * The head observed when the session closed, wrapped in `untrusted`'s
4349
+ * markers; null where none was observed. A commit made mid-session is not it.
4350
+ */
4351
+ headSha: v.nullable(v.string()),
4352
+ startedAt: v.string(),
4353
+ /** Null when the search named no term, only filters. */
4354
+ matchedIn: v.nullable(SearchSessionMatchFieldSchema),
4355
+ /**
4356
+ * Where the session opens on the dashboard. Added by the CLI, which knows the
4357
+ * dashboard's address; the server does not send it.
4358
+ */
4359
+ url: v.optional(v.string()),
4360
+ /** A window around the match, wrapped in `untrusted`'s markers; null when the search named no term. */
4361
+ excerpt: v.nullable(v.string()),
4362
+ });
4363
+ function searchCorpusReportSchema(hit) {
4364
+ return v.variant('status', [
4365
+ v.object({
4366
+ status: v.literal('searched'),
4367
+ /** Every match in scope, counted past the returned page. */
4368
+ total: v.pipe(v.number(), v.integer(), v.minValue(0)),
4369
+ narrowedBy: v.nullable(SearchNarrowingSchema),
4370
+ /** Newest first, at most the request's limit. */
4371
+ hits: v.array(hit),
4372
+ }),
4373
+ v.object({
4374
+ status: v.literal('skipped'),
4375
+ reason: SearchSkipReasonSchema,
4376
+ }),
4377
+ ]);
4378
+ }
4379
+ export const SearchGuidesReportSchema = searchCorpusReportSchema(SearchGuideHitSchema);
4380
+ export const SearchVerdictsReportSchema = searchCorpusReportSchema(SearchVerdictHitSchema);
4381
+ export const SearchContentReportSchema = searchCorpusReportSchema(SearchContentHitSchema);
4382
+ export const SearchCommentsReportSchema = searchCorpusReportSchema(SearchCommentHitSchema);
4383
+ export const SearchTurnsReportSchema = searchCorpusReportSchema(SearchTurnHitSchema);
4384
+ export const SearchSessionsReportSchema = searchCorpusReportSchema(SearchSessionHitSchema);
4385
+ /**
4386
+ * A search's answer: **a report per corpus, never a bare list.**
4387
+ *
4388
+ * Keyed by corpus so every corpus is always accounted for — searched with its
4389
+ * total, or skipped with its reason — and `notYetSearchable` names the ones no
4390
+ * search reaches. A caller reading zero hits therefore always knows what the
4391
+ * zero covers, which is the difference between "nothing matched here" and "you
4392
+ * never said this".
4393
+ */
4394
+ export const SearchResponseSchema = v.object({
4395
+ corpora: v.object({
4396
+ guides: SearchGuidesReportSchema,
4397
+ verdicts: SearchVerdictsReportSchema,
4398
+ /**
4399
+ * Optional because a server that predates the `content` corpus does not
4400
+ * send it — and then did not search it, which a caller must say rather
4401
+ * than read as zero hits.
4402
+ */
4403
+ content: v.optional(SearchContentReportSchema),
4404
+ /** Optional for the same reason as `content`. Covers comments on guides and documents, and the caller's own comments on their sessions. */
4405
+ comments: v.optional(SearchCommentsReportSchema),
4406
+ /** Optional for the same reason as `content`. The caller's own turns, never a workspace-mate's. */
4407
+ turns: v.optional(SearchTurnsReportSchema),
4408
+ /** Optional for the same reason as `content`. The caller's own sessions, never a workspace-mate's. */
4409
+ sessions: v.optional(SearchSessionsReportSchema),
4410
+ }),
4411
+ // `comments` is what a server from before session comments were told apart
4412
+ // from item comments still sends; a newer client must read that response, not
4413
+ // refuse it. `session-comments`, `turns` and `sessions` are what servers sent
4414
+ // before those corpora were searchable.
4415
+ notYetSearchable: v.array(v.picklist([
4416
+ ...SEARCH_UNIMPLEMENTED_CORPORA,
4417
+ 'comments',
4418
+ 'session-comments',
4419
+ 'turns',
4420
+ 'sessions',
4421
+ ])),
4422
+ untrusted: GuideHistoryUntrustedSchema,
4423
+ });
4424
+ // ---------------------------------------------------------------------------
4425
+ // Parse wrappers (throw ValiError on invalid input)
4426
+ // ---------------------------------------------------------------------------
4427
+ export function parseGuideBundleResponse(data) {
4428
+ return v.parse(GuideBundleResponseSchema, data);
4429
+ }
4430
+ export function parseRawGuideFilePayload(data) {
4431
+ return v.parse(RawGuideFilePayloadSchema, data);
4432
+ }
4433
+ export function parseGuideMemberFilesResponse(data) {
4434
+ return v.parse(GuideMemberFilesResponseSchema, data);
4435
+ }
4436
+ export function parseBundleListResponse(data) {
4437
+ return v.parse(BundleListResponseSchema, data);
4438
+ }
4439
+ export function parseWorkspaceListResponse(data) {
4440
+ return v.parse(WorkspaceListResponseSchema, data);
4441
+ }
4442
+ export function parseCreateScopedTokenRequest(data) {
4443
+ return v.parse(CreateScopedTokenRequestSchema, data);
4444
+ }
4445
+ export function parseRevokeScopedTokenRequest(data) {
4446
+ return v.parse(RevokeScopedTokenRequestSchema, data);
4447
+ }
4448
+ export function parseCreateBundleRequest(data) {
4449
+ return v.parse(CreateBundleRequestSchema, data);
4450
+ }
4451
+ export function parseCreateBundleResponse(data) {
4452
+ return v.parse(CreateBundleResponseSchema, data);
4453
+ }
4454
+ export function parseAttachBundleMemberRequest(data) {
4455
+ return v.parse(AttachBundleMemberRequestSchema, data);
4456
+ }
4457
+ export function parseAttachBundleMemberResponse(data) {
4458
+ return v.parse(AttachBundleMemberResponseSchema, data);
4459
+ }
4460
+ export function parseAttachBundleMembersResponse(data) {
4461
+ return v.parse(AttachBundleMembersResponseSchema, data);
4462
+ }
4463
+ export function parseDetachBundleMemberResponse(data) {
4464
+ return v.parse(DetachBundleMemberResponseSchema, data);
4465
+ }
4466
+ export function parseSubscribeBundleRequest(data) {
4467
+ return v.parse(SubscribeBundleRequestSchema, data);
4468
+ }
4469
+ export function parseSubscribeBundleResponse(data) {
4470
+ return v.parse(SubscribeBundleResponseSchema, data);
4471
+ }
4472
+ export function parseResolveSubscriptionsRequest(data) {
4473
+ return v.parse(ResolveSubscriptionsRequestSchema, data);
4474
+ }
4475
+ export function parseResolveSubscriptionsResponse(data) {
4476
+ return v.parse(ResolveSubscriptionsResponseSchema, data);
4477
+ }
4478
+ export function parseUpdateBundleRequest(data) {
4479
+ return v.parse(UpdateBundleRequestSchema, data);
4480
+ }
4481
+ export function parseUpdateBundleResponse(data) {
4482
+ return v.parse(UpdateBundleResponseSchema, data);
4483
+ }
4484
+ export function parseDeleteBundleResponse(data) {
4485
+ return v.parse(DeleteBundleResponseSchema, data);
4486
+ }
4487
+ export function parseContextItemsResponse(data) {
4488
+ return v.parse(ContextItemsResponseSchema, data);
4489
+ }
4490
+ export function parseBundleArtifactsResponse(data) {
4491
+ return v.parse(BundleArtifactsResponseSchema, data);
4492
+ }
4493
+ export function parseCaptureRequest(data) {
4494
+ return v.parse(CaptureRequestSchema, data);
4495
+ }
4496
+ export function parseCaptureResponse(data) {
4497
+ return v.parse(CaptureResponseSchema, data);
4498
+ }
4499
+ export function parseBundleArtifactVersionsResponse(data) {
4500
+ return v.parse(BundleArtifactVersionsResponseSchema, data);
4501
+ }
4502
+ export function parseDashboardSyncRequest(data) {
4503
+ return v.parse(DashboardSyncRequestSchema, data);
4504
+ }
4505
+ export function parseExtractedFeedbackBatch(data) {
4506
+ return v.parse(ExtractedFeedbackBatchSchema, data);
4507
+ }
4508
+ /**
4509
+ * Accept the pre-rename spelling of the agent session id on a run-log line.
4510
+ *
4511
+ * Run-log lines are an **at-rest** format: a CLI build writes them to disk and
4512
+ * a later build reads them. `runs-to-sessions-rename` renamed this field from
4513
+ * `sessionId` to `agentSessionId`, so every line an older build already
4514
+ * appended carries the old key. The reader that consumes them treats a parse
4515
+ * failure as "skip this line", which for a queued action means losing it rather
4516
+ * than retrying it — so refusing the old spelling would silently drop whatever
4517
+ * was pending at the moment the user upgraded.
4518
+ *
4519
+ * Reading both is therefore not a courtesy to old clients, it is the difference
4520
+ * between a delayed upload and a lost one. It is also a window, not a steady
4521
+ * state: it can go once no queue file predating the rename can still exist,
4522
+ * which is after the queue's own retention has turned over.
4523
+ */
4524
+ function adoptLegacyAgentSessionId(data) {
4525
+ if (typeof data !== 'object' || data === null || Array.isArray(data))
4526
+ return data;
4527
+ const record = data;
4528
+ if ('agentSessionId' in record || typeof record['sessionId'] !== 'string')
4529
+ return data;
4530
+ const { sessionId, ...rest } = record;
4531
+ return { ...rest, agentSessionId: sessionId };
4532
+ }
4533
+ export function parseActionEntry(data) {
4534
+ return v.parse(ActionEntrySchema, adoptLegacyAgentSessionId(data));
4535
+ }
4536
+ export function parseGuideHistoryRequest(data) {
4537
+ return v.parse(GuideHistoryRequestSchema, data);
4538
+ }
4539
+ export function parseGuideHistoryResponse(data) {
4540
+ return v.parse(GuideHistoryResponseSchema, data);
4541
+ }
4542
+ export function parseAnnounceItemCommentsRequest(data) {
4543
+ return v.parse(AnnounceItemCommentsRequestSchema, data);
4544
+ }
4545
+ export function parseResolveItemCommentResponse(data) {
4546
+ return v.parse(ResolveItemCommentResponseSchema, data);
4547
+ }
4548
+ export function parseAnnounceItemCommentsResponse(data) {
4549
+ return v.parse(AnnounceItemCommentsResponseSchema, data);
4550
+ }
4551
+ export function parseAgentCommentResponse(data) {
4552
+ return v.parse(AgentCommentResponseSchema, data);
4553
+ }
4554
+ export function parseItemCommentsResponse(data) {
4555
+ return v.parse(ItemCommentsResponseSchema, data);
4556
+ }
4557
+ export function parseCommentEvidenceResponse(data) {
4558
+ return v.parse(CommentEvidenceResponseSchema, data);
4559
+ }
4560
+ export function parseRunGradeRequest(data) {
4561
+ return v.parse(SessionGradeRequestSchema, data);
4562
+ }
4563
+ export function parseSessionGradeResponse(data) {
4564
+ return v.parse(SessionGradeResponseSchema, data);
4565
+ }
4566
+ export function parseSessionDigestResponse(data) {
4567
+ return v.parse(SessionDigestResponseSchema, data);
4568
+ }
4569
+ export function parseSearchResponse(data) {
4570
+ return v.parse(SearchResponseSchema, data);
4571
+ }
4572
+ //# sourceMappingURL=schemas.js.map