Runs

ActivityStep

interface declared in resources/activity.ts

One tool call rendered as an activity step.

cursorFromRequest

function declared in resources/forward.ts

Native EventSource sends Last-Event-ID on reconnect; it takes precedence over the URL cursor.

(request: Request) => number

DescribeTool

type declared in resources/activity.ts

Turn a streamed tool call into a label, or return null to omit it.

(tool: string, summary: string) => string | null

describeToolDefault

variable declared in resources/activity.ts

Plain labels for the tools every node can use.

(tool: string, summary: string) => string | null

followActivity

function declared in resources/activity.ts

Yield an immutable activity snapshot after every streamed tool-call change.

(stream: AsyncIterable<NodeStreamEvent>, options?: { describe?: DescribeTool; }) => AsyncGenerator<ActivityStep[]>

forwardRunEvents

function declared in resources/forward.ts

(crouter: AppClient, runId: string, options: { after: number; signal?: AbortSignal; }) => Response

JsonSchema

type declared in types.ts

A JSON Schema object. The daemon validates structured results against it.

{ [x: string]: unknown; }

OutputSchema

type declared in types.ts

A structured-result schema: a JSON string, a JSON Schema object, or anything exposing toJSONSchema() — which a Zod v4 object does.

string | JsonSchema | { toJSONSchema(): JsonSchema; }

PendingRun

interface declared in resources/run-watcher.ts

A run the app is still waiting on: whose runtime holds it, and its id. pending() returns these from the app's own rows.

RequestOptions

interface declared in types.ts

The final argument of every request-capable method.

RUN_NOTICE_SCOPE

variable declared in resources/run-notice.ts

The scope a run-notice token carries.

RunActivity

type declared in resources/runs.ts

RunObject.activity while the run is running.

{ phase: 'starting' | 'thinking' | 'writing' | 'submitting_result' | 'between_turns'; } | { phase: 'tool'; tool: { name: string; summary: string | null; }; }

RunActivityEvent

interface declared in resources/run-watcher.ts

One live-progress reading RunWatcher hands to onActivity: a running run's activity and the runs.get answer it came from.

RunDeleteResult

interface declared in resources/runs.ts

RunEnded

type declared in resources/run-watcher.ts

One ending RunWatcher hands to onEnded. run is the runs.get answer that came to rest, or null when gone.

{ userId: string; runId: string; ended: Exclude<RunEnding, 'gone'>; run: RunObject; } | { userId: string; runId: string; ended: 'gone'; run: null; } | { userId: string; runId: string; ended: 'unknown'; status: string; run: RunObject; }

RunEnding

type declared in resources/run-watcher.ts

How a watched run came to rest. gone: the runtime answered 404 not_found for it (the run was deleted).

"gone" | "idle" | "settled" | "waiting_on_user"

RunEventListener

type declared in resources/run-stream.ts

(event: RunEventOf<T>) => void

RunNotice

interface declared in resources/run-notice.ts

RunNoticeError

class declared in resources/run-notice.ts

A run notice that failed verification. An app maps it to HTTP 401 and stores nothing.

RunObject

interface declared in resources/runs.ts

RunParsedOutcome

type declared in resources/runs.ts

A settled runs.parse run: the run outcome plus output_parsed, typed to the schema and non-null exactly when kind is result.

((({ node_id: import("@north-light/api").NodeIdDTO; revision: number; settled_at: import("@north-light/api").IsoTime; final_report: string | null; structured_result: unknown | null; detail: import("@north-light/api").NodeOutcomeDetailV1 | null; } & { kind: 'failure'; reason: 'declined'; declined: import("@north-light/api").DeclinedResultDTO | null; details: import("@north-light/api").DeclinedResultDTO | null; }) | ({ node_id: import("@north-light/api").NodeIdDTO; revision: number; settled_at: import("@north-light/api").IsoTime; final_report: string | null; structured_result: unknown | null; detail: import("@north-light/api").NodeOutcomeDetailV1 | null; } & { kind: 'failure'; reason: 'canceled' | 'deadline_exceeded' | 'cap_exhausted'; declined: null; }) | ({ node_id: import("@north-light/api").NodeIdDTO; revision: number; settled_at: import("@north-light/api").IsoTime; final_report: string | null; structured_result: unknown | null; detail: import("@north-light/api").NodeOutcomeDetailV1 | null; } & { kind: 'failure'; reason: 'runtime_error'; declined: null; details: { crouter_reason: string; }; })) & { output_parsed: null; }) | ({ node_id: import("@north-light/api").NodeIdDTO; revision: number; settled_at: import("@north-light/api").IsoTime; final_report: string | null; structured_result: unknown | null; detail: import("@north-light/api").NodeOutcomeDetailV1 | null; } & { kind: 'result'; reason: 'finalized'; declined: null; } & { output_parsed: T; })

RunParseOptions

interface declared in resources/runs.ts

RunParseParams

type declared in resources/runs.ts

runs.parse params: runs.start's, with output_schema required.

RunReply

class declared in resources/run-reply.ts

The reply to one message: the root's turn that delivers it. Consume it once: iterate it, or call collect() (text plus how it ended, with an optional onDelta while it streams) or text(). It ends after turn.completed (or run.settled) and closes its event stream; aborting the signal rejects with APIUserAbortError.

RunReplyCollectOptions

interface declared in resources/run-reply.ts

RunReply.collect options.

RunReplyEnding

type declared in resources/run-reply.ts

How a reply ended (RunReply.collect): - completed: the turn finished cleanly; text may still be empty when the model wrote nothing. - error: the turn's last assistant message failed; error says why. - waiting_on_user: the turn ended on a question to the person; the run waits for an answer. - settled: the run settled before the turn completed; outcome says how.

"completed" | "error" | "settled" | "waiting_on_user"

RunReplyEvent

type declared in resources/run-reply.ts

One event of the reply to a message (runs.reply).

{ type: 'text.delta'; delta: string; sequence_number: number; } | { type: 'message.done'; text: string; stop_reason: AssistantStopReasonDTO; sequence_number: number; } | { type: 'turn.completed'; run_status: Exclude<RunStatusDTO, 'settled'>; stop_reason: string; error?: TurnErrorDTO; message_ids: string[]; sequence_number: number; } | { type: 'run.settled'; outcome: RunOutcomeDTO; sequence_number: number; }

RunReplyResult

interface declared in resources/run-reply.ts

The whole reply, from RunReply.collect.

RunStartParams

interface declared in resources/runs.ts

RunStartResult

interface declared in resources/runs.ts

RunStatus

type declared in resources/runs.ts

"idle" | "running" | "settled" | "waiting_on_user"

RunStream

class declared in resources/run-stream.ts

A resumable run event stream. Closing it does not stop the run.

Iteration ends normally in exactly two cases, told apart by idle: the run settled (idle is false) or the runtime sent event: idle and closed (idle is true: the run is quiet, nothing is lost, and cursor is where to reopen with runs.events(runId, {after: cursor}) when there is something to read). After the idle frame the stream does not reconnect on its own. A transport or protocol failure throws instead, as before.

RunStreamEnd

interface declared in resources/run-stream.ts

How a RunStream ended without an error: the run settled, or the runtime closed an idle stream (no running turn and no new event for its quiet window) and cursor is where to reopen it.

RunTrace

type declared in resources/runs.ts

runs.trace in its rendered form; message content narrows on type and role fields on role.

RunWatcher

class declared in resources/run-watcher.ts

Follows an app's background runs until each comes to rest (settled, idle, waiting_on_user, or deleted), and hands each ending to onEnded at least once. Build it with oauth.watchRuns(...), then start().

Delivery is keyed in memory on (runId, status, latest_sequence): a run still in pending() after delivery is re-read once per sweep without wait and delivered again only when that key changes (it worked again, or an idle run was later canceled to settled); a sweep that reads running goes back to the long-poll. The app's rows are the durable record, so a restarted watcher re-derives everything from pending().

With onActivity, each running read whose activity (as JSON) differs from the last handed over is reported, and running runs are read with a short wait (activityWait), since the runtime's long-poll answers early only at rest.

RunWatchOptions

interface declared in resources/run-watcher.ts

SchemaOutput

type declared in types.ts

The value type an OutputSchema describes, inferred from a Zod or Standard Schema object.

T extends { _output: infer Output; } ? Output : T extends { '~standard': { types?: { output: infer Output; }; }; } ? Output : unknown

SentRunMessage

interface declared in resources/run-reply.ts

What runs.message returns: the message a reply answers.

UnknownRunEvent

type declared in resources/run-stream.ts

An event under a type this SDK version does not declare (a newer daemon's), or read by field name.

verifyRunNotice

function declared in resources/run-notice.ts

Verify a runtime→app run notice: the bearer is a directory-signed outbound token for runNoticeUrl (signature, iss, aud, exp), scope exactly crtr:run_notice, grantee the app's own principal; the body is {run_id, latest_sequence}. Throws RunNoticeError (answer 401) on any failure.

(request: Request, options: VerifyRunNoticeOptions) => Promise<RunNotice>

VerifyRunNoticeOptions

interface declared in resources/run-notice.ts