steps

APIs for implementing a factory-owned custom agent step. Most workflows use runAgent and other generated routines instead.

Call these inside "use step" code. createAgentRunner provides a live provider model with jigs policy applied. See Custom agent steps.

Agent runner

AgentRunner

A harness ready to run in a worktree, from createAgentRunner. Pass model to the AI SDK's generateText, read the session reference from its result with sessionFrom, and call close when the call is done.

Methods

close()

close(): Promise<void>;

Release the worktree lock and stop what the harness started. Safe to call twice.

Returns

Promise<void>

sessionFrom()

sessionFrom(result): AgentSessionRef | undefined;

The session reference in a generateText result, for a later step to resume.

Parameters

Parameter	Type
result	{ providerMetadata?: Record<string, Record<string, unknown>> | null; }
result.providerMetadata?	Record<string, Record<string, unknown>> | null

Returns

AgentSessionRef | undefined

Properties

Property	Type	Description
model	LanguageModel	The live provider model, with jigs' policy already applied.

---

AgentRunnerOptions

Where createAgentRunner runs a harness, and the session it resumes.

Properties

Property	Type	Description
cwd	string	The worktree the agent works in.
resume?	AgentSessionRef	A session reference from an earlier call to resume.
run	RunMetadata	The run the step belongs to: getWorkflowMetadata() inside the step.

---

createAgentRunner()

function createAgentRunner(harness, options): Promise<AgentRunner>;

Open a Codex harness inside a factory's own step, the way the built-in agent step does: the environment allowlist with the factory's agents.env, the request and just-in-time checks, the worktree lock, and Codex's private home and app server. The returned model is the live provider, ready for generateText.

Parameters

Parameter	Type
harness	Harness
options	AgentRunnerOptions

Returns

Promise<AgentRunner>

Remarks

Call it inside a "use step" function, never in a workflow. The step can hand the provider a function, such as a tool-approval hook or a logger, because a step runs where functions are allowed; pass it through the AI SDK call.

It throws JitCheckError when a just-in-time check fails, and AgentSessionError when resume names a session this harness cannot resume. Claude Code and Pi have no AI SDK provider model, so their descriptors throw: run them with runAgent.

It reads the run's status before opening the harness and watches it until close. It throws a fatal error instead of opening on a cancelled run, and once the run is cancelled every provider call through model is aborted and fails with that fatal error.

Example

import type { AgentSessionRef, Harness } from "@jigs-ai/jigs";
import { createAgentRunner } from "@jigs-ai/jigs/steps";
import { generateText } from "ai";
import { getWorkflowMetadata } from "workflow";

export async function runWithTemperature(request: {
  harness: Harness;
  cwd: string;
  prompt: string;
  resume?: AgentSessionRef | undefined;
}) {
  "use step";
  const runner = await createAgentRunner(request.harness, {
    cwd: request.cwd,
    run: getWorkflowMetadata(),
    resume: request.resume,
  });
  try {
    const result = await generateText({ model: runner.model, prompt: request.prompt, temperature: 0 });
    return { text: result.text, session: runner.sessionFrom(result) };
  } finally {
    await runner.close();
  }
}

Errors

AgentSessionError

A durable agent session is missing or cannot be resumed by this harness.

Extends

• Error

Properties

Property	Type	Default value
name	"AgentSessionError"	"AgentSessionError"

---

ProviderApiError

A provider answered a call with a failure: an error status, or a refusal in its body.

Extends

• JigsError

Extended by

• GitHubApiError
• SlackApiError

Constructors

Constructor

new ProviderApiError(init): ProviderApiError;

Parameters

Parameter	Type
init	ProviderApiErrorInit

Returns

ProviderApiError

Overrides

JigsError.constructor

Properties

Property	Type	Description
body	string	-
code?	string	-
hint?	string	What the reader can do about it. Quote each command to run in backticks, as in stop the service first: `pnpm exec jigs service stop` : the CLI prints it on its own line.
provider	Provider	-
status	number	-

Runtime metadata

RunMetadata

type RunMetadata = Pick<WorkflowMetadata, "workflowRunId">;

The run a step belongs to: getWorkflowMetadata() inside the step.