Class RunPatcher

constructor

• new RunPatcher(
      client: ApiClient,
      runId: string,
      baseVersion: number,
      options?: RunPatcherOptions,
  ): RunPatcher

  Creates the patcher.

  Parameters

  • client: ApiClient

    The REST client (bound to the run by the caller, 07 SR9).

  • runId: string

    The run.

  • baseVersion: number

    The version of the Run that startRun or resumeRun answered.

  • options: RunPatcherOptions = {}

    Settings, clock and the onEnded callback.

  Returns RunPatcher

baseVersion

Readonlyclient

Readonlyclock

ended

patchesSent

ReadonlyrunId

Readonlysettings

aclose

• aclose(): Promise<void>

  Stops the throttle timer without sending; a patch already on its way completes.

  Returns Promise<void>

  A promise that resolves when the timer has stopped.

addStep

• addStep(kind: string, name: string, options?: AddStepOptions): string

  Adds a step; its ID is a UUIDv7 of the adapter, the server assigns ordinal.

  Parameters

  • kind: string

    tool_call, subagent, background_job, workflow or status.

  • name: string

    The step name.

  • options: AddStepOptions = {}

    title, status, parentStepId and detail.

  Returns string

  The step ID.

clearLastApiRetry

• clearLastApiRetry(): void

  Removes /metrics/last_api_retry.

  Returns void

clearPlan

• clearPlan(): void

  Removes /plan.

  Returns void

clearStatusLine

• clearStatusLine(): void

  Removes /status_line.

  Returns void

flush

• flush(): Promise<void>

  Sends the pending changes now (one patch), rebasing after a version conflict.

  A patch that finds the run ended stops the patcher and returns. After a transient refusal (5xx, 429, a conflict that outlasted the rebases) or a transport error the changes stay pending, values set meanwhile win; a permanent refusal (for example 400 validation_failed) drops the patch, so one bad value never blocks the later updates.

  Returns Promise<void>

  A promise that resolves when the patch was sent (or there was nothing to send).

  Throws

  ProblemError for a refusal other than the end of the run, or the version conflict after sdk.retry_max_attempts rounds; TransportError when no answer arrived.

followupAbsorbed

• followupAbsorbed(messageId: string): void

  Marks a follow-up as absorbed by the runtime.

  Parameters

  • messageId: string

    The follow-up message.

  Returns void

  Throws

  RangeError when the follow-up is already absorbed.

followupDelivered

• followupDelivered(messageId: string): void

  Marks a follow-up as delivered to the runtime.

  Parameters

  • messageId: string

    The follow-up message.

  Returns void

  Throws

  RangeError when the follow-up is already further.

onGatewayError

• onGatewayError(error: GatewayOpError): Promise<void>

  Handles an error frame of a run.update of this run.

  base_version_conflict loads getRun and sends the last ops again on its version; conflict (run_not_active) ends the patcher.

  Parameters

  • error: GatewayOpError

    The error of the frame.

  Returns Promise<void>

  A promise that resolves when the reaction is done.

  Throws

  ProblemError when getRun fails.

sendOps

• sendOps(ops: readonly {}[]): Promise<number>

  Sends raw RFC 6902 operations at once, after checking them against PATCH_PATHS.

  Parameters

  • ops: readonly {}[]

    The operations.

  Returns Promise<number>

  The new version.

  Throws

  PatchPathError when an operation names a path or op outside 09 5.3 (before any request); ProblemError when the server refused.

  Example

  await patcher.sendOps([{ op: "replace", path: "/status_line", value: "Reading" }]);
  Copy

setCost

• setCost(amountMicros: number, currency: string): void

  Sets /cost; always an estimate (is_estimate: true).

  Parameters

  • amountMicros: number

    The amount in millionths of the currency unit.

  • currency: string

    The ISO 4217 code.

  Returns void

setLastApiRetry

• setLastApiRetry(attempt: number, options?: LastApiRetryOptions): void

  Sets /metrics/last_api_retry.

  Parameters

  • attempt: number

    The attempt number.

  • options: LastApiRetryOptions = {}

    maxRetries, retryDelayMs and error, each if known.

  Returns void

setLastTextExcerpt

• setLastTextExcerpt(text: string): void

  Sets /last_text_excerpt (the server keeps its last run.excerpt_max_chars).

  Parameters

  • text: string

    The draft text so far.

  Returns void

setMetric

• setMetric(name: string, value: number): void

  Sets /metrics/<name>.

  Parameters

  • name: string

    One of METRIC_FIELDS (MetricField); a plain string is checked at run time.

  • value: number

    The number.

  Returns void

  Throws

  RangeError when name is not a metric of run_metrics.v1.

setModel

• setModel(model: string): void

  Sets /model.

  Parameters

  • model: string

    The model name of the runtime.

  Returns void

setPlan

• setPlan(items: readonly PlanItem[]): void

  Sets /plan.

  Parameters

  • items: readonly PlanItem[]

    Plan items with id, text and status.

  Returns void

setStatusLine

• setStatusLine(text: string): void

  Sets /status_line.

  Parameters

  • text: string

    The status line.

  Returns void

updateStep

• updateStep(stepId: string, changes: UpdateStepOptions): void

  Changes a step; an unsent add absorbs the change.

  Parameters

  • stepId: string

    The step.

  • changes: UpdateStepOptions

    status, title, detail and finishedAt; absent members stay.

  Returns void

useGateway

• useGateway(gateway: RunUpdateGateway): void

  Sends patches with the gateway op run.update instead of REST.

  The gateway has no success reply, so the next base is assumed as baseVersion + 1; route an error frame of a run.update of this run to RunPatcher.onGatewayError, which loads getRun after base_version_conflict and sends again.

  Parameters

  • gateway: RunUpdateGateway

    The gateway consumer.

  Returns void