Class RunHandle

constructor

• new RunHandle(
      client: ApiClient,
      runId: string,
      threadId: string,
      options?: RunHandleOptions,
  ): RunHandle

  Creates the handle of a run that has not started yet.

  Parameters

  • client: ApiClient

    The client of the adapter.

  • runId: string

    The run.

  • threadId: string

    The run's thread.

  • options: RunHandleOptions = {}

    Outbox, settings and the onWaiting callback.

  Returns RunHandle

Readonlyclient

finished

Readonlyoutbox

ReadonlyrunId

ReadonlythreadId

tokenJti

waiting

cancelled

• get cancelled(): AbortSignal

  Aborted when the run was cancelled or ended on the server; hand it to the runtime so its work stops (run.cancel_requested, run_not_active, run_inactive).

  Returns AbortSignal

patch

• get patch(): RunPatcher

  The live-box patcher.

  Returns RunPatcher

  Throws

  Error when the run has not started yet (inside prepare).

startedPatcher

• get startedPatcher(): RunPatcher | undefined

  The patcher once the run started, else undefined.

  Returns RunPatcher | undefined

version

• get version(): number

  The run document version the patcher works on (0 before the start).

  Returns number

awaitInput

• awaitInput(statusLine: string): Promise<void>

  Waits for a person (awaitRunInput); the run goes to waiting_input.

  Pending patches are sent first. The adapter resumes the run with the token of the next follow-up or interaction.

  Parameters

  • statusLine: string

    What the run waits for.

  Returns Promise<void>

  A promise that resolves when the run waits.

  Throws

  ProblemError when the patch or awaitRunInput was refused.

finish

• finish(
      state: "failed" | "cancelled" | "completed",
      options?: FinishOptions,
  ): Promise<void>

  Ends the run (finishRun) after sending pending patches.

  A final flush refused by the server or without an answer is dropped, and a finishRun answered with run_inactive or run_not_active counts as already ended, not as an error; the server answers a repeated equal end state with 200. A second call does nothing.

  Parameters

  • state: "failed" | "cancelled" | "completed"

    completed, failed or cancelled.

  • options: FinishOptions = {}

    reason, summary, metrics and costs.

  Returns Promise<void>

  A promise that resolves when the run has ended.

  Throws

  ProblemError for another refusal of the server.

loadContext

• loadContext(): Promise<{}>

  Loads the run context (getRunContext); render it with renderContext.

  Returns Promise<{}>

  The context.

  Throws

  ProblemError when the server refused.

onCancel

• onCancel(callback: () => void): () => void

  Registers a callback for the cancellation; after it, the callback runs at once.

  Parameters

  • callback: () => void

    Called once when the run is cancelled or ended on the server.

  Returns () => void

  A function that removes the callback.

reportSession

• reportSession(report: {}, options?: ReportSessionOptions): Promise<{}>

  Reports the agent session of this run in its thread (reportAgentSession, 09 9.1 and 9.5).

  If-Match is the compare-and-swap over the session row's version: absent when the run has no row yet (the report creates it), otherwise the version of the row. Each call carries a fresh Idempotency-Key, so the client may repeat it after a lost answer.

  Parameters

  • report: {}

    The AgentSessionReport (external_session_ref, model, started, bind_failed).

  • options: ReportSessionOptions = {}

    ifMatch, the row version.

  Returns Promise<{}>

  The session row; its version is the next ifMatch.

  Throws

  ProblemError, for example 412 version_conflict or 409 conflict with session_bound_elsewhere, session_changed or session_not_bound.

send

• send(
      contentMd: string,
      options?: Readonly<Record<string, unknown>>,
  ): Promise<unknown>

  Sends a reply in the run's thread through the outbox, with runId set.

  Parameters

  • contentMd: string

    The Markdown text.

  • options: Readonly<Record<string, unknown>> = {}

    Further options of the outbox's sendMessage.

  Returns Promise<unknown>

  The outbox entry.

  Throws

  Error when the handle has no outbox.

setCancelled

• setCancelled(): void

  Marks the run as cancelled and calls the cancel callbacks (once).

  The adapter calls it for run.cancel_requested; the patcher calls it when the server says the run has ended.

  Returns void

started

• started(run: {}, tokenJti: string): void

  Notes that startRun or resumeRun answered 200 with run.

  Parameters

  • run: {}

    The answered run (its version is the patch base).

  • tokenJti: string

    The jti the run started or resumed with.

  Returns void