Runs

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.

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"

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.

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"

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

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