@mossbear/protocol 0.1.0-alpha.72 → 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,11 +1092,20 @@ 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
1077
- * and the person handed to their agent.
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.
1078
1098
  */
1079
- evidence: v.optional(v.pipe(v.string(), v.maxLength(500))),
1099
+ finding: v.optional(ContextItemFindingSchema),
1100
+ /**
1101
+ * Whether the person approved a comment Mossbear drafted. Present on every
1102
+ * Mossbear comment and absent on a person's or an agent's, which are
1103
+ * requests as written. `false` is a draft nobody has read yet: a reader shows
1104
+ * it to the user and acts only on their go-ahead. Only a client that reports
1105
+ * a version able to mark drafts is ever listed one, so an older reader that
1106
+ * strips this field never receives a draft it would print as a request.
1107
+ */
1108
+ approved: v.optional(v.boolean()),
1080
1109
  /** The author's display name as the workspace shows it, or null. Never an email. */
1081
1110
  authorName: v.nullable(v.string()),
1082
1111
  /** ISO timestamp, machine format. */
@@ -1463,30 +1492,31 @@ export const ItemCommentsResponseSchema = v.object({
1463
1492
  untrusted: v.optional(v.nullable(GuideHistoryUntrustedSchema)),
1464
1493
  });
1465
1494
  /**
1466
- * The evidence behind one Mossbear comment an agent was handed
1467
- * (`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`).
1468
1497
  *
1469
- * `list_comments` carries a one-line pointer; this is the envelope it points
1470
- * at: the summary, the observable change the edit predicts, and the cited
1471
- * sessions. Readable only through a comment the comment read itself would
1472
- * deliver to this reader, so an unapproved edit, another person's, or one
1473
- * drafted from another repo has no evidence here either.
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.
1474
1505
  *
1475
- * Citations are reduced to what the reader may see: their own sessions, with a
1476
- * date and a short excerpt of the grader's reasoning or of their own redacted
1477
- * correction turn. A `navigation` citation — a skill load counted when a
1478
- * suggestion was drafted from how the skill's files were read — has an empty
1479
- * excerpt: it is dated evidence that a session loaded the skill, and nothing
1480
- * more. `citationsWithheld` counts any that were dropped, so a short
1481
- * 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.
1482
1512
  */
1483
1513
  export const CommentEvidenceCitationSchema = v.object({
1484
1514
  /**
1485
- * `navigation` is a skill load whose reads drafted the suggestion. It carries
1486
- * no excerpt (an empty string): it is evidence of how a skill was used, not of
1487
- * a failure. `action` is a recorded step of a workflow repeated across
1488
- * sessions: evidence of a habit, not of a failure. A server sends it only to a
1489
- * 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.
1490
1520
  */
1491
1521
  kind: v.picklist(['verdict', 'turn', 'navigation', 'action']),
1492
1522
  sessionId: NonEmptyStringSchema,
@@ -1495,15 +1525,54 @@ export const CommentEvidenceCitationSchema = v.object({
1495
1525
  /** Wrapped in the response's untrusted markers. */
1496
1526
  excerpt: v.string(),
1497
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
+ });
1498
1558
  export const CommentEvidenceResponseSchema = v.object({
1499
1559
  /** The comment's full id, even when the request named a prefix. */
1500
1560
  commentId: NonEmptyStringSchema,
1501
1561
  itemName: v.string(),
1502
1562
  itemPath: v.nullable(v.string()),
1503
- /** Wrapped in the response's untrusted markers. */
1504
- summary: v.string(),
1505
- /** 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. */
1506
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),
1507
1576
  citations: v.array(CommentEvidenceCitationSchema),
1508
1577
  citationsWithheld: v.pipe(v.number(), v.integer()),
1509
1578
  untrusted: GuideHistoryUntrustedSchema,
@@ -1897,18 +1966,6 @@ const DashboardGuideSuggestionStatusSchema = v.picklist([
1897
1966
  'accepted',
1898
1967
  'dismissed',
1899
1968
  ]);
1900
- const DashboardFeedbackCandidateStatusSchema = v.picklist([
1901
- 'inferred',
1902
- 'confirmed',
1903
- 'dismissed',
1904
- ]);
1905
- const DashboardFeedbackSignalTypeSchema = v.picklist([
1906
- 'correction',
1907
- 'approval',
1908
- 'implied_preference',
1909
- 'stated_preference',
1910
- 'skill_suggestion',
1911
- ]);
1912
1969
  export const ProposalCitationSchema = v.object({
1913
1970
  agentSessionId: v.string(),
1914
1971
  timestamp: v.optional(v.string()),
@@ -2246,17 +2303,9 @@ export const DashboardGuideSuggestionSchema = v.object({
2246
2303
  sourceActionIds: v.optional(v.array(v.union([v.string(), ProposalCitationSchema]))),
2247
2304
  status: v.optional(DashboardGuideSuggestionStatusSchema),
2248
2305
  });
2249
- export const DashboardFeedbackCandidateSchema = v.object({
2250
- id: v.optional(v.string()),
2251
- signal: v.string(),
2252
- signalType: DashboardFeedbackSignalTypeSchema,
2253
- confidence: v.optional(v.pipe(v.number(), v.minValue(0), v.maxValue(1))),
2254
- occurrences: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
2255
- status: v.optional(DashboardFeedbackCandidateStatusSchema),
2256
- });
2257
2306
  /** Max number of actions accepted in a single `POST /api/sync` request. */
2258
2307
  export const MAX_SYNC_ACTIONS_BATCH = 500;
2259
- /** Max number of guideSuggestions/feedbackCandidates/runUsage entries per sync request. */
2308
+ /** Max number of guideSuggestions/runUsage entries per sync request. */
2260
2309
  export const MAX_SYNC_AUX_BATCH = 100;
2261
2310
  /**
2262
2311
  * Max rule files one delivery manifest enumerates. Well above what a real repo
@@ -2428,7 +2477,6 @@ export const SyncOriginSchema = v.picklist(['session-start']);
2428
2477
  export const DashboardSyncRequestSchema = v.object({
2429
2478
  actions: v.optional(v.pipe(v.array(DashboardSyncActionSchema), v.maxLength(MAX_SYNC_ACTIONS_BATCH))),
2430
2479
  guideSuggestions: v.optional(v.pipe(v.array(DashboardGuideSuggestionSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
2431
- feedbackCandidates: v.optional(v.pipe(v.array(DashboardFeedbackCandidateSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
2432
2480
  runUsage: v.optional(v.pipe(v.array(DashboardSessionUsageSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
2433
2481
  skillUsage: v.optional(v.pipe(v.array(DashboardSkillUsageSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
2434
2482
  turns: v.optional(v.pipe(v.array(DashboardSyncTurnSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
@@ -3059,6 +3107,12 @@ const SessionGradeIdentifierSchema = v.pipe(v.string(), v.trim(), v.minLength(1)
3059
3107
  export const SessionGradeRequestSchema = v.pipe(v.object({
3060
3108
  session: v.optional(SessionGradeIdentifierSchema),
3061
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')),
3062
3116
  }), v.check((request) => (request.session !== undefined) !== (request.agent_session !== undefined), 'Pass exactly one of session or agent_session'));
3063
3117
  /**
3064
3118
  * Which of four states the run's grade is in — a required field rather than
@@ -3143,30 +3197,88 @@ export const SessionGradeResponseSchema = v.object({
3143
3197
  untrusted: v.nullable(GuideHistoryUntrustedSchema),
3144
3198
  });
3145
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
+ // ---------------------------------------------------------------------------
3146
3249
  // Search — one term across the caller's evidence (`GET /api/v1/search`)
3147
3250
  // ---------------------------------------------------------------------------
3148
3251
  /**
3149
- * The corpora a search can reach today (`universal-search`, deliverable 1).
3252
+ * The corpora a search can reach today.
3150
3253
  *
3151
3254
  * `guides` is guide bodies and their author-written eval criteria; `verdicts`
3152
- * is the grader's reasoning for why a session did or did not follow a guide.
3153
- * One registry on the server declares how each is matched and scoped; this
3154
- * list is only what a caller may name.
3155
- */
3156
- 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
+ ];
3157
3269
  export const SearchCorpusIdSchema = v.picklist(SEARCH_CORPUS_IDS);
3158
3270
  /**
3159
- * Every stored text no search reaches yet — session findings, actions and
3160
- * their narration, guide suggestions, and feedback candidates. Every response
3161
- * names them, so "nothing found" can never be read as covering them. (Earlier
3162
- * wordings of a guide are deliberately never searched, which is a different
3163
- * 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.)
3164
3277
  */
3165
3278
  export const SEARCH_UNIMPLEMENTED_CORPORA = [
3166
- 'findings',
3279
+ 'session-comments',
3280
+ 'sessions',
3167
3281
  'actions',
3168
- 'suggestions',
3169
- 'feedback-candidates',
3170
3282
  ];
3171
3283
  export const SearchUnimplementedCorpusSchema = v.picklist(SEARCH_UNIMPLEMENTED_CORPORA);
3172
3284
  /** Hits returned per corpus when the caller does not say. */
@@ -3197,6 +3309,41 @@ v.check((value) => value.replace(/[*?]/g, '').length >= 2, 'q must contain at le
3197
3309
  */
3198
3310
  export const SEARCH_DETAILS = ['excerpt', 'section'];
3199
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);
3200
3347
  export const SearchRequestSchema = v.object({
3201
3348
  q: SearchTermSchema,
3202
3349
  /** Which corpora to search; every one when absent. */
@@ -3218,6 +3365,26 @@ export const SearchRequestSchema = v.object({
3218
3365
  * id the caller cannot read matches nothing. Does not touch other corpora.
3219
3366
  */
3220
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))),
3221
3388
  });
3222
3389
  /**
3223
3390
  * Why a corpus was not searched. Codes, never prose: each caller writes its own
@@ -3229,6 +3396,8 @@ export const SearchSkipReasonSchema = v.picklist([
3229
3396
  // The caller's token is limited to certain bundles, and grading results are
3230
3397
  // never among what such a token reaches.
3231
3398
  'not-granted',
3399
+ // The filters named only kinds of subject that no search reaches yet.
3400
+ 'not-yet-searchable',
3232
3401
  ]);
3233
3402
  /** Why a searched corpus covered less than the caller's whole scope. */
3234
3403
  export const SearchNarrowingSchema = v.picklist(['narrowed-by-bundle-allowlist']);
@@ -3274,6 +3443,108 @@ export const SearchVerdictHitSchema = v.object({
3274
3443
  occurredAt: v.string(),
3275
3444
  reasoning: v.string(),
3276
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
+ });
3277
3548
  function searchCorpusReportSchema(hit) {
3278
3549
  return v.variant('status', [
3279
3550
  v.object({
@@ -3292,6 +3563,9 @@ function searchCorpusReportSchema(hit) {
3292
3563
  }
3293
3564
  export const SearchGuidesReportSchema = searchCorpusReportSchema(SearchGuideHitSchema);
3294
3565
  export const SearchVerdictsReportSchema = searchCorpusReportSchema(SearchVerdictHitSchema);
3566
+ export const SearchContentReportSchema = searchCorpusReportSchema(SearchContentHitSchema);
3567
+ export const SearchCommentsReportSchema = searchCorpusReportSchema(SearchCommentHitSchema);
3568
+ export const SearchTurnsReportSchema = searchCorpusReportSchema(SearchTurnHitSchema);
3295
3569
  /**
3296
3570
  * A search's answer: **a report per corpus, never a bare list.**
3297
3571
  *
@@ -3305,8 +3579,21 @@ export const SearchResponseSchema = v.object({
3305
3579
  corpora: v.object({
3306
3580
  guides: SearchGuidesReportSchema,
3307
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),
3308
3592
  }),
3309
- 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'])),
3310
3597
  untrusted: GuideHistoryUntrustedSchema,
3311
3598
  });
3312
3599
  // ---------------------------------------------------------------------------
@@ -3499,6 +3786,9 @@ export function parseRunGradeRequest(data) {
3499
3786
  export function parseSessionGradeResponse(data) {
3500
3787
  return v.parse(SessionGradeResponseSchema, data);
3501
3788
  }
3789
+ export function parseSessionDigestResponse(data) {
3790
+ return v.parse(SessionDigestResponseSchema, data);
3791
+ }
3502
3792
  export function parseSearchResponse(data) {
3503
3793
  return v.parse(SearchResponseSchema, data);
3504
3794
  }