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

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>

---

postTicketHumanInputRequest()

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; installationName: string; issueId: string; sessionId: string; }
request.halt	Halt
request.installationName	string
request.issueId	string
request.sessionId	string

Returns

Promise<void>

---

postTicketNote()

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; sessionId: string; }
request.installationName	string
request.issueId	string
request.note	TicketNote
request.sessionId	string

Returns

Promise<void>

---

resolveLinearIssue()

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

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>

PagerDuty incidents

fetchIncidentSnapshot()

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>

---

postIncidentNote()

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

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

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

Parameters

Parameter	Type
pullRequest	PullRequestRef
body	string

Returns

Promise<{ id: number; }>

---

createPullRequest()

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; }
request.body	string
request.draft?	boolean
request.title	string
request.worktree	Worktree

Returns

Promise<OpenedPullRequest>

---

fetchPullRequestState()

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

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

Parameters

Parameter	Type
pullRequest	PullRequestRef
options?	PullRequestReadOptions

Returns

Promise<PullRequestSnapshot>

---

markPullRequestReady()

function markPullRequestReady(pullRequest): Promise<PullRequestSnapshot>;

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

Parameters

Parameter	Type
pullRequest	PullRequestRef

Returns

Promise<PullRequestSnapshot>

---

mergePullRequest()

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
expectedHeadSha	string
options?	MergeOptions

Returns

Promise<MergeOutcome>

---

replyToPullRequestReviewThread()

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

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

Parameters

Parameter	Type
pullRequest	PullRequestRef
rootCommentId	number
body	string

Returns

Promise<{ id: number; }>

---

reviewPullRequest()

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

Post a review on a pull request.

Parameters

Parameter	Type
pullRequest	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()

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>

---

postSlackMessage()

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

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

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

Parameters

Parameter	Type
worktree	Worktree
approvedCommit	string

Returns

Promise<{ headSha: string; }>

---

pushBranch()

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

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

Parameters

Parameter	Type
worktree	Worktree

Returns

Promise<{ headSha: string; }>

---

readBranchState()

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
baseSha?	string

Returns

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

---

readChange()

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
base?	string

Returns

Promise<ChangeSummary>

---

readPatch()

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
base	string
head	string
paths	string[]

Returns

Promise<ChangePatch>

---

readWorktreeDiff()

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
baseSha?	string

Returns

Promise<string>

Agent execution

executeAgent()

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

Returns

Promise< | AgentResult | { jitFailure: object & object[]; } | { resumeFailed: string; }>

---

executeJev()

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

Execute typed decision questions against one shared state.

Type Parameters

Type Parameter
QUESTIONS extends JevQuestions

Parameters

Parameter	Type
request	AskJevOptions<QUESTIONS>

Returns

Promise<JevResult<QUESTIONS>>

---

executeModel()

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

Returns

Promise<ModelResult>

Workspaces and resources

createRunDirectory()

function createRunDirectory(): Promise<string>;

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

Returns

Promise<string>

---

listBindings()

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

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

Returns

Promise<RepositoryRef & object[]>

---

provisionPullRequestWorktree()

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

Returns

Promise<PullRequestWorktree>

---

provisionWorktree()

function provisionWorktree(request): Promise<Worktree>;

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

Parameters

Parameter	Type
request	WorktreeRequest

Returns

Promise<Worktree>

---

registerResource()

function registerResource(resource): Promise<RunResource>;

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

Parameters

Parameter	Type
resource	RunResource

Returns

Promise<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()

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>

---

removeRunDirectory()

function removeRunDirectory(): Promise<void>;

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

Returns

Promise<void>

Linear agent sessions

executeLinearAgentTurn()

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

Returns

Promise<TurnStepResult>

---

listLinearAgentSessionPrompts()

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[]>

---

openLinearAgentSession()

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

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; ephemeral?: boolean; installationName: string; once?: string; sessionId: string; }
request.content	LinearAgentActivityContent
request.ephemeral?	boolean
request.installationName	string
request.once?	string
request.sessionId	string

Returns

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

---

setLinearAgentSessionUrls()

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>