---
url: https://salimhamed.github.io/jigs/api/jigs.md
---
# 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

```ts
new ClaimConflictError(resource, owningRunId): ClaimConflictError;
```

###### Parameters

| Parameter | Type |
| :------ | :------ |
| `resource` | `string` |
| `owningRunId` | `string` |

###### Returns

[`ClaimConflictError`](#claimconflicterror)

###### Overrides

```ts
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

```ts
new JigsError(message, hint?): JigsError;
```

###### Parameters

| Parameter | Type |
| :------ | :------ |
| `message` | `string` |
| `hint?` | `string` |

###### Returns

[`JigsError`](#jigserror)

###### Overrides

```ts
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`](#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`](#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`](#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`](#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`](#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`](#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`](#pullrequestcomment)\[] | - |
|  `draft` | `boolean` | - |
|  `failingChecks` | [`CheckRun`](#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`](#pullrequestreview)\[] | - |
|  `reviewThreads` | [`ReviewThread`](#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`](#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

```ts
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`](#agentsessionref) |

#### Type Parameters

| Type Parameter | Default type |
| :------ | :------ |
| `T` | `unknown` |

***

### AgentSessionRef

```ts
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](#describeharness) renders it. |
|  `harness` | [`Harness`](#harness-2)\[`"kind"`] | - |
|  `id` | `string` | - |

***

### ApprovalSignal

```ts
type ApprovalSignal = z.output<typeof approvalSignalSchema>;
```

The review or label signal that authorizes an automatic merge.

***

### AskableHarness

```ts
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

```ts
type AskableModelSource = Exclude<ModelSource, OpenaiCodexSource>;
```

A model source accepted by a direct model call.

***

### AskAgentOptions

```ts
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`](#askableharness) |
|  `output?` | `z.ZodType`<`T`> |
|  `prompt` | `string` |
|  `system?` | `string` |

***

### AskJevOptions

```ts
type AskJevOptions<QUESTIONS> = object;
```

A decision request in workflow and durable wire form.

#### Type Parameters

| Type Parameter |
| :------ |
| `QUESTIONS` *extends* [`JevQuestions`](#jevquestions) |

#### Properties

| Property | Type |
| :------ | :------ |
|  `model` | [`OpenrouterSource`](#openroutersource) |
|  `questions` | `QUESTIONS` |
|  `state` | [`JevState`](#jevstate) |

***

### AskModelOptions

```ts
type AskModelOptions<T> = object;
```

Options for one API model call.

#### Type Parameters

| Type Parameter | Default type |
| :------ | :------ |
| `T` | `undefined` |

#### Properties

| Property | Type |
| :------ | :------ |
|  `model` | [`AskableModelSource`](#askablemodelsource) |
|  `output?` | `z.ZodType`<`T`> |
|  `prompt` | `string` |
|  `system?` | `string` |

***

### BindingDefinition

```ts
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

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

***

### ChangeStatus

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

How a file differs between the base and head trees.

***

### ChoiceQuestion

```ts
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

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

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

#### Type Declaration

| Name | Type |
| :------ | :------ |
| `kind` | `"claude"` |
| `mcpServers?` | `Record`<`string`, [`McpServerConfig`](#mcpserverconfig)> |
| `model` | `string` |

***

### ClaudeHarnessSettings

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

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

***

### ClaudePolicyKey

```ts
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

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

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

#### Type Declaration

| Name | Type |
| :------ | :------ |
| `kind` | `"codex"` |
| `mcpServers?` | `Record`<`string`, [`McpServerConfig`](#mcpserverconfig)> |
| `model` | `string` |

***

### CodexHarnessSettings

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

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

***

### CodexPolicyKey

```ts
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

```ts
type GitHubDefinition = z.input<typeof githubSchema>;
```

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

***

### Halt

```ts
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`](#haltquestion)\[] |
|  `where` | `string` |

***

### HaltOption

```ts
type HaltOption = z.infer<typeof haltOptionSchema>;
```

One answer choice for a question shown to a human.

***

### HaltQuestion

```ts
type HaltQuestion = z.infer<typeof haltQuestionSchema>;
```

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

***

### Harness

```ts
type Harness = 
  | ClaudeHarness
  | CodexHarness
  | PiHarness;
```

A serializable agent-program descriptor.

***

### HarnessForOptions

```ts
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](#toolfree), so `askAgent` accepts it, when the options name no tools
or MCP servers.

#### Type Parameters

| Type Parameter |
| :------ |
| `H` |
| `O` |

***

### HarnessKind

```ts
type HarnessKind = Harness["kind"];
```

The stable name of an agent harness.

***

### JevAnswer

```ts
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`](#jevquestion) |

***

### JevAnswers

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

Answers narrowed independently for every named question.

#### Type Parameters

| Type Parameter |
| :------ |
| `QUESTIONS` *extends* [`JevQuestions`](#jevquestions) |

***

### JevQuestion

```ts
type JevQuestion = 
  | YesNoQuestion
  | ChoiceQuestion
  | ScoreQuestion;
```

Any question accepted by `askJev`.

***

### JevQuestions

```ts
type JevQuestions = Record<string, JevQuestion>;
```

Named decision questions evaluated against one shared state.

***

### JevResult

```ts
type JevResult<QUESTIONS> = object;
```

A typed decision result.

#### Type Parameters

| Type Parameter |
| :------ |
| `QUESTIONS` *extends* [`JevQuestions`](#jevquestions) |

#### Properties

| Property | Type |
| :------ | :------ |
|  `answers` | [`JevAnswers`](#jevanswers)<`QUESTIONS`> |

***

### JevState

```ts
type JevState = string | JevJsonObject | JevJsonValue[];
```

JSON-compatible evidence evaluated by a decision model.

***

### JsonOnly

```ts
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

```ts
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

```ts
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

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

***

### McpHttpServerConfig

```ts
type McpHttpServerConfig = object;
```

Configuration for an MCP server reached over HTTP.

#### Properties

| Property | Type |
| :------ | :------ |
|  `headers?` | `Record`<`string`, `string`> |
|  `probe` | [`McpToolProbe`](#mcptoolprobe) |
|  `url` | `string` |

***

### McpServerConfig

```ts
type McpServerConfig = 
  | McpStdioServerConfig
  | McpHttpServerConfig;
```

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

***

### McpStdioServerConfig

```ts
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) |

***

### McpToolProbe

```ts
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

```ts
type MergeDefinition = z.input<typeof mergePolicySchema>;
```

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

***

### MergePolicy

```ts
type MergePolicy = z.output<typeof mergePolicySchema>;
```

The effective pull request merge behavior for a binding.

***

### ModelKind

```ts
type ModelKind = ModelSource["kind"];
```

The stable name of a model source.

***

### ModelResult

```ts
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

```ts
type ModelSource = 
  | OpenrouterSource
  | OpenaiCompatibleSource
  | OpenaiCodexSource;
```

Any configured source from which a model can answer.

***

### OpenaiCodexSource

```ts
type OpenaiCodexSource = object;
```

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

#### Properties

| Property | Type |
| :------ | :------ |
|  `kind` | `"openai-codex"` |
|  `model` | `string` |

***

### OpenaiCompatibleSource

```ts
type OpenaiCompatibleSource = object;
```

An OpenAI-compatible API model source.

#### Properties

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

***

### OpenrouterSource

```ts
type OpenrouterSource = object;
```

An OpenRouter API model source.

#### Properties

| Property | Type |
| :------ | :------ |
|  `apiKeyEnv` | `string` |
|  `kind` | `"openrouter"` |
|  `model` | `string` |

***

### OutputJsonSchema

```ts
type OutputJsonSchema = Record<string, unknown>;
```

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

***

### PiHarness

```ts
type PiHarness = 
  | PiOpenaiCompatibleHarness
  | PiOtherHarness;
```

A Pi harness descriptor backed by a nested model source.

***

### PiHarnessOptions

```ts
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`](#piopenaicompatibleoptions)> |

***

### PiMcpHttpServerConfig

```ts
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

```ts
type PiMcpServerConfig = 
  | PiMcpStdioServerConfig
  | PiMcpHttpServerConfig;
```

An explicitly configured MCP server accepted by the Pi harness.

***

### PiMcpStdioServerConfig

```ts
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

```ts
type PiOpenaiCompatibleHarness = SharedPiHarness & object;
```

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

#### Type Declaration

| Name | Type |
| :------ | :------ |
| `compat` | [`PiOpenaiCompatibleOptions`](#piopenaicompatibleoptions) |
| `model` | [`OpenaiCompatibleSource`](#openaicompatiblesource) |

***

### PiOpenaiCompatibleOptions

```ts
type PiOpenaiCompatibleOptions = object;
```

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

#### Properties

| Property | Type |
| :------ | :------ |
|  `supportsDeveloperRole` | `boolean` |
|  `supportsReasoningEffort` | `boolean` |

***

### PiOtherHarness

```ts
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`](#modelsource), [`OpenaiCompatibleSource`](#openaicompatiblesource)> |

***

### PullRequestRef

```ts
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

```ts
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

```ts
{
  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. |

```ts
{
  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`](#reviewthread)\[] | Inline and conversation threads that still need answers. |

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

| Name | Type | Description |
| :------ | :------ | :------ |
| `failing` | [`CheckRun`](#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. |

```ts
{
  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()

```ts
type RebuildContextPrompt = (input) => string;
```

Renders instructions for rebuilding an agent's working context.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `input` | [`RebuildContextPromptInput`](#rebuildcontextpromptinput) |

#### Returns

`string`

***

### RebuildContextPromptInput

```ts
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

```ts
type ReleasePolicy = z.input<typeof releaseSchema>;
```

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

***

### RunAgentOptions

```ts
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`](#harness-2) | - |
|  `output?` | `z.ZodType`<`T`> | - |
|  `prompt` | `string` | - |
|  `resume?` | [`AgentSessionRef`](#agentsessionref) | The session reference of an earlier run to continue. |

***

### ScoreQuestion

```ts
type ScoreQuestion = object;
```

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

#### Properties

| Property | Type |
| :------ | :------ |
|  `instructions` | `string` |
|  `levels` | `string`\[] |
|  `type` | `"score"` |

***

### StatusReason

```ts
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

```ts
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

```ts
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`](#ticketsnapshot) |

***

### TicketLink

```ts
type TicketLink = object;
```

A named external link attached to a Linear ticket.

#### Properties

| Property | Type |
| :------ | :------ |
|  `title` | `string` |
|  `url` | `string` |

***

### TicketNote

```ts
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

```ts
type TicketRef = object;
```

A compact reference to a related Linear ticket.

#### Properties

| Property | Type |
| :------ | :------ |
|  `id` | `string` |
|  `identifier` | `string` |
|  `title` | `string` |

***

### TicketReviewPrompt()

```ts
type TicketReviewPrompt = (input) => string;
```

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

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `input` | [`TicketReviewPromptInput`](#ticketreviewpromptinput) |

#### Returns

`string`

***

### TicketReviewPromptInput

```ts
type TicketReviewPromptInput = object;
```

The rendered ticket supplied to a ticket-review prompt.

#### Properties

| Property | Type |
| :------ | :------ |
|  `ticket` | `string` |

***

### TicketSnapshot

```ts
type TicketSnapshot = object;
```

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

#### Properties

| Property | Type |
| :------ | :------ |
|  `blockedBy` | [`TicketRef`](#ticketref)\[] |
|  `blocks` | [`TicketRef`](#ticketref)\[] |
|  `branchName` | `string` |
|  `comments` | [`TicketComment`](#ticketcomment)\[] |
|  `description` | `string` |
|  `fetchedAt` | `string` |
|  `id` | `string` |
|  `identifier` | `string` |
|  `labels` | `string`\[] |
|  `links` | [`TicketLink`](#ticketlink)\[] |
|  `state` | `string` |
|  `subIssues` | [`TicketRef`](#ticketref)\[] |
|  `title` | `string` |
|  `url` | `string` |

***

### TicketWorkflowInputs

```ts
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

```ts
type ToolFree = object;
```

Marks a descriptor that names no tools or MCP servers.

#### Properties

| Property | Type |
| :------ | :------ |
|  `mcpServers?` | `never` |
|  `tools?` | `never` |

***

### WebhooksDefinition

```ts
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

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

***

### WorkflowInputs

```ts
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

```ts
type YesNoQuestion = object;
```

A calibrated yes-or-no question.

#### Properties

| Property | Type |
| :------ | :------ |
|  `instructions` | `string` |
|  `type` | `"yes-no"` |

## Variables

### approvalSignalSchema

```ts
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

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

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

***

### haltQuestionSchema

```ts
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

```ts
const harnesses: object;
```

Constructors for agent-harness descriptors.

#### Type Declaration

| Name | Type | Default value |
| :------ | :------ | :------ |
|  `claude()` | <`O`>(`settings`) => [`HarnessForOptions`](#harnessforoptions)<[`ClaudeHarness`](#claudeharness), `O`> | `claudeHarness` |
|  `codex()` | <`O`>(`settings`) => [`CodexHarness`](#codexharness) | `codexHarness` |
|  `pi()` | { <`O`> (`model`, `options?`): [`HarnessForOptions`](#harnessforoptions)<[`PiOpenaiCompatibleHarness`](#piopenaicompatibleharness), `O`>; <`O`> (`model`, `options?`): [`HarnessForOptions`](#harnessforoptions)<[`PiOtherHarness`](#piotherharness), `O`>; <`M`, `O`> (`model`, `options?`): [`HarnessForOptions`](#harnessforoptions)<[`PiHarness`](#piharness), `O`>; } | `piHarness` |

***

### harnessKinds

```ts
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

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

***

### mergePolicySchema

```ts
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

```ts
const models: object;
```

Constructors for model-source descriptors.

#### Type Declaration

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

***

### rebuildContextPrompt

```ts
const rebuildContextPrompt: RebuildContextPrompt;
```

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

***

### ticketInputSchema

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

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

***

### ticketReviewPrompt

```ts
const ticketReviewPrompt: TicketReviewPrompt;
```

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

***

### ticketReviewVerdictSchema

```ts
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()

```ts
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`](#choicequestion)<`OPTIONS`>

***

### defaultPullRequestScope()

```ts
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()

```ts
function defineFactory<T>(factory): T;
```

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

#### Type Parameters

| Type Parameter |
| :------ |
| `T` *extends* [`FactoryDefinition`](#factorydefinition) |

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `factory` | `T` |

#### Returns

`T`

***

### defineWorkflow()

```ts
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`](#workflowdefinition)<`S`> |

#### Returns

[`WorkflowDefinition`](#workflowdefinition)<`S`>

#### Example

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

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

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

***

### describeHarness()

```ts
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`](#harness-2) |

#### Returns

`string`

***

### interpolate()

```ts
function interpolate(template, values): string;
```

Replace named `{{ placeholders }}` once, leaving unknown names unchanged.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `template` | `string` |
| `values` | `Record`<`string`, `string`> |

#### Returns

`string`

***

### isPullRequestMergeReady()

```ts
function isPullRequestMergeReady(snapshot, approval): boolean;
```

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

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `snapshot` | [`PullRequestSnapshot`](#pullrequestsnapshot) |
| `approval` | | { `kind`: `"review"`; } | { `kind`: `"label"`; `name`: `string`; } |

#### Returns

`boolean`

***

### parseMarkers()

```ts
function parseMarkers(body): PullRequestMarker[];
```

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

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `body` | `string` |

#### Returns

[`PullRequestMarker`](#pullrequestmarker)\[]

***

### pullRequestSnapshotKey()

```ts
function pullRequestSnapshotKey(snapshot): string;
```

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

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `snapshot` | [`PullRequestSnapshot`](#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()

```ts
function renderChangeSummary(summary): string;
```

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

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `summary` | [`ChangeSummary`](#changesummary) |

#### Returns

`string`

***

### renderChecks()

```ts
function renderChecks(failing): string;
```

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

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `failing` | [`CheckRun`](#checkrun)\[] |

#### Returns

`string`

***

### renderTicketSnapshot()

```ts
function renderTicketSnapshot(snapshot): string;
```

Render a ticket snapshot as Markdown for an agent prompt.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `snapshot` | [`TicketSnapshot`](#ticketsnapshot) |

#### Returns

`string`

***

### score()

```ts
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`](#scorequestion)

***

### unreachable()

```ts
function unreachable(value): never;
```

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

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `value` | `never` |

#### Returns

`never`

***

### yesNo()

```ts
function yesNo(instructions): YesNoQuestion;
```

Build a calibrated yes-or-no question.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `instructions` | `string` |

#### Returns

[`YesNoQuestion`](#yesnoquestion)

## Factory plumbing

### JitCheckError

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

#### Extends

* `Error`

#### Constructors

##### Constructor

```ts
new JitCheckError(failures): JitCheckError;
```

###### Parameters

| Parameter | Type |
| :------ | :------ |
| `failures` | `object` & `object`\[] |

###### Returns

[`JitCheckError`](#jitcheckerror)

###### Overrides

```ts
Error.constructor
```

#### Properties

| Property | Type |
| :------ | :------ |
|  `failures` | `object` & `object`\[] |

***

### AgentRequest

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

Serializable agent request passed to a durable step.

***

### ModelRequest

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

Serializable API model request passed to a durable step.

#### Type Declaration

| Name | Type |
| :------ | :------ |
| `outputSchema?` | [`OutputJsonSchema`](#outputjsonschema) |

***

### unwrapAgentStep()

```ts
function unwrapAgentStep(result): AgentResult;
```

Convert returned execution failure markers into errors the workflow throws.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `result` | | [`AgentResult`](#agentresult) | { `jitFailure`: `object` & `object`\[]; } | { `resumeFailed`: `string`; } |

#### Returns

[`AgentResult`](#agentresult)