Skip to main content
This page documents four general-purpose built-in procedures; Forge ships more, and you can see them all under Platform → Procedures. Each runs as deterministic code in a sandbox, reads and writes files through the 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:
Each step reads its input as a 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):
File branch (more than 1,000 records):
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:
  • rowNumber is 1-indexed and counts the header as row 1, so the first data row is row 2.
  • An empty field means 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 with rowNumber: -1, for example "additional 49000 validation error(s) omitted (cap=1000)".

Error codes

Row validation failures never raise; they accumulate in errors[].

Example

The downstream node consumes 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 in skippedCount) 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-15 is midnight UTC.
  • A naive datetime such as 2026-04-15T12:00:00 is UTC.
  • An aware datetime such as 2026-04-15T08:00:00-04:00 keeps its offset.
Arrays that mix time zones compare correctly.

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:
The executor resolves 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.
The file’s content is an array; sheet order in the workbook matches array order:
  • name: 1 to 31 characters, none of \ / ? * [ ] :, unique across the array.
  • columns: the ordered header row.
  • rows: records keyed by header name.
Sheet names. Excel reserves \ / ? * [ ] : 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

The workbook is bound as a workflow output under the key 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

The orchestrator validates the upstream binding against the procedure’s input schema before it starts the sandbox; a mismatch surfaces as an INVALID_INPUT branch.

Example: agent tool

Any agent whose permissions grant file_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, createdAt or updatedAt within a calendar month.
  • You want filtering done before any model sees the data, so token cost scales with the filtered count.
Use something else when:
  • You query a single team once — call the project_management capability 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

Assignee, project and state are resolved before the file is written, so a downstream agent needs no Linear access. An archived assignee, project or state resolves to null; the rest of the row stays intact.

Termination

The loop stops only when Linear reports pageInfo.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. For period: "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 the linear/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.