---
url: https://salimhamed.github.io/jigs/api/factory/steps.md
---
# factory/steps

Durable steps your workflows import from `#jigs/steps`.
Each wrapper carries its own "use step" directive and stable factory identity.

## Linear and human input

### fetchTicketSnapshot() {#fetchticketsnapshot}

```ts
function fetchTicketSnapshot(ticket): Promise<TicketSnapshot>;
```

Read the ticket's current details, comments, and related issues from Linear.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `ticket` | { `installationName`: `string`; `issueId`: `string`; } |
| `ticket.installationName` | `string` |
| `ticket.issueId` | `string` |

#### Returns

`Promise`<[`TicketSnapshot`](../jigs.md#ticketsnapshot)>

***

### postTicketHumanInputRequest() {#posttickethumaninputrequest}

```ts
function postTicketHumanInputRequest(request): Promise<void>;
```

Ask in the ticket's Linear agent session for human input. Use haltForHuman() to also wait for a
reply.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `request` | { `halt`: [`Halt`](../jigs.md#halt); `installationName`: `string`; `issueId`: `string`; `sessionId`: `string`; } |
| `request.halt` | [`Halt`](../jigs.md#halt) |
| `request.installationName` | `string` |
| `request.issueId` | `string` |
| `request.sessionId` | `string` |

#### Returns

`Promise`<`void`>

***

### postTicketNote() {#postticketnote}

```ts
function postTicketNote(request): Promise<void>;
```

Post a note in the ticket's Linear agent session that asks for nothing and waits for nothing.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `request` | { `installationName`: `string`; `issueId`: `string`; `note`: [`TicketNote`](../jigs.md#ticketnote); `sessionId`: `string`; } |
| `request.installationName` | `string` |
| `request.issueId` | `string` |
| `request.note` | [`TicketNote`](../jigs.md#ticketnote) |
| `request.sessionId` | `string` |

#### Returns

`Promise`<`void`>

***

### resolveLinearIssue() {#resolvelinearissue}

```ts
function resolveLinearIssue(request): Promise<LinearIssueRef>;
```

Resolve a Linear ticket identifier or issue ID before claiming it.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `request` | { `installationName`: `string`; `reference`: `string`; } |
| `request.installationName` | `string` |
| `request.reference` | `string` |

#### Returns

`Promise`<`LinearIssueRef`>

***

### setTicketStatus() {#setticketstatus}

```ts
function setTicketStatus(request): Promise<TicketStatusResult>;
```

Move a ticket to a named state when this workflow's policy says to.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `request` | { `installationName`: `string`; `issueId`: `string`; `stateName`: `string`; } |
| `request.installationName` | `string` |
| `request.issueId` | `string` |
| `request.stateName` | `string` |

#### Returns

`Promise`<[`TicketStatusResult`](../steps/linear.md#ticketstatusresult)>

## PagerDuty incidents

### fetchIncidentSnapshot() {#fetchincidentsnapshot}

```ts
function fetchIncidentSnapshot(incident): Promise<IncidentSnapshot>;
```

Read a snapshot of the PagerDuty incident.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `incident` | { `incidentId`: `string`; `installationName`: `string`; } |
| `incident.incidentId` | `string` |
| `incident.installationName` | `string` |

#### Returns

`Promise`<[`IncidentSnapshot`](../jigs.md#incidentsnapshot)>

***

### postIncidentNote() {#postincidentnote}

```ts
function postIncidentNote(note): Promise<{
  noteId: string;
}>;
```

Add a plain-text note to the PagerDuty incident, ending in a line that names this run.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `note` | { `content`: `string`; `incidentId`: `string`; `installationName`: `string`; } |
| `note.content` | `string` |
| `note.incidentId` | `string` |
| `note.installationName` | `string` |

#### Returns

`Promise`<{
`noteId`: `string`;
}>

## Pull requests

### commentOnPullRequest() {#commentonpullrequest}

```ts
function commentOnPullRequest(pullRequest, body): Promise<{
  id: number;
}>;
```

Add a comment to the pull request's main conversation.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `pullRequest` | [`PullRequestRef`](../jigs.md#pullrequestref) |
| `body` | `string` |

#### Returns

`Promise`<{
`id`: `number`;
}>

***

### createPullRequest() {#createpullrequest}

```ts
function createPullRequest(request): Promise<OpenedPullRequest>;
```

Create a pull request for a branch that has already been pushed.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `request` | { `body`: `string`; `draft?`: `boolean`; `title`: `string`; `worktree`: [`Worktree`](../jigs.md#worktree-3); } |
| `request.body` | `string` |
| `request.draft?` | `boolean` |
| `request.title` | `string` |
| `request.worktree` | [`Worktree`](../jigs.md#worktree-3) |

#### Returns

`Promise`<[`OpenedPullRequest`](../steps/pull-requests.md#openedpullrequest)>

***

### fetchPullRequestState() {#fetchpullrequeststate}

```ts
function fetchPullRequestState(pullRequest, options?): Promise<PullRequestSnapshot>;
```

Read a pull request's reviews, comments, CI results, approval, and merge state.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `pullRequest` | [`PullRequestRef`](../jigs.md#pullrequestref) |
| `options?` | [`PullRequestReadOptions`](../jigs.md#pullrequestreadoptions) |

#### Returns

`Promise`<[`PullRequestSnapshot`](../jigs.md#pullrequestsnapshot)>

***

### markPullRequestReady() {#markpullrequestready}

```ts
function markPullRequestReady(pullRequest): Promise<PullRequestSnapshot>;
```

Mark a draft pull request ready for review and return its current state.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `pullRequest` | [`PullRequestRef`](../jigs.md#pullrequestref) |

#### Returns

`Promise`<[`PullRequestSnapshot`](../jigs.md#pullrequestsnapshot)>

***

### mergePullRequest() {#mergepullrequest}

```ts
function mergePullRequest(
   pullRequest, 
   expectedHeadSha, 
options?): Promise<MergeOutcome>;
```

Merge the pull request with the first method its repository allows of squash, merge commit
and rebase, pinned to the approved head.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `pullRequest` | [`PullRequestRef`](../jigs.md#pullrequestref) |
| `expectedHeadSha` | `string` |
| `options?` | [`MergeOptions`](../jigs.md#mergeoptions) |

#### Returns

`Promise`<[`MergeOutcome`](../steps/pull-requests.md#mergeoutcome)>

***

### replyToPullRequestReviewThread() {#replytopullrequestreviewthread}

```ts
function replyToPullRequestReviewThread(
   pullRequest, 
   rootCommentId, 
   body): Promise<{
  id: number;
}>;
```

Reply to an existing code-review thread on a pull request.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `pullRequest` | [`PullRequestRef`](../jigs.md#pullrequestref) |
| `rootCommentId` | `number` |
| `body` | `string` |

#### Returns

`Promise`<{
`id`: `number`;
}>

***

### reviewPullRequest() {#reviewpullrequest}

```ts
function reviewPullRequest(pullRequest, review): Promise<{
  id: number;
}>;
```

Post a review on a pull request.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `pullRequest` | [`PullRequestRef`](../jigs.md#pullrequestref) |
| `review` | { `body`: `string`; `comments?`: `object`\[]; `event`: `"comment"` | `"approve"` | `"request-changes"`; } |
| `review.body` | `string` |
| `review.comments?` | `object`\[] |
| `review.event` | `"comment"` | `"approve"` | `"request-changes"` |

#### Returns

`Promise`<{
`id`: `number`;
}>

## Slack messages

### fetchSlackMessage() {#fetchslackmessage}

```ts
function fetchSlackMessage(message): Promise<SlackMessageSnapshot>;
```

Read a Slack message and its thread replies, with each author's name and email.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `message` | { `channel`: `string`; `installationName`: `string`; `ts`: `string`; } |
| `message.channel` | `string` |
| `message.installationName` | `string` |
| `message.ts` | `string` |

#### Returns

`Promise`<[`SlackMessageSnapshot`](../jigs.md#slackmessagesnapshot)>

***

### postSlackMessage() {#postslackmessage}

```ts
function postSlackMessage(message): Promise<string>;
```

Post plain mrkdwn text to a Slack channel, or reply in the thread under `threadTs`.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `message` | { `channel`: `string`; `installationName`: `string`; `text`: `string`; `threadTs?`: `string`; } |
| `message.channel` | `string` |
| `message.installationName` | `string` |
| `message.text` | `string` |
| `message.threadTs?` | `string` |

#### Returns

`Promise`<`string`>

## Git changes

### pushApprovedChange() {#pushapprovedchange}

```ts
function pushApprovedChange(worktree, approvedCommit): Promise<{
  headSha: string;
}>;
```

Recheck approval and push only the reviewed commit, including on retries.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `worktree` | [`Worktree`](../jigs.md#worktree-3) |
| `approvedCommit` | `string` |

#### Returns

`Promise`<{
`headSha`: `string`;
}>

***

### pushBranch() {#pushbranch}

```ts
function pushBranch(worktree): Promise<{
  headSha: string;
}>;
```

Push the worktree's branch to its remote, including any newly committed changes.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `worktree` | [`Worktree`](../jigs.md#worktree-3) |

#### Returns

`Promise`<{
`headSha`: `string`;
}>

***

### readBranchState() {#readbranchstate}

```ts
function readBranchState(worktree, baseSha?): Promise<{
  commits: number;
  dirty: boolean;
  headSha: string;
}>;
```

Check commits since the base, the branch's current commit, and uncommitted changes.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `worktree` | [`Worktree`](../jigs.md#worktree-3) |
| `baseSha?` | `string` |

#### Returns

`Promise`<{
`commits`: `number`;
`dirty`: `boolean`;
`headSha`: `string`;
}>

***

### readChange() {#readchange}

```ts
function readChange(worktree, base?): Promise<ChangeSummary>;
```

Read committed file changes and subjects up to HEAD, defaulting to the worktree's base.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `worktree` | [`Worktree`](../jigs.md#worktree-3) |
| `base?` | `string` |

#### Returns

`Promise`<[`ChangeSummary`](../jigs.md#changesummary)>

***

### readPatch() {#readpatch}

```ts
function readPatch(
   worktree, 
   base, 
   head, 
paths): Promise<ChangePatch>;
```

Read capped patches for literal named paths between the summary's commits.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `worktree` | [`Worktree`](../jigs.md#worktree-3) |
| `base` | `string` |
| `head` | `string` |
| `paths` | `string`\[] |

#### Returns

`Promise`<[`ChangePatch`](../jigs.md#changepatch)>

***

### readWorktreeDiff() {#readworktreediff}

```ts
function readWorktreeDiff(worktree, baseSha?): Promise<string>;
```

Read committed changes, defaulting to the worktree's base commit. Large diffs are truncated.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `worktree` | [`Worktree`](../jigs.md#worktree-3) |
| `baseSha?` | `string` |

#### Returns

`Promise`<`string`>

## Agent execution

### executeAgent() {#executeagent}

```ts
function executeAgent(request): Promise<
  | AgentResult
  | {
  jitFailure: object & object[];
}
  | {
  resumeFailed: string;
}>;
```

Execute an agent in a working directory. Use runAgent() to pass an output schema and parse its answer.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `request` | [`AgentRequest`](../jigs.md#agentrequest) |

#### Returns

`Promise`<
| [`AgentResult`](../jigs.md#agentresult)
| {
`jitFailure`: `object` & `object`\[];
}
| {
`resumeFailed`: `string`;
}>

***

### executeJev() {#executejev}

```ts
function executeJev<QUESTIONS>(request): Promise<JevResult<QUESTIONS>>;
```

Execute typed decision questions against one shared state.

#### Type Parameters

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

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `request` | [`AskJevOptions`](../jigs.md#askjevoptions)<`QUESTIONS`> |

#### Returns

`Promise`<[`JevResult`](../jigs.md#jevresult)<`QUESTIONS`>>

***

### executeModel() {#executemodel}

```ts
function executeModel(request): Promise<ModelResult>;
```

Execute a model request without tools. Use askModel() to pass an output schema and parse its answer.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `request` | [`ModelRequest`](../jigs.md#modelrequest) |

#### Returns

`Promise`<[`ModelResult`](../jigs.md#modelresult)>

## Workspaces and resources

### createRunDirectory() {#createrundirectory}

```ts
function createRunDirectory(): Promise<string>;
```

Prepare this run's scratch directory, preserving it when the run resumes.

#### Returns

`Promise`<`string`>

***

### listBindings() {#listbindings}

```ts
function listBindings(): Promise<RepositoryRef & object[]>;
```

List every binding in the factory's configuration on GitHub, with the repository it points at.

#### Returns

`Promise`<[`RepositoryRef`](../jigs.md#repositoryref) & `object`\[]>

***

### provisionPullRequestWorktree() {#provisionpullrequestworktree}

```ts
function provisionPullRequestWorktree(request): Promise<PullRequestWorktree>;
```

Check out a pull request's head commit in a worktree for this run, with no branch to push.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `request` | [`PullRequestWorktreeRequest`](../steps/workspaces.md#pullrequestworktreerequest) |

#### Returns

`Promise`<[`PullRequestWorktree`](../jigs.md#pullrequestworktree)>

***

### provisionWorktree() {#provisionworktree}

```ts
function provisionWorktree(request): Promise<Worktree>;
```

Prepare a worktree for this run, reusing it when the run resumes.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `request` | [`WorktreeRequest`](../steps/workspaces.md#worktreerequest) |

#### Returns

`Promise`<[`Worktree`](../jigs.md#worktree-3)>

***

### registerResource() {#registerresource}

```ts
function registerResource(resource): Promise<RunResource>;
```

Record a resource on this run independently of the workflow's return value.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `resource` | [`RunResource`](../jigs.md#runresource) |

#### Returns

`Promise`<[`RunResource`](../jigs.md#runresource)>

#### Remarks

Register anything a person may need to find in `jigs status`. Kind and identity
together name the record; registering again updates its URL. Create external
resources in a separate step when creation is not safe to repeat, then register
them here so registration retries cannot repeat creation. The record is observation
only: jigs never deletes what it names. The kinds jigs records and releases itself
(`worktree`, `branch`, `run-directory`, `codex-home`, `pi-home`, `claude-plugins`) are reserved.

***

### release() {#release}

```ts
function release(policy?): Promise<ReleaseReport>;
```

Release this run's resources now and return the report. The service already does this when
the run ends; call it to release early, to read the report, or to pass this run's policy.

#### Parameters

| Parameter | Type | Description |
| :------ | :------ | :------ |
| `policy?` | { `onFailure`: `"release"` | `"keep"`; `onSuccess`: `"release"` | `"keep"`; } | - |
| `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. |

#### Returns

`Promise`<[`ReleaseReport`](../jigs.md#releasereport)>

***

### removeRunDirectory() {#removerundirectory}

```ts
function removeRunDirectory(): Promise<void>;
```

Remove this run's scratch directory after its work is complete.

#### Returns

`Promise`<`void`>

## Linear agent sessions

### executeLinearAgentTurn() {#executelinearagentturn}

```ts
function executeLinearAgentTurn(request): Promise<TurnStepResult>;
```

Run one turn of a conversation in a Linear agent session, posting its status and answers there.
Use linearAgentConversation() to hold the whole conversation.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `request` | [`LinearAgentTurnRequest`](../steps/linear.md#linearagentturnrequest) |

#### Returns

`Promise`<`TurnStepResult`>

***

### listLinearAgentSessionPrompts() {#listlinearagentsessionprompts}

```ts
function listLinearAgentSessionPrompts(session): Promise<LinearAgentPrompt[]>;
```

Read every message people sent into a Linear agent session, oldest first.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `session` | { `installationName`: `string`; `sessionId`: `string`; } |
| `session.installationName` | `string` |
| `session.sessionId` | `string` |

#### Returns

`Promise`<[`LinearAgentPrompt`](../steps/linear.md#linearagentprompt)\[]>

***

### openLinearAgentSession() {#openlinearagentsession}

```ts
function openLinearAgentSession(request): Promise<{
  sessionId: string;
}>;
```

Open a Linear agent session on an issue as the factory's app, linked to this run.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `request` | { `installationName`: `string`; `issueId`: `string`; } |
| `request.installationName` | `string` |
| `request.issueId` | `string` |

#### Returns

`Promise`<{
`sessionId`: `string`;
}>

***

### postLinearAgentActivity() {#postlinearagentactivity}

```ts
function postLinearAgentActivity(request): Promise<{
  createdAt: string;
  id: string;
}>;
```

Post a thought, action, elicitation, response or error into a Linear agent session as the
factory's app.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `request` | { `content`: [`LinearAgentActivityContent`](../steps/linear.md#linearagentactivitycontent); `ephemeral?`: `boolean`; `installationName`: `string`; `once?`: `string`; `sessionId`: `string`; } |
| `request.content` | [`LinearAgentActivityContent`](../steps/linear.md#linearagentactivitycontent) |
| `request.ephemeral?` | `boolean` |
| `request.installationName` | `string` |
| `request.once?` | `string` |
| `request.sessionId` | `string` |

#### Returns

`Promise`<{
`createdAt`: `string`;
`id`: `string`;
}>

***

### setLinearAgentSessionUrls() {#setlinearagentsessionurls}

```ts
function setLinearAgentSessionUrls(request): Promise<void>;
```

Replace the links a Linear agent session shows, after the run's dashboard.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `request` | { `installationName`: `string`; `sessionId`: `string`; `urls`: `object`\[]; } |
| `request.installationName` | `string` |
| `request.sessionId` | `string` |
| `request.urls` | `object`\[] |

#### Returns

`Promise`<`void`>