SDK reference

The @cori-do/sdk package — step constructors, shared options, and step file structure.

Installation

@cori-do/sdk is a dependency of your workflow's step files. It is automatically available when step files are compiled by the Cori CLI. You do not need to install it separately in the workflow folder.

Node.js ≥ 20 is required for step file execution.

Step file structure

Every step file must:

Export a typed input Zod schema as a named export input
Export a typed output Zod schema as a named export output
Export a step.* constructor as the default export
Use a two-digit numeric prefix in the filename (01_, 02_, …)

Schemas are enforced at runtime. A step's declared output schema is not documentation: the runner validates the produced output against it after every code and cli step (LLM steps are enforced provider-side), and a mismatch fails the step with a per-field error naming what drifted. A workflow that runs green really did honor its declared contracts.

steps/01_example.ts

import { step } from '@cori-do/sdk';
import { z } from 'zod';

export const input = z.object({
  value: z.string(),
});

export const output = z.object({
  result: z.string(),
});

export default step.cli({
  description: 'Example step',
  command: ({ input }) => `echo ${input.value}`,
  parse_output: (stdout) => ({ result: stdout.trim() }),
});

Step constructors

All five constructors are available on the step object:

import { step } from '@cori-do/sdk';

step.cli({ ... })
step.mcp_tool({ ... })
step.code({ ... })
step.llm({ ... })
step.builtin({ ... })  // deferred in v1

Shared options

All step constructors accept these shared options:

Option	Type	Required	Default	Description
`description`	string	✓	—	Human-readable description of what this step does. Required.
`retries`	object		See Retries and timeouts	Retry configuration.
`retries.max`	number		Per-kind default	Maximum number of attempts.
`retries.backoff`	`"linear" \| "exponential"`		`"exponential"`	Backoff strategy for retries.
`timeout_ms`	number		Per-kind default	Per-attempt timeout in milliseconds.

`step.cli` options

Option	Type	Required	Description
`description`	string	✓
`command`	`(ctx) => string`	✓	Shell command to run. Receives `{ input }`.
`parse_output`	`(stdout: string) => output`	✓	Parse stdout into the step's output type.
`env`	`(ctx) => Record<string, string>`		Additional environment variables.

`step.mcp_tool` options

Option	Type	Required	Description
`description`	string	✓
`server`	string	✓	MCP server name (must match `mcp_servers` in manifest).
`tool`	string	✓	Tool name on the MCP server.
`args`	`(ctx) => object`	✓	Tool arguments. Receives `{ input }`.
`parse_output`	`(result: unknown) => output`	✓	Parse the tool's result into the step's output type.

`step.code` options

Option	Type	Required	Description
`description`	string	✓
`run`	`(ctx) => output`	✓	Pure function. Receives `{ input }`. Must not perform I/O.

`step.llm` options

Option	Type	Required	Description
`description`	string	✓
`model`	string	✓	Model identifier (e.g., `"gpt-4o-mini"`). Provider inferred from name.
`prompt`	`(ctx) => string`	✓	Prompt string. Receives `{ input }`.
`output_schema`	Zod schema	✓	Must match the file's `output` export.
`system`	string		Optional system prompt.

`step.builtin` — deferred in v1

Builtin constructors exist in the SDK but the v1 runtime does not execute them. See Activity kinds.

SDK reference

On this page