TypeScript SDK - Infragrid Docs

The infragrid package provides a typed Runbook builder, Runbook lifecycle methods, and Run polling helpers for Node.js 18 or newer.

The unscoped npm package is documented from the codex/sdk-runbooks preview. Do not replace an existing production dependency until its registry release is announced.

Install

npm install infragrid

Create a client

import { Infragrid } from "infragrid"

const client = new Infragrid() // reads INFRAGRID_API_KEY

Option	Default	Purpose
`apiKey`	`INFRAGRID_API_KEY`	Workspace server credential
`baseUrl`	`INFRAGRID_BASE_URL` or `https://api.infragrid.ai`	Explicit API origin
`timeoutMs`	30,000	Per-request timeout
`fetch`	`globalThis.fetch`	Custom transport

Build a Runbook

import { Infragrid, input } from "infragrid"

const client = new Infragrid()

const runbook = await client
  .runbook("research-company")
  .parameter({ id: "company", name: "Company", type: "string", required: true })
  .navigate("open", "https://www.google.com", {
    applicationScope: ["google.com"],
    completionCondition: "The search page is visible."
  })
  .primitive(
    "search",
    "browser.type",
    { target: { role: "combobox", name: "Search" }, text: input("company"), submit: true },
    "Search for the supplied company.",
    {
      surface: "browser",
      effect: "external-write",
      risk: "medium",
      applicationScope: ["google.com"],
      completionCondition: "Search results are visible."
    }
  )
  .agent("summarize", "Find the official site and summarize the company.", {
    surface: "browser",
    effect: "read",
    risk: "low",
    applicationScope: ["public web"],
    completionCondition: "The output contains an official URL and summary.",
    allowedPrimitives: ["browser.navigate", "browser.click", "browser.read"],
    maxActions: 20
  })
  .publish()

Use primitive() for an exact action. Use agent() for a bounded semantic step that may adapt using only its declared primitive allowlist. Every step declares its surface, effect, risk, application scope, and completion condition.

Run a published Runbook

const created = await client.runbooks.run(runbook.id, {
  inputs: { company: "Acme" },
  executionTarget: "cloud" // or "local"
})

const finished = await client.runs.wait(created.id, {
  pollIntervalMs: 2_000,
  timeoutMs: 15 * 60_000,
  onUpdate: (run) => console.log(run.status)
})

Methods

Method	Purpose
`runbook(title)`	Start a local `RunbookBuilder`
`runbooks.create(input)`	Save a draft or published Runbook
`runbooks.list({ limit })`	List Runbooks
`runbooks.get(runbookId)`	Retrieve one Runbook
`runbooks.update(runbookId, input)`	Replace a Runbook using `expectedVersion`
`runbooks.publish(runbookId, expectedVersion?)`	Publish a reviewed revision
`runbooks.run(runbookId, input)`	Start a Run pinned to a published Runbook revision
`runs.create(input)`	Start an ad-hoc task Run
`runs.list({ limit, offset })`	List Runs
`runs.get(runId)`	Retrieve one Run
`runs.wait(runId, options)`	Poll until terminal
`runs.cancel(runId)`	Request cancellation

Pass an AbortSignal to runs.wait() to interrupt polling.

Errors

All exported error classes derive from InfragridError. Authentication, permission, missing-resource, conflict, rate-limit, timeout, connection, and server failures have specific subclasses.

Last modified on August 28, 2026