@cyanheads/secedgar-mcp-server 0.18.1 → 0.19.1

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 (141) hide show
  1. package/AGENTS.md +36 -24
  2. package/CLAUDE.md +36 -24
  3. package/README.md +16 -12
  4. package/changelog/0.19.x/0.19.0.md +47 -0
  5. package/changelog/0.19.x/0.19.1.md +35 -0
  6. package/changelog/template.md +10 -3
  7. package/dist/config/server-config.js +2 -2
  8. package/dist/config/server-config.js.map +1 -1
  9. package/dist/index.js +27 -9
  10. package/dist/index.js.map +1 -1
  11. package/dist/mcp-server/tools/dataset-schema.d.ts +14 -0
  12. package/dist/mcp-server/tools/dataset-schema.d.ts.map +1 -0
  13. package/dist/mcp-server/tools/dataset-schema.js +16 -0
  14. package/dist/mcp-server/tools/dataset-schema.js.map +1 -0
  15. package/dist/mcp-server/tools/definitions/company-search.tool.d.ts +44 -14
  16. package/dist/mcp-server/tools/definitions/company-search.tool.d.ts.map +1 -1
  17. package/dist/mcp-server/tools/definitions/company-search.tool.js +197 -62
  18. package/dist/mcp-server/tools/definitions/company-search.tool.js.map +1 -1
  19. package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts +26 -12
  20. package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts.map +1 -1
  21. package/dist/mcp-server/tools/definitions/compare-companies.tool.js +41 -39
  22. package/dist/mcp-server/tools/definitions/compare-companies.tool.js.map +1 -1
  23. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts +12 -3
  24. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts.map +1 -1
  25. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js +23 -9
  26. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js.map +1 -1
  27. package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js +2 -2
  28. package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js.map +1 -1
  29. package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts +16 -16
  30. package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts.map +1 -1
  31. package/dist/mcp-server/tools/definitions/dataframe-query.tool.js +17 -17
  32. package/dist/mcp-server/tools/definitions/dataframe-query.tool.js.map +1 -1
  33. package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts +26 -12
  34. package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts.map +1 -1
  35. package/dist/mcp-server/tools/definitions/fetch-frames.tool.js +15 -37
  36. package/dist/mcp-server/tools/definitions/fetch-frames.tool.js.map +1 -1
  37. package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts +36 -20
  38. package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts.map +1 -1
  39. package/dist/mcp-server/tools/definitions/find-holders.tool.js +26 -41
  40. package/dist/mcp-server/tools/definitions/find-holders.tool.js.map +1 -1
  41. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts +28 -12
  42. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts.map +1 -1
  43. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js +30 -44
  44. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js.map +1 -1
  45. package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts +50 -14
  46. package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts.map +1 -1
  47. package/dist/mcp-server/tools/definitions/get-filing.tool.js +193 -59
  48. package/dist/mcp-server/tools/definitions/get-filing.tool.js.map +1 -1
  49. package/dist/mcp-server/tools/definitions/get-financials.tool.d.ts +14 -6
  50. package/dist/mcp-server/tools/definitions/get-financials.tool.d.ts.map +1 -1
  51. package/dist/mcp-server/tools/definitions/get-financials.tool.js +38 -41
  52. package/dist/mcp-server/tools/definitions/get-financials.tool.js.map +1 -1
  53. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts +28 -12
  54. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts.map +1 -1
  55. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js +22 -35
  56. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js.map +1 -1
  57. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts +28 -12
  58. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts.map +1 -1
  59. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js +22 -31
  60. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js.map +1 -1
  61. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts +36 -20
  62. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts.map +1 -1
  63. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js +22 -39
  64. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js.map +1 -1
  65. package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts +28 -12
  66. package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts.map +1 -1
  67. package/dist/mcp-server/tools/definitions/get-material-events.tool.js +23 -32
  68. package/dist/mcp-server/tools/definitions/get-material-events.tool.js.map +1 -1
  69. package/dist/mcp-server/tools/definitions/get-snapshot.tool.d.ts +16 -7
  70. package/dist/mcp-server/tools/definitions/get-snapshot.tool.d.ts.map +1 -1
  71. package/dist/mcp-server/tools/definitions/get-snapshot.tool.js +24 -32
  72. package/dist/mcp-server/tools/definitions/get-snapshot.tool.js.map +1 -1
  73. package/dist/mcp-server/tools/definitions/index.d.ts +232 -101
  74. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  75. package/dist/mcp-server/tools/definitions/search-concepts.tool.js +3 -3
  76. package/dist/mcp-server/tools/definitions/search-concepts.tool.js.map +1 -1
  77. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts +46 -20
  78. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts.map +1 -1
  79. package/dist/mcp-server/tools/definitions/search-filings.tool.js +126 -68
  80. package/dist/mcp-server/tools/definitions/search-filings.tool.js.map +1 -1
  81. package/dist/mcp-server/tools/resolved-as.d.ts +10 -0
  82. package/dist/mcp-server/tools/resolved-as.d.ts.map +1 -0
  83. package/dist/mcp-server/tools/resolved-as.js +13 -0
  84. package/dist/mcp-server/tools/resolved-as.js.map +1 -0
  85. package/dist/mcp-server/tools/sec-upstream-errors.d.ts +44 -0
  86. package/dist/mcp-server/tools/sec-upstream-errors.d.ts.map +1 -0
  87. package/dist/mcp-server/tools/sec-upstream-errors.js +48 -0
  88. package/dist/mcp-server/tools/sec-upstream-errors.js.map +1 -0
  89. package/dist/services/canvas-bridge/canvas-bridge.d.ts +98 -45
  90. package/dist/services/canvas-bridge/canvas-bridge.d.ts.map +1 -1
  91. package/dist/services/canvas-bridge/canvas-bridge.js +137 -126
  92. package/dist/services/canvas-bridge/canvas-bridge.js.map +1 -1
  93. package/dist/services/canvas-bridge/sql-gate-extras.d.ts +4 -17
  94. package/dist/services/canvas-bridge/sql-gate-extras.d.ts.map +1 -1
  95. package/dist/services/canvas-bridge/sql-gate-extras.js +4 -22
  96. package/dist/services/canvas-bridge/sql-gate-extras.js.map +1 -1
  97. package/dist/services/edgar/concept-map.d.ts +10 -6
  98. package/dist/services/edgar/concept-map.d.ts.map +1 -1
  99. package/dist/services/edgar/concept-map.js +90 -22
  100. package/dist/services/edgar/concept-map.js.map +1 -1
  101. package/dist/services/edgar/data/former-tickers.json +24159 -0
  102. package/dist/services/edgar/edgar-api-service.d.ts +250 -62
  103. package/dist/services/edgar/edgar-api-service.d.ts.map +1 -1
  104. package/dist/services/edgar/edgar-api-service.js +808 -189
  105. package/dist/services/edgar/edgar-api-service.js.map +1 -1
  106. package/dist/services/edgar/filing-to-text.d.ts +71 -2
  107. package/dist/services/edgar/filing-to-text.d.ts.map +1 -1
  108. package/dist/services/edgar/filing-to-text.js +533 -5
  109. package/dist/services/edgar/filing-to-text.js.map +1 -1
  110. package/dist/services/edgar/former-tickers.d.ts +47 -0
  111. package/dist/services/edgar/former-tickers.d.ts.map +1 -0
  112. package/dist/services/edgar/former-tickers.js +77 -0
  113. package/dist/services/edgar/former-tickers.js.map +1 -0
  114. package/dist/services/edgar/listing-codes.d.ts +47 -0
  115. package/dist/services/edgar/listing-codes.d.ts.map +1 -0
  116. package/dist/services/edgar/listing-codes.js +110 -0
  117. package/dist/services/edgar/listing-codes.js.map +1 -0
  118. package/dist/services/edgar/mirror/edgar-mirror.d.ts +11 -1
  119. package/dist/services/edgar/mirror/edgar-mirror.d.ts.map +1 -1
  120. package/dist/services/edgar/mirror/edgar-mirror.js +19 -1
  121. package/dist/services/edgar/mirror/edgar-mirror.js.map +1 -1
  122. package/dist/services/edgar/mirror/tickers-sync.d.ts.map +1 -1
  123. package/dist/services/edgar/mirror/tickers-sync.js +1 -3
  124. package/dist/services/edgar/mirror/tickers-sync.js.map +1 -1
  125. package/dist/services/edgar/mirror/types.d.ts +3 -1
  126. package/dist/services/edgar/mirror/types.d.ts.map +1 -1
  127. package/dist/services/edgar/mirror/types.js +3 -1
  128. package/dist/services/edgar/mirror/types.js.map +1 -1
  129. package/dist/services/edgar/trigram-similarity.d.ts +5 -3
  130. package/dist/services/edgar/trigram-similarity.d.ts.map +1 -1
  131. package/dist/services/edgar/trigram-similarity.js +18 -17
  132. package/dist/services/edgar/trigram-similarity.js.map +1 -1
  133. package/dist/services/edgar/types.d.ts +20 -7
  134. package/dist/services/edgar/types.d.ts.map +1 -1
  135. package/package.json +6 -5
  136. package/server.json +3 -3
  137. package/skills/secedgar-guide/SKILL.md +3 -3
  138. package/dist/mcp-server/tools/escape-inline.d.ts +0 -35
  139. package/dist/mcp-server/tools/escape-inline.d.ts.map +0 -1
  140. package/dist/mcp-server/tools/escape-inline.js +0 -51
  141. package/dist/mcp-server/tools/escape-inline.js.map +0 -1
@@ -13,6 +13,7 @@ export declare const getFilingTool: import("@cyanheads/mcp-ts-core").ToolDefinit
13
13
  include_xbrl: z.ZodDefault<z.ZodBoolean>;
14
14
  offset: z.ZodDefault<z.ZodNumber>;
15
15
  section: z.ZodOptional<z.ZodString>;
16
+ find: z.ZodOptional<z.ZodString>;
16
17
  }, z.core.$strip>, z.ZodObject<{
17
18
  accession_number: z.ZodString;
18
19
  form: z.ZodOptional<z.ZodString>;
@@ -60,6 +61,11 @@ export declare const getFilingTool: import("@cyanheads/mcp-ts-core").ToolDefinit
60
61
  heading: z.ZodString;
61
62
  offset: z.ZodNumber;
62
63
  }, z.core.$strip>>>;
64
+ occurrences: z.ZodOptional<z.ZodArray<z.ZodObject<{
65
+ offset: z.ZodNumber;
66
+ context: z.ZodString;
67
+ }, z.core.$strip>>>;
68
+ occurrences_total: z.ZodOptional<z.ZodNumber>;
63
69
  filing_url: z.ZodString;
64
70
  }, z.core.$strip>, readonly [{
65
71
  readonly reason: "document_not_found";
@@ -90,21 +96,33 @@ export declare const getFilingTool: import("@cyanheads/mcp-ts-core").ToolDefinit
90
96
  readonly reason: "section_not_found";
91
97
  readonly code: JsonRpcErrorCode.NotFound;
92
98
  readonly when: "The section string matched no detected heading and no line of the document";
93
- readonly recovery: "Pick a heading from the outline in the error message, pass a subheading exactly as the document prints it, or use offset paging instead.";
99
+ readonly recovery: "Pick a heading from the outline in the error message or pass a subheading exactly as the document prints it; pass a phrase that is not a heading as find, or page with offset.";
100
+ }, {
101
+ readonly reason: "phrase_not_found";
102
+ readonly code: JsonRpcErrorCode.NotFound;
103
+ readonly when: "No occurrence of the find phrase starts at or after offset: the document does not contain it, or holds it only before offset";
104
+ readonly recovery: "Check the phrase against the document text, or pass a smaller offset to search from earlier in the document.";
94
105
  }, {
95
- readonly reason: "rate_limited";
106
+ readonly reason: 'rate_limited';
96
107
  readonly code: JsonRpcErrorCode.RateLimited;
97
108
  readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
98
- readonly recovery: "Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.";
109
+ readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
99
110
  readonly retryable: true;
100
- readonly thrownBy: "service";
111
+ readonly thrownBy: 'service';
101
112
  }, {
102
- readonly reason: "sec_unreachable";
113
+ readonly reason: 'sec_unreachable';
103
114
  readonly code: JsonRpcErrorCode.ServiceUnavailable;
104
115
  readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
105
- readonly recovery: "Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.";
116
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
117
+ readonly retryable: true;
118
+ readonly thrownBy: 'service';
119
+ }, {
120
+ readonly reason: 'sec_unavailable';
121
+ readonly code: JsonRpcErrorCode.ServiceUnavailable;
122
+ readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
123
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
106
124
  readonly retryable: true;
107
- readonly thrownBy: "service";
125
+ readonly thrownBy: 'service';
108
126
  }], {
109
127
  readonly notice: z.ZodOptional<z.ZodString>;
110
128
  readonly truncated: z.ZodOptional<z.ZodBoolean>;
@@ -120,6 +138,7 @@ export declare function createGetFilingTool(options: LimitClampOptions): import(
120
138
  include_xbrl: z.ZodDefault<z.ZodBoolean>;
121
139
  offset: z.ZodDefault<z.ZodNumber>;
122
140
  section: z.ZodOptional<z.ZodString>;
141
+ find: z.ZodOptional<z.ZodString>;
123
142
  }, z.core.$strip>, z.ZodObject<{
124
143
  accession_number: z.ZodString;
125
144
  form: z.ZodOptional<z.ZodString>;
@@ -167,6 +186,11 @@ export declare function createGetFilingTool(options: LimitClampOptions): import(
167
186
  heading: z.ZodString;
168
187
  offset: z.ZodNumber;
169
188
  }, z.core.$strip>>>;
189
+ occurrences: z.ZodOptional<z.ZodArray<z.ZodObject<{
190
+ offset: z.ZodNumber;
191
+ context: z.ZodString;
192
+ }, z.core.$strip>>>;
193
+ occurrences_total: z.ZodOptional<z.ZodNumber>;
170
194
  filing_url: z.ZodString;
171
195
  }, z.core.$strip>, readonly [{
172
196
  readonly reason: "document_not_found";
@@ -197,21 +221,33 @@ export declare function createGetFilingTool(options: LimitClampOptions): import(
197
221
  readonly reason: "section_not_found";
198
222
  readonly code: JsonRpcErrorCode.NotFound;
199
223
  readonly when: "The section string matched no detected heading and no line of the document";
200
- readonly recovery: "Pick a heading from the outline in the error message, pass a subheading exactly as the document prints it, or use offset paging instead.";
224
+ readonly recovery: "Pick a heading from the outline in the error message or pass a subheading exactly as the document prints it; pass a phrase that is not a heading as find, or page with offset.";
225
+ }, {
226
+ readonly reason: "phrase_not_found";
227
+ readonly code: JsonRpcErrorCode.NotFound;
228
+ readonly when: "No occurrence of the find phrase starts at or after offset: the document does not contain it, or holds it only before offset";
229
+ readonly recovery: "Check the phrase against the document text, or pass a smaller offset to search from earlier in the document.";
201
230
  }, {
202
- readonly reason: "rate_limited";
231
+ readonly reason: 'rate_limited';
203
232
  readonly code: JsonRpcErrorCode.RateLimited;
204
233
  readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
205
- readonly recovery: "Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.";
234
+ readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
206
235
  readonly retryable: true;
207
- readonly thrownBy: "service";
236
+ readonly thrownBy: 'service';
208
237
  }, {
209
- readonly reason: "sec_unreachable";
238
+ readonly reason: 'sec_unreachable';
210
239
  readonly code: JsonRpcErrorCode.ServiceUnavailable;
211
240
  readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
212
- readonly recovery: "Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.";
241
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
242
+ readonly retryable: true;
243
+ readonly thrownBy: 'service';
244
+ }, {
245
+ readonly reason: 'sec_unavailable';
246
+ readonly code: JsonRpcErrorCode.ServiceUnavailable;
247
+ readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
248
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
213
249
  readonly retryable: true;
214
- readonly thrownBy: "service";
250
+ readonly thrownBy: 'service';
215
251
  }], {
216
252
  readonly notice: z.ZodOptional<z.ZodString>;
217
253
  readonly truncated: z.ZodOptional<z.ZodBoolean>;
@@ -1 +1 @@
1
- {"version":3,"file":"get-filing.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-filing.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAG3E,OAAO,EACL,KAAK,iBAAiB,EAGvB,MAAM,mCAAmC,CAAC;AA6K3C,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAukBxB,CAAC;AAEH,2FAA2F;AAC3F,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAE7D"}
1
+ {"version":3,"file":"get-filing.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-filing.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAE3E,OAAO,EACL,KAAK,iBAAiB,EAGvB,MAAM,mCAAmC,CAAC;AA4L3C,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6pBxB,CAAC;AAEH,2FAA2F;AAC3F,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAE7D"}
@@ -4,12 +4,12 @@
4
4
  */
5
5
  import { tool, z } from '@cyanheads/mcp-ts-core';
6
6
  import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
7
- import { markdown } from '@cyanheads/mcp-ts-core/utils';
8
- import { escapeInline } from '../escape-inline.js';
7
+ import { escapeMarkdownInline, markdown } from '@cyanheads/mcp-ts-core/utils';
9
8
  import { limitClamp, withLimitClamps, } from '../limit-clamp.js';
9
+ import { SEC_UPSTREAM_ERRORS } from '../sec-upstream-errors.js';
10
10
  import { CallScope } from '../../../services/edgar/call-scope.js';
11
11
  import { filingArchiveUrl, getEdgarApiService } from '../../../services/edgar/edgar-api-service.js';
12
- import { detectHeadings, filingToExtract, foldForHeadingMatch, getExtractCache, headingKey, isTocHeading, MARKER_TITLE_RE, matchSectionLine, setExtractCache, spaceRunInMarker, windowText, withoutSubItemLabel, } from '../../../services/edgar/filing-to-text.js';
12
+ import { detectHeadings, filingToExtract, findPhrase, foldForHeadingMatch, getExtractCache, headingKey, isTocHeading, linkedSectionStart, MARKER_TITLE_RE, matchSectionLine, setExtractCache, spaceRunInMarker, windowText, withoutSubItemLabel, } from '../../../services/edgar/filing-to-text.js';
13
13
  const MAX_DOCUMENTS_IN_FORMAT = 10;
14
14
  /**
15
15
  * Per-category cap on the catalog rendered into an error message. Distinct from
@@ -30,27 +30,35 @@ const FILING_CONTENT_BEGIN = '--- BEGIN SEC FILING CONTENT (upstream document te
30
30
  const FILING_CONTENT_END = '--- END SEC FILING CONTENT ---';
31
31
  /** Sentinel key suffix when no specific document is requested (primary document path). */
32
32
  const PRIMARY_SENTINEL = '\x00primary';
33
+ /** Longest `find` phrase, in characters (#238). */
34
+ const MAX_FIND_CHARS = 200;
35
+ /** Most occurrences of a `find` phrase one response lists; `occurrences_total` counts them all. */
36
+ const MAX_LISTED_OCCURRENCES = 20;
37
+ /** How far before an occurrence a `find` page may open: to its line's start, else a word's. */
38
+ const FIND_PAGE_LEAD_CHARS = 200;
39
+ /** Characters of document text an occurrence's `context` keeps on each side of the match. */
40
+ const OCCURRENCE_CONTEXT_CHARS = 40;
33
41
  /** What an archive miss asks the caller to pass, after a verb (#203). */
34
42
  const FILER_CIK = "the filer's CIK as cik (resolve it with secedgar_company_search)";
35
43
  /** Leads an archive miss's hint when SEC could not answer a lookup of the filing's filers (#215). */
36
44
  const FILER_LOOKUP_UNAVAILABLE = 'The filer lookup for this accession number was unavailable, so some directories that may hold the filing were not searched.';
37
45
  const documentEntrySchema = z
38
46
  .object({
39
- name: z.string().describe('Document filename within the filing archive.'),
47
+ name: z.string().describe('Filename in the filing archive.'),
40
48
  type: z
41
49
  .string()
42
- .describe('SEC document type (e.g., "10-K", "EX-21.1", "GRAPHIC"), or without a submission header a filename-inferred label ("exhibit", "PDF", "unknown").'),
50
+ .describe('SEC type ("10-K", "EX-21.1", "GRAPHIC"); with no submission header, a filename label ("exhibit", "PDF", "unknown").'),
43
51
  description: z
44
52
  .string()
45
53
  .optional()
46
- .describe('SEC description (e.g., "Subsidiaries of the Registrant"). Absent when none.'),
54
+ .describe('SEC description, e.g. "Subsidiaries of the Registrant".'),
47
55
  size: z.number().optional().describe('File size in bytes.'),
48
56
  binary: z
49
57
  .boolean()
50
58
  .optional()
51
59
  .describe('True for a binary entry (scan, PDF, archive, spreadsheet); absent otherwise.'),
52
60
  })
53
- .describe('One document entry from the filing.');
61
+ .describe('One filing document.');
54
62
  /** `content_limit`: a page holds at most 200,000 characters (#197). */
55
63
  const contentLimit = limitClamp({
56
64
  tool: 'secedgar_get_filing',
@@ -59,10 +67,10 @@ const contentLimit = limitClamp({
59
67
  cap: 200_000,
60
68
  bound: 1_000_000,
61
69
  shape: (n) => n.default(50000),
62
- description: 'Maximum characters of document text to return per page. 10-K filings can exceed 500,000 characters; S-1/A can exceed 1,000,000. Default 50,000 captures ~12,000 words (typically business overview, risk factors, and MD&A). Increase to 200,000 for full financial statements, or decrease for quick summaries. Use offset or section for subsequent pages.',
70
+ description: 'Maximum characters of document text to return per page. 10-K filings can exceed 500,000 characters; S-1/A can exceed 1,000,000. Default 50,000 captures ~12,000 words (typically business overview, risk factors, and MD&A). Increase to 200,000 for full financial statements, or decrease for quick summaries. Page on with offset; section and find open a page at a heading or a phrase.',
63
71
  });
64
72
  export const getFilingTool = tool('secedgar_get_filing', {
65
- description: "Fetch a specific filing's metadata and document content by accession number. Returns the primary document as readable text. Use offset/next_offset for multi-page access to large filings (10-K, S-1 can exceed 1M chars): pass the next_offset from a truncated response as offset, without section, to read the next page. Use section to jump directly to a heading (e.g. 'risk factors', 'item 7') without needing an offset.",
73
+ description: "Fetch a specific filing's metadata and document content by accession number. Returns the primary document as readable text. Use offset/next_offset for multi-page access to large filings (10-K, S-1 can exceed 1M chars): pass the next_offset from a truncated response as offset, without section or find, to read the next page. Use section to jump directly to a heading (e.g. 'risk factors', 'item 7') without needing an offset, or find to open the page at a phrase in the text (e.g. 'net revenue retention') and list where it occurs.",
66
74
  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
67
75
  // Agent-facing disclosure of the content window. `content_truncated` types the
68
76
  // fact on the wire; this carries how much of the document the page actually
@@ -71,7 +79,7 @@ export const getFilingTool = tool('secedgar_get_filing', {
71
79
  notice: z
72
80
  .string()
73
81
  .optional()
74
- .describe('How to read the next page, which file was read when the archive does not serve the indexed primary, when section landed on a document line rather than a detected heading, and how many headings were detected when the outline lists fewer.'),
82
+ .describe('How to read the next page or list more occurrences of find, which file was read when the archive does not serve the indexed primary, when section landed on a document line rather than a detected heading, and how many headings were detected when the outline lists fewer.'),
75
83
  truncated: z
76
84
  .boolean()
77
85
  .optional()
@@ -114,24 +122,15 @@ export const getFilingTool = tool('secedgar_get_filing', {
114
122
  reason: 'section_not_found',
115
123
  code: JsonRpcErrorCode.NotFound,
116
124
  when: 'The section string matched no detected heading and no line of the document',
117
- recovery: 'Pick a heading from the outline in the error message, pass a subheading exactly as the document prints it, or use offset paging instead.',
125
+ recovery: 'Pick a heading from the outline in the error message or pass a subheading exactly as the document prints it; pass a phrase that is not a heading as find, or page with offset.',
118
126
  },
119
127
  {
120
- reason: 'rate_limited',
121
- code: JsonRpcErrorCode.RateLimited,
122
- when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs",
123
- recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.',
124
- retryable: true,
125
- thrownBy: 'service',
126
- },
127
- {
128
- reason: 'sec_unreachable',
129
- code: JsonRpcErrorCode.ServiceUnavailable,
130
- when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent",
131
- recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.',
132
- retryable: true,
133
- thrownBy: 'service',
128
+ reason: 'phrase_not_found',
129
+ code: JsonRpcErrorCode.NotFound,
130
+ when: 'No occurrence of the find phrase starts at or after offset: the document does not contain it, or holds it only before offset',
131
+ recovery: 'Check the phrase against the document text, or pass a smaller offset to search from earlier in the document.',
134
132
  },
133
+ ...SEC_UPSTREAM_ERRORS,
135
134
  ],
136
135
  input: z.object({
137
136
  accession_number: z
@@ -157,12 +156,17 @@ export const getFilingTool = tool('secedgar_get_filing', {
157
156
  .int()
158
157
  .min(0)
159
158
  .default(0)
160
- .describe('Character offset into the extracted document text. Pass next_offset from a truncated response to continue reading the next page, and leave section out: section takes precedence over offset. Default 0 reads from the beginning.'),
159
+ .describe('Character offset into the extracted document text. Pass next_offset from a truncated response to continue reading the next page, and leave section and find out: section takes precedence over offset, and with find, offset is where the search starts. Default 0 reads from the beginning.'),
161
160
  section: z
162
161
  .string()
163
162
  .min(1)
164
163
  .optional()
165
- .describe("Jump to a named section, matched against every detected heading and the document's own lines (e.g. 'risk factors', 'item 7', 'item 2.02', 'certain relationships'). The first match wins, in this order: a heading equal to the value, or whose title after its Item/Part marker equals it; the first Item or Part heading containing it; a document line equal to it — a subheading the outline omits ('Liquidity and Capital Resources') — unless the line labels a table row; the first other heading containing it; a table-row label equal to it, else a document line starting with it. In a proxy statement (DEF 14A and its variants), whose ITEM headings are ballot proposals, the first heading of any kind containing the value comes before both document-line steps. Within each heading step a body heading wins over a table-of-contents row, which lands only when nothing else at that step matches. A line landing says so in the notice; table-of-contents rows and wrapped cross-references are never line landings. A leading 20-F sub-item label on a heading or line ('3D.', 'B.') is ignored, so 'risk factors' reaches '3D. RISK FACTORS'; the value itself is matched as given. A value ending in a number matches only that number: 'item 1' reaches Item 1 and Item 1A, never Items 10–16, and 'part i' never reaches Part II. Every step ignores case, whitespace, and quote style, so a heading copied from the outline resolves whether it carries the filing's non-breaking spaces and curly quotes or plain ones; the steps comparing a whole heading or line (equal to, starting with) also ignore the punctuation between an Item or Part marker and its title, so 'Item 1A Risk Factors' reaches 'Item 1A. – Risk Factors'. Takes precedence over offset when both are provided, so leave it out when paging on with next_offset. On a miss, the error message includes the detected outline so you can pick the correct heading."),
164
+ .describe("Jump to a named section, matched against every detected heading and the document's own lines (e.g. 'risk factors', 'item 7', 'item 2.02', 'certain relationships'). The first match wins, in this order: a heading equal to the value, or whose title after its Item/Part marker equals it; the first Item or Part heading containing it; a document line equal to it — a subheading the outline omits ('Liquidity and Capital Resources') — unless the line labels a table row; the first other heading containing it; a table-row label equal to it, else a document line starting with it. In a proxy statement (DEF 14A and its variants), whose ITEM headings are ballot proposals, the first heading of any kind containing the value comes before both document-line steps. Within each heading step a body heading wins over a table-of-contents row, which lands only when nothing else at that step matches; a table-of-contents row that links to its section lands on that section. A line landing says so in the notice; table-of-contents rows and wrapped cross-references are never line landings. A leading 20-F sub-item label on a heading or line ('3D.', 'B.') is ignored, so 'risk factors' reaches '3D. RISK FACTORS'; the value itself is matched as given. A value ending in a number matches only that number: 'item 1' reaches Item 1 and Item 1A, never Items 10–16, and 'part i' never reaches Part II. Every step ignores case, whitespace, and quote style, so a heading copied from the outline resolves whether it carries the filing's non-breaking spaces and curly quotes or plain ones; the steps comparing a whole heading or line (equal to, starting with) also ignore the punctuation between an Item or Part marker and its title, so 'Item 1A Risk Factors' reaches 'Item 1A. – Risk Factors'. For a phrase in the text that is not a heading, use find. Takes precedence over find and offset, so leave it out when paging on with next_offset. On a miss, the error message includes the detected outline so you can pick the correct heading."),
165
+ find: z
166
+ .string()
167
+ .max(MAX_FIND_CHARS)
168
+ .optional()
169
+ .describe("Open the page at a phrase in the document's text (e.g. 'net revenue retention') and list where it occurs. Matched as a substring, ignoring case, whitespace runs, and quote style, so a phrase broken across a line matches; no patterns or whole-word matching. The page opens at the first occurrence at or after offset — at its line's start when that is at most 200 characters earlier, else at the first word starting within those 200 — and occurrences lists up to 20 from there with context, occurrences_total counting the whole document. Blank reads as omitted. With find, offset is where the search starts, so leave find out when paging on with next_offset; section takes precedence over find."),
166
170
  }),
167
171
  output: z.object({
168
172
  accession_number: z.string().describe('Filing accession number, normalized to dash format.'),
@@ -213,7 +217,7 @@ export const getFilingTool = tool('secedgar_get_filing', {
213
217
  next_offset: z
214
218
  .number()
215
219
  .optional()
216
- .describe('Offset of the next page, to pass as offset without section; present while content_truncated is true.'),
220
+ .describe('Offset of the next page, to pass as offset without section or find; present while content_truncated is true.'),
217
221
  outline: z
218
222
  .array(z
219
223
  .object({
@@ -224,7 +228,22 @@ export const getFilingTool = tool('secedgar_get_filing', {
224
228
  })
225
229
  .describe('One detected heading with its offset.'))
226
230
  .optional()
227
- .describe('Up to 50 detected headings, on the first page of a truncated response (offset=0, no section). Past 50, Item and Part headings come first (bare TOC copies of titled ones dropped), then the earliest others; the notice gives the detected count. Pass a heading offset as offset, or its text as section.'),
231
+ .describe('Up to 50 detected headings on a truncated first page (offset=0, no section or find). Past 50: Item and Part headings first (bare TOC copies of titled ones dropped), then the earliest; the notice gives the count. Pass text as section (a linked TOC row lands on its section) or offset as offset.'),
232
+ occurrences: z
233
+ .array(z
234
+ .object({
235
+ offset: z.number().describe('Character offset where the occurrence starts.'),
236
+ context: z
237
+ .string()
238
+ .describe('The match and up to 40 characters either side, whitespace runs as one space.'),
239
+ })
240
+ .describe('One occurrence of find.'))
241
+ .optional()
242
+ .describe('With find: up to 20 occurrences, from the one the page opens at.'),
243
+ occurrences_total: z
244
+ .number()
245
+ .optional()
246
+ .describe('With find: occurrences in the whole document.'),
228
247
  filing_url: z.string().describe('Direct URL to the filing on SEC.gov.'),
229
248
  }),
230
249
  async handler(input, ctx) {
@@ -235,11 +254,14 @@ export const getFilingTool = tool('secedgar_get_filing', {
235
254
  // A blank `document` reads as omitted (#203): no archive file has a blank name,
236
255
  // and requesting one fetches SEC's directory listing page instead.
237
256
  const document = input.document?.trim() ? input.document : undefined;
257
+ // A blank `find` reads as omitted too (#238), the way a form client sends an unset field.
258
+ const find = input.find?.trim() ? input.find : undefined;
238
259
  const documentKey = document ?? PRIMARY_SENTINEL;
239
260
  const cacheKey = `${accn}:${documentKey}`;
240
261
  // If we have a cache hit, skip the document fetch entirely.
241
262
  const cached = getExtractCache(cacheKey);
242
263
  let fullText;
264
+ let links;
243
265
  let resolvedCik;
244
266
  let index;
245
267
  let targetName;
@@ -343,8 +365,14 @@ export const getFilingTool = tool('secedgar_get_filing', {
343
365
  filingPrimaryName = resolved.filingPrimaryName;
344
366
  unservedPrimary = resolved.unservedPrimary;
345
367
  records = resolved.records;
346
- fullText = filingToExtract(resolved.html);
347
- const extract = { text: fullText, document: targetName, cik: resolvedCik };
368
+ links = [];
369
+ fullText = filingToExtract(resolved.html, links);
370
+ const extract = {
371
+ text: fullText,
372
+ links,
373
+ document: targetName,
374
+ cik: resolvedCik,
375
+ };
348
376
  setExtractCache(cacheKey, extract);
349
377
  }
350
378
  else {
@@ -363,6 +391,7 @@ export const getFilingTool = tool('secedgar_get_filing', {
363
391
  index = metaResolved.index;
364
392
  records = metaResolved.records;
365
393
  fullText = cached.text;
394
+ links = cached.links;
366
395
  targetName = cached.document;
367
396
  filingPrimaryName = metaResolved.filingPrimaryName;
368
397
  // A primary read cached from the full submission keeps reporting it (#158).
@@ -387,9 +416,12 @@ export const getFilingTool = tool('secedgar_get_filing', {
387
416
  const form = idx >= 0 ? recent.form[idx] : header?.form;
388
417
  const filingDate = idx >= 0 ? recent.filingDate[idx] : header?.filingDate;
389
418
  const periodEnding = idx >= 0 ? recent.reportDate[idx] : header?.periodOfReport;
390
- // Determine effective offset (section wins over raw offset)
419
+ // Where the page starts: section, else find, else offset. Under find, offset
420
+ // is where the search starts (#238).
391
421
  let effectiveOffset = input.offset ?? 0;
392
422
  let lineNotice;
423
+ let phrase;
424
+ let findNotice;
393
425
  if (input.section) {
394
426
  // Every detected heading is a candidate; the 50-entry cap is the
395
427
  // rendered outline's alone (#169).
@@ -402,7 +434,7 @@ export const getFilingTool = tool('secedgar_get_filing', {
402
434
  ? undefined
403
435
  : resolveSection(fullText, headings, input.section, PROXY_FORM_RE.test(form ?? ''));
404
436
  // The notices are authored Markdown, so the caller's section text is escaped.
405
- const sectionText = escapeInline(input.section);
437
+ const sectionText = escapeMarkdownInline(input.section);
406
438
  if (landing?.source === 'line') {
407
439
  lineNotice = `No detected heading matches section '${sectionText}', so this page starts at the first document line that does.`;
408
440
  }
@@ -418,8 +450,8 @@ export const getFilingTool = tool('secedgar_get_filing', {
418
450
  : 'Outline:';
419
451
  const outlineBlock = outline.length > 0 ? `\n\n${outlineLabel}\n${renderOutline(outline)}` : '';
420
452
  const hint = headings.length > 0
421
- ? 'Pick a heading from the outline above and pass it as section; a subheading the outline omits matches when passed exactly as the document prints it.'
422
- : 'No headings were detected in this document — use offset paging instead.';
453
+ ? 'Pick a heading from the outline above and pass it as section; a subheading the outline omits matches when passed exactly as the document prints it. For a phrase that is not a heading, pass it as find instead.'
454
+ : 'No headings were detected in this document — pass a phrase as find to locate it in the text, or use offset paging.';
423
455
  const problem = blank
424
456
  ? `Section is blank: ${describeBlankSection(input.section)}, leaving nothing to match.`
425
457
  : `Section '${input.section}' not found in this document.`;
@@ -429,7 +461,46 @@ export const getFilingTool = tool('secedgar_get_filing', {
429
461
  recovery: { hint },
430
462
  });
431
463
  }
432
- effectiveOffset = landing.offset;
464
+ // A table-of-contents row that links forward lands on its section (#239).
465
+ effectiveOffset =
466
+ (landing.source === 'heading'
467
+ ? linkedSectionStart(fullText, landing.heading, links)
468
+ : undefined) ?? landing.offset;
469
+ }
470
+ else if (find) {
471
+ const matches = findPhrase(fullText, find, input.offset, MAX_LISTED_OCCURRENCES);
472
+ const first = matches.listed[0];
473
+ if (first === undefined) {
474
+ // Each rule's hint names only that rule: absent from the document, or present only before offset.
475
+ const [problem, hint] = matches.total === 0
476
+ ? [
477
+ `Phrase '${find}' does not occur in this document.`,
478
+ 'Check the spelling, or pass a shorter part of the phrase: find ignores case, whitespace runs, and quote style, and matches every other character as given.',
479
+ ]
480
+ : [
481
+ `Phrase '${find}' does not occur at or after offset ${input.offset}; ${matches.before === 1 ? 'its one occurrence comes' : `all ${matches.before} occurrences come`} before it.`,
482
+ 'Pass a smaller offset, or leave offset out, to search from the start of the document.',
483
+ ];
484
+ throw ctx.fail('phrase_not_found', problem, {
485
+ find,
486
+ offset: input.offset,
487
+ occurrences_before: matches.before,
488
+ recovery: { hint },
489
+ });
490
+ }
491
+ effectiveOffset = findPageStart(fullText, first.offset);
492
+ phrase = {
493
+ occurrences: matches.listed.map((o) => ({
494
+ offset: o.offset,
495
+ context: occurrenceContext(fullText, o),
496
+ })),
497
+ total: matches.total,
498
+ };
499
+ const atOrAfter = matches.total - matches.before;
500
+ const last = matches.listed[matches.listed.length - 1] ?? first;
501
+ if (atOrAfter > matches.listed.length) {
502
+ findNotice = `${matches.listed.length} of the ${atOrAfter} occurrences at or after offset ${input.offset} are listed; to list the next ones, pass the same find with offset ${last.end}.`;
503
+ }
433
504
  }
434
505
  // Validate offset
435
506
  if (effectiveOffset >= fullText.length && fullText.length > 0) {
@@ -439,32 +510,37 @@ export const getFilingTool = tool('secedgar_get_filing', {
439
510
  });
440
511
  }
441
512
  const { text, truncated, totalLength, nextOffset } = windowText(fullText, effectiveOffset, pageLimit);
442
- // Emit outline on first-page truncated responses (not on subsequent pages or section jumps)
443
- const shouldEmitOutline = truncated && effectiveOffset === 0 && !input.section;
513
+ // Emit outline on first-page truncated responses (not on subsequent pages, section jumps, or find pages)
514
+ const shouldEmitOutline = truncated && effectiveOffset === 0 && !input.section && !find;
444
515
  const detected = shouldEmitOutline ? detectHeadings(fullText) : undefined;
445
516
  const outline = detected && selectOutline(detected);
446
517
  // `notice` is last-wins across notice/truncated, so the fallback disclosure,
447
- // the line-landing note, and the outline cut ride inside the truncation
448
- // guidance. The outline is emitted only on a truncated page, so the cut
449
- // always has guidance to join.
518
+ // the line-landing note, the find continuation, and the outline cut ride
519
+ // inside the truncation guidance. The outline is emitted only on a truncated
520
+ // page, so the cut always has guidance to join.
450
521
  const fallbackNotice = unservedPrimary
451
- ? `The filing index names ${escapeInline(unservedPrimary)} as the primary document, but the SEC archive does not serve it, so this text is the full submission file ${escapeInline(targetName)}.`
522
+ ? `The filing index names ${escapeMarkdownInline(unservedPrimary)} as the primary document, but the SEC archive does not serve it, so this text is the full submission file ${escapeMarkdownInline(targetName)}.`
452
523
  : undefined;
453
524
  if (truncated) {
454
- // section outranks offset, so a caller who keeps it reads this page again.
525
+ // section outranks offset, so a caller who keeps it reads this page again;
526
+ // one who keeps find searches on from next_offset instead of reading it.
455
527
  const nextPage = input.section
456
528
  ? 'as offset without section to read the next page — section takes precedence over offset.'
457
- : 'as offset to read the next page, or jump with section.';
529
+ : find
530
+ ? 'as offset without find to read the next page — with find, offset is where the search starts.'
531
+ : 'as offset to read the next page, or jump with section.';
458
532
  const paging = `Showing ${text.length} of ${totalLength} characters. Pass next_offset (${nextOffset ?? '?'}) ${nextPage}`;
459
533
  const outlineCut = detected && outline && outlineCutNote(outline, detected);
460
534
  ctx.enrich.truncated({
461
535
  shown: text.length,
462
536
  cap: pageLimit,
463
- guidance: [fallbackNotice, lineNotice, paging, outlineCut].filter(Boolean).join(' '),
537
+ guidance: [fallbackNotice, lineNotice, findNotice, paging, outlineCut]
538
+ .filter(Boolean)
539
+ .join(' '),
464
540
  });
465
541
  }
466
- else if (fallbackNotice || lineNotice) {
467
- ctx.enrich.notice([fallbackNotice, lineNotice].filter(Boolean).join(' '));
542
+ else if (fallbackNotice || lineNotice || findNotice) {
543
+ ctx.enrich.notice([fallbackNotice, lineNotice, findNotice].filter(Boolean).join(' '));
468
544
  }
469
545
  // Headers give canonical document types; without them categorization falls
470
546
  // back to name-pattern inference.
@@ -502,18 +578,22 @@ export const getFilingTool = tool('secedgar_get_filing', {
502
578
  content_total_length: totalLength,
503
579
  next_offset: nextOffset,
504
580
  outline,
581
+ occurrences: phrase?.occurrences,
582
+ occurrences_total: phrase?.total,
505
583
  filing_url: filingArchiveUrl(resolvedCik, accn, targetName),
506
584
  };
507
585
  },
508
586
  format: (result) => {
509
587
  const formLabel = result.form ?? 'Filing';
510
588
  // SEC's name, the filer's headings, and document descriptions render through
511
- // escapeInline, so content[] reads back the structuredContent value (#221).
589
+ // escapeMarkdownInline, so content[] reads back the structuredContent value (#221).
512
590
  // The body between the sentinels (#69) is a fenced block sized past its own
513
591
  // backtick runs instead (#226): it reads back the same and keeps its column
514
592
  // layout, where escaping writes each leading space and tab as a character
515
593
  // reference and a rendered paragraph collapses whitespace runs.
516
- const entity = result.company_name ? escapeInline(result.company_name) : 'Unknown entity';
594
+ const entity = result.company_name
595
+ ? escapeMarkdownInline(result.company_name)
596
+ : 'Unknown entity';
517
597
  const header = `**${formLabel}** — ${entity} (CIK ${result.cik})`;
518
598
  const filedPart = result.filing_date ? `Filed: ${result.filing_date}` : 'Filed: Unknown';
519
599
  const periodPart = result.period_ending ? ` | Period: ${result.period_ending}` : '';
@@ -528,15 +608,22 @@ export const getFilingTool = tool('secedgar_get_filing', {
528
608
  const docs = formatDocumentSection(result.documents);
529
609
  const outline = result.outline?.map((h) => ({
530
610
  ...h,
531
- heading: escapeInline(h.heading),
611
+ heading: escapeMarkdownInline(h.heading),
532
612
  }));
533
613
  const outlineText = outline?.length ? `\n\nOutline:\n${renderOutline(outline)}` : '';
614
+ // Each context is SEC text after an authored `[offset] ` label, so it renders
615
+ // escaped and reads back as the structuredContent value (#238).
616
+ const occurrencesText = result.occurrences
617
+ ? `\n\nOccurrences (${result.occurrences_total} in the document):\n${result.occurrences
618
+ .map((o) => ` [${o.offset}] ${escapeMarkdownInline(o.context)}`)
619
+ .join('\n')}`
620
+ : '';
534
621
  const url = `\nURL: ${result.filing_url}`;
535
622
  const body = markdown().codeBlock(result.content, 'text').build();
536
623
  return [
537
624
  {
538
625
  type: 'text',
539
- text: `${header}\n${dateLine}\n${meta}${docs}${outlineText}${url}\n\n${FILING_CONTENT_BEGIN}\n${body}\n${FILING_CONTENT_END}`,
626
+ text: `${header}\n${dateLine}\n${meta}${docs}${outlineText}${occurrencesText}${url}\n\n${FILING_CONTENT_BEGIN}\n${body}\n${FILING_CONTENT_END}`,
540
627
  },
541
628
  ];
542
629
  },
@@ -689,31 +776,77 @@ function resolveSection(text, headings, section, proxy) {
689
776
  const labelled = [key, title].some((k) => k !== undefined && withoutSubItemLabel(k) === exactNeedle);
690
777
  return labelled ? 1 : undefined;
691
778
  });
779
+ const onHeading = (heading) => ({
780
+ heading,
781
+ offset: heading.offset,
782
+ source: 'heading',
783
+ });
692
784
  if (exact)
693
- return { offset: exact.offset, source: 'heading' };
785
+ return onHeading(exact);
694
786
  const needle = foldForSectionMatch(section);
695
787
  const contains = (h) => sectionMatches(foldForSectionMatch(h.heading), needle);
696
788
  if (proxy) {
697
789
  const heading = first(contains);
698
790
  if (heading)
699
- return { offset: heading.offset, source: 'heading' };
791
+ return onHeading(heading);
700
792
  const line = matchSectionLine(text, section);
701
793
  return line ? { offset: line.offset, source: 'line' } : undefined;
702
794
  }
703
795
  const itemOrPart = first((h) => isStructuralHeading(h) && contains(h));
704
796
  if (itemOrPart)
705
- return { offset: itemOrPart.offset, source: 'heading' };
797
+ return onHeading(itemOrPart);
706
798
  const line = matchSectionLine(text, section);
707
799
  // Tier 2 missed, so any heading containing the value is a non-Item one.
708
800
  const other = first(contains);
709
801
  if (line?.equal)
710
802
  return { offset: line.offset, source: other ? 'line-over-heading' : 'line' };
711
803
  if (other)
712
- return { offset: other.offset, source: 'heading' };
804
+ return onHeading(other);
713
805
  if (line)
714
806
  return { offset: line.offset, source: 'line' };
715
807
  return;
716
808
  }
809
+ /** Whether the character at `at` is whitespace as `\s` reads it; false past either end. */
810
+ function isSpaceAt(text, at) {
811
+ return /\s/.test(text.charAt(at));
812
+ }
813
+ /**
814
+ * Where a `find` page opens for an occurrence at `at` (#238): the start of the
815
+ * occurrence's line when that is at most {@link FIND_PAGE_LEAD_CHARS} characters
816
+ * earlier, else the first word starting within those characters, else the
817
+ * occurrence itself. Reads at most that many characters back.
818
+ */
819
+ function findPageStart(text, at) {
820
+ const floor = Math.max(0, at - FIND_PAGE_LEAD_CHARS);
821
+ const newline = text.slice(floor, at).lastIndexOf('\n');
822
+ if (newline !== -1)
823
+ return floor + newline + 1;
824
+ if (floor === 0 || text.charAt(floor - 1) === '\n')
825
+ return floor;
826
+ for (let i = floor; i < at; i++) {
827
+ if (isSpaceAt(text, i - 1) && !isSpaceAt(text, i))
828
+ return i;
829
+ }
830
+ return at;
831
+ }
832
+ /**
833
+ * An occurrence's `context`: the match and up to {@link OCCURRENCE_CONTEXT_CHARS}
834
+ * characters of document text on each side, each whitespace run shown as one
835
+ * space. An edge never splits a surrogate pair.
836
+ */
837
+ function occurrenceContext(text, { offset, end }) {
838
+ let start = Math.max(0, offset - OCCURRENCE_CONTEXT_CHARS);
839
+ let stop = Math.min(text.length, end + OCCURRENCE_CONTEXT_CHARS);
840
+ if (start > 0 && isLowSurrogate(text.charCodeAt(start)))
841
+ start++;
842
+ if (stop < text.length && isLowSurrogate(text.charCodeAt(stop)))
843
+ stop--;
844
+ return text.slice(start, stop).replace(/\s+/g, ' ');
845
+ }
846
+ /** Whether a code unit is the second half of a surrogate pair. */
847
+ function isLowSurrogate(code) {
848
+ return code >= 0xdc00 && code <= 0xdfff;
849
+ }
717
850
  /**
718
851
  * A blank `section` described by its length and the code points it holds, each
719
852
  * named once in order of first appearance ("its 2 characters are all whitespace
@@ -1096,9 +1229,10 @@ function accessionPrefixCik(accessionNumber) {
1096
1229
  }
1097
1230
  /**
1098
1231
  * Run an optional SEC lookup, answering `undefined` when SEC is unavailable for it:
1099
- * no response or an unreadable body (`sec_unreachable`), a 5xx, or a full-text
1100
- * search backend failure or refusal (`efts_degraded_response`), all
1101
- * `ServiceUnavailable`, or a 504, which maps to `Timeout`. Everything else is
1232
+ * no response or an unreadable body (`sec_unreachable`), a 500, 502, 503, or 504
1233
+ * once its retries are spent (`sec_unavailable`, #233), or a full-text search
1234
+ * backend failure or refusal (`efts_degraded_response`), all
1235
+ * `ServiceUnavailable`, or a 408 or 425, which map to `Timeout`. Everything else is
1102
1236
  * rethrown untouched — the caller's cancellation, a rate-limit refusal (SEC's block
1103
1237
  * covers every request the call would send next), and any other failure that says
1104
1238
  * the request itself is wrong.
@@ -1401,7 +1535,7 @@ function formatDocList(entries) {
1401
1535
  d.type,
1402
1536
  d.binary ? 'binary' : null,
1403
1537
  d.size !== undefined ? `${d.size}B` : null,
1404
- d.description ? `"${escapeInline(d.description)}"` : null,
1538
+ d.description ? `"${escapeMarkdownInline(d.description)}"` : null,
1405
1539
  ]
1406
1540
  .filter(Boolean)
1407
1541
  .join(', ');