Skip to main content

NewRun

@forge/monorepo

@forge/monorepo / backend/src / NewRun

Type Alias: NewRun

NewRun = object

Defined in: backend/src/persistence/index.ts:163

Properties​

agentId​

readonly agentId: AgentId

Defined in: backend/src/persistence/index.ts:179

agentVersion​

readonly agentVersion: number

Defined in: backend/src/persistence/index.ts:180

conversationId?​

readonly optional conversationId?: ConversationId

Defined in: backend/src/persistence/index.ts:178

The conversation this run belongs to, or absent for a run that belongs to none — #198.

Required until now, which meant a triggered automation — a webhook, a schedule, a flow step — had to invent a conversation id to exist at all. That is #164 exactly: Run carried no principal, so every host fabricated one, the shipped example used "example-worker", and every per-person figure silently became a machine's. Nothing failed. A fabricated conversation id would do the same to every conversation-scoped query, and it would look like data.

Absent is a fact about the run, not a missing field: the conversation-scoped capabilities — history, compaction, thread summaries — are then unavailable rather than operating on nothing. Asking for them is a programming error and says so.

id​

readonly id: RunId

Defined in: backend/src/persistence/index.ts:164

input?​

readonly optional input?: unknown

Defined in: backend/src/persistence/index.ts:206

What this run was asked to do — #202.

Added because a conversation-less run had nowhere to carry its request. #198 made a run able to exist without a conversation, and a triggered automation or a flow's agent step is exactly that — but the only place a prompt could live was a Message, and Message.conversationId is required. So the shape said a run needs no conversation while the storage said its input does.

A property of the run rather than a message, which is also the more honest model: a webhook's payload and a flow step's brief are the run's input, not something somebody said in a thread. A run inside a conversation still reads its history; this is for the runs that have none.

limits?​

readonly optional limits?: object

Defined in: backend/src/persistence/index.ts:216

Per-run ceilings, overriding the agent manifest's — #202 AC-3.

A flow derives these from what it has left to spend, re-derived per step, so a member cannot outspend the team. Without them the child would take the manifest's limits, which are a property of the agent and therefore the same for every member of every team — and a team's budget would bound nothing.

Partial on purpose: a caller narrowing one dimension should not have to restate the rest.

costCeilingMinorUnits?​

readonly optional costCeilingMinorUnits?: number

maxSteps?​

readonly optional maxSteps?: number

wallClockTimeoutMs?​

readonly optional wallClockTimeoutMs?: number

principalId?​

readonly optional principalId?: PrincipalId

Defined in: backend/src/persistence/index.ts:192

Who this run is for, and with what roles — #164.

Optional on the type only so existing callers keep compiling; supplying it is what lets a durable worker rebuild the caller's identity instead of inventing one. A run carried a tenant and nothing else, so buildContext(run) had no principal to return and every host fabricated one — the shipped example used "example-worker" with roleIds: ["editor"], which attributed every person's memory to one identity and ran a viewer's admitted run with editor rights.

Recorded at admission, from the authenticated caller. Never from anything the model produced.

roleIds?​

readonly optional roleIds?: readonly string[]

Defined in: backend/src/persistence/index.ts:193