jigs

Everything a factory's configuration and workflows import from jigs: the factory and workflow definitions, harness and model descriptors, the data steps hand back, question helpers, and pure renderers.

Steps and routines come from your factory's generated #jigs/steps and #jigs/routines.

Classes

ClaimConflictError

A ticket-claim failure that identifies the run already holding the ticket.

Extends

• Error

Constructors

Constructor

new ClaimConflictError(resource, owningRunId): ClaimConflictError;

Parameters

Parameter	Type
resource	string
owningRunId	string

Returns

ClaimConflictError

Overrides

Error.constructor

Properties

Property	Type
owningRunId	string
resource	string

---

JigsError

An operator-readable failure that is safe to construct inside a workflow.

Extends

• Error

Constructors

Constructor

new JigsError(message, hint?): JigsError;

Parameters

Parameter	Type
message	string
hint?	string

Returns

JigsError

Overrides

Error.constructor

Properties

Property	Type
hint?	string

Interfaces

AgentsDefinition

Settings for the agent harnesses this factory runs.

Properties

Property	Type	Description
env?	string[]	Names of service environment variables every agent harness also receives. A harness otherwise starts with only a small base set, such as PATH and HOME, and the variables its own driver needs. Model credentials and the variables jigs sets itself are refused: name a model credential on its model source instead.

---

ChangePatch

Patches for selected paths between two resolved commits.

Properties

Property	Type	Description
patches	object[]	Patch text for each selected path, in first-requested order.
truncated	boolean	Whether the shared text limit cut off any patch text.

---

ChangeSummary

A bounded description of the committed changes between two Git refs.

Properties

Property	Type	Description
base	string	The resolved base commit.
commits	object[]	Commits reachable from head but not base, newest first.
files	FileChange[]	Files that differ directly between the base and head trees.
head	string	The resolved head commit.
truncated	boolean	Whether file or commit limits caused results to be omitted.

---

CheckRun

A check or commit status reported on a pull request head.

Properties

Property	Type
conclusion	string | null
name	string
url	string

---

Factory

What a factory repo hands the service: its workflows, keyed by name, and the schedules that fire them. A schedule is keyed by its own name rather than nested under a workflow — the name is what runs, status and jigs doctor refer to, and one workflow can carry several.

Properties

Property	Type	Description
schedules?	Record<string, Schedule>	-
webhooks?	object	Which provider webhook routes the service mounts. Absent, it mounts none.
webhooks.github	object	-
webhooks.github.enabled	boolean	-
webhooks.linear	object	-
webhooks.linear.enabled	boolean	-
webhooks.url	string	-
workflows	Record<string, AnyWorkflowDefinition>	-

---

FactoryDefinition

Operating settings and deferred workflow modules declared by a factory.

Properties

Property	Type	Description
agents?	AgentsDefinition	-
bindings?	Record<string, { copy?: string[]; hookTimeoutMinutes?: number; merge?: { by?: "jigs" | "human"; method?: "squash" | "merge" | "rebase"; }; postCreate?: string[]; remote: string; }>	-
github?	object	-
github.identities?	( | { mode: "pat"; } | { appId: number; coAuthor?: string; installations: Record<string, number>; mode: "app"; operator: string; privateKeyPath: string; })[]	-
linear?	object	-
linear.identity?	| { mode: "key"; } | { mode: "app"; }	-
merge?	object	-
merge.approval?	| { kind: "review"; } | { kind: "label"; name: string; }	The signal that authorizes an automatic merge.
merge.by?	"jigs" | "human"	Whether jigs merges an eligible pull request or waits for a person to merge it.
merge.method?	"squash" | "merge" | "rebase"	The GitHub merge method to use when jigs performs the merge.
release?	object	-
release.onFailure	"release" | "keep"	What to do with eligible resources after a failed or cancelled run.
release.onSuccess	"release" | "keep"	What to do with eligible resources after a completed run.
schedules?	Record<string, Schedule>	-
service	object	-
service.dashboardPort	number	-
service.pollIntervalSeconds?	object	Seconds between the service's re-reads of each parked run, per provider. Each defaults to 300 and may not go below 30. Up to a tenth of the interval is taken off at random so services do not all poll at once.
service.pollIntervalSeconds.github?	number	-
service.pollIntervalSeconds.linear?	number	-
service.port?	number	-
webhooks?	object	-
webhooks.github	object	-
webhooks.github.enabled	boolean	-
webhooks.linear	object	-
webhooks.linear.enabled	boolean	-
webhooks.url	string	-
workflows	Record<string, () => Promise<{ default: AnyWorkflowDefinition; }>>	-

---

FileChange

One file changed between the base and head trees.

Properties

Property	Type	Description
additions	number	The number of added lines, or zero for a binary file.
deletions	number	The number of deleted lines, or zero for a binary file.
path	string	The changed path. Renames use the path in the head tree.
status	ChangeStatus	How the path differs between the two trees.

---

HumanReply

The first human ticket reply that wakes a halted run.

Properties

Property	Type
author	object
author.id	string
author.name	string
body	string
commentId	string
createdAt	string

---

PullRequestComment

A comment on the pull request conversation, which hangs off no thread.

Properties

Property	Type
body	string
createdAt	string
id	number
updatedAt	string
user	string
userType	string

---

PullRequestMarker

Hidden progress metadata stored in a pull request comment.

Properties

Property	Type	Description
kind	MarkerKind	reply answers the thing named by source, completion records work finished for it, and status is a note about a commit — a stand-down after a refused merge, a CI failure jigs could not repair, or a merge refused for a state that will pass.
reason?	StatusReason	Required on a status marker, meaningless on any other.
run	string	The run that wrote it. Provenance for a reader; never matched on.
scope	string	The continuation identity. It survives run replacement, so a later run answering for the same scope sees this work as its own and does not redo it. Another scope's marker means "some jigs workflow wrote this", never "my work is done".
source?	string	What this answers: a comment as id@updatedAt, or a commit sha.

---

PullRequestReview

A submitted GitHub review of a pull request.

Properties

Property	Type
body	string
commitSha?	string
id	number
state	string
submittedAt	string
user	string

---

PullRequestSnapshot

GitHub facts about a pull request, without a judgment about outstanding work.

Properties

Property	Type	Description
ci	"red" | "green" | "pending"	-
conversationComments	PullRequestComment[]	-
draft	boolean	-
failingChecks	CheckRun[]	-
headSha	string	-
labels	string[]	Label names on the pull request; the label approval signal reads these.
mergeCommitSha	string | null	The merge commit, once GitHub has made one.
merged	boolean	-
mergeState	string	GitHub's own verdict on whether the pull request can merge right now, folding in conflicts, required checks and required reviews. "clean" is the only value that permits a merge; "unknown" means GitHub has not finished computing it, so the answer is "not yet, ask again".
reviews	PullRequestReview[]	-
reviewThreads	ReviewThread[]	-
state	"open" | "closed"	-

---

ReleaseReport

The result of applying a release policy to one run's managed resources.

Properties

Property	Type	Description
policy	object	The policy applied by this release attempt.
policy.onFailure	"release" | "keep"	What to do with eligible resources after a failed or cancelled run.
policy.onSuccess	"release" | "keep"	What to do with eligible resources after a completed run.
runDirectory	ReleasedResource	The scratch directory's local path, removal flag and reason for the result.
worktrees	ReleasedResource & object[]	Results for the run's worktrees, including paths, branches, removal flags, unmerged commit counts and reasons for anything retained.

---

ReviewComment

A comment anchored to a file in a pull request review.

Properties

Property	Type
body	string
createdAt	string
id	number
line	number | null
path	string
rootId	number
updatedAt	string
user	string

---

ReviewThread

A pull request review conversation, with its optional file location.

Properties

Property	Type
comments	ReviewComment[]
line	number | null
origin?	"conversation"
path	string
rootId	number

---

RunResource

A durable thing that a run created or otherwise owns a reference to.

Properties

Property	Type	Description
identity	string	The stable name that distinguishes this resource from others of the same kind.
kind	string	The resource category, such as worktree or run-directory.
url	string	An absolute URL where a human can inspect the resource.

---

Schedule

One recurring trigger: a workflow, when to fire it, and the inputs to fire it with.

Properties

Property	Type	Description
cron	string	Five fields, evaluated in the service host's local time zone.
inputs	Record<string, unknown>	-
workflow	string	-

---

ThreadAnswers

Answers routed back to pull-request threads and an optional commit explanation.

Properties

Property	Type	Description
answers	object[]	Replies to post, using null to answer feedback on the pull request conversation.
commitExplanation	string | null	A note explaining the pushed commit, or null when no explanation should be posted.

---

TicketClaim

A ticket held exclusively by the current workflow run.

Properties

Property	Type	Description
hook	Hook<unknown>	-
identifier	string	-
issueId	string	-
postedCommentIds	string[]	Every comment this run has posted on the ticket. A parked run skips these when it looks for a human's reply.
token	string	-

---

WorkflowDefinition

A workflow: its function, its input schema, and what a run needs before it may start.

Type Parameters

Type Parameter	Default type
S extends z.ZodType	z.ZodType

Properties

Property	Type	Description
inputs	S	-
release?	object	-
release.onFailure	"release" | "keep"	What to do with eligible resources after a failed or cancelled run.
release.onSuccess	"release" | "keep"	What to do with eligible resources after a completed run.
requires?	WorkflowRequires	What the workflow needs before a run can start: the agents it runs, the integrations, bindings and API model sources it uses. The service checks the CLI of every agent's harness when it starts, and preflight checks everything listed before every run. List only what the workflow uses. Example const agents = { builder: harnesses.claude({ model: "opus" }), reviewer: harnesses.codex({ model: "gpt-5.6-sol" }), }; export default defineWorkflow({ inputs, requires: { agents, integrations: ["linear", "github"] }, workflow: shipTicket, });
workflow	(inputs) => Promise<unknown>	-

---

Worktree

A provisioned repository worktree and the commit it was cut from.

Properties

Property	Type
baseSha	string
branch	string
defaultBranch	string
path	string

Type Aliases

AgentResult

type AgentResult<T> = ModelResult<T> & object;

A model result with the session reference an agent harness returned, when it returned one.

Type Declaration

Name	Type
session?	AgentSessionRef

Type Parameters

Type Parameter	Default type
T	unknown

---

AgentSessionRef

type AgentSessionRef = object;

A session reference: the small piece of data that lets a later runAgent call resume the same harness session. Pass it back as resume.

Properties

Property	Type	Description
descriptor	string	The harness descriptor the session was recorded on, as describeHarness renders it.
harness	Harness["kind"]	-
id	string	-

---

ApprovalSignal

type ApprovalSignal = z.output<typeof approvalSignalSchema>;

The review or label signal that authorizes an automatic merge.

---

AskableHarness

type AskableHarness = 
  | ClaudeHarness & ToolFree
  | PiHarness & ToolFree;

A harness askAgent can run with no tools: Claude Code or Pi, without MCP servers or a Pi tool allowlist. Codex has no mode without tools.

---

AskableModelSource

type AskableModelSource = Exclude<ModelSource, OpenaiCodexSource>;

A model source accepted by a direct model call.

---

AskAgentOptions

type AskAgentOptions<T> = object;

Options for one harness turn without tools or a worktree.

Type Parameters

Type Parameter	Default type
T	undefined

Properties

Property	Type
harness	AskableHarness
output?	z.ZodType<T>
prompt	string
system?	string

---

AskJevOptions

type AskJevOptions<QUESTIONS> = object;

A decision request in workflow and durable wire form.

Type Parameters

Type Parameter
QUESTIONS extends JevQuestions

Properties

Property	Type
model	OpenrouterSource
questions	QUESTIONS
state	JevState

---

AskModelOptions

type AskModelOptions<T> = object;

Options for one API model call.

Type Parameters

Type Parameter	Default type
T	undefined

Properties

Property	Type
model	AskableModelSource
output?	z.ZodType<T>
prompt	string
system?	string

---

BindingDefinition

type BindingDefinition = z.input<typeof bindingSchema>;

A repository this factory works in: its remote, how a worktree cut from it is provisioned, and any merge settings that differ from the factory's.

Example

bindings: {
  api: {
    remote: "git@github.com:acme/api.git",
    postCreate: ["pnpm install"],
    merge: { by: "jigs", method: "rebase" },
  },
},

---

ChangeStatus

type ChangeStatus = "added" | "modified" | "deleted" | "renamed" | "other";

How a file differs between the base and head trees.

---

ChoiceQuestion

type ChoiceQuestion<OPTIONS> = object;

A question answered with one named option.

Type Parameters

Type Parameter	Default type
OPTIONS extends Record<string, string>	Record<string, string>

Properties

Property	Type
instructions	string
options	OPTIONS
type	"choice"

---

ClaudeHarness

type ClaudeHarness = JsonOnly<Omit<ClaudeCodeSettings, ClaudePolicyKey>> & object;

A Claude Code harness descriptor: the provider's own settings that are data, minus each ClaudePolicyKey, plus the model and jigs' MCP server shape.

Type Declaration

Name	Type
kind	"claude"
mcpServers?	Record<string, McpServerConfig>
model	string

---

ClaudeHarnessSettings

type ClaudeHarnessSettings = Omit<ClaudeHarness, "kind">;

The one argument harnesses.claude takes: the model and any Claude Code settings.

---

ClaudePolicyKey

type ClaudePolicyKey = typeof claudePolicyKeys[number];

A Claude Code setting a descriptor cannot name, because jigs sets it itself or holds it as policy.

Remarks

jigs sets the working directory, environment, executable and session for every step, and holds permissions, setting sources and MCP servers as policy. extraArgs and sdkOptions would rewrite any of those. agents, settings and plugins would bring in unprobed MCP servers, environment, permissions and hooks from outside the worktree; they come from the repository's project settings instead.

---

CodexHarness

type CodexHarness = JsonOnly<Omit<CodexAppServerSettings, CodexPolicyKey>> & object;

A Codex harness descriptor: the provider's own settings that are data, minus each CodexPolicyKey, plus the model and jigs' MCP server shape.

Type Declaration

Name	Type
kind	"codex"
mcpServers?	Record<string, McpServerConfig>
model	string

---

CodexHarnessSettings

type CodexHarnessSettings = Omit<CodexHarness, "kind">;

The one argument harnesses.codex takes: the model and any Codex settings.

---

CodexPolicyKey

type CodexPolicyKey = typeof codexPolicyKeys[number];

A Codex setting a descriptor cannot name, because jigs sets it itself or holds it as policy.

Remarks

jigs sets the working directory, environment, executable, thread and session for every step, and holds the approval and sandbox policies and MCP servers. configOverrides would rewrite the sandbox and MCP tables.

---

GitHubDefinition

type GitHubDefinition = z.input<typeof githubSchema>;

Who jigs is on GitHub: the operator's own token, or a GitHub App installation.

---

Halt

type Halt = object;

What the ticket comment says, in the words a stranger to the repo reads. headline is one plain sentence naming what jigs paused and why, where names the routine it paused in so the footer can say so, about restates the ticket itself, notes are plain bullet lines, and onReply decides what the comment asks the human to do: choose between the questions ("continue") or repair something and let the step run again ("retry").

Properties

Property	Type
about?	string
headline	string
notes?	string[]
onReply	"continue" | "retry"
questions?	HaltQuestion[]
where	string

---

HaltOption

type HaltOption = z.infer<typeof haltOptionSchema>;

One answer choice for a question shown to a human.

---

HaltQuestion

type HaltQuestion = z.infer<typeof haltQuestionSchema>;

A question shown to a human while a run waits for their reply.

---

Harness

type Harness = 
  | ClaudeHarness
  | CodexHarness
  | PiHarness;

A serializable agent-program descriptor.

---

HarnessForOptions

type HarnessForOptions<H, O> = [Extract<keyof O, keyof ToolFree>] extends [never] ? H & ToolFree : H;

The descriptor a harness constructor returns for its options. It is also ToolFree, so askAgent accepts it, when the options name no tools or MCP servers.

Type Parameters

Type Parameter
H
O

---

HarnessKind

type HarnessKind = Harness["kind"];

The stable name of an agent harness.

---

JevAnswer

type JevAnswer<QUESTION> = QUESTION extends ChoiceQuestion<infer OPTIONS> ? object : QUESTION extends ScoreQuestion ? object : object;

The calibrated answer shape selected by one question descriptor.

Type Parameters

Type Parameter
QUESTION extends JevQuestion

---

JevAnswers

type JevAnswers<QUESTIONS> = { [KEY in keyof QUESTIONS]: JevAnswer<QUESTIONS[KEY]> };

Answers narrowed independently for every named question.

Type Parameters

Type Parameter
QUESTIONS extends JevQuestions

---

JevQuestion

type JevQuestion = 
  | YesNoQuestion
  | ChoiceQuestion
  | ScoreQuestion;

Any question accepted by askJev.

---

JevQuestions

type JevQuestions = Record<string, JevQuestion>;

Named decision questions evaluated against one shared state.

---

JevResult

type JevResult<QUESTIONS> = object;

A typed decision result.

Type Parameters

Type Parameter
QUESTIONS extends JevQuestions

Properties

Property	Type
answers	JevAnswers<QUESTIONS>

---

JevState

type JevState = string | JevJsonObject | JevJsonValue[];

JSON-compatible evidence evaluated by a decision model.

---

JsonOnly

type JsonOnly<T> = { [K in keyof T as false extends IsData<Exclude<T[K], undefined>> ? never : K]: T[K] };

The keys of a settings type whose values are data, so they can cross into a step.

Type Parameters

Type Parameter
T

---

JsonValue

type JsonValue = 
  | string
  | number
  | boolean
  | null
  | JsonValue[]
  | {
[key: string]: JsonValue;
};

A value that can be serialized as JSON and embedded in a prompt or comment.

---

LinearDefinition

type LinearDefinition = z.input<typeof linearSchema>;

Who jigs is on Linear: key acts as the user whose LINEAR_API_KEY is in .env, app acts as a Linear OAuth application from LINEAR_CLIENT_ID and LINEAR_CLIENT_SECRET. Defaults to key.

Example

linear: { identity: { mode: "app" } },

---

McpHttpServerConfig

type McpHttpServerConfig = object;

Configuration for an MCP server reached over HTTP.

Properties

Property	Type
headers?	Record<string, string>
probe	McpToolProbe
url	string

---

McpServerConfig

type McpServerConfig = 
  | McpStdioServerConfig
  | McpHttpServerConfig;

An MCP server an agent harness can expose to the model.

---

McpStdioServerConfig

type McpStdioServerConfig = object;

Configuration for an MCP server launched as a child process.

Properties

Property	Type
args?	string[]
command	string
env?	Record<string, string>
probe	McpToolProbe

---

McpToolProbe

type McpToolProbe = object;

A harmless MCP tool call used to prove that a configured server is available.

Properties

Property	Type
arguments?	Record<string, unknown>
tool	string

---

MergeDefinition

type MergeDefinition = z.input<typeof mergePolicySchema>;

Who merges, by which of GitHub's three methods, and what signal permits it.

---

MergePolicy

type MergePolicy = z.output<typeof mergePolicySchema>;

The effective pull request merge behavior for a binding.

---

ModelKind

type ModelKind = ModelSource["kind"];

The stable name of a model source.

---

ModelResult

type ModelResult<T> = object;

Text and structured output returned by a model call.

Type Parameters

Type Parameter	Default type
T	unknown

Properties

Property	Type
output	T
text	string

---

ModelSource

type ModelSource = 
  | OpenrouterSource
  | OpenaiCompatibleSource
  | OpenaiCodexSource;

Any configured source from which a model can answer.

---

OpenaiCodexSource

type OpenaiCodexSource = object;

The Codex subscription model source used only by the Pi harness.

Properties

Property	Type
kind	"openai-codex"
model	string

---

OpenaiCompatibleSource

type OpenaiCompatibleSource = object;

An OpenAI-compatible API model source.

Properties

Property	Type
apiKeyEnv?	string
baseUrl	string
kind	"openai-compatible"
model	string
name	string

---

OpenrouterSource

type OpenrouterSource = object;

An OpenRouter API model source.

Properties

Property	Type
apiKeyEnv	string
kind	"openrouter"
model	string

---

OutputJsonSchema

type OutputJsonSchema = Record<string, unknown>;

The serializable JSON Schema sent across the workflow-step boundary.

---

PiHarness

type PiHarness = 
  | PiOpenaiCompatibleHarness
  | PiOtherHarness;

A Pi harness descriptor backed by a nested model source.

---

PiHarnessOptions

type PiHarnessOptions = Pick<PiHarness, "thinking" | "tools" | "mcpServers"> & object;

Options for harnesses.pi. compat applies only to an OpenAI-compatible model source.

Type Declaration

Name	Type
compat?	Partial<PiOpenaiCompatibleOptions>

---

PiMcpHttpServerConfig

type PiMcpHttpServerConfig = Omit<McpHttpServerConfig, "headers"> & object & 
  | {
  auth: "oauth";
  bearerTokenEnv?: never;
}
  | {
  auth?: false;
  bearerTokenEnv?: never;
}
  | {
  auth?: never;
  bearerTokenEnv: string;
};

An HTTP MCP server Pi exposes through an explicit direct-tool allowlist.

Type Declaration

Name	Type	Description
headers?	Record<string, string>	Maps HTTP header names to step-side source environment variable names.
tools	string[]	Raw MCP tool names the model may call. This must include the probe tool.

---

PiMcpServerConfig

type PiMcpServerConfig = 
  | PiMcpStdioServerConfig
  | PiMcpHttpServerConfig;

An explicitly configured MCP server accepted by the Pi harness.

---

PiMcpStdioServerConfig

type PiMcpStdioServerConfig = Omit<McpStdioServerConfig, "env"> & object;

A stdio MCP server Pi exposes through an explicit direct-tool allowlist.

Type Declaration

Name	Type	Description
env?	Record<string, string>	Maps child variable names to step-side source environment variable names.
tools	string[]	Raw MCP tool names the model may call. This must include the probe tool.

---

PiOpenaiCompatibleHarness

type PiOpenaiCompatibleHarness = SharedPiHarness & object;

A Pi harness descriptor backed by an OpenAI-compatible source, with its compatibility hints.

Type Declaration

Name	Type
compat	PiOpenaiCompatibleOptions
model	OpenaiCompatibleSource

---

PiOpenaiCompatibleOptions

type PiOpenaiCompatibleOptions = object;

Pi-specific compatibility hints for an OpenAI-compatible model.

Properties

Property	Type
supportsDeveloperRole	boolean
supportsReasoningEffort	boolean

---

PiOtherHarness

type PiOtherHarness = SharedPiHarness & object;

A Pi harness descriptor backed by any source other than an OpenAI-compatible one.

Type Declaration

Name	Type
compat?	never
model	Exclude<ModelSource, OpenaiCompatibleSource>

---

PullRequestRef

type PullRequestRef = object;

Identifies a pull request by repository owner, repository name and number.

Properties

Property	Type	Description
number	number	The repository-local pull request number.
owner	string	The GitHub organization or account that owns the repository.
repo	string	The repository name.

---

PullRequestWake

type PullRequestWake = 
  | {
  headSha: string;
  kind: "merge-ready";
  retryNoted: boolean;
}
  | {
  body?: string;
  kind: "review-comments";
  threads: ReviewThread[];
}
  | {
  failing: CheckRun[];
  headSha: string;
  kind: "ci-red";
  mentionLogin: string | null;
}
  | {
  kind: "closed";
  merged: boolean;
};

What is outstanding on the pull request right now. Every wake describes current state, so the same state yields the same wake until the consumer leaves evidence on the pull request that it is done with it:

• review-comments: feedback with no answer carrying this scope's marker.
• ci-red: the current head is red, with no marked stand-down for it.
• merge-ready: GitHub reports the pull request mergeable and the configured approval signal is present, with no marked stand-down for it. retryNoted says a refusal jigs is waiting out was already reported for this head, so the retry is silent.
• closed: terminal.

Type Declaration

{
  headSha: string;
  kind: "merge-ready";
  retryNoted: boolean;
}

Name	Type	Description
headSha	string	The reviewed commit that the merge must still target.
kind	"merge-ready"	Identifies a pull request that is ready for an attempted merge.
retryNoted	boolean	Whether a transient refusal for this commit was already reported.

{
  body?: string;
  kind: "review-comments";
  threads: ReviewThread[];
}

Name	Type	Description
body?	string	The changes-requested review summary, when the feedback included one.
kind	"review-comments"	Identifies unanswered review feedback.
threads	ReviewThread[]	Inline and conversation threads that still need answers.

{
  failing: CheckRun[];
  headSha: string;
  kind: "ci-red";
  mentionLogin: string | null;
}

Name	Type	Description
failing	CheckRun[]	Failed checks reported by the provider.
headSha	string	The commit whose checks failed.
kind	"ci-red"	Identifies a failed build on the current commit.
mentionLogin	string | null	The most recent human reviewer to notify when repair cannot continue.

{
  kind: "closed";
  merged: boolean;
}

Name	Type	Description
kind	"closed"	Identifies a terminal, closed pull request.
merged	boolean	Whether the pull request closed by merging.

---

RebuildContextPrompt()

type RebuildContextPrompt = (input) => string;

Renders instructions for rebuilding an agent's working context.

Parameters

Parameter	Type
input	RebuildContextPromptInput

Returns

string

---

RebuildContextPromptInput

type RebuildContextPromptInput = object;

Material a fresh agent needs to continue work after a session cannot resume.

Properties

Property	Type
brief	string
diff	string
threads	string
ticket	string

---

ReleasePolicy

type ReleasePolicy = z.input<typeof releaseSchema>;

Selects whether eligible run resources are released for each terminal outcome.

---

RunAgentOptions

type RunAgentOptions<T> = object;

Options for an agent that works inside a directory.

Type Parameters

Type Parameter	Default type
T	undefined

Properties

Property	Type	Description
cwd	string	-
harness	Harness	-
output?	z.ZodType<T>	-
prompt	string	-
resume?	AgentSessionRef	The session reference of an earlier run to continue.

---

ScoreQuestion

type ScoreQuestion = object;

A question scored over ordered levels, from lowest to highest.

Properties

Property	Type
instructions	string
levels	string[]
type	"score"

---

StatusReason

type StatusReason = "merge" | "ci" | "merge-retry";

Why a status note was written, so one note never silences another. merge and ci stand a commit down; merge-retry only records that the refusal was already reported, and leaves the commit merge-ready.

---

TicketComment

type TicketComment = object;

A Linear ticket comment captured in a workflow snapshot.

Properties

Property	Type
author	string | null
body	string
createdAt	string
id	string

---

TicketHandoff

type TicketHandoff = object;

What a ticket review hands the builder: the brief plus the snapshot it was written from. Both travel together on purpose — the ticket is authoritative wherever the two conflict, and review or verify steps judge the work against the snapshot's acceptance criteria, never against the brief, so a re-planning agent cannot move the goalposts.

assumptions is what the review decided for itself rather than asked about. It is posted to the ticket, so a human can still correct it.

Properties

Property	Type
assumptions	string[]
brief	string
snapshot	TicketSnapshot

---

TicketLink

type TicketLink = object;

A named external link attached to a Linear ticket.

Properties

Property	Type
title	string
url	string

---

TicketNote

type TicketNote = object;

A comment jigs posts on the ticket that asks for nothing and suspends nothing. It carries its own words, the way a halt does, so the renderer owns the layout and every caller owns what it says.

Properties

Property	Type	Description
closing	string	What the reader should do with it.
headline	string	One plain sentence naming what jigs is about to do, or has stopped doing.
notes	string[]	The bullet lines under it.

---

TicketRef

type TicketRef = object;

A compact reference to a related Linear ticket.

Properties

Property	Type
id	string
identifier	string
title	string

---

TicketReviewPrompt()

type TicketReviewPrompt = (input) => string;

Renders instructions for an agent to turn a ticket into an actionable handoff.

Parameters

Parameter	Type
input	TicketReviewPromptInput

Returns

string

---

TicketReviewPromptInput

type TicketReviewPromptInput = object;

The rendered ticket supplied to a ticket-review prompt.

Properties

Property	Type
ticket	string

---

TicketSnapshot

type TicketSnapshot = object;

The fixed ticket state shared by every step in one workflow activation.

Properties

Property	Type
blockedBy	TicketRef[]
blocks	TicketRef[]
branchName	string
comments	TicketComment[]
description	string
fetchedAt	string
id	string
identifier	string
labels	string[]
links	TicketLink[]
state	string
subIssues	TicketRef[]
title	string
url	string

---

TicketWorkflowInputs

type TicketWorkflowInputs<S> = WorkflowInputs<S>;

Ticket references are ordinary inputs; resolve them explicitly in a step.

Type Parameters

Type Parameter
S extends z.ZodType<{ ticket: string; }>

---

ToolFree

type ToolFree = object;

Marks a descriptor that names no tools or MCP servers.

Properties

Property	Type
mcpServers?	never
tools?	never

---

WebhooksDefinition

type WebhooksDefinition = z.input<typeof webhooksSchema>;

Where provider webhooks reach the service, and which providers send them. Without this section the service still wakes parked runs by polling.

Example

webhooks: {
  url: "https://factory.example.ts.net",
  github: { enabled: true },
  linear: { enabled: false },
},

---

WorkflowInputs

type WorkflowInputs<S> = z.output<S> & Injected;

Parsed workflow inputs with the trigger that started the run.

Type Parameters

Type Parameter
S extends z.ZodType

---

YesNoQuestion

type YesNoQuestion = object;

A calibrated yes-or-no question.

Properties

Property	Type
instructions	string
type	"yes-no"

Variables

approvalSignalSchema

const approvalSignalSchema: ZodDiscriminatedUnion<[ZodObject<{
  kind: ZodLiteral<"review">;
}, $strict>, ZodObject<{
  kind: ZodLiteral<"label">;
  name: ZodString;
}, $strict>], "kind">;

Selects how the operator authorizes an automatic merge.

---

haltOptionSchema

const haltOptionSchema: ZodObject<{
  label: ZodString;
  recommended: ZodOptional<ZodBoolean>;
}, $strict>;

Validates an answer choice with a nonempty label and an optional recommendation marker.

---

haltQuestionSchema

const haltQuestionSchema: ZodObject<{
  context: ZodOptional<ZodString>;
  options: ZodOptional<ZodArray<ZodObject<{
     label: ZodString;
     recommended: ZodOptional<ZodBoolean>;
  }, $strict>>>;
  question: ZodString;
}, $strict>;

Validates a question with nonempty text, optional context and optional suggested answers.

---

harnesses

const harnesses: object;

Constructors for agent-harness descriptors.

Type Declaration

Name	Type	Default value
claude()	<O>(settings) => HarnessForOptions<ClaudeHarness, O>	claudeHarness
codex()	<O>(settings) => CodexHarness	codexHarness
pi()	{ <O> (model, options?): HarnessForOptions<PiOpenaiCompatibleHarness, O>; <O> (model, options?): HarnessForOptions<PiOtherHarness, O>; <M, O> (model, options?): HarnessForOptions<PiHarness, O>; }	piHarness

---

harnessKinds

const harnessKinds: ["claude" | "codex" | "pi", ...("claude" | "codex" | "pi")[]];

Every harness kind this release of jigs can build, taken from the keys of harnesses. Use it for a workflow input that names a harness, so a new kind appears without editing the input.

Example

const inputs = z.object({ harness: z.enum(harnessKinds) });

---

mergePolicySchema

const mergePolicySchema: ZodObject<{
  approval: ZodDefault<ZodDiscriminatedUnion<[ZodObject<{
     kind: ZodLiteral<"review">;
   }, $strict>, ZodObject<{
     kind: ZodLiteral<"label">;
     name: ZodString;
  }, $strict>], "kind">>;
  by: ZodDefault<ZodEnum<{
     human: "human";
     jigs: "jigs";
  }>>;
  method: ZodDefault<ZodEnum<{
     merge: "merge";
     rebase: "rebase";
     squash: "squash";
  }>>;
}, $strict>;

Configures who merges a pull request, how it is merged and how approval is recorded.

Remarks

by chooses an automatic jigs merge or a human merge. method selects squash, merge-commit or rebase behavior. approval requires either a review of the current commit or a named label that remains valid after later pushes.

---

models

const models: object;

Constructors for model-source descriptors.

Type Declaration

Name	Type	Description
openaiCodex()	(model) => OpenaiCodexSource	Build a source that runs through the Codex subscription Pi is logged in to. Only harnesses.pi accepts it.
openaiCompatible()	(options) => OpenaiCompatibleSource	Build a source for an OpenAI-compatible server.
openrouter()	(model, options) => OpenrouterSource	Build an OpenRouter source. Its key is read from OPENROUTER_API_KEY unless apiKeyEnv names another variable.

---

rebuildContextPrompt

const rebuildContextPrompt: RebuildContextPrompt;

The default prompt for continuing reviewed work in a fresh agent session.

---

ticketInputSchema

const ticketInputSchema: ZodUnion<readonly [ZodUUID, ZodString]>;

Accept a Linear issue UUID or an uppercase team-and-number ticket identifier.

---

ticketReviewPrompt

const ticketReviewPrompt: TicketReviewPrompt;

The default prompt for reviewing a Linear ticket before implementation begins.

---

ticketReviewVerdictSchema

const ticketReviewVerdictSchema: ZodObject<{
  about: ZodString;
  assumptions: ZodArray<ZodString>;
  brief: ZodString;
  questions: ZodArray<ZodObject<{
     context: ZodOptional<ZodString>;
     options: ZodOptional<ZodArray<ZodObject<{
        label: ZodString;
        recommended: ZodOptional<ZodBoolean>;
     }, $strict>>>;
     question: ZodString;
  }, $strict>>;
  verdict: ZodEnum<{
     needs-human: "needs-human";
     proceed: "proceed";
  }>;
}, $strict>;

Structured verdict returned by the agent that reviews a ticket before work starts.

Functions

choice()

function choice<OPTIONS>(instructions, options): ChoiceQuestion<OPTIONS>;

Build a question answered with one named option.

Type Parameters

Type Parameter
OPTIONS extends Record<string, string>

Parameters

Parameter	Type
instructions	string
options	OPTIONS

Returns

ChoiceQuestion<OPTIONS>

---

defaultPullRequestScope()

function defaultPullRequestScope(subject): string;

The scope a caller gets when it names none: this workflow's function name and the subject it was given — a ticket key, or the pull request itself. Pass an explicit scope to continue another workflow's work, or to review a pull request independently of the run delivering it.

Parameters

Parameter	Type
subject	string

Returns

string

---

defineFactory()

function defineFactory<T>(factory): T;

Preserve the declaration's inferred keys without loading its workflows.

Type Parameters

Type Parameter
T extends FactoryDefinition

Parameters

Parameter	Type
factory	T

Returns

T

---

defineWorkflow()

function defineWorkflow<S>(definition): WorkflowDefinition<S>;

Declare a workflow as the default export of its file. It returns the definition unchanged; it exists so TypeScript checks the workflow's parameter against the input schema.

Type Parameters

Type Parameter
S extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

Parameters

Parameter	Type
definition	WorkflowDefinition<S>

Returns

WorkflowDefinition<S>

Example

const inputs = z.object({ binding: z.string() });

export async function hello(input: WorkflowInputs<typeof inputs>) {
  "use workflow";
  // ...
}

export default defineWorkflow({ inputs, workflow: hello });

---

describeHarness()

function describeHarness(harness): string;

A harness descriptor as a string that ignores field order: two descriptors that list the same settings in another order render the same.

Parameters

Parameter	Type
harness	Harness

Returns

string

---

interpolate()

function interpolate(template, values): string;

Replace named once, leaving unknown names unchanged.

Parameters

Parameter	Type
template	string
values	Record<string, string>

Returns

string

---

isPullRequestMergeReady()

function isPullRequestMergeReady(snapshot, approval): boolean;

Whether current GitHub facts satisfy the configured approval and merge requirements.

Parameters

Parameter	Type
snapshot	PullRequestSnapshot
approval	| { kind: "review"; } | { kind: "label"; name: string; }

Returns

boolean

---

parseMarkers()

function parseMarkers(body): PullRequestMarker[];

Every marker in one comment body, in the order they appear.

Parameters

Parameter	Type
body	string

Returns

PullRequestMarker[]

---

pullRequestSnapshotKey()

function pullRequestSnapshotKey(snapshot): string;

A comparison key for the facts in a pull request snapshot.

Parameters

Parameter	Type
snapshot	PullRequestSnapshot

Returns

string

Remarks

Collection ordering and incidental fields do not change the key. Compare keys for equality; the key format is opaque and is not a durable identifier.

---

renderChangeSummary()

function renderChangeSummary(summary): string;

Render a Markdown review summary with commits, totals and up to 60 changed-file rows.

Parameters

Parameter	Type
summary	ChangeSummary

Returns

string

---

renderChecks()

function renderChecks(failing): string;

Render failed checks as a Markdown list for a pull request note.

Parameters

Parameter	Type
failing	CheckRun[]

Returns

string

---

renderTicketSnapshot()

function renderTicketSnapshot(snapshot): string;

Render a ticket snapshot as Markdown for an agent prompt.

Parameters

Parameter	Type
snapshot	TicketSnapshot

Returns

string

---

score()

function score(instructions, levels): ScoreQuestion;

Build a question scored over ordered levels, from lowest to highest.

Parameters

Parameter	Type
instructions	string
levels	string[]

Returns

ScoreQuestion

---

unreachable()

function unreachable(value): never;

Fail an exhaustive branch if an unexpected value reaches it at runtime.

Parameters

Parameter	Type
value	never

Returns

never

---

yesNo()

function yesNo(instructions): YesNoQuestion;

Build a calibrated yes-or-no question.

Parameters

Parameter	Type
instructions	string

Returns

YesNoQuestion

Factory plumbing

JitCheckError

A failed just-in-time tool check, with repair details for each failure.

Extends

• Error

Constructors

Constructor

new JitCheckError(failures): JitCheckError;

Parameters

Parameter	Type
failures	object & object[]

Returns

JitCheckError

Overrides

Error.constructor

Properties

Property	Type
failures	object & object[]

---

AgentRequest

type AgentRequest = 
  | Omit<RunAgentOptions, "output"> & object
  | Omit<AskAgentOptions, "output"> & object;

Serializable agent request passed to a durable step.

---

ModelRequest

type ModelRequest = Omit<AskModelOptions, "output"> & object;

Serializable API model request passed to a durable step.

Type Declaration

Name	Type
outputSchema?	OutputJsonSchema

---

unwrapAgentStep()

function unwrapAgentStep(result): AgentResult;

Convert returned execution failure markers into errors the workflow throws.

Parameters

Parameter	Type
result	| AgentResult | { jitFailure: object & object[]; } | { resumeFailed: string; }

Returns

AgentResult