@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.
- package/AGENTS.md +36 -24
- package/CLAUDE.md +36 -24
- package/README.md +16 -12
- package/changelog/0.19.x/0.19.0.md +47 -0
- package/changelog/0.19.x/0.19.1.md +35 -0
- package/changelog/template.md +10 -3
- package/dist/config/server-config.js +2 -2
- package/dist/config/server-config.js.map +1 -1
- package/dist/index.js +27 -9
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/tools/dataset-schema.d.ts +14 -0
- package/dist/mcp-server/tools/dataset-schema.d.ts.map +1 -0
- package/dist/mcp-server/tools/dataset-schema.js +16 -0
- package/dist/mcp-server/tools/dataset-schema.js.map +1 -0
- package/dist/mcp-server/tools/definitions/company-search.tool.d.ts +44 -14
- package/dist/mcp-server/tools/definitions/company-search.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/company-search.tool.js +197 -62
- package/dist/mcp-server/tools/definitions/company-search.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts +26 -12
- package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/compare-companies.tool.js +41 -39
- package/dist/mcp-server/tools/definitions/compare-companies.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts +12 -3
- package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js +23 -9
- package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js +2 -2
- package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts +16 -16
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.js +17 -17
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts +26 -12
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.js +15 -37
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts +36 -20
- package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/find-holders.tool.js +26 -41
- package/dist/mcp-server/tools/definitions/find-holders.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts +28 -12
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js +30 -44
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts +50 -14
- package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-filing.tool.js +193 -59
- package/dist/mcp-server/tools/definitions/get-filing.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-financials.tool.d.ts +14 -6
- package/dist/mcp-server/tools/definitions/get-financials.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-financials.tool.js +38 -41
- package/dist/mcp-server/tools/definitions/get-financials.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts +28 -12
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js +22 -35
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts +28 -12
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js +22 -31
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts +36 -20
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js +22 -39
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts +28 -12
- package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-material-events.tool.js +23 -32
- package/dist/mcp-server/tools/definitions/get-material-events.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-snapshot.tool.d.ts +16 -7
- package/dist/mcp-server/tools/definitions/get-snapshot.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-snapshot.tool.js +24 -32
- package/dist/mcp-server/tools/definitions/get-snapshot.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +232 -101
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-concepts.tool.js +3 -3
- package/dist/mcp-server/tools/definitions/search-concepts.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts +46 -20
- package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-filings.tool.js +126 -68
- package/dist/mcp-server/tools/definitions/search-filings.tool.js.map +1 -1
- package/dist/mcp-server/tools/resolved-as.d.ts +10 -0
- package/dist/mcp-server/tools/resolved-as.d.ts.map +1 -0
- package/dist/mcp-server/tools/resolved-as.js +13 -0
- package/dist/mcp-server/tools/resolved-as.js.map +1 -0
- package/dist/mcp-server/tools/sec-upstream-errors.d.ts +44 -0
- package/dist/mcp-server/tools/sec-upstream-errors.d.ts.map +1 -0
- package/dist/mcp-server/tools/sec-upstream-errors.js +48 -0
- package/dist/mcp-server/tools/sec-upstream-errors.js.map +1 -0
- package/dist/services/canvas-bridge/canvas-bridge.d.ts +98 -45
- package/dist/services/canvas-bridge/canvas-bridge.d.ts.map +1 -1
- package/dist/services/canvas-bridge/canvas-bridge.js +137 -126
- package/dist/services/canvas-bridge/canvas-bridge.js.map +1 -1
- package/dist/services/canvas-bridge/sql-gate-extras.d.ts +4 -17
- package/dist/services/canvas-bridge/sql-gate-extras.d.ts.map +1 -1
- package/dist/services/canvas-bridge/sql-gate-extras.js +4 -22
- package/dist/services/canvas-bridge/sql-gate-extras.js.map +1 -1
- package/dist/services/edgar/concept-map.d.ts +10 -6
- package/dist/services/edgar/concept-map.d.ts.map +1 -1
- package/dist/services/edgar/concept-map.js +90 -22
- package/dist/services/edgar/concept-map.js.map +1 -1
- package/dist/services/edgar/data/former-tickers.json +24159 -0
- package/dist/services/edgar/edgar-api-service.d.ts +250 -62
- package/dist/services/edgar/edgar-api-service.d.ts.map +1 -1
- package/dist/services/edgar/edgar-api-service.js +808 -189
- package/dist/services/edgar/edgar-api-service.js.map +1 -1
- package/dist/services/edgar/filing-to-text.d.ts +71 -2
- package/dist/services/edgar/filing-to-text.d.ts.map +1 -1
- package/dist/services/edgar/filing-to-text.js +533 -5
- package/dist/services/edgar/filing-to-text.js.map +1 -1
- package/dist/services/edgar/former-tickers.d.ts +47 -0
- package/dist/services/edgar/former-tickers.d.ts.map +1 -0
- package/dist/services/edgar/former-tickers.js +77 -0
- package/dist/services/edgar/former-tickers.js.map +1 -0
- package/dist/services/edgar/listing-codes.d.ts +47 -0
- package/dist/services/edgar/listing-codes.d.ts.map +1 -0
- package/dist/services/edgar/listing-codes.js +110 -0
- package/dist/services/edgar/listing-codes.js.map +1 -0
- package/dist/services/edgar/mirror/edgar-mirror.d.ts +11 -1
- package/dist/services/edgar/mirror/edgar-mirror.d.ts.map +1 -1
- package/dist/services/edgar/mirror/edgar-mirror.js +19 -1
- package/dist/services/edgar/mirror/edgar-mirror.js.map +1 -1
- package/dist/services/edgar/mirror/tickers-sync.d.ts.map +1 -1
- package/dist/services/edgar/mirror/tickers-sync.js +1 -3
- package/dist/services/edgar/mirror/tickers-sync.js.map +1 -1
- package/dist/services/edgar/mirror/types.d.ts +3 -1
- package/dist/services/edgar/mirror/types.d.ts.map +1 -1
- package/dist/services/edgar/mirror/types.js +3 -1
- package/dist/services/edgar/mirror/types.js.map +1 -1
- package/dist/services/edgar/trigram-similarity.d.ts +5 -3
- package/dist/services/edgar/trigram-similarity.d.ts.map +1 -1
- package/dist/services/edgar/trigram-similarity.js +18 -17
- package/dist/services/edgar/trigram-similarity.js.map +1 -1
- package/dist/services/edgar/types.d.ts +20 -7
- package/dist/services/edgar/types.d.ts.map +1 -1
- package/package.json +6 -5
- package/server.json +3 -3
- package/skills/secedgar-guide/SKILL.md +3 -3
- package/dist/mcp-server/tools/escape-inline.d.ts +0 -35
- package/dist/mcp-server/tools/escape-inline.d.ts.map +0 -1
- package/dist/mcp-server/tools/escape-inline.js +0 -51
- 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
|
|
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:
|
|
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:
|
|
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:
|
|
111
|
+
readonly thrownBy: 'service';
|
|
101
112
|
}, {
|
|
102
|
-
readonly reason:
|
|
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:
|
|
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:
|
|
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
|
|
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:
|
|
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:
|
|
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:
|
|
236
|
+
readonly thrownBy: 'service';
|
|
208
237
|
}, {
|
|
209
|
-
readonly reason:
|
|
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:
|
|
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:
|
|
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;
|
|
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('
|
|
47
|
+
name: z.string().describe('Filename in the filing archive.'),
|
|
40
48
|
type: z
|
|
41
49
|
.string()
|
|
42
|
-
.describe('SEC
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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: '
|
|
121
|
-
code: JsonRpcErrorCode.
|
|
122
|
-
when:
|
|
123
|
-
recovery: '
|
|
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
|
|
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
|
|
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
|
-
|
|
347
|
-
|
|
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
|
-
//
|
|
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 =
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
448
|
-
// guidance. The outline is emitted only on a truncated
|
|
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 ${
|
|
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
|
-
:
|
|
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]
|
|
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
|
-
//
|
|
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
|
|
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:
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
1100
|
-
*
|
|
1101
|
-
*
|
|
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 ? `"${
|
|
1538
|
+
d.description ? `"${escapeMarkdownInline(d.description)}"` : null,
|
|
1405
1539
|
]
|
|
1406
1540
|
.filter(Boolean)
|
|
1407
1541
|
.join(', ');
|