Shared types and constants

Classes

DiagnosticsApi: Read-only views of the server's own health: trace summaries, its backend processes, host resources, resource history and the latest storage cleanup report. None of these signal a process, run a cleanup or restart the resource monitor; those stay on client.rpc. Trace causes, log messages and command lines are text that other programs wrote, and can hold host paths.
LocalServersApi: The local servers that the server's preview discovery finds on its host: listeners that it attributes to a thread terminal (terminal) or to the agent of a thread (agent), of every thread, plus each configured URL that answers as a web server, which can have no owner. Process names are text that other programs chose.

Members

messageId: The message the snippet is from. Older servers omit it.
runId: The run that ignored Stop; the server refuses once a newer run has started.

Constants

SPEECH_STREAM_PATH: The socket path.
SPEECH_STREAM_MAX_CHUNK_BYTES: The largest binary audio message the server reads: one second of 16 kHz mono Float32 PCM.
SpeechStreamText: The text so far: committed does not change again, tentative can.
SpeechStreamEvent: A text message that the server sends. ready answers start, update answers each audio message, finished answers finish, and error comes before the server closes with 1008.
SPEECH_MAX_OPTIONS_BYTES: The largest options JSON the server reads.
DEFAULT_SPEECH_TRANSCRIPTION_OPTIONS: The default recognition preferences, as upstream's clients send them.
DpopPrivateJwk: The P-256 key that a proof-bound session signs with. d is the private part.
TARGET_T3_CODE_VERSION: T3 Code release targeted by this library, independent of the library version.
SecretRef: A one-use handle to a secret the user entered for an agent; the agent never sees the value.
ORCHESTRATION_PROTOCOL_VERSION: The orchestration wire protocol this client speaks; the server refuses others.
ORCHESTRATION_PROTOCOL_QUERY_PARAM: Query parameter on the /ws upgrade that names the protocol.
ORCHESTRATION_PROTOCOL_HEADER: Header on orchestration HTTP routes that names the protocol.
CLIENT_CAPABILITIES_QUERY_PARAM: Query parameter on the /ws upgrade that lists the wire shapes a client understands, comma-separated.
SETTINGS_SECRET_REFERENCES_CAPABILITY: Secret settings fields may hold a secret provider reference in place of a string. A client that omits it sees a reference as a saved, redacted secret.
OrchestrationProjectShell: Project summary shared by the shell and the application project APIs.
ProjectMutation: What projects.mutate and POST /api/projects/mutate accept.
UsageDay: Calendar day as YYYY-MM-DD.
UsageTokenTotals: Cached and cache-creation input tokens are disjoint from uncached input tokens. reasoningTokens is a subset of outputTokens; never add it on top.

Functions

assetUrlParams()

The assets.read params of a relativeUrl from assets.createUrl.

export function assetUrlParams(relativeUrl: string): { token: string; path: string };

attachmentUploadUrlParams()

The attachments.upload params of a relativeUrl from attachments.createUploadUrl.

export function attachmentUploadUrlParams(relativeUrl: string): { token: string };

webhookUrlParams()

The route params of a webhook endpoint's path, from scheduledTasks.webhookEndpoint.

export function webhookUrlParams(path: string): { hookId: string; token: string };

encodeSpeechPcmRequest()

Frames 16 kHz mono Float32 pcm with its recognition options as the body of voice.transcribe or voice.transcribeCloud. Raises T3PreconditionError for invalid options, for audio that is not whole samples and for options over SPEECH_MAX_OPTIONS_BYTES.

export function encodeSpeechPcmRequest(
  pcm: Uint8Array,
  options: SpeechTranscriptionOptions = DEFAULT_SPEECH_TRANSCRIPTION_OPTIONS,
): Uint8Array<ArrayBuffer>;

DiagnosticsApi

Read-only views of the server’s own health: trace summaries, its backend processes, host resources, resource history and the latest storage cleanup report. None of these signal a process, run a cleanup or restart the resource monitor; those stay on client.rpc. Trace causes, log messages and command lines are text that other programs wrote, and can hold host paths.

Kind: global class

DiagnosticsApi

diagnosticsApi.traces()

Span and failure summaries from the server’s trace files (diagnostics:read). A read failure keeps the partial counts and sets error.

traces(signal?: AbortSignal): Promise<ServerTraceDiagnosticsResult>;

Kind: instance method of DiagnosticsApi

diagnosticsApi.processes()

The server’s signalable descendants, with CPU and memory (diagnostics:read): child processes and the root processes of agents and terminals. The server process itself is not in processes or the totals; resourceHistory covers it.

processes(signal?: AbortSignal): Promise<ServerProcessDiagnosticsResult>;

Kind: instance method of DiagnosticsApi

diagnosticsApi.hostResources()

CPU and memory of the server host (orchestration:read).

hostResources(signal?: AbortSignal): Promise<HostResourcesSnapshot>;

Kind: instance method of DiagnosticsApi

diagnosticsApi.resourceHistory()

Resource use of the server’s processes over windowMs, in buckets of bucketMs, with the top processes and monitor health (diagnostics:read).

resourceHistory(
    input: ResourceTelemetryHistoryInput,
    signal?: AbortSignal,
  ): Promise<ResourceTelemetryHistory>;

Kind: instance method of DiagnosticsApi

diagnosticsApi.storageCleanupReport()

The latest storage cleanup report, or null before the first cleanup (orchestration:read). Reads the first item of the report stream and closes it.

storageCleanupReport(signal?: AbortSignal): Promise<StorageCleanupReportUpdate>;

Kind: instance method of DiagnosticsApi

LocalServersApi

The local servers that the server’s preview discovery finds on its host: listeners that it attributes to a thread terminal (terminal) or to the agent of a thread (agent), of every thread, plus each configured URL that answers as a web server, which can have no owner. Process names are text that other programs chose.

Kind: global class

LocalServersApi
- .watch()
- .list()
- .stop()

localServersApi.watch()

Follow the listeners (orchestration:read): a fresh scan, then each change. The server also probes configuredUrls.

watch(
    input: SubscribeDiscoveredLocalServersInput = {},
    options?: { readonly signal?: AbortSignal },
  ): AsyncIterable<DecodedStreamItem<DiscoveredLocalServerList>>;

Kind: instance method of LocalServersApi

localServersApi.list()

The listeners of one fresh scan (orchestration:read), from the first watch item.

list(
    input: SubscribeDiscoveredLocalServersInput = {},
    signal?: AbortSignal,
  ): Promise<DiscoveredLocalServerList>;

Kind: instance method of LocalServersApi

localServersApi.stop()

Stop a listener’s process group (terminal:operate): SIGTERM, then SIGKILL after a grace period. The server scans again and signals only a listener with this pid and port that it attributes to a terminal or an agent; otherwise it fails with PreviewStopLocalServerError reason not-found. A process group shared with the server fails with reason shared-group.

async stop(input: PreviewStopLocalServerInput, signal?: AbortSignal): Promise<void>;

Kind: instance method of LocalServersApi

messageId

The message the snippet is from. Older servers omit it.

Kind: global variable

runId

The run that ignored Stop; the server refuses once a newer run has started.

Kind: global variable

SPEECH_STREAM_PATH

The socket path.

Kind: global constant

SPEECH_STREAM_MAX_CHUNK_BYTES

The largest binary audio message the server reads: one second of 16 kHz mono Float32 PCM.

Kind: global constant

SpeechStreamText

The text so far: committed does not change again, tentative can.

Kind: global constant

SpeechStreamEvent

A text message that the server sends. ready answers start, update answers each audio message, finished answers finish, and error comes before the server closes with 1008.

Kind: global constant

SPEECH_MAX_OPTIONS_BYTES

The largest options JSON the server reads.

Kind: global constant

DEFAULT_SPEECH_TRANSCRIPTION_OPTIONS

The default recognition preferences, as upstream’s clients send them.

Kind: global constant

DpopPrivateJwk

The P-256 key that a proof-bound session signs with. d is the private part.

Kind: global constant

TARGET_T3_CODE_VERSION

T3 Code release targeted by this library, independent of the library version.

Kind: global constant

SecretRef

A one-use handle to a secret the user entered for an agent; the agent never sees the value.

Kind: global constant

ORCHESTRATION_PROTOCOL_VERSION

The orchestration wire protocol this client speaks; the server refuses others.

Kind: global constant

ORCHESTRATION_PROTOCOL_QUERY_PARAM

Query parameter on the /ws upgrade that names the protocol.

Kind: global constant

ORCHESTRATION_PROTOCOL_HEADER

Header on orchestration HTTP routes that names the protocol.

Kind: global constant

CLIENT_CAPABILITIES_QUERY_PARAM

Query parameter on the /ws upgrade that lists the wire shapes a client understands, comma-separated.

Kind: global constant

SETTINGS_SECRET_REFERENCES_CAPABILITY

Secret settings fields may hold a secret provider reference in place of a string. A client that omits it sees a reference as a saved, redacted secret.

Kind: global constant

OrchestrationProjectShell

Project summary shared by the shell and the application project APIs.

Kind: global constant

ProjectMutation

What projects.mutate and POST /api/projects/mutate accept.

Kind: global constant

UsageDay

Calendar day as YYYY-MM-DD.

Kind: global constant

UsageTokenTotals

Cached and cache-creation input tokens are disjoint from uncached input tokens. reasoningTokens is a subset of outputTokens; never add it on top.

Kind: global constant

assetUrlParams()

The assets.read params of a relativeUrl from assets.createUrl.

export function assetUrlParams(relativeUrl: string): { token: string; path: string };

Kind: global function

attachmentUploadUrlParams()

The attachments.upload params of a relativeUrl from attachments.createUploadUrl.

export function attachmentUploadUrlParams(relativeUrl: string): { token: string };

Kind: global function

webhookUrlParams()

The route params of a webhook endpoint’s path, from scheduledTasks.webhookEndpoint.

export function webhookUrlParams(path: string): { hookId: string; token: string };

Kind: global function

encodeSpeechPcmRequest()

export function encodeSpeechPcmRequest(
  pcm: Uint8Array,
  options: SpeechTranscriptionOptions = DEFAULT_SPEECH_TRANSCRIPTION_OPTIONS,
): Uint8Array<ArrayBuffer>;

Kind: global function