file_hosting capability, and is exposed both as a workflow graph node and as an agent tool. Every procedure moves bulk data as files, so no agent has to hold a full record set in its context window.
All four are idempotent: re-invoking one is safe. Workflow
router nodes can branch on their error codes; INVALID_INPUT is almost always an authoring bug upstream and should fail fast rather than retry.
Typical composition
A monthly engineering report chains the procedures with agents only where judgment is needed:file and writes its output as a file. Token cost stays proportional to the records an agent actually needs to see, not the total count.
core-parse-csv
core-parse-csv reads a CSV file, validates each row against a typed schema, and returns either inline records (up to 1,000 rows) or a file of records (above 1,000 rows).
Inputs
Each
schema value is a { type, required? } descriptor:
required defaults to false. Columns in the CSV but absent from schema are dropped: schema is the authoritative list of fields that flow downstream.
Outputs
The output shape depends on the parsed row count. Inline branch (1,000 records or fewer):recordsFile is a JSON array of the same record shape. Inline records flow through workflow state and are cheap to consume; above about 1,000 records the payload would dominate the run’s state, so the procedure switches to a file and the consumer that needs the data reads it.
Row errors
errors[] is always present. Each entry describes one row-level validation failure:
rowNumberis 1-indexed and counts the header as row 1, so the first data row is row 2.- An empty
fieldmeans a row-level failure, such as a required column missing from the header. - Parsing continues past row errors; a bad row does not abort the run. Structural corruption, such as an embedded NUL byte, is a terminal
INVALID_INPUT. errors[]is capped at 1,000 entries. When the cap is hit, the last entry is a sentinel withrowNumber: -1, for example"additional 49000 validation error(s) omitted (cap=1000)".
Error codes
Row validation failures never raise; they accumulate in
errors[].
Example
records or recordsFile through the workflow’s binding layer.
core-filter-by-date-range
core-filter-by-date-range reads a JSON array of records and keeps the ones whose date field falls inside a closed [from, to] interval. Use it between a paginated source (Linear issues, Asana tasks, GitHub pull requests) and a step that only cares about one period.
Inputs
Outputs
Record order is preserved; the procedure filters, it does not sort.
Skipped and filtered records
A record is skipped (counted inskippedCount) when it is not a JSON object, lacks the dateField key, or holds a value that is not a parseable ISO 8601 string. A record is filtered out (counted in neither) when its date is well-formed but outside the range. The input count minus matchedCount + skippedCount is the number of well-formed, out-of-range records.
Time zones
Dates and bounds are parsed as ISO 8601 and normalized to UTC before comparison:- A date such as
2026-04-15is midnight UTC. - A naive datetime such as
2026-04-15T12:00:00is UTC. - An aware datetime such as
2026-04-15T08:00:00-04:00keeps its offset.
Size and determinism
The procedure loads the whole input into memory; there is no streaming path. The input, the decoded array and the serialized output must fit in 512 MB together, and the run must finish in 60 seconds. For larger inputs, split upstream. The filter is linear in record count. Identical inputs produce byte-identical output: order is preserved, JSON is serialized without whitespace and without sorting keys, and the procedure reads no clock, random seed or network state. That makes it safe for runs that need replay equivalence, such as evals.Error codes
Example
Keep only the Linear issues completed in April 2026:paginate.ticketsFile to a fileId before it starts the filter sandbox.
core-build-xlsx-workbook
core-build-xlsx-workbook builds an .xlsx workbook from a JSON file of sheets. Use it whenever a downstream consumer — a report email, a Slack post, a human reviewer — needs a spreadsheet instead of inline records. It builds the workbook entirely in the sandbox, so compute time is its only cost.
Inputs
The procedure takes one input,sheetsFile: the file ID of a JSON file that holds the ordered list
of sheets. Write the file with file_put (or take it from an upstream step) and pass its ID.
name: 1 to 31 characters, none of\ / ? * [ ] :, unique across the array.columns: the ordered header row.rows: records keyed by header name.
\ / ? * [ ] : in worksheet names and caps them at 31 characters. The procedure rejects a violating name with INVALID_INPUT rather than truncating it. Names are unique case-insensitively, as in Excel: Issues and ISSUES collide.
Columns and rows. Cells are written in columns order. Row keys not listed in columns are dropped, and missing keys produce empty cells: columns is the schema and rows is the data.
Output
workbookFile. Downstream nodes (publish, email, chat attachment) reference its fileId; no raw bytes flow through workflow state.
Formula injection prevention
A cell whose first character is=, +, -, @, or a leading tab, carriage return or line feed is treated as a formula by Excel, Google Sheets and LibreOffice when the cell type is unspecified. A malicious upstream value such as =HYPERLINK(...) can exfiltrate data, and in older Excel builds a crafted value can run a command when the file opens.
The CSV mitigation — prepending an apostrophe — does not work for XLSX: the apostrophe is written verbatim and shows up in the cell, corrupting values like phone numbers (-555-1234) and @username handles. Instead, the procedure forces every cell that starts with a dangerous prefix to the text type. Excel, Google Sheets and LibreOffice all render it as literal text, and the value is preserved exactly. Numbers, booleans, empty values and dates pass through unchanged, because they cannot be interpreted as formulas.
This addresses the threat model in the OWASP CSV Injection guidance, with the XLSX-specific mitigation.
Column widths
Columns are sized to their longest displayed value, capped at 50 characters so one long cell does not stretch a column across the screen. If you need wider columns, split the field or post-process the file.Example: workflow node
INVALID_INPUT branch.
Example: agent tool
Any agent whose permissions grantfile_hosting and include this procedure can call it as a tool with a sheetsFile file ID. It returns a fileId the agent can pass to a publish or attachment tool:
Error codes
linear-paginate-issues
linear-paginate-issues pages through every team in a Linear workspace and keeps the issues whose date field falls in one calendar month, with no agent in the loop. An agent driving pagination itself can exhaust its step budget and stop early; this procedure keeps going until Linear says there are no more pages.
It is idempotent but not deterministic: the algorithm repeats exactly for the same Linear state, but live issues change between invocations, so cached results are not interchangeable.
When to use it
Use it when:- You need every issue across every team, not one team or one page.
- You filter by
completedAt,createdAtorupdatedAtwithin a calendar month. - You want filtering done before any model sees the data, so token cost scales with the filtered count.
- You query a single team once — call the
project_managementcapability from an agent. - You filter by a non-date field such as assignee, label or priority — author a filter procedure or do it in an agent.
- Your source is not Linear.
Inputs
A
teamFilter key that does not exist in the workspace fails immediately with INVALID_INPUT; a typo would otherwise produce a silently empty report.
Output
null; the rest of the row stays intact.
Termination
The loop stops only when Linear reportspageInfo.hasNextPage == false. A page on which the date filter rejected every issue does not stop it: Linear interleaves issues from many periods, so page 12 can still hold matches after an empty page 11.
Date filter
Bounds are inclusive on both ends. Forperiod: "2026-04" the window is 2026-04-01T00:00:00.000Z to 2026-04-30T23:59:59.999Z — the last millisecond of the month, not midnight, so an issue closed at 23:59:42 on the last day is included. Issues whose dateField is null, such as open issues filtered by completedAt, are excluded.
Connection and authority
The procedure calls Linear GraphQL through thelinear/api vendor connection. Forge’s egress firewall injects the connection’s Authorization header for api.linear.app; the procedure never reads a raw secret. Provision the connection at the scope the dispatch uses before invoking it. The procedure requires the vendors:read permission and uses file_hosting to write its output. Reading the resulting file still requires authority over its file binding.
Error codes
Resource profile
Runtime and cost depend on team count, issue count, Linear latency, throttling and sandbox placement. Inspect the actual invocation rather than assuming a fixed time or cost.
Related
- Procedures — what a procedure is and how it is governed
- Author a procedure — write your own
- Files and bindings — how procedures pass files between steps

