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

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 (44) hide show
  1. package/dist/index.d.ts +2 -0
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js +2 -0
  4. package/dist/index.js.map +1 -1
  5. package/dist/publicModelCatalog.d.ts +19 -0
  6. package/dist/publicModelCatalog.d.ts.map +1 -0
  7. package/dist/publicModelCatalog.generated.d.ts +2 -0
  8. package/dist/publicModelCatalog.generated.d.ts.map +1 -0
  9. package/dist/publicModelCatalog.generated.js +469 -0
  10. package/dist/publicModelCatalog.generated.js.map +1 -0
  11. package/dist/publicModelCatalog.js +68 -0
  12. package/dist/publicModelCatalog.js.map +1 -0
  13. package/dist/publicModelCatalog.test.d.ts +2 -0
  14. package/dist/publicModelCatalog.test.d.ts.map +1 -0
  15. package/dist/publicModelCatalog.test.js +88 -0
  16. package/dist/publicModelCatalog.test.js.map +1 -0
  17. package/dist/publicModelNativeAliases.d.ts +5 -0
  18. package/dist/publicModelNativeAliases.d.ts.map +1 -0
  19. package/dist/publicModelNativeAliases.js +8 -0
  20. package/dist/publicModelNativeAliases.js.map +1 -0
  21. package/dist/schemas.d.ts +1567 -131
  22. package/dist/schemas.d.ts.map +1 -1
  23. package/dist/schemas.js +588 -74
  24. package/dist/schemas.js.map +1 -1
  25. package/dist/schemas.test.js +60 -32
  26. package/dist/schemas.test.js.map +1 -1
  27. package/dist/types.d.ts +1 -2
  28. package/dist/types.d.ts.map +1 -1
  29. package/dist/types.js.map +1 -1
  30. package/dist/usageOnly.d.ts +157 -0
  31. package/dist/usageOnly.d.ts.map +1 -0
  32. package/dist/usageOnly.js +47 -0
  33. package/dist/usageOnly.js.map +1 -0
  34. package/dist/usageOnly.test.d.ts +2 -0
  35. package/dist/usageOnly.test.d.ts.map +1 -0
  36. package/dist/usageOnly.test.js +188 -0
  37. package/dist/usageOnly.test.js.map +1 -0
  38. package/dist/whatSyncs.d.ts +1 -1
  39. package/dist/whatSyncs.d.ts.map +1 -1
  40. package/dist/whatSyncs.js +1 -5
  41. package/dist/whatSyncs.js.map +1 -1
  42. package/dist/whatSyncs.test.js +1 -4
  43. package/dist/whatSyncs.test.js.map +1 -1
  44. package/package.json +3 -2
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
@@ -1433,6 +1454,94 @@ export const AnnounceItemCommentsResponseSchema = v.object({
1433
1454
  /** How many of those were under the cap and have now been counted as announced. */
1434
1455
  announced: v.pipe(v.number(), v.integer(), v.minValue(0)),
1435
1456
  });
1457
+ /**
1458
+ * How many comments one agent session may leave on one subject, not counting its
1459
+ * whole-subject comment. Anchored comments and replies share it.
1460
+ */
1461
+ export const MAX_AGENT_COMMENTS_PER_SUBJECT = 50;
1462
+ /** The longest an agent comment's text may be, in characters. */
1463
+ export const MAX_AGENT_COMMENT_BODY_CHARS = 4000;
1464
+ /**
1465
+ * Why an agent comment was refused, as the `code` on the error body. A caller
1466
+ * branches on these; the message beside one is for a person.
1467
+ */
1468
+ export const AGENT_COMMENT_ERROR_CODES = [
1469
+ /** The request named no agent session. The CLI never makes one up. */
1470
+ 'agent_session_required',
1471
+ /** This agent session has used its comments on the subject. */
1472
+ 'agent_comment_limit_reached',
1473
+ /** An agent comment is text only: it may not carry replacement text. */
1474
+ 'agent_comment_text_only',
1475
+ /** The subject or comment is not one this account can comment on. */
1476
+ 'agent_comment_target_missing',
1477
+ /** A comment names a passage that is not whole lines of the item as it is now. */
1478
+ 'agent_comment_passage_not_found',
1479
+ /** The passage appears more than once, so which one is meant is unknown. */
1480
+ 'agent_comment_passage_ambiguous',
1481
+ /** The item already carries as many open comments as it may. */
1482
+ 'item_comment_limit_reached',
1483
+ ];
1484
+ export const AgentCommentErrorCodeSchema = v.picklist(AGENT_COMMENT_ERROR_CODES);
1485
+ const AgentCommentTargetIdSchema = v.pipe(v.string(), v.minLength(1), v.maxLength(128));
1486
+ /**
1487
+ * Leave a comment, or reply to one, as an agent (`POST /api/v1/context/comments`).
1488
+ *
1489
+ * **`target` names what the comment is about, one way.** `item` is the id a
1490
+ * bundle read gave for a guide or document, `session` is an agent session id of
1491
+ * the caller's own (the key a search hit and the session digest hand out), and
1492
+ * `reply` is the id of a comment to answer. A reply joins that comment's thread
1493
+ * and the subject it is about.
1494
+ *
1495
+ * **Who the agent is comes from `agent`, and `sessionId` is the harness's own
1496
+ * id as the CLI read it.** A request without one is refused with
1497
+ * `agent_session_required`, and the CLI and tool offer no way to type one. The
1498
+ * server cannot check it against the harness, so it is a claim by the holder of
1499
+ * the token: the comment is always written under that token's account, and the
1500
+ * handle shown for it names a session only as far as the claim is true.
1501
+ *
1502
+ * **Text only.** There is no replacement-text field, and a request that carries
1503
+ * one is refused with `agent_comment_text_only` rather than having it dropped.
1504
+ */
1505
+ export const AgentCommentRequestSchema = v.object({
1506
+ target: v.variant('kind', [
1507
+ v.object({ kind: v.literal('item'), id: AgentCommentTargetIdSchema }),
1508
+ v.object({ kind: v.literal('session'), id: AgentCommentTargetIdSchema }),
1509
+ v.object({ kind: v.literal('reply'), id: AgentCommentTargetIdSchema }),
1510
+ ]),
1511
+ body: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(MAX_AGENT_COMMENT_BODY_CHARS)),
1512
+ /**
1513
+ * The passage an item comment is about, as the exact text of one or more whole
1514
+ * lines of the item (a paragraph, a heading, a list). None means the item as a
1515
+ * whole. The server finds the lines; a passage that is not in the item as it is
1516
+ * now is refused with `agent_comment_passage_not_found`.
1517
+ */
1518
+ passage: v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(8000))),
1519
+ agent: v.object({
1520
+ sessionId: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(128)),
1521
+ harness: HarnessIdSchema,
1522
+ /** The agent's own statement of its model, when it knows it. */
1523
+ model: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(100))),
1524
+ cliVersion: v.optional(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(64))),
1525
+ }),
1526
+ });
1527
+ /**
1528
+ * The comment a create settled on. `created` is false when this agent session
1529
+ * already had a whole-subject comment on the subject: that comment comes back
1530
+ * unchanged and nothing was written.
1531
+ */
1532
+ export const AgentCommentResponseSchema = v.object({
1533
+ created: v.boolean(),
1534
+ comment: v.object({
1535
+ id: v.string(),
1536
+ threadId: v.string(),
1537
+ subject: v.object({
1538
+ kind: v.picklist(['item', 'session']),
1539
+ id: v.string(),
1540
+ }),
1541
+ body: v.string(),
1542
+ createdAt: v.string(),
1543
+ }),
1544
+ });
1436
1545
  /**
1437
1546
  * One comment on the on-demand read, with the item it is about named on the comment.
1438
1547
  *
@@ -1471,32 +1580,31 @@ export const ItemCommentsResponseSchema = v.object({
1471
1580
  untrusted: v.optional(v.nullable(GuideHistoryUntrustedSchema)),
1472
1581
  });
1473
1582
  /**
1474
- * The evidence behind one Mossbear comment an agent was handed
1475
- * (`GET /api/v1/context/comments/evidence`, `drafted-guide-suggestions` slice 7).
1583
+ * The evidence behind one Mossbear finding an agent was handed
1584
+ * (`GET /api/v1/context/comments/evidence`).
1476
1585
  *
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.
1586
+ * `list_comments` carries the claim and a one-line tier; this is the finding
1587
+ * in full: the claim, the change it predicts in future sessions, what the
1588
+ * drafter did not read, and the evidence for its tier. Readable only through a
1589
+ * comment the comment read itself would deliver to this reader, so another
1590
+ * person's finding, one drafted from another repo, or a draft listed only to a
1591
+ * newer client has no evidence here either. A draft the reader was listed
1592
+ * does: an agent can say why it was raised before the person approves it.
1484
1593
  *
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.
1594
+ * Citations (observed and usage findings) are reduced to what the reader may
1595
+ * see: their own sessions, with a date and a short excerpt of the grader's
1596
+ * reasoning or of their own redacted correction turn. A `navigation` citation
1597
+ * has an empty excerpt: it is dated evidence that a session loaded the skill,
1598
+ * and nothing more. `citationsWithheld` counts any that were dropped, so a
1599
+ * short list is never mistaken for the whole of it.
1492
1600
  */
1493
1601
  export const CommentEvidenceCitationSchema = v.object({
1494
1602
  /**
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.
1603
+ * `navigation` is a skill load counted when a finding was drafted from how
1604
+ * the skill's files were read: evidence of how a skill was used, not of a
1605
+ * failure. `action` is a recorded step of a workflow repeated across
1606
+ * sessions. A server sends it only to a client that names a version new
1607
+ * enough to parse it.
1500
1608
  */
1501
1609
  kind: v.picklist(['verdict', 'turn', 'navigation', 'action']),
1502
1610
  sessionId: NonEmptyStringSchema,
@@ -1505,17 +1613,87 @@ export const CommentEvidenceCitationSchema = v.object({
1505
1613
  /** Wrapped in the response's untrusted markers. */
1506
1614
  excerpt: v.string(),
1507
1615
  });
1616
+ /** What a usage finding adds to its citations: the counts for one reference file. */
1617
+ export const CommentEvidenceUsageSchema = v.object({
1618
+ /** The reference's skill-relative path, wrapped in the response's untrusted markers. */
1619
+ path: v.string(),
1620
+ /** Eligible loads of the skill. */
1621
+ loads: v.pipe(v.number(), v.integer()),
1622
+ /** Distinct sessions those loads span. */
1623
+ sessions: v.pipe(v.number(), v.integer()),
1624
+ /** Loads followed by a successful read of the reference. */
1625
+ loadsWithRead: v.pipe(v.number(), v.integer()),
1626
+ });
1627
+ /**
1628
+ * What a practice finding adds: the rubric check it answers and the rubric's
1629
+ * version, the practice lines it weighs with their sources, the facts measured
1630
+ * from the file, and the answer to each item of evidence the check asks for.
1631
+ * `answers[].answer` is model-written, so it travels wrapped in the response's
1632
+ * untrusted markers.
1633
+ */
1634
+ export const CommentEvidencePracticeSchema = v.object({
1635
+ check: v.object({ id: v.string(), name: v.string() }),
1636
+ rubricVersion: v.pipe(v.number(), v.integer()),
1637
+ // Optional, so a CLI reads a dashboard that has not shipped these fields yet:
1638
+ // the two release independently.
1639
+ practices: v.optional(v.array(v.object({
1640
+ text: v.string(),
1641
+ source: v.object({ title: v.string(), url: v.string() }),
1642
+ })), []),
1643
+ facts: v.optional(v.array(v.string()), []),
1644
+ answers: v.optional(v.array(v.object({ item: v.string(), answer: v.string() })), []),
1645
+ });
1646
+ /**
1647
+ * A comment the person (or Mossbear) left on one of the sessions a finding
1648
+ * cites — the person's own account of what the agent should have known, set
1649
+ * beside the grader's excerpt (`guide-findings-plan.md` → Your note on a
1650
+ * session).
1651
+ *
1652
+ * **Reachable only here.** A comment about a session is never listed by
1653
+ * `list_comments` or announced at session start: it is context for a finding,
1654
+ * found by following the finding's citation, not a request.
1655
+ */
1656
+ export const CommentEvidenceSessionCommentSchema = v.object({
1657
+ sessionId: NonEmptyStringSchema,
1658
+ /** Only the person's own notes are sent today; `mossbear` is reserved. */
1659
+ authorKind: v.picklist(['person', 'mossbear']),
1660
+ /** ISO, when the comment was written. */
1661
+ at: v.string(),
1662
+ /** Wrapped in the response's untrusted markers. */
1663
+ body: v.string(),
1664
+ });
1508
1665
  export const CommentEvidenceResponseSchema = v.object({
1509
1666
  /** The comment's full id, even when the request named a prefix. */
1510
1667
  commentId: NonEmptyStringSchema,
1511
1668
  itemName: v.string(),
1512
1669
  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. */
1670
+ tier: FindingTierSchema,
1671
+ /** One line saying how the finding is known; server-written, outside the markers. */
1672
+ tierLine: v.string(),
1673
+ /** What the drafter did not read; server-written, outside the markers. */
1674
+ blindSpot: v.string(),
1675
+ /** What goes wrong, wrapped in the response's untrusted markers. */
1676
+ claim: v.string(),
1677
+ /** What future sessions should show if the finding is fixed, wrapped; null if none. */
1516
1678
  prediction: v.nullable(v.string()),
1679
+ /** A usage finding's counts; null on every other tier. */
1680
+ usage: v.nullable(CommentEvidenceUsageSchema),
1681
+ /** A practice finding's rubric check; null on every other tier. */
1682
+ practice: v.nullable(CommentEvidencePracticeSchema),
1517
1683
  citations: v.array(CommentEvidenceCitationSchema),
1518
1684
  citationsWithheld: v.pipe(v.number(), v.integer()),
1685
+ /**
1686
+ * Comments on the cited sessions, newest first, wrapped in the untrusted
1687
+ * markers. Defaulted so a response from a server that predates the field
1688
+ * still parses.
1689
+ */
1690
+ sessionComments: v.optional(v.array(CommentEvidenceSessionCommentSchema), []),
1691
+ /**
1692
+ * Comments on the cited sessions that were left out to keep the response
1693
+ * bounded (the newest few per session are sent), so a short list is never
1694
+ * mistaken for the whole of it. Zero when none were.
1695
+ */
1696
+ sessionCommentsWithheld: v.optional(v.pipe(v.number(), v.integer()), 0),
1519
1697
  untrusted: GuideHistoryUntrustedSchema,
1520
1698
  });
1521
1699
  /** Max number of context item ids a push may cite as its transform sources. */
@@ -1858,7 +2036,8 @@ export const InboxArchiveResponseSchema = v.object({
1858
2036
  // hard parse error on an otherwise valid history read.
1859
2037
  export const ContextItemVersionSchema = v.object({
1860
2038
  id: v.string(),
1861
- // Monotonic per doc; the newest version equals the item's current `version`.
2039
+ // Monotonic checkpoint number. Autosave may advance the current item token
2040
+ // beyond its latest checkpoint, and saved numbers can have gaps.
1862
2041
  version: v.pipe(v.number(), v.integer(), v.minValue(1)),
1863
2042
  contentHash: v.string(),
1864
2043
  authorType: v.string(),
@@ -1907,18 +2086,6 @@ const DashboardGuideSuggestionStatusSchema = v.picklist([
1907
2086
  'accepted',
1908
2087
  'dismissed',
1909
2088
  ]);
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
2089
  export const ProposalCitationSchema = v.object({
1923
2090
  agentSessionId: v.string(),
1924
2091
  timestamp: v.optional(v.string()),
@@ -2256,17 +2423,9 @@ export const DashboardGuideSuggestionSchema = v.object({
2256
2423
  sourceActionIds: v.optional(v.array(v.union([v.string(), ProposalCitationSchema]))),
2257
2424
  status: v.optional(DashboardGuideSuggestionStatusSchema),
2258
2425
  });
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
2426
  /** Max number of actions accepted in a single `POST /api/sync` request. */
2268
2427
  export const MAX_SYNC_ACTIONS_BATCH = 500;
2269
- /** Max number of guideSuggestions/feedbackCandidates/runUsage entries per sync request. */
2428
+ /** Max number of guideSuggestions/runUsage entries per sync request. */
2270
2429
  export const MAX_SYNC_AUX_BATCH = 100;
2271
2430
  /**
2272
2431
  * Max rule files one delivery manifest enumerates. Well above what a real repo
@@ -2438,7 +2597,6 @@ export const SyncOriginSchema = v.picklist(['session-start']);
2438
2597
  export const DashboardSyncRequestSchema = v.object({
2439
2598
  actions: v.optional(v.pipe(v.array(DashboardSyncActionSchema), v.maxLength(MAX_SYNC_ACTIONS_BATCH))),
2440
2599
  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
2600
  runUsage: v.optional(v.pipe(v.array(DashboardSessionUsageSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
2443
2601
  skillUsage: v.optional(v.pipe(v.array(DashboardSkillUsageSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
2444
2602
  turns: v.optional(v.pipe(v.array(DashboardSyncTurnSchema), v.maxLength(MAX_SYNC_AUX_BATCH))),
@@ -3069,12 +3227,18 @@ const SessionGradeIdentifierSchema = v.pipe(v.string(), v.trim(), v.minLength(1)
3069
3227
  export const SessionGradeRequestSchema = v.pipe(v.object({
3070
3228
  session: v.optional(SessionGradeIdentifierSchema),
3071
3229
  agent_session: v.optional(SessionGradeIdentifierSchema),
3230
+ /**
3231
+ * Opt in to the session digest: the grade plus the turns, self-report and
3232
+ * git position of the session. Omitted, the small grade payload that
3233
+ * `mossbear sessions` and session start read is unchanged.
3234
+ */
3235
+ detail: v.optional(v.literal('digest')),
3072
3236
  }), v.check((request) => (request.session !== undefined) !== (request.agent_session !== undefined), 'Pass exactly one of session or agent_session'));
3073
3237
  /**
3074
3238
  * Which of four states the run's grade is in — a required field rather than
3075
3239
  * something a reader infers from a null `grade`.
3076
3240
  *
3077
- * The four are four different sentences, and the absence of a grade is never
3241
+ * These states need different sentences, and the absence of a grade is never
3078
3242
  * one of them on its own:
3079
3243
  *
3080
3244
  * - `pending` — no grade yet, and the grading sweep can still pick the run
@@ -3087,12 +3251,14 @@ export const SessionGradeRequestSchema = v.pipe(v.object({
3087
3251
  * - `expired` — no grade, and the run closed too long ago for the sweep to
3088
3252
  * select it. It will never be graded, and telling a reader to wait would
3089
3253
  * promise work the system does not do.
3254
+ * - `grading_off` — only usage was synced; no behavioral grade is requested.
3090
3255
  */
3091
3256
  export const SessionGradeStateSchema = v.picklist([
3092
3257
  'pending',
3093
3258
  'graded',
3094
3259
  'nothing_to_grade',
3095
3260
  'expired',
3261
+ 'grading_off',
3096
3262
  ]);
3097
3263
  /**
3098
3264
  * The run-level verdict vocabulary — `aligned | misaligned | not_applicable`.
@@ -3153,31 +3319,92 @@ export const SessionGradeResponseSchema = v.object({
3153
3319
  untrusted: v.nullable(GuideHistoryUntrustedSchema),
3154
3320
  });
3155
3321
  // ---------------------------------------------------------------------------
3322
+ // Session digest — `GET /api/v1/runs/grade?detail=digest`
3323
+ // ---------------------------------------------------------------------------
3324
+ /** Most turns one digest returns; `turnsTotal` says how many the session has. */
3325
+ export const SESSION_DIGEST_MAX_TURNS = 50;
3326
+ /** What the digest cannot carry yet, named so an absence is never read as "none". */
3327
+ export const SESSION_DIGEST_UNAVAILABLE = [
3328
+ 'comments',
3329
+ 'resumeCommand',
3330
+ 'cloudUrl',
3331
+ ];
3332
+ export const SessionDigestUnavailableSchema = v.picklist(SESSION_DIGEST_UNAVAILABLE);
3333
+ export const SessionDigestTurnSchema = v.object({
3334
+ ordinal: v.number(),
3335
+ /** What the user said, **wrapped in the response's untrusted markers** and bounded. */
3336
+ text: v.string(),
3337
+ /** The steering classifier's label, or null when the turn was never classified. */
3338
+ steeringLabel: v.nullable(v.string()),
3339
+ });
3340
+ export const SessionDigestSchema = v.object({
3341
+ /** The agent's own closing account of the session, wrapped and bounded; null when it gave none. */
3342
+ selfReport: v.nullable(v.string()),
3343
+ /** The user's turns in order, at most `SESSION_DIGEST_MAX_TURNS`. */
3344
+ turns: v.array(SessionDigestTurnSchema),
3345
+ /** Every turn the session recorded, so a cut list is not read as the whole. */
3346
+ turnsTotal: v.number(),
3347
+ /** The repository's identity digest, or null when the session recorded none. */
3348
+ repoId: v.nullable(v.string()),
3349
+ /** The branch observed at close, wrapped like any text taken from the repo; null when unrecorded. */
3350
+ branch: v.nullable(v.string()),
3351
+ /** The head commit observed at close, or null. A commit made mid-session is not it. */
3352
+ headSha: v.nullable(v.string()),
3353
+ /** The session's page on the dashboard, as a path; the client prefixes the dashboard address. */
3354
+ dashboardPath: v.string(),
3355
+ /** Absolute dashboard link, added by the client that knows the address. */
3356
+ dashboardUrl: v.optional(v.string()),
3357
+ /** Comments on this session, wrapped; empty until sessions can be commented on. */
3358
+ comments: v.array(v.string()),
3359
+ /** The parts of a digest no session carries yet. */
3360
+ notYetAvailable: v.array(SessionDigestUnavailableSchema),
3361
+ });
3362
+ export const SessionDigestResponseSchema = v.object({
3363
+ run: GradedSessionSchema,
3364
+ state: SessionGradeStateSchema,
3365
+ grade: v.nullable(SessionGradeSchema),
3366
+ digest: SessionDigestSchema,
3367
+ /** One marker pair over every wrapped block in the response, present always. */
3368
+ untrusted: GuideHistoryUntrustedSchema,
3369
+ });
3370
+ // ---------------------------------------------------------------------------
3156
3371
  // Search — one term across the caller's evidence (`GET /api/v1/search`)
3157
3372
  // ---------------------------------------------------------------------------
3158
3373
  /**
3159
- * The corpora a search can reach today (`universal-search`, deliverable 1).
3374
+ * The corpora a search can reach today.
3160
3375
  *
3161
3376
  * `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'];
3377
+ * is the grader's reasoning for why a session did or did not follow a guide;
3378
+ * `content` is the name and body of the documents saved in bundles; `comments`
3379
+ * is the text of comments left on guides and documents and, for a caller that
3380
+ * reads them (`SearchRequest.sessionComments`), on its own sessions; `turns` is what the
3381
+ * caller themself said to their agents, redacted; `sessions` is the grader's
3382
+ * summary of the caller's own sessions and the agent's closing report. One
3383
+ * registry on the server declares how each is matched and scoped; this list is
3384
+ * only what a caller may name.
3385
+ */
3386
+ export const SEARCH_CORPUS_IDS = [
3387
+ 'guides',
3388
+ 'verdicts',
3389
+ 'content',
3390
+ 'comments',
3391
+ 'turns',
3392
+ 'sessions',
3393
+ ];
3167
3394
  export const SearchCorpusIdSchema = v.picklist(SEARCH_CORPUS_IDS);
3168
3395
  /**
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.)
3174
- */
3175
- export const SEARCH_UNIMPLEMENTED_CORPORA = [
3176
- 'findings',
3177
- 'actions',
3178
- 'suggestions',
3179
- 'feedback-candidates',
3180
- ];
3396
+ * Every stored text no search reaches yet — the actions and their narration.
3397
+ * Every response names them, so "nothing found" can never be read as covering
3398
+ * them. (Earlier wordings of a guide are deliberately never searched, which is a
3399
+ * different thing from not yet.)
3400
+ */
3401
+ export const SEARCH_UNIMPLEMENTED_CORPORA = ['actions'];
3402
+ /**
3403
+ * What a response still names as not searched for a caller that did not say it
3404
+ * reads session comments (`SearchRequest.sessionComments`): they were left out
3405
+ * of its `comments`, so saying otherwise would read a zero as covering them.
3406
+ */
3407
+ export const SEARCH_SESSION_COMMENTS_UNSEARCHED = 'session-comments';
3181
3408
  export const SearchUnimplementedCorpusSchema = v.picklist(SEARCH_UNIMPLEMENTED_CORPORA);
3182
3409
  /** Hits returned per corpus when the caller does not say. */
3183
3410
  export const SEARCH_DEFAULT_LIMIT = 10;
@@ -3207,8 +3434,52 @@ v.check((value) => value.replace(/[*?]/g, '').length >= 2, 'q must contain at le
3207
3434
  */
3208
3435
  export const SEARCH_DETAILS = ['excerpt', 'section'];
3209
3436
  export const SearchDetailSchema = v.picklist(SEARCH_DETAILS);
3210
- export const SearchRequestSchema = v.object({
3211
- q: SearchTermSchema,
3437
+ /** Frontmatter filters a `content` search accepts at once. */
3438
+ export const SEARCH_MAX_FRONTMATTER_FILTERS = 3;
3439
+ /**
3440
+ * One top-level frontmatter field a `content` item must carry, by exact scalar
3441
+ * value (`type: recipe`). The key is a plain YAML key so it can be matched
3442
+ * without being interpreted; the value is literal text, compared
3443
+ * case-insensitively.
3444
+ */
3445
+ 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) => {
3446
+ const count = Object.keys(fields).length;
3447
+ return count >= 1 && count <= SEARCH_MAX_FRONTMATTER_FILTERS;
3448
+ }, `frontmatter takes between 1 and ${SEARCH_MAX_FRONTMATTER_FILTERS} fields`));
3449
+ /** Who wrote a comment: a person, an agent, or Mossbear itself. */
3450
+ export const SEARCH_COMMENT_AUTHOR_KINDS = ['person', 'agent', 'mossbear'];
3451
+ export const SearchCommentAuthorKindSchema = v.picklist(SEARCH_COMMENT_AUTHOR_KINDS);
3452
+ /**
3453
+ * What a comment is attached to. `item` is a guide or a document; `session` is a
3454
+ * run the caller made. Session comments are the caller's own and never reach a
3455
+ * workspace-mate.
3456
+ */
3457
+ export const SEARCH_COMMENT_SUBJECT_KINDS = ['item', 'session'];
3458
+ export const SearchCommentSubjectKindSchema = v.picklist(SEARCH_COMMENT_SUBJECT_KINDS);
3459
+ /**
3460
+ * What a user turn was, as the session classifier labels it. The same
3461
+ * vocabulary the classifier writes; a `turns` search may keep only some.
3462
+ */
3463
+ export const SEARCH_STEERING_LABELS = [
3464
+ 'correction',
3465
+ 'steering',
3466
+ 'new request',
3467
+ 'acknowledgement',
3468
+ 'insufficient evidence',
3469
+ ];
3470
+ export const SearchSteeringLabelSchema = v.picklist(SEARCH_STEERING_LABELS);
3471
+ /**
3472
+ * One exact value a `sessions` search filters on — a head sha, a branch name or
3473
+ * a repo digest. Compared as written, so it is trimmed and bounded but never
3474
+ * case-folded or treated as a pattern.
3475
+ */
3476
+ 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'));
3477
+ export const SearchRequestObjectSchema = v.object({
3478
+ /**
3479
+ * The term. Optional only for a `sessions` search that names a filter (`headSha`,
3480
+ * `branch` or `repoId`): "which session ended at this commit" has no words to match.
3481
+ */
3482
+ q: v.optional(SearchTermSchema),
3212
3483
  /** Which corpora to search; every one when absent. */
3213
3484
  corpora: v.optional(v.pipe(v.array(SearchCorpusIdSchema), v.minLength(1))),
3214
3485
  /**
@@ -3228,7 +3499,55 @@ export const SearchRequestSchema = v.object({
3228
3499
  * id the caller cannot read matches nothing. Does not touch other corpora.
3229
3500
  */
3230
3501
  fileIds: v.optional(v.pipe(v.array(NonEmptyStringSchema), v.minLength(1), v.maxLength(SEARCH_MAX_LIMIT))),
3502
+ /**
3503
+ * Restrict the `content` corpus to items whose frontmatter carries every one
3504
+ * of these fields. Does not touch other corpora.
3505
+ */
3506
+ frontmatter: v.optional(SearchFrontmatterSchema),
3507
+ /**
3508
+ * Restrict the `comments` corpus to comments written by these kinds of
3509
+ * author. Does not touch other corpora.
3510
+ */
3511
+ authorKinds: v.optional(v.pipe(v.array(SearchCommentAuthorKindSchema), v.minLength(1))),
3512
+ /**
3513
+ * Restrict the `comments` corpus to comments on these kinds of subject. Does
3514
+ * not touch other corpora.
3515
+ */
3516
+ subjectKinds: v.optional(v.pipe(v.array(SearchCommentSubjectKindSchema), v.minLength(1))),
3517
+ /**
3518
+ * Restrict the `turns` corpus to turns the classifier gave one of these
3519
+ * labels. A turn with no label never matches. Does not touch other corpora.
3520
+ */
3521
+ steeringLabels: v.optional(v.pipe(v.array(SearchSteeringLabelSchema), v.minLength(1))),
3522
+ /**
3523
+ * Restrict the `sessions` corpus to sessions whose recorded head was exactly
3524
+ * this commit when they closed. A commit made mid-session matches nothing:
3525
+ * the head is the one observed at close. Does not touch other corpora.
3526
+ */
3527
+ headSha: v.optional(SearchSessionFilterValueSchema),
3528
+ /** Restrict the `sessions` corpus to sessions that closed on exactly this branch. Does not touch other corpora. */
3529
+ branch: v.optional(SearchSessionFilterValueSchema),
3530
+ /** Restrict the `sessions` corpus to sessions recorded under exactly this repo id. Does not touch other corpora. */
3531
+ repoId: v.optional(SearchSessionFilterValueSchema),
3532
+ /**
3533
+ * Whether the caller can read a `comments` hit on a session. A client from
3534
+ * before session comments were searchable validates the whole response
3535
+ * strictly and would reject one, so the server returns them only to a caller
3536
+ * that says it can, and tells every other caller they were not searched.
3537
+ * Absent means it cannot.
3538
+ */
3539
+ sessionComments: v.optional(v.boolean()),
3231
3540
  });
3541
+ /**
3542
+ * A request with no term searches the caller's sessions by filter alone, so it
3543
+ * must name one, and must not name another corpus (which has nothing to match).
3544
+ */
3545
+ export const SearchRequestSchema = v.pipe(SearchRequestObjectSchema, v.forward(v.check((request) => request.q !== undefined ||
3546
+ request.headSha !== undefined ||
3547
+ request.branch !== undefined ||
3548
+ 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 ||
3549
+ request.corpora === undefined ||
3550
+ request.corpora.every((id) => id === 'sessions'), 'without q only the sessions corpus can be searched'), ['corpora']));
3232
3551
  /**
3233
3552
  * Why a corpus was not searched. Codes, never prose: each caller writes its own
3234
3553
  * sentence, and the dashboard's has to be a translatable one.
@@ -3236,9 +3555,14 @@ export const SearchRequestSchema = v.object({
3236
3555
  export const SearchSkipReasonSchema = v.picklist([
3237
3556
  'excluded-by-caller',
3238
3557
  'timed-out',
3239
- // The caller's token is limited to certain bundles, and grading results are
3240
- // never among what such a token reaches.
3558
+ // The caller's token is limited to certain bundles, and grading results, the
3559
+ // caller's turns and sessions, and comments on their sessions are never among
3560
+ // what such a token reaches.
3241
3561
  'not-granted',
3562
+ // A filter named only kinds of subject this caller cannot be given: `session`
3563
+ // from a client that did not say it reads session comments, which is also what
3564
+ // a server from before they were searchable said to every caller.
3565
+ 'not-yet-searchable',
3242
3566
  ]);
3243
3567
  /** Why a searched corpus covered less than the caller's whole scope. */
3244
3568
  export const SearchNarrowingSchema = v.picklist(['narrowed-by-bundle-allowlist']);
@@ -3284,6 +3608,164 @@ export const SearchVerdictHitSchema = v.object({
3284
3608
  occurredAt: v.string(),
3285
3609
  reasoning: v.string(),
3286
3610
  });
3611
+ /**
3612
+ * A saved document whose name or body matched — an item `pull_context` returns
3613
+ * as `type: content`. The name, workspace name and excerpt are wrapped in
3614
+ * `untrusted`'s markers.
3615
+ */
3616
+ export const SearchContentHitSchema = v.object({
3617
+ itemId: NonEmptyStringSchema,
3618
+ /** Wrapped in `untrusted`'s markers; null when the item has no name. */
3619
+ name: v.nullable(v.string()),
3620
+ workspaceId: NonEmptyStringSchema,
3621
+ /** Wrapped in `untrusted`'s markers. */
3622
+ workspaceName: v.string(),
3623
+ /**
3624
+ * Slugs of the bundles that hold the item and that the caller may read — the
3625
+ * argument `pull_context` takes to read the whole document. Never more than
3626
+ * a scoped caller's allowlist reaches.
3627
+ */
3628
+ bundles: v.array(v.string()),
3629
+ updatedAt: v.string(),
3630
+ /**
3631
+ * Where the item opens on the dashboard. Added by the CLI, which knows the
3632
+ * dashboard's address; the server does not send it.
3633
+ */
3634
+ url: v.optional(v.string()),
3635
+ /** A window around the match, wrapped in `untrusted`'s markers. */
3636
+ excerpt: v.string(),
3637
+ });
3638
+ /** What every matched comment carries, whatever it is attached to. */
3639
+ const searchCommentHitFields = {
3640
+ commentId: NonEmptyStringSchema,
3641
+ /** The thread's root; equal to `commentId` for a root comment. */
3642
+ threadId: NonEmptyStringSchema,
3643
+ authorKind: SearchCommentAuthorKindSchema,
3644
+ /** Whether the thread has been resolved — a resolved thread is answered, not open. */
3645
+ resolved: v.boolean(),
3646
+ createdAt: v.string(),
3647
+ /**
3648
+ * Where the comment's subject opens on the dashboard. Added by the CLI, which
3649
+ * knows the dashboard's address; the server does not send it.
3650
+ */
3651
+ url: v.optional(v.string()),
3652
+ /** A window around the match, wrapped in `untrusted`'s markers. */
3653
+ excerpt: v.string(),
3654
+ };
3655
+ /**
3656
+ * A comment on a guide or document that matched. `body` and `itemName` and
3657
+ * `workspaceName` are wrapped in `untrusted`'s markers.
3658
+ */
3659
+ export const SearchItemCommentHitSchema = v.object({
3660
+ ...searchCommentHitFields,
3661
+ subjectKind: v.literal('item'),
3662
+ itemId: NonEmptyStringSchema,
3663
+ /**
3664
+ * The guide the item belongs to, or null for a standalone document. A comment
3665
+ * on a guide sits on its body file, so this is the id the dashboard's guide
3666
+ * page takes; `itemId` is the one a document page takes.
3667
+ */
3668
+ guideId: v.nullable(NonEmptyStringSchema),
3669
+ /** Wrapped in `untrusted`'s markers; null when the item has no name. */
3670
+ itemName: v.nullable(v.string()),
3671
+ workspaceId: NonEmptyStringSchema,
3672
+ /** Wrapped in `untrusted`'s markers. */
3673
+ workspaceName: v.string(),
3674
+ /** Whether the item has been edited since the comment was written. */
3675
+ itemChangedSince: v.boolean(),
3676
+ /**
3677
+ * Whether the match is in the comment's text or in the replacement it
3678
+ * suggests (Mossbear's drafted edits).
3679
+ */
3680
+ matchedIn: v.picklist(['body', 'suggestion']),
3681
+ /**
3682
+ * A Mossbear suggestion's draft state: whether its owner has handed it to
3683
+ * their agents. Absent on a person's or an agent's comment and on a reply.
3684
+ */
3685
+ approved: v.optional(v.boolean()),
3686
+ });
3687
+ /**
3688
+ * A comment on one of the caller's own sessions that matched. It has no
3689
+ * workspace and no item: `sessionId` is the id the dashboard's session page
3690
+ * takes. The excerpt is wrapped in `untrusted`'s markers.
3691
+ */
3692
+ export const SearchSessionCommentHitSchema = v.object({
3693
+ ...searchCommentHitFields,
3694
+ subjectKind: v.literal('session'),
3695
+ sessionId: NonEmptyStringSchema,
3696
+ matchedIn: v.literal('body'),
3697
+ });
3698
+ export const SearchCommentHitSchema = v.variant('subjectKind', [
3699
+ SearchItemCommentHitSchema,
3700
+ SearchSessionCommentHitSchema,
3701
+ ]);
3702
+ /**
3703
+ * One thing the caller said to an agent, redacted at the source. `excerpt` and
3704
+ * `projectId` and `branch` are wrapped in `untrusted`'s markers: a turn is text a
3705
+ * person typed (or pasted) and a branch name is whatever git was told.
3706
+ */
3707
+ export const SearchTurnHitSchema = v.object({
3708
+ /** The agent's own session id — the key a session digest takes. */
3709
+ agentSessionId: NonEmptyStringSchema,
3710
+ /**
3711
+ * The dashboard's id for the session, which its session page takes. Null when
3712
+ * the session has not been recorded as a run yet.
3713
+ */
3714
+ sessionId: v.nullable(NonEmptyStringSchema),
3715
+ /** Which turn of the session this was, counting from 1. */
3716
+ ordinal: v.pipe(v.number(), v.integer(), v.minValue(1)),
3717
+ /** Null when the classifier has not labelled the turn. */
3718
+ steeringLabel: v.nullable(SearchSteeringLabelSchema),
3719
+ /** Wrapped in `untrusted`'s markers; null where the session recorded none. */
3720
+ projectId: v.nullable(v.string()),
3721
+ /** Wrapped in `untrusted`'s markers; null where the session recorded none. */
3722
+ branch: v.nullable(v.string()),
3723
+ createdAt: v.string(),
3724
+ /**
3725
+ * Where the session opens on the dashboard. Added by the CLI, which knows the
3726
+ * dashboard's address; the server does not send it.
3727
+ */
3728
+ url: v.optional(v.string()),
3729
+ /** A window around the match, wrapped in `untrusted`'s markers. */
3730
+ excerpt: v.string(),
3731
+ });
3732
+ /** Which of a session's stored texts a `sessions` hit matched. */
3733
+ export const SEARCH_SESSION_MATCH_FIELDS = ['grade', 'self_report'];
3734
+ export const SearchSessionMatchFieldSchema = v.picklist(SEARCH_SESSION_MATCH_FIELDS);
3735
+ /**
3736
+ * One of the caller's own sessions, found by what the grader said about it or
3737
+ * what the agent reported at the end. `repoId`, `projectId`, `branch`,
3738
+ * `headSha` and `excerpt` are wrapped in `untrusted`'s markers: the first four
3739
+ * are whatever a checkout reported, and the excerpt is model-authored or
3740
+ * written by an agent.
3741
+ */
3742
+ export const SearchSessionHitSchema = v.object({
3743
+ /** The agent's own session id — the key a session digest takes. */
3744
+ agentSessionId: NonEmptyStringSchema,
3745
+ /** The dashboard's id for the session, which its session page takes. */
3746
+ sessionId: NonEmptyStringSchema,
3747
+ /** Wrapped in `untrusted`'s markers; null where the session recorded none. */
3748
+ repoId: v.nullable(v.string()),
3749
+ /** Wrapped in `untrusted`'s markers; null where the session recorded none. */
3750
+ projectId: v.nullable(v.string()),
3751
+ /** Wrapped in `untrusted`'s markers; null where the session recorded none. */
3752
+ branch: v.nullable(v.string()),
3753
+ /**
3754
+ * The head observed when the session closed, wrapped in `untrusted`'s
3755
+ * markers; null where none was observed. A commit made mid-session is not it.
3756
+ */
3757
+ headSha: v.nullable(v.string()),
3758
+ startedAt: v.string(),
3759
+ /** Null when the search named no term, only filters. */
3760
+ matchedIn: v.nullable(SearchSessionMatchFieldSchema),
3761
+ /**
3762
+ * Where the session opens on the dashboard. Added by the CLI, which knows the
3763
+ * dashboard's address; the server does not send it.
3764
+ */
3765
+ url: v.optional(v.string()),
3766
+ /** A window around the match, wrapped in `untrusted`'s markers; null when the search named no term. */
3767
+ excerpt: v.nullable(v.string()),
3768
+ });
3287
3769
  function searchCorpusReportSchema(hit) {
3288
3770
  return v.variant('status', [
3289
3771
  v.object({
@@ -3302,6 +3784,10 @@ function searchCorpusReportSchema(hit) {
3302
3784
  }
3303
3785
  export const SearchGuidesReportSchema = searchCorpusReportSchema(SearchGuideHitSchema);
3304
3786
  export const SearchVerdictsReportSchema = searchCorpusReportSchema(SearchVerdictHitSchema);
3787
+ export const SearchContentReportSchema = searchCorpusReportSchema(SearchContentHitSchema);
3788
+ export const SearchCommentsReportSchema = searchCorpusReportSchema(SearchCommentHitSchema);
3789
+ export const SearchTurnsReportSchema = searchCorpusReportSchema(SearchTurnHitSchema);
3790
+ export const SearchSessionsReportSchema = searchCorpusReportSchema(SearchSessionHitSchema);
3305
3791
  /**
3306
3792
  * A search's answer: **a report per corpus, never a bare list.**
3307
3793
  *
@@ -3315,8 +3801,30 @@ export const SearchResponseSchema = v.object({
3315
3801
  corpora: v.object({
3316
3802
  guides: SearchGuidesReportSchema,
3317
3803
  verdicts: SearchVerdictsReportSchema,
3804
+ /**
3805
+ * Optional because a server that predates the `content` corpus does not
3806
+ * send it — and then did not search it, which a caller must say rather
3807
+ * than read as zero hits.
3808
+ */
3809
+ content: v.optional(SearchContentReportSchema),
3810
+ /** Optional for the same reason as `content`. Covers comments on guides and documents, and the caller's own comments on their sessions. */
3811
+ comments: v.optional(SearchCommentsReportSchema),
3812
+ /** Optional for the same reason as `content`. The caller's own turns, never a workspace-mate's. */
3813
+ turns: v.optional(SearchTurnsReportSchema),
3814
+ /** Optional for the same reason as `content`. The caller's own sessions, never a workspace-mate's. */
3815
+ sessions: v.optional(SearchSessionsReportSchema),
3318
3816
  }),
3319
- notYetSearchable: v.array(SearchUnimplementedCorpusSchema),
3817
+ // `comments` is what a server from before session comments were told apart
3818
+ // from item comments still sends; a newer client must read that response, not
3819
+ // refuse it. `session-comments`, `turns` and `sessions` are what servers sent
3820
+ // before those corpora were searchable.
3821
+ notYetSearchable: v.array(v.picklist([
3822
+ ...SEARCH_UNIMPLEMENTED_CORPORA,
3823
+ 'comments',
3824
+ 'session-comments',
3825
+ 'turns',
3826
+ 'sessions',
3827
+ ])),
3320
3828
  untrusted: GuideHistoryUntrustedSchema,
3321
3829
  });
3322
3830
  // ---------------------------------------------------------------------------
@@ -3497,6 +4005,9 @@ export function parseAnnounceItemCommentsRequest(data) {
3497
4005
  export function parseAnnounceItemCommentsResponse(data) {
3498
4006
  return v.parse(AnnounceItemCommentsResponseSchema, data);
3499
4007
  }
4008
+ export function parseAgentCommentResponse(data) {
4009
+ return v.parse(AgentCommentResponseSchema, data);
4010
+ }
3500
4011
  export function parseItemCommentsResponse(data) {
3501
4012
  return v.parse(ItemCommentsResponseSchema, data);
3502
4013
  }
@@ -3509,6 +4020,9 @@ export function parseRunGradeRequest(data) {
3509
4020
  export function parseSessionGradeResponse(data) {
3510
4021
  return v.parse(SessionGradeResponseSchema, data);
3511
4022
  }
4023
+ export function parseSessionDigestResponse(data) {
4024
+ return v.parse(SessionDigestResponseSchema, data);
4025
+ }
3512
4026
  export function parseSearchResponse(data) {
3513
4027
  return v.parse(SearchResponseSchema, data);
3514
4028
  }