@mossbear/protocol 0.1.0-alpha.73 → 0.1.0-alpha.74

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/schemas.js CHANGED
@@ -1040,6 +1040,26 @@ export const GuideHistoryUntrustedSchema = v.object({
1040
1040
  * never the thing that silently drops a comment a person left.
1041
1041
  */
1042
1042
  export const MAX_ITEM_COMMENTS_ON_WIRE = 20;
1043
+ /** What a finding rests on: graded sessions, how loads read a skill, or the rubric alone. */
1044
+ export const FindingTierSchema = v.picklist(['observed', 'usage', 'practice']);
1045
+ /**
1046
+ * What a Mossbear finding carries on the comment read, besides its claim.
1047
+ *
1048
+ * `tierLine` and `blindSpot` are written by the server from data it holds —
1049
+ * the cited sessions, the load counts, the rubric check — never by a model, so
1050
+ * they sit outside the response's untrusted markers. `prediction` is
1051
+ * model-authored and arrives inside them. A finding never carries replacement
1052
+ * text: the reader's agent has the repository and writes the fix.
1053
+ */
1054
+ export const ContextItemFindingSchema = v.object({
1055
+ tier: FindingTierSchema,
1056
+ /** How the finding is known, in one line: "Seen in 3 sessions (2026-09-15 – 2026-10-03)". */
1057
+ tierLine: v.pipe(v.string(), v.maxLength(300)),
1058
+ /** What the drafter did not read, fixed per tier. */
1059
+ blindSpot: v.pipe(v.string(), v.maxLength(300)),
1060
+ /** What should change in later sessions if the finding is fixed, wrapped in the untrusted markers. */
1061
+ prediction: v.nullable(v.string()),
1062
+ });
1043
1063
  /**
1044
1064
  * One comment a **person** left about a context item, riding the item it is about.
1045
1065
  *
@@ -1072,10 +1092,11 @@ export const ContextItemCommentSchema = v.object({
1072
1092
  */
1073
1093
  suggestion: v.optional(v.string()),
1074
1094
  /**
1075
- * One line saying what a server-drafted comment was drawn from — counts and
1076
- * dates, never the cited text. Present only on a comment Mossbear drafted.
1095
+ * What a comment Mossbear wrote is: a finding about the item, never an edit.
1096
+ * Present only on a Mossbear comment. The comment's `body` begins with the
1097
+ * claim (what goes wrong); this carries what the claim rests on.
1077
1098
  */
1078
- evidence: v.optional(v.pipe(v.string(), v.maxLength(500))),
1099
+ finding: v.optional(ContextItemFindingSchema),
1079
1100
  /**
1080
1101
  * Whether the person approved a comment Mossbear drafted. Present on every
1081
1102
  * Mossbear comment and absent on a person's or an agent's, which are
@@ -1471,32 +1492,31 @@ export const ItemCommentsResponseSchema = v.object({
1471
1492
  untrusted: v.optional(v.nullable(GuideHistoryUntrustedSchema)),
1472
1493
  });
1473
1494
  /**
1474
- * The evidence behind one Mossbear comment an agent was handed
1475
- * (`GET /api/v1/context/comments/evidence`, `drafted-guide-suggestions` slice 7).
1495
+ * The evidence behind one Mossbear finding an agent was handed
1496
+ * (`GET /api/v1/context/comments/evidence`).
1476
1497
  *
1477
- * `list_comments` carries a one-line pointer; this is the envelope it points
1478
- * at: the summary, the observable change the edit predicts, and the cited
1479
- * sessions. Readable only through a comment the comment read itself would
1480
- * deliver to this reader, so another person's edit, one drafted from another
1481
- * repo, or a draft listed only to a newer client has no evidence here either.
1482
- * A draft the reader was listed does: an agent can say why it was suggested
1483
- * before the person approves it.
1498
+ * `list_comments` carries the claim and a one-line tier; this is the finding
1499
+ * in full: the claim, the change it predicts in future sessions, what the
1500
+ * drafter did not read, and the evidence for its tier. Readable only through a
1501
+ * comment the comment read itself would deliver to this reader, so another
1502
+ * person's finding, one drafted from another repo, or a draft listed only to a
1503
+ * newer client has no evidence here either. A draft the reader was listed
1504
+ * does: an agent can say why it was raised before the person approves it.
1484
1505
  *
1485
- * Citations are reduced to what the reader may see: their own sessions, with a
1486
- * date and a short excerpt of the grader's reasoning or of their own redacted
1487
- * correction turn. A `navigation` citation — a skill load counted when a
1488
- * suggestion was drafted from how the skill's files were read — has an empty
1489
- * excerpt: it is dated evidence that a session loaded the skill, and nothing
1490
- * more. `citationsWithheld` counts any that were dropped, so a short
1491
- * list is never mistaken for the whole of it.
1506
+ * Citations (observed and usage findings) are reduced to what the reader may
1507
+ * see: their own sessions, with a date and a short excerpt of the grader's
1508
+ * reasoning or of their own redacted correction turn. A `navigation` citation
1509
+ * has an empty excerpt: it is dated evidence that a session loaded the skill,
1510
+ * and nothing more. `citationsWithheld` counts any that were dropped, so a
1511
+ * short list is never mistaken for the whole of it.
1492
1512
  */
1493
1513
  export const CommentEvidenceCitationSchema = v.object({
1494
1514
  /**
1495
- * `navigation` is a skill load whose reads drafted the suggestion. It carries
1496
- * no excerpt (an empty string): it is evidence of how a skill was used, not of
1497
- * a failure. `action` is a recorded step of a workflow repeated across
1498
- * sessions: evidence of a habit, not of a failure. A server sends it only to a
1499
- * client that names a version new enough to parse it.
1515
+ * `navigation` is a skill load counted when a finding was drafted from how
1516
+ * the skill's files were read: evidence of how a skill was used, not of a
1517
+ * failure. `action` is a recorded step of a workflow repeated across
1518
+ * sessions. A server sends it only to a client that names a version new
1519
+ * enough to parse it.
1500
1520
  */
1501
1521
  kind: v.picklist(['verdict', 'turn', 'navigation', 'action']),
1502
1522
  sessionId: NonEmptyStringSchema,
@@ -1505,15 +1525,54 @@ export const CommentEvidenceCitationSchema = v.object({
1505
1525
  /** Wrapped in the response's untrusted markers. */
1506
1526
  excerpt: v.string(),
1507
1527
  });
1528
+ /** What a usage finding adds to its citations: the counts for one reference file. */
1529
+ export const CommentEvidenceUsageSchema = v.object({
1530
+ /** The reference's skill-relative path, wrapped in the response's untrusted markers. */
1531
+ path: v.string(),
1532
+ /** Eligible loads of the skill. */
1533
+ loads: v.pipe(v.number(), v.integer()),
1534
+ /** Distinct sessions those loads span. */
1535
+ sessions: v.pipe(v.number(), v.integer()),
1536
+ /** Loads followed by a successful read of the reference. */
1537
+ loadsWithRead: v.pipe(v.number(), v.integer()),
1538
+ });
1539
+ /**
1540
+ * What a practice finding adds: the rubric check it answers and the rubric's
1541
+ * version, the practice lines it weighs with their sources, the facts measured
1542
+ * from the file, and the answer to each item of evidence the check asks for.
1543
+ * `answers[].answer` is model-written, so it travels wrapped in the response's
1544
+ * untrusted markers.
1545
+ */
1546
+ export const CommentEvidencePracticeSchema = v.object({
1547
+ check: v.object({ id: v.string(), name: v.string() }),
1548
+ rubricVersion: v.pipe(v.number(), v.integer()),
1549
+ // Optional, so a CLI reads a dashboard that has not shipped these fields yet:
1550
+ // the two release independently.
1551
+ practices: v.optional(v.array(v.object({
1552
+ text: v.string(),
1553
+ source: v.object({ title: v.string(), url: v.string() }),
1554
+ })), []),
1555
+ facts: v.optional(v.array(v.string()), []),
1556
+ answers: v.optional(v.array(v.object({ item: v.string(), answer: v.string() })), []),
1557
+ });
1508
1558
  export const CommentEvidenceResponseSchema = v.object({
1509
1559
  /** The comment's full id, even when the request named a prefix. */
1510
1560
  commentId: NonEmptyStringSchema,
1511
1561
  itemName: v.string(),
1512
1562
  itemPath: v.nullable(v.string()),
1513
- /** Wrapped in the response's untrusted markers. */
1514
- summary: v.string(),
1515
- /** What future sessions should show if the edit works, wrapped; null if none. */
1563
+ tier: FindingTierSchema,
1564
+ /** One line saying how the finding is known; server-written, outside the markers. */
1565
+ tierLine: v.string(),
1566
+ /** What the drafter did not read; server-written, outside the markers. */
1567
+ blindSpot: v.string(),
1568
+ /** What goes wrong, wrapped in the response's untrusted markers. */
1569
+ claim: v.string(),
1570
+ /** What future sessions should show if the finding is fixed, wrapped; null if none. */
1516
1571
  prediction: v.nullable(v.string()),
1572
+ /** A usage finding's counts; null on every other tier. */
1573
+ usage: v.nullable(CommentEvidenceUsageSchema),
1574
+ /** A practice finding's rubric check; null on every other tier. */
1575
+ practice: v.nullable(CommentEvidencePracticeSchema),
1517
1576
  citations: v.array(CommentEvidenceCitationSchema),
1518
1577
  citationsWithheld: v.pipe(v.number(), v.integer()),
1519
1578
  untrusted: GuideHistoryUntrustedSchema,
@@ -1907,18 +1966,6 @@ const DashboardGuideSuggestionStatusSchema = v.picklist([
1907
1966
  'accepted',
1908
1967
  'dismissed',
1909
1968
  ]);
1910
- const DashboardFeedbackCandidateStatusSchema = v.picklist([
1911
- 'inferred',
1912
- 'confirmed',
1913
- 'dismissed',
1914
- ]);
1915
- const DashboardFeedbackSignalTypeSchema = v.picklist([
1916
- 'correction',
1917
- 'approval',
1918
- 'implied_preference',
1919
- 'stated_preference',
1920
- 'skill_suggestion',
1921
- ]);
1922
1969
  export const ProposalCitationSchema = v.object({
1923
1970
  agentSessionId: v.string(),
1924
1971
  timestamp: v.optional(v.string()),
@@ -2256,17 +2303,9 @@ export const DashboardGuideSuggestionSchema = v.object({
2256
2303
  sourceActionIds: v.optional(v.array(v.union([v.string(), ProposalCitationSchema]))),
2257
2304
  status: v.optional(DashboardGuideSuggestionStatusSchema),
2258
2305
  });
2259
- export const DashboardFeedbackCandidateSchema = v.object({
2260
- id: v.optional(v.string()),
2261
- signal: v.string(),
2262
- signalType: DashboardFeedbackSignalTypeSchema,
2263
- confidence: v.optional(v.pipe(v.number(), v.minValue(0), v.maxValue(1))),
2264
- occurrences: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
2265
- status: v.optional(DashboardFeedbackCandidateStatusSchema),
2266
- });
2267
2306
  /** Max number of actions accepted in a single `POST /api/sync` request. */
2268
2307
  export const MAX_SYNC_ACTIONS_BATCH = 500;
2269
- /** Max number of guideSuggestions/feedbackCandidates/runUsage entries per sync request. */
2308
+ /** Max number of guideSuggestions/runUsage entries per sync request. */
2270
2309
  export const MAX_SYNC_AUX_BATCH = 100;
2271
2310
  /**
2272
2311
  * Max rule files one delivery manifest enumerates. Well above what a real repo
@@ -2438,7 +2477,6 @@ export const SyncOriginSchema = v.picklist(['session-start']);
2438
2477
  export const DashboardSyncRequestSchema = v.object({
2439
2478
  actions: v.optional(v.pipe(v.array(DashboardSyncActionSchema), v.maxLength(MAX_SYNC_ACTIONS_BATCH))),
2440
2479
  guideSuggestions: v.optional(v.pipe(v.array(DashboardGuideSuggestionSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
2441
- feedbackCandidates: v.optional(v.pipe(v.array(DashboardFeedbackCandidateSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
2442
2480
  runUsage: v.optional(v.pipe(v.array(DashboardSessionUsageSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
2443
2481
  skillUsage: v.optional(v.pipe(v.array(DashboardSkillUsageSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
2444
2482
  turns: v.optional(v.pipe(v.array(DashboardSyncTurnSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
@@ -3069,6 +3107,12 @@ const SessionGradeIdentifierSchema = v.pipe(v.string(), v.trim(), v.minLength(1)
3069
3107
  export const SessionGradeRequestSchema = v.pipe(v.object({
3070
3108
  session: v.optional(SessionGradeIdentifierSchema),
3071
3109
  agent_session: v.optional(SessionGradeIdentifierSchema),
3110
+ /**
3111
+ * Opt in to the session digest: the grade plus the turns, self-report and
3112
+ * git position of the session. Omitted, the small grade payload that
3113
+ * `mossbear sessions` and session start read is unchanged.
3114
+ */
3115
+ detail: v.optional(v.literal('digest')),
3072
3116
  }), v.check((request) => (request.session !== undefined) !== (request.agent_session !== undefined), 'Pass exactly one of session or agent_session'));
3073
3117
  /**
3074
3118
  * Which of four states the run's grade is in — a required field rather than
@@ -3153,30 +3197,88 @@ export const SessionGradeResponseSchema = v.object({
3153
3197
  untrusted: v.nullable(GuideHistoryUntrustedSchema),
3154
3198
  });
3155
3199
  // ---------------------------------------------------------------------------
3200
+ // Session digest — `GET /api/v1/runs/grade?detail=digest`
3201
+ // ---------------------------------------------------------------------------
3202
+ /** Most turns one digest returns; `turnsTotal` says how many the session has. */
3203
+ export const SESSION_DIGEST_MAX_TURNS = 50;
3204
+ /** What the digest cannot carry yet, named so an absence is never read as "none". */
3205
+ export const SESSION_DIGEST_UNAVAILABLE = [
3206
+ 'comments',
3207
+ 'resumeCommand',
3208
+ 'cloudUrl',
3209
+ ];
3210
+ export const SessionDigestUnavailableSchema = v.picklist(SESSION_DIGEST_UNAVAILABLE);
3211
+ export const SessionDigestTurnSchema = v.object({
3212
+ ordinal: v.number(),
3213
+ /** What the user said, **wrapped in the response's untrusted markers** and bounded. */
3214
+ text: v.string(),
3215
+ /** The steering classifier's label, or null when the turn was never classified. */
3216
+ steeringLabel: v.nullable(v.string()),
3217
+ });
3218
+ export const SessionDigestSchema = v.object({
3219
+ /** The agent's own closing account of the session, wrapped and bounded; null when it gave none. */
3220
+ selfReport: v.nullable(v.string()),
3221
+ /** The user's turns in order, at most `SESSION_DIGEST_MAX_TURNS`. */
3222
+ turns: v.array(SessionDigestTurnSchema),
3223
+ /** Every turn the session recorded, so a cut list is not read as the whole. */
3224
+ turnsTotal: v.number(),
3225
+ /** The repository's identity digest, or null when the session recorded none. */
3226
+ repoId: v.nullable(v.string()),
3227
+ /** The branch observed at close, wrapped like any text taken from the repo; null when unrecorded. */
3228
+ branch: v.nullable(v.string()),
3229
+ /** The head commit observed at close, or null. A commit made mid-session is not it. */
3230
+ headSha: v.nullable(v.string()),
3231
+ /** The session's page on the dashboard, as a path; the client prefixes the dashboard address. */
3232
+ dashboardPath: v.string(),
3233
+ /** Absolute dashboard link, added by the client that knows the address. */
3234
+ dashboardUrl: v.optional(v.string()),
3235
+ /** Comments on this session, wrapped; empty until sessions can be commented on. */
3236
+ comments: v.array(v.string()),
3237
+ /** The parts of a digest no session carries yet. */
3238
+ notYetAvailable: v.array(SessionDigestUnavailableSchema),
3239
+ });
3240
+ export const SessionDigestResponseSchema = v.object({
3241
+ run: GradedSessionSchema,
3242
+ state: SessionGradeStateSchema,
3243
+ grade: v.nullable(SessionGradeSchema),
3244
+ digest: SessionDigestSchema,
3245
+ /** One marker pair over every wrapped block in the response, present always. */
3246
+ untrusted: GuideHistoryUntrustedSchema,
3247
+ });
3248
+ // ---------------------------------------------------------------------------
3156
3249
  // Search — one term across the caller's evidence (`GET /api/v1/search`)
3157
3250
  // ---------------------------------------------------------------------------
3158
3251
  /**
3159
- * The corpora a search can reach today (`universal-search`, deliverable 1).
3252
+ * The corpora a search can reach today.
3160
3253
  *
3161
3254
  * `guides` is guide bodies and their author-written eval criteria; `verdicts`
3162
- * is the grader's reasoning for why a session did or did not follow a guide.
3163
- * One registry on the server declares how each is matched and scoped; this
3164
- * list is only what a caller may name.
3165
- */
3166
- export const SEARCH_CORPUS_IDS = ['guides', 'verdicts'];
3255
+ * is the grader's reasoning for why a session did or did not follow a guide;
3256
+ * `content` is the name and body of the documents saved in bundles; `comments`
3257
+ * is the text of comments left on guides and documents; `turns` is what the
3258
+ * caller themself said to their agents, redacted. One registry on the
3259
+ * server declares how each is matched and scoped; this list is only what a
3260
+ * caller may name.
3261
+ */
3262
+ export const SEARCH_CORPUS_IDS = [
3263
+ 'guides',
3264
+ 'verdicts',
3265
+ 'content',
3266
+ 'comments',
3267
+ 'turns',
3268
+ ];
3167
3269
  export const SearchCorpusIdSchema = v.picklist(SEARCH_CORPUS_IDS);
3168
3270
  /**
3169
- * Every stored text no search reaches yet — session findings, actions and
3170
- * their narration, guide suggestions, and feedback candidates. Every response
3171
- * names them, so "nothing found" can never be read as covering them. (Earlier
3172
- * wordings of a guide are deliberately never searched, which is a different
3173
- * thing from not yet.)
3271
+ * Every stored text no search reaches yet — comments left on a session (a
3272
+ * comment on a guide or document is searched; findings and guide suggestions
3273
+ * are comments), the sessions a run records, and the actions and
3274
+ * their narration. Every response names them, so "nothing found" can never be read
3275
+ * as covering them. (Earlier wordings of a guide are deliberately never
3276
+ * searched, which is a different thing from not yet.)
3174
3277
  */
3175
3278
  export const SEARCH_UNIMPLEMENTED_CORPORA = [
3176
- 'findings',
3279
+ 'session-comments',
3280
+ 'sessions',
3177
3281
  'actions',
3178
- 'suggestions',
3179
- 'feedback-candidates',
3180
3282
  ];
3181
3283
  export const SearchUnimplementedCorpusSchema = v.picklist(SEARCH_UNIMPLEMENTED_CORPORA);
3182
3284
  /** Hits returned per corpus when the caller does not say. */
@@ -3207,6 +3309,41 @@ v.check((value) => value.replace(/[*?]/g, '').length >= 2, 'q must contain at le
3207
3309
  */
3208
3310
  export const SEARCH_DETAILS = ['excerpt', 'section'];
3209
3311
  export const SearchDetailSchema = v.picklist(SEARCH_DETAILS);
3312
+ /** Frontmatter filters a `content` search accepts at once. */
3313
+ export const SEARCH_MAX_FRONTMATTER_FILTERS = 3;
3314
+ /**
3315
+ * One top-level frontmatter field a `content` item must carry, by exact scalar
3316
+ * value (`type: recipe`). The key is a plain YAML key so it can be matched
3317
+ * without being interpreted; the value is literal text, compared
3318
+ * case-insensitively.
3319
+ */
3320
+ 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) => {
3321
+ const count = Object.keys(fields).length;
3322
+ return count >= 1 && count <= SEARCH_MAX_FRONTMATTER_FILTERS;
3323
+ }, `frontmatter takes between 1 and ${SEARCH_MAX_FRONTMATTER_FILTERS} fields`));
3324
+ /** Who wrote a comment: a person, an agent, or Mossbear itself. */
3325
+ export const SEARCH_COMMENT_AUTHOR_KINDS = ['person', 'agent', 'mossbear'];
3326
+ export const SearchCommentAuthorKindSchema = v.picklist(SEARCH_COMMENT_AUTHOR_KINDS);
3327
+ /**
3328
+ * What a comment is attached to. `item` is a guide or a document; `session` is
3329
+ * accepted so a caller can ask for it, but nothing searches session comments
3330
+ * yet, and a request that names only `session` says so rather than returning
3331
+ * an empty match.
3332
+ */
3333
+ export const SEARCH_COMMENT_SUBJECT_KINDS = ['item', 'session'];
3334
+ export const SearchCommentSubjectKindSchema = v.picklist(SEARCH_COMMENT_SUBJECT_KINDS);
3335
+ /**
3336
+ * What a user turn was, as the session classifier labels it. The same
3337
+ * vocabulary the classifier writes; a `turns` search may keep only some.
3338
+ */
3339
+ export const SEARCH_STEERING_LABELS = [
3340
+ 'correction',
3341
+ 'steering',
3342
+ 'new request',
3343
+ 'acknowledgement',
3344
+ 'insufficient evidence',
3345
+ ];
3346
+ export const SearchSteeringLabelSchema = v.picklist(SEARCH_STEERING_LABELS);
3210
3347
  export const SearchRequestSchema = v.object({
3211
3348
  q: SearchTermSchema,
3212
3349
  /** Which corpora to search; every one when absent. */
@@ -3228,6 +3365,26 @@ export const SearchRequestSchema = v.object({
3228
3365
  * id the caller cannot read matches nothing. Does not touch other corpora.
3229
3366
  */
3230
3367
  fileIds: v.optional(v.pipe(v.array(NonEmptyStringSchema), v.minLength(1), v.maxLength(SEARCH_MAX_LIMIT))),
3368
+ /**
3369
+ * Restrict the `content` corpus to items whose frontmatter carries every one
3370
+ * of these fields. Does not touch other corpora.
3371
+ */
3372
+ frontmatter: v.optional(SearchFrontmatterSchema),
3373
+ /**
3374
+ * Restrict the `comments` corpus to comments written by these kinds of
3375
+ * author. Does not touch other corpora.
3376
+ */
3377
+ authorKinds: v.optional(v.pipe(v.array(SearchCommentAuthorKindSchema), v.minLength(1))),
3378
+ /**
3379
+ * Restrict the `comments` corpus to comments on these kinds of subject. Does
3380
+ * not touch other corpora.
3381
+ */
3382
+ subjectKinds: v.optional(v.pipe(v.array(SearchCommentSubjectKindSchema), v.minLength(1))),
3383
+ /**
3384
+ * Restrict the `turns` corpus to turns the classifier gave one of these
3385
+ * labels. A turn with no label never matches. Does not touch other corpora.
3386
+ */
3387
+ steeringLabels: v.optional(v.pipe(v.array(SearchSteeringLabelSchema), v.minLength(1))),
3231
3388
  });
3232
3389
  /**
3233
3390
  * Why a corpus was not searched. Codes, never prose: each caller writes its own
@@ -3239,6 +3396,8 @@ export const SearchSkipReasonSchema = v.picklist([
3239
3396
  // The caller's token is limited to certain bundles, and grading results are
3240
3397
  // never among what such a token reaches.
3241
3398
  'not-granted',
3399
+ // The filters named only kinds of subject that no search reaches yet.
3400
+ 'not-yet-searchable',
3242
3401
  ]);
3243
3402
  /** Why a searched corpus covered less than the caller's whole scope. */
3244
3403
  export const SearchNarrowingSchema = v.picklist(['narrowed-by-bundle-allowlist']);
@@ -3284,6 +3443,108 @@ export const SearchVerdictHitSchema = v.object({
3284
3443
  occurredAt: v.string(),
3285
3444
  reasoning: v.string(),
3286
3445
  });
3446
+ /**
3447
+ * A saved document whose name or body matched — an item `pull_context` returns
3448
+ * as `type: content`. The name, workspace name and excerpt are wrapped in
3449
+ * `untrusted`'s markers.
3450
+ */
3451
+ export const SearchContentHitSchema = v.object({
3452
+ itemId: NonEmptyStringSchema,
3453
+ /** Wrapped in `untrusted`'s markers; null when the item has no name. */
3454
+ name: v.nullable(v.string()),
3455
+ workspaceId: NonEmptyStringSchema,
3456
+ /** Wrapped in `untrusted`'s markers. */
3457
+ workspaceName: v.string(),
3458
+ /**
3459
+ * Slugs of the bundles that hold the item and that the caller may read — the
3460
+ * argument `pull_context` takes to read the whole document. Never more than
3461
+ * a scoped caller's allowlist reaches.
3462
+ */
3463
+ bundles: v.array(v.string()),
3464
+ updatedAt: v.string(),
3465
+ /**
3466
+ * Where the item opens on the dashboard. Added by the CLI, which knows the
3467
+ * dashboard's address; the server does not send it.
3468
+ */
3469
+ url: v.optional(v.string()),
3470
+ /** A window around the match, wrapped in `untrusted`'s markers. */
3471
+ excerpt: v.string(),
3472
+ });
3473
+ /**
3474
+ * A comment on a guide or document that matched. `body` and `itemName` and
3475
+ * `workspaceName` are wrapped in `untrusted`'s markers.
3476
+ */
3477
+ export const SearchCommentHitSchema = v.object({
3478
+ commentId: NonEmptyStringSchema,
3479
+ /** The thread's root; equal to `commentId` for a root comment. */
3480
+ threadId: NonEmptyStringSchema,
3481
+ authorKind: SearchCommentAuthorKindSchema,
3482
+ subjectKind: v.literal('item'),
3483
+ itemId: NonEmptyStringSchema,
3484
+ /**
3485
+ * The guide the item belongs to, or null for a standalone document. A comment
3486
+ * on a guide sits on its body file, so this is the id the dashboard's guide
3487
+ * page takes; `itemId` is the one a document page takes.
3488
+ */
3489
+ guideId: v.nullable(NonEmptyStringSchema),
3490
+ /** Wrapped in `untrusted`'s markers; null when the item has no name. */
3491
+ itemName: v.nullable(v.string()),
3492
+ workspaceId: NonEmptyStringSchema,
3493
+ /** Wrapped in `untrusted`'s markers. */
3494
+ workspaceName: v.string(),
3495
+ /** Whether the thread has been resolved — a resolved thread is answered, not open. */
3496
+ resolved: v.boolean(),
3497
+ /** Whether the item has been edited since the comment was written. */
3498
+ itemChangedSince: v.boolean(),
3499
+ /**
3500
+ * Whether the match is in the comment's text or in the replacement it
3501
+ * suggests (Mossbear's drafted edits).
3502
+ */
3503
+ matchedIn: v.picklist(['body', 'suggestion']),
3504
+ /**
3505
+ * A Mossbear suggestion's draft state: whether its owner has handed it to
3506
+ * their agents. Absent on a person's or an agent's comment and on a reply.
3507
+ */
3508
+ approved: v.optional(v.boolean()),
3509
+ createdAt: v.string(),
3510
+ /**
3511
+ * Where the comment's item opens on the dashboard. Added by the CLI, which
3512
+ * knows the dashboard's address; the server does not send it.
3513
+ */
3514
+ url: v.optional(v.string()),
3515
+ /** A window around the match, wrapped in `untrusted`'s markers. */
3516
+ excerpt: v.string(),
3517
+ });
3518
+ /**
3519
+ * One thing the caller said to an agent, redacted at the source. `excerpt` and
3520
+ * `projectId` and `branch` are wrapped in `untrusted`'s markers: a turn is text a
3521
+ * person typed (or pasted) and a branch name is whatever git was told.
3522
+ */
3523
+ export const SearchTurnHitSchema = v.object({
3524
+ /** The agent's own session id — the key a session digest takes. */
3525
+ agentSessionId: NonEmptyStringSchema,
3526
+ /**
3527
+ * The dashboard's id for the session, which its session page takes. Null when
3528
+ * the session has not been recorded as a run yet.
3529
+ */
3530
+ sessionId: v.nullable(NonEmptyStringSchema),
3531
+ /** Which turn of the session this was, counting from 1. */
3532
+ ordinal: v.pipe(v.number(), v.integer(), v.minValue(1)),
3533
+ /** Null when the classifier has not labelled the turn. */
3534
+ steeringLabel: v.nullable(SearchSteeringLabelSchema),
3535
+ /** Wrapped in `untrusted`'s markers; null where the session recorded none. */
3536
+ projectId: v.nullable(v.string()),
3537
+ /** Wrapped in `untrusted`'s markers; null where the session recorded none. */
3538
+ branch: v.nullable(v.string()),
3539
+ createdAt: v.string(),
3540
+ /**
3541
+ * Where the session opens on the dashboard. Added by the CLI, which knows the
3542
+ * dashboard's address; the server does not send it.
3543
+ */
3544
+ url: v.optional(v.string()),
3545
+ /** A window around the match, wrapped in `untrusted`'s markers. */
3546
+ excerpt: v.string(),
3547
+ });
3287
3548
  function searchCorpusReportSchema(hit) {
3288
3549
  return v.variant('status', [
3289
3550
  v.object({
@@ -3302,6 +3563,9 @@ function searchCorpusReportSchema(hit) {
3302
3563
  }
3303
3564
  export const SearchGuidesReportSchema = searchCorpusReportSchema(SearchGuideHitSchema);
3304
3565
  export const SearchVerdictsReportSchema = searchCorpusReportSchema(SearchVerdictHitSchema);
3566
+ export const SearchContentReportSchema = searchCorpusReportSchema(SearchContentHitSchema);
3567
+ export const SearchCommentsReportSchema = searchCorpusReportSchema(SearchCommentHitSchema);
3568
+ export const SearchTurnsReportSchema = searchCorpusReportSchema(SearchTurnHitSchema);
3305
3569
  /**
3306
3570
  * A search's answer: **a report per corpus, never a bare list.**
3307
3571
  *
@@ -3315,8 +3579,21 @@ export const SearchResponseSchema = v.object({
3315
3579
  corpora: v.object({
3316
3580
  guides: SearchGuidesReportSchema,
3317
3581
  verdicts: SearchVerdictsReportSchema,
3582
+ /**
3583
+ * Optional because a server that predates the `content` corpus does not
3584
+ * send it — and then did not search it, which a caller must say rather
3585
+ * than read as zero hits.
3586
+ */
3587
+ content: v.optional(SearchContentReportSchema),
3588
+ /** Optional for the same reason as `content`. Covers comments on guides and documents only. */
3589
+ comments: v.optional(SearchCommentsReportSchema),
3590
+ /** Optional for the same reason as `content`. The caller's own turns, never a workspace-mate's. */
3591
+ turns: v.optional(SearchTurnsReportSchema),
3318
3592
  }),
3319
- notYetSearchable: v.array(SearchUnimplementedCorpusSchema),
3593
+ // `comments` is what a server from before session comments were told apart
3594
+ // from item comments still sends; a newer client must read that response, not
3595
+ // refuse it. Servers now send `session-comments`.
3596
+ notYetSearchable: v.array(v.picklist([...SEARCH_UNIMPLEMENTED_CORPORA, 'comments', 'turns'])),
3320
3597
  untrusted: GuideHistoryUntrustedSchema,
3321
3598
  });
3322
3599
  // ---------------------------------------------------------------------------
@@ -3509,6 +3786,9 @@ export function parseRunGradeRequest(data) {
3509
3786
  export function parseSessionGradeResponse(data) {
3510
3787
  return v.parse(SessionGradeResponseSchema, data);
3511
3788
  }
3789
+ export function parseSessionDigestResponse(data) {
3790
+ return v.parse(SessionDigestResponseSchema, data);
3791
+ }
3512
3792
  export function parseSearchResponse(data) {
3513
3793
  return v.parse(SearchResponseSchema, data);
3514
3794
  }