steps/linear

Low-level Linear operations for factory-owned steps. #jigs/steps wraps the ones jigs routines and recipes use, such as postTicketNote; call the rest, such as createComment, from your own "use step" function. Higher-level waiting such as haltForHuman comes from #jigs/routines.

See Waiting and external events.

Resolve and read

LinearIssueMatch

A matching Linear ticket returned by a project title search.

Properties

Property	Type
description	string
id	string
identifier	string
state	string
title	string
url	string

---

fetchTicketSnapshot()

function fetchTicketSnapshot(__namedParameters): Promise<TicketSnapshot>;

Read the ticket’s current details and discussion.

Parameters

Parameter	Type
__namedParameters	{ installationName: string; issueId: string; }
__namedParameters.installationName	string
__namedParameters.issueId	string

Returns

Promise<TicketSnapshot>

---

findIssueInProject()

function findIssueInProject(__namedParameters): Promise<LinearIssueMatch | null>;

Find the newest ticket in a project whose title starts with the given text.

Parameters

Parameter	Type
__namedParameters	{ installationName: string; project: string; titlePrefix: string; }
__namedParameters.installationName	string
__namedParameters.project	string
__namedParameters.titlePrefix	string

Returns

Promise<LinearIssueMatch | null>

---

resolveLinearIssue()

function resolveLinearIssue(__namedParameters): Promise<LinearIssueRef>;

Resolve a Linear identifier or issue ID before claiming or reading the ticket.

Parameters

Parameter	Type
__namedParameters	{ installationName: string; reference: string; }
__namedParameters.installationName	string
__namedParameters.reference	string

Returns

Promise<LinearIssueRef>

Create and update

CreateIssueInProjectInput

Fields used to create a Linear ticket in a project's first team.

Properties

Property	Type
description	string
project	string
title	string

---

TicketStatusResult

The before-and-after state names from a ticket status update.

Properties

Property	Type
changed	boolean
from	string
to	string

---

createComment()

function createComment(__namedParameters): Promise<{
  createdAt: string;
  id: string;
}>;

Post a comment on a ticket. An id (UUID v4) names the comment in advance, so a caller can find it again after a lost response instead of posting twice.

Parameters

Parameter	Type
__namedParameters	{ body: string; id?: string; installationName: string; issueId: string; }
__namedParameters.body	string
__namedParameters.id?	string
__namedParameters.installationName	string
__namedParameters.issueId	string

Returns

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

---

createIssueInProject()

function createIssueInProject(__namedParameters): Promise<{
  id: string;
  identifier: string;
  url: string;
}>;

Create a ticket in the project’s first team.

Parameters

Parameter	Type
__namedParameters	CreateIssueInProjectInput & object

Returns

Promise<{ id: string; identifier: string; url: string; }>

---

setTicketStatus()

function setTicketStatus(__namedParameters): Promise<TicketStatusResult>;

Set a ticket to one of its team's named states.

Parameters

Parameter	Type
__namedParameters	{ installationName: string; issueId: string; stateName: string; }
__namedParameters.installationName	string
__namedParameters.issueId	string
__namedParameters.stateName	string

Returns

Promise<TicketStatusResult>

Human interaction primitives

postTicketHumanInputRequest()

function postTicketHumanInputRequest(
   __namedParameters, 
   metadata, 
render): Promise<void>;

Ask in the run's Linear agent session for a person to help the run continue.

Parameters

Parameter	Type	Default value
__namedParameters	{ halt: Halt; installationName: string; issueId: string; sessionId: string; }	undefined
__namedParameters.halt	Halt	undefined
__namedParameters.installationName	string	undefined
__namedParameters.issueId	string	undefined
__namedParameters.sessionId	string	undefined
metadata	StepRunMetadata	undefined
render	RenderHumanInputRequest	renderHumanInputRequest

Returns

Promise<void>

Remarks

Posts the halt as an elicitation, which shows the session as waiting for input. Mentions the factory's linear.operator, or the ticket's creator when it is not set, then the assignee and the halt's mention emails, each person once. A person Linear cannot find is skipped with a warning; the question always posts. A changed operator takes effect when the service restarts, which jigs up does.

---

postTicketNote()

function postTicketNote(
   __namedParameters, 
   metadata, 
render): Promise<void>;

Tell ticket participants something in the run's Linear agent session, without waiting for a reply.

Parameters

Parameter	Type	Default value
__namedParameters	{ installationName: string; issueId: string; note: TicketNote; sessionId: string; }	undefined
__namedParameters.installationName	string	undefined
__namedParameters.issueId	string	undefined
__namedParameters.note	TicketNote	undefined
__namedParameters.sessionId	string	undefined
metadata	StepRunMetadata	undefined
render	RenderTicketNote	renderTicketNote

Returns

Promise<void>

Remarks

A note that ends the run is the session's final response, even for a failure: Linear offers Retry on a session that ends in an error, and a run that has ended cannot take it. A note that waits on people is an elicitation, which shows the session as awaiting input. Any other note is a response followed by a short thought, which keeps the session working so Stop still ends the run. Mentions in each of them notify. Mentions the same people as postTicketHumanInputRequest, with the note's mention emails as the extras.

Rendering/customization

HumanInputContext

type HumanInputContext = object;

What the question's footer says about the run that asked it. The factory's step wrapper builds it from the Workflow SDK's metadata, which the workflow cannot see. Where the run paused belongs to the halt, not the context: only the routine that raised it knows.

Properties

Property	Type
runId	string
workflow?	string

---

RenderHumanInputRequest()

type RenderHumanInputRequest = (halt, context, participants) => string;

Renders the question that asks a person to unblock a run.

Parameters

Parameter	Type
halt	Halt
context	HumanInputContext
participants	TicketParticipants

Returns

string

---

RenderTicketNote()

type RenderTicketNote = (note, participants) => string;

Renders a note for ticket participants that asks for nothing.

Parameters

Parameter	Type
note	TicketNote
participants	TicketParticipants

Returns

string

---

TicketParticipants

type TicketParticipants = object;

Who the message is for. mentions is the final list the message greets, in order and each person once: the operator (or, without one, the ticket's creator), the assignee, then any extra people the step was asked to mention. A custom renderer greets mentions rather than working it out again; the other fields are there for context and may be null.

Properties

Property	Type	Description
assignee	LinearProfile | null	-
creator	LinearProfile | null	-
mentions	LinearProfile[]	-
operator	LinearProfile | null	The configured operator, or null when none is set or Linear could not find them.

---

renderHumanInputRequest

const renderHumanInputRequest: RenderHumanInputRequest;

Render the default question as Linear Markdown.

---

renderTicketNote

const renderTicketNote: RenderTicketNote;

Render the default ticket note as Linear Markdown.

Linear agent sessions

LinearAgentActivityContent

type LinearAgentActivityContent = 
  | {
  body: string;
  type: "thought";
}
  | {
  action: string;
  parameter: string;
  result?: string;
  type: "action";
}
  | {
  body: string;
  type: "elicitation";
}
  | {
  body: string;
  type: "response";
}
  | {
  body: string;
  type: "error";
};

What the factory's app posts into a Linear agent session. A thought or an action shows progress; an elicitation asks the person for input; a response or an error ends the app's turn, and Linear waits for the person.

---

LinearAgentPrompt

type LinearAgentPrompt = object;

One message a person sent into a Linear agent session, oldest first when listed.

Remarks

signal is null for a plain reply and "stop" when the person pressed stop; Linear also names continue, auth and select. sourceCommentId is the comment the reply was written as, and is null for a stop.

Properties

Property	Type
author	object
author.id	string
author.name	string
body	string
createdAt	string
id	string
signal	string | null
sourceCommentId	string | null

---

executeLinearAgentTurn()

function executeLinearAgentTurn(
   request, 
   metadata, 
deps): Promise<TurnStepResult>;

Run one turn of a conversation in a Linear agent session.

Parameters

Parameter	Type	Default value
request	LinearAgentTurnRequest	undefined
metadata	StepRunMetadata	undefined
deps	LinearAgentTurnDeps	defaultDeps

Returns

Promise<TurnStepResult>

Remarks

The turn takes the opening mention, if given, and every reply in the session not in consumed, so a retry takes the replies that arrived while the turn ran. A stop among them ends the turn stopped before it starts. While the turn runs, a status line is posted as an ephemeral thought, at most every five seconds, and each answer is posted as a response once written.

---

listLinearAgentSessionPrompts()

function listLinearAgentSessionPrompts(__namedParameters): Promise<LinearAgentPrompt[]>;

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

Parameters

Parameter	Type
__namedParameters	{ installationName: string; sessionId: string; }
__namedParameters.installationName	string
__namedParameters.sessionId	string

Returns

Promise<LinearAgentPrompt[]>

Remarks

The mention that opened the session is not one of them. A message whose signal is "stop" is the person pressing stop.

---

openLinearAgentSession()

function openLinearAgentSession(__namedParameters, metadata): Promise<{
  sessionId: string;
}>;

Open a Linear agent session on an issue as the factory's app, showing the run's dashboard when the service hosts one, and return its id.

Parameters

Parameter	Type
__namedParameters	{ installationName: string; issueId: string; }
__namedParameters.installationName	string
__namedParameters.issueId	string
metadata	RunMetadata

Returns

Promise<{ sessionId: string; }>

Remarks

Linear starts the session at once. Its create call takes no id of its own, so a retry after a lost response may open a second session.

---

postLinearAgentActivity()

function postLinearAgentActivity(__namedParameters, metadata): Promise<{
  createdAt: string;
  id: string;
}>;

Post an activity into a Linear agent session as the factory's app.

Parameters

Parameter	Type
__namedParameters	{ content: LinearAgentActivityContent; ephemeral?: boolean; installationName: string; once?: string; sessionId: string; }
__namedParameters.content	LinearAgentActivityContent
__namedParameters.ephemeral?	boolean
__namedParameters.installationName	string
__namedParameters.once?	string
__namedParameters.sessionId	string
metadata	Pick<StepRunMetadata, "workflowRunId" | "stepId">

Returns

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

Remarks

Only a thought or an action may be ephemeral; Linear replaces an ephemeral activity with the next one. Every retry of one step posts the same activity, so a lost response never posts it twice. With once, the activity is posted at most once per key in the session, from any step.

---

setLinearAgentSessionUrls()

function setLinearAgentSessionUrls(__namedParameters, metadata): Promise<void>;

Replace the links a Linear agent session shows, such as a pull request. The run's dashboard comes first when the service hosts one.

Parameters

Parameter	Type
__namedParameters	{ installationName: string; sessionId: string; urls: object[]; }
__namedParameters.installationName	string
__namedParameters.sessionId	string
__namedParameters.urls	object[]
metadata	RunMetadata

Returns

Promise<void>

Type Aliases

LinearAgentTurnRequest

type LinearAgentTurnRequest = object;

One turn of a conversation in a Linear agent session: the harness and worktree it runs in, the mention that opened the session until a turn takes it, and consumed, the ids of the messages earlier turns took. The turn takes every newer reply in the session.

Properties

Property	Type
consumed	string[]
cwd	string
harness	Harness
installationName	string
instructions?	string
opening?	ConversationMessage
sessionId	string