TypeScript SDK core API

This reference describes the declarations exported by @stacklok-oss/mecatl-sdk.

Symbol index

Symbol	Kind
ActivityGapError	Class
AgentEvent	Type alias
Agents	Interface
ApprovalEventPayload	Interface
ArchivedConversationMessage	Interface
AttachedRun	Interface
AttachOptions	Interface
audioPart	Function
audioPartFromBlob	Function
AudioPromptPart	Interface
AuthenticationError	Class
ClearSessionOptions	Interface
Client	Interface
ClientDiagnosticsOptions	Interface
Commands	Interface
CompactionArchiveEventPayload	Interface
connect	Function
ConnectionStatus	Type alias
ConnectionStatusListener	Type alias
ConnectionStatusStore	Interface
ConnectOptions	Type alias
createHttpTransport	Function
createRawClient	Function
CreateSessionOptions	Interface
CreateTeamOptions	Interface
CredentialOptions	Interface
CredentialProvider	Type alias
CursorExpiredError	Class
CursorMalformedError	Class
CursorScopeError	Class
DiagnosticFieldValue	Type alias
DiagnosticLevel	Type alias
DiagnosticRecord	Interface
DiagnosticsSink	Type alias
DreamPlans	Interface
DreamTargetCapability	Interface
ErrorOrigin	Type alias
Event	Type alias
EventCommon	Interface
EventContent	Interface
EventContentBlock	Interface
EventOf	Type alias
EventPayloads	Interface
EventUsage	Interface
ForkSessionOptions	Interface
getRawJson	Function
HookEventPayload	Interface
HttpTransportOptions	Interface
imagePart	Function
imagePartFromBlob	Function
ImagePromptPart	Interface
IncompatibleServerError	Class
InjectedTransportOptions	Interface
InvalidStateError	Class
KnownEvent	Type alias
KnownEventKind	Type alias
LearnedSkills	Interface
LearningAttempts	Interface
LearningProposals	Interface
ManualDreamCapabilities	Interface
MAX_MEDIA_PART_BYTES	Variable
MAX_PROMPT_MEDIA_BYTES	Variable
MAX_PROMPT_MEDIA_PARTS	Variable
McpAuthorization	Interface
McpAuthorizationOutcome	Interface
McpAuthorizationPresentation	Interface
McpAuthorizationStream	Interface
McpConnectorStatus	Interface
McpInventory	Interface
MECATL_ATTACH_FILTERED_KINDS	Variable
MECATL_ERROR_CODES	Variable
MECATL_EVENT_KINDS	Variable
MECATL_WATCH_PHASES	Variable
MecatlError	Class
MecatlErrorCode	Type alias
MecatlErrorOptions	Interface
MediaPartOptions	Interface
MediaPartSource	Interface
ModelRetryEventPayload	Interface
Models	Interface
NoRunsError	Class
ParallelEventPayload	Interface
PermissionAskAlreadyResolvedError	Class
PermissionAskEventPayload	Interface
PermissionAskResponder	Type alias
PermissionVerdict	Type alias
PLAN_APPROVAL_TOOL	Variable
PLAN_APPROVED_PROCEED_TEXT	Variable
PlanApprovalRequiredError	Class
PlanApprovalResponder	Type alias
PlanApprovalVerdict	Type alias
PlanContinuationStartError	Class
PlanResolution	Interface
PlanResolutionResult	Interface
PromptInput	Type alias
PromptPart	Type alias
PromptValidationError	Class
PromptValidationReason	Type alias
ProtocolError	Class
RawClient	Interface
RawClientOptions	Interface
Reflection	Interface
RequestOptions	Type alias
ResultEventPayload	Interface
RetryDisposition	Type alias
Run	Interface
RunControls	Interface
RunOptions	Interface
RunResult	Interface
ScheduleEventPayload	Interface
Schedules	Interface
SdkCursor	Type alias
SDKErrorCode	Type alias
Server	Interface
ServerCapabilities	Interface
ServerCompatibility	Interface
ServerError	Class
ServerErrorCode	Type alias
ServerFeature	Type alias
ServerFeature	Variable
ServerInfo	Interface
ServerInfoOptions	Interface
ServerPosture	Type alias
ServerPosture	Variable
Session	Interface
SESSION_ID_HEADER_NAME	Variable
SessionActivity	Interface
SessionActivityReplayStatus	Interface
SessionBusyError	Class
SessionCapabilities	Interface
SessionLimits	Interface
SessionMcpConnectors	Interface
SessionMcpServer	Interface
SessionMode	Type alias
SessionMode	Variable
SessionPlacement	Interface
SessionRelationship	Interface
SessionResolvedModel	Interface
Sessions	Interface
SessionSnapshot	Interface
SessionSnapshotLimits	Interface
SessionTitle	Interface
SessionTitleAttempt	Interface
SessionTitleEventPayload	Interface
SessionTokenUsage	Interface
SessionTranscript	Interface
SessionTranscriptMessage	Interface
Skills	Interface
Soul	Interface
SteerAck	Interface
SteerCancelAck	Interface
SteerCancelOutcome	Type alias
SteerControlOptions	Interface
SteerEventPayload	Interface
SteerOutcome	Type alias
SteerOutcomeEventPayload	Interface
Storage	Interface
StreamProgress	Type alias
SubagentEventPayload	Interface
SUPPORTED_API_MAJOR	Variable
Team	Interface
TeamEvent	Type alias
TeamEventPayload	Interface
TeamFindingEventPayload	Interface
TeamMemberDispositionEventPayload	Interface
TeamMemberOptions	Interface
TeamMemberRunEvent	Type alias
TeamMemberSpecEventPayload	Interface
TeamMessageOptions	Interface
TeamOutcomeRunEvent	Interface
TeamRun	Interface
TeamRunEvent	Type alias
Teams	Interface
TeamTaskEventPayload	Interface
textPart	Function
TextPromptPart	Interface
TitleAttemptEventPayload	Interface
ToolCallEventPayload	Interface
ToolResultEventPayload	Interface
TransportError	Class
TransportKind	Type alias
TurnEndEventPayload	Interface
UnknownEvent	Type alias
UnknownGrpcEvent	Interface
UnknownHttpEvent	Interface
UnknownWatchEnvelope	Interface
UnsupportedFeatureError	Class
UserModel	Interface
UserPromptEventPayload	Interface
WATCH_SESSION_EVENTS_FEATURE	Variable
WatchBoundaryEnvelope	Interface
WatchEnvelope	Type alias
WatchEventEnvelope	Interface
WatchGapEnvelope	Interface
withSessionAffinity	Function
WorkspaceEnrollmentControls	Interface
WorkspaceEnrollmentState	Interface
Worktrees	Interface

Classes

ActivityGapError

Durable activity is known to contain a delivery gap.

export declare class ActivityGapError extends MecatlError

Callable members: constructor

ActivityGapError.constructor

Constructs a new instance of the ActivityGapError class

constructor(message?: string, options?: Omit<MecatlErrorOptions, "code">);

Parameters:

• message (string, optional)
• options (Omit<MecatlErrorOptions, "code">, optional)

AuthenticationError

Credential resolution or server authentication failed.

export declare class AuthenticationError extends MecatlError

Callable members: constructor

AuthenticationError.constructor

Constructs a new instance of the AuthenticationError class

constructor(message: string, options: Omit<MecatlErrorOptions, "code">);

Parameters:

• message (string)
• options (Omit<MecatlErrorOptions, "code">)

CursorExpiredError

The server cursor belongs to a superseded event-log generation.

export declare class CursorExpiredError extends MecatlError

Callable members: constructor

CursorExpiredError.constructor

Constructs a new instance of the CursorExpiredError class

constructor(message: string, options: Omit<MecatlErrorOptions, "code">);

Parameters:

• message (string)
• options (Omit<MecatlErrorOptions, "code">)

CursorMalformedError

An SDK cursor is not a structurally valid sdkcur/1 envelope.

export declare class CursorMalformedError extends MecatlError

Callable members: constructor

CursorMalformedError.constructor

Constructs a new instance of the CursorMalformedError class

constructor(message?: string, options?: Omit<MecatlErrorOptions, "code">);

Parameters:

• message (string, optional)
• options (Omit<MecatlErrorOptions, "code">, optional)

CursorScopeError

An SDK cursor would widen the set of durable events delivered by its source view.

export declare class CursorScopeError extends MecatlError

Callable members: constructor

CursorScopeError.constructor

Constructs a new instance of the CursorScopeError class

constructor(message?: string);

Parameters:

• message (string, optional)

IncompatibleServerError

The connected server does not satisfy the SDK compatibility floor.

export declare class IncompatibleServerError extends MecatlError

Callable members: constructor

IncompatibleServerError.constructor

Constructs a new instance of the IncompatibleServerError class

constructor(message: string, options: Omit<MecatlErrorOptions, "code">);

Parameters:

• message (string)
• options (Omit<MecatlErrorOptions, "code">)

InvalidStateError

An operation is invalid for the current local SDK lifecycle state.

export declare class InvalidStateError extends MecatlError

Callable members: constructor

InvalidStateError.constructor

Constructs a new instance of the InvalidStateError class

constructor(message: string, options: Omit<MecatlErrorOptions, "code">);

Parameters:

• message (string)
• options (Omit<MecatlErrorOptions, "code">)

MecatlError

Base class for every error authored by the SDK.

export declare class MecatlError extends Error

Callable members: constructor, toJSON()

MecatlError.code

readonly code: MecatlErrorCode;

MecatlError.constructor

Constructs a new instance of the MecatlError class

constructor(message: string, options: MecatlErrorOptions);

Parameters:

• message (string)
• options (MecatlErrorOptions)

MecatlError.requestId

readonly requestId: string | undefined;

MecatlError.status

readonly status: number | undefined;

MecatlError.toJSON

Returns a JSON-safe representation without the original cause.

toJSON(): Record<string, unknown>;

Returns: Record<string, unknown>

MecatlError.transport

readonly transport: ErrorOrigin;

NoRunsError

The readable session log contains no event associated with a run.

export declare class NoRunsError extends MecatlError

Callable members: constructor

NoRunsError.constructor

Constructs a new instance of the NoRunsError class

constructor();

PermissionAskAlreadyResolvedError

A permission ask is no longer pending on its originating run.

export declare class PermissionAskAlreadyResolvedError extends InvalidStateError

Callable members: constructor

PermissionAskAlreadyResolvedError.askId

readonly askId: string;

PermissionAskAlreadyResolvedError.constructor

Constructs a new instance of the PermissionAskAlreadyResolvedError class

constructor(askId: string, options: Omit<MecatlErrorOptions, "code">);

Parameters:

• askId (string)
• options (Omit<MecatlErrorOptions, "code">)

PlanApprovalRequiredError

query() plan mode was requested without its required plan-specific responder.

export declare class PlanApprovalRequiredError extends InvalidStateError

Callable members: constructor

PlanApprovalRequiredError.constructor

Constructs a new instance of the PlanApprovalRequiredError class

constructor();

PlanContinuationStartError

The approved plan's continuation could not be admitted before it received a run ID.

export declare class PlanContinuationStartError extends MecatlError

Callable members: constructor

PlanContinuationStartError.constructor

Constructs a new instance of the PlanContinuationStartError class

constructor(message: string, options: Omit<MecatlErrorOptions, "code">);

Parameters:

• message (string)
• options (Omit<MecatlErrorOptions, "code">)

PromptValidationError

A structured prompt failed local validation before any request was sent.

export declare class PromptValidationError extends MecatlError

Callable members: constructor

PromptValidationError.constructor

Constructs a new instance of the PromptValidationError class

constructor(reason: PromptValidationReason, message: string);

Parameters:

• reason (PromptValidationReason)
• message (string)

PromptValidationError.reason

readonly reason: PromptValidationReason;

ProtocolError

A transport response violated the SDK's protocol contract.

export declare class ProtocolError extends MecatlError

Callable members: constructor

ProtocolError.constructor

Constructs a new instance of the ProtocolError class

constructor(message: string, options: Omit<MecatlErrorOptions, "code">);

Parameters:

• message (string)
• options (Omit<MecatlErrorOptions, "code">)

ServerError

A typed domain failure returned by the Mecatl server.

export declare class ServerError extends MecatlError

Callable members: constructor

ServerError.code

readonly code: ServerErrorCode;

ServerError.constructor

Constructs a new instance of the ServerError class

constructor(message: string, options: Omit<MecatlErrorOptions, "code"> & {
        code: ServerErrorCode;
    });

Parameters:

• message (string)
• options (Omit<MecatlErrorOptions, "code"> & { code: ServerErrorCode; })

SessionBusyError

A local run is already active on this Session handle.

export declare class SessionBusyError extends InvalidStateError

TransportError

A request failed before the server returned a domain response.

export declare class TransportError extends MecatlError

Callable members: constructor

TransportError.constructor

Constructs a new instance of the TransportError class

constructor(message: string, options: Omit<MecatlErrorOptions, "code">);

Parameters:

• message (string)
• options (Omit<MecatlErrorOptions, "code">)

UnsupportedFeatureError

The connected server does not advertise a required feature.

export declare class UnsupportedFeatureError extends MecatlError

Callable members: constructor

UnsupportedFeatureError.constructor

Constructs a new instance of the UnsupportedFeatureError class

constructor(feature: string, options: Omit<MecatlErrorOptions, "code">);

Parameters:

• feature (string)
• options (Omit<MecatlErrorOptions, "code">)

UnsupportedFeatureError.feature

readonly feature: string;

Functions

audioPart

Constructs an audio part from inline bytes or an HTTPS URL.

export declare function audioPart(options: MediaPartOptions): AudioPromptPart;

Parameters:

• options (MediaPartOptions): Audio source and MIME type.

Returns: AudioPromptPart: A validated audio prompt part.

Throws: PromptValidationError when the source, MIME type, or size is invalid.

audioPartFromBlob

Constructs an audio part from a browser Blob or File.

export declare function audioPartFromBlob(blob: Blob, mimeType?: string): Promise<AudioPromptPart>;

Parameters:

• blob (Blob): Browser media value to read.
• mimeType (string, optional): Audio MIME type. Defaults to the Blob's type.

Returns: Promise<AudioPromptPart>: A validated audio prompt part containing the Blob's bytes.

Throws: PromptValidationError when the MIME type or size is invalid.

connect

Creates an isomorphic Client over HTTP or a caller-injected transport.

export declare function connect(options: ConnectOptions): Client;

Parameters:

• options (ConnectOptions): HTTP transport settings or a caller-owned transport.

Returns: Client: A high-level Mecatl client.

createHttpTransport

Creates a browser-compatible Connect-ES transport over Mecatl's HTTP and SSE API.

export declare function createHttpTransport(options: HttpTransportOptions): Transport;

Parameters:

• options (HttpTransportOptions): HTTP endpoint, credentials, and fetch implementation.

Returns: Transport: A Connect-ES transport for Mecatl's HTTP and SSE routes.

createRawClient

Creates a transport-neutral client for low-level RPC operations. Before the first requested operation, the client performs a stateless compatibility check.

export declare function createRawClient(options: RawClientOptions): RawClient;

Parameters:

• options (RawClientOptions): Caller-owned transport and its protocol kind.

Returns: RawClient: A low-level client that enforces SDK compatibility before operations.

getRawJson

Returns the exact JSON value received by the HTTP transport, including unknown fields.

export declare function getRawJson(message: object): JsonValue | undefined;

Parameters:

• message (object): Decoded protobuf message returned by the SDK.

Returns: JsonValue | undefined: The original JSON value, or undefined when none was recorded.

imagePart

Constructs an image part from inline bytes or an HTTPS URL.

export declare function imagePart(options: MediaPartOptions): ImagePromptPart;

Parameters:

• options (MediaPartOptions): Image source and MIME type.

Returns: ImagePromptPart: A validated image prompt part.

Throws: PromptValidationError when the source, MIME type, or size is invalid.

imagePartFromBlob

Constructs an image part from a browser Blob or File.

export declare function imagePartFromBlob(blob: Blob, mimeType?: string): Promise<ImagePromptPart>;

Parameters:

• blob (Blob): Browser media value to read.
• mimeType (string, optional): Image MIME type. Defaults to the Blob's type.

Returns: Promise<ImagePromptPart>: A validated image prompt part containing the Blob's bytes.

Throws: PromptValidationError when the MIME type or size is invalid.

textPart

Constructs a text segment for a structured prompt.

export declare function textPart(text: string): TextPromptPart;

Parameters:

• text (string): Text to send in this prompt segment.

Returns: TextPromptPart: A text prompt part.

withSessionAffinity

Returns call options bound to one explicit session without replacing caller headers. Throws synchronously when sessionId cannot be represented byte-exactly as the affinity header. The binding is a routing hint only; authentication and authorization remain independent.

export declare function withSessionAffinity(sessionId: string, options?: CallOptions): CallOptions;

Parameters:

• sessionId (string): Session ID to carry as the affinity header.
• options (CallOptions, optional): Existing call options whose headers must be preserved.

Returns: CallOptions: Call options containing exactly one session-affinity header.

Throws: RangeError when the session ID is not printable ASCII or is otherwise invalid.

Interfaces

Agents

Resolved agent-definition inventory operations.

export interface Agents

Callable members: list()

Agents.list

Lists the resolved agent definitions.

list(request: ListAgentsRequest, options?: RequestOptions): Promise<ListAgentsResponse>;

Parameters:

• request (ListAgentsRequest)
• options (RequestOptions, optional)

Returns: Promise<ListAgentsResponse>

ApprovalEventPayload

The payload of an approval replay event.

export interface ApprovalEventPayload

ApprovalEventPayload.allowAlways

readonly allowAlways: boolean;

ApprovalEventPayload.askId

readonly askId: string;

ApprovalEventPayload.callId

readonly callId: string;

ApprovalEventPayload.tool

readonly tool: string;

ApprovalEventPayload.verdict

readonly verdict: string;

ArchivedConversationMessage

One conversation entry in a compaction archive.

export interface ArchivedConversationMessage

ArchivedConversationMessage.parts

readonly parts: readonly EventContent[];

ArchivedConversationMessage.providerPhase

readonly providerPhase: string;

ArchivedConversationMessage.reasoning

readonly reasoning: string;

ArchivedConversationMessage.reasoningItemId

readonly reasoningItemId: string;

ArchivedConversationMessage.role

readonly role: string;

ArchivedConversationMessage.text

readonly text: string;

ArchivedConversationMessage.toolCalls

readonly toolCalls: readonly ToolCallEventPayload[];

ArchivedConversationMessage.toolResult

readonly toolResult?: ToolResultEventPayload | undefined;

AttachedRun

A durable activity stream bound to one run.

export interface AttachedRun extends SessionActivity

Callable members: approve(), cancel(), resolveAsk(), steer()

AttachedRun.approve

Reports that approval controls are unavailable on durable attachments.

approve(askId: string, allow: boolean): Promise<never>;

Parameters:

• askId (string): Permission-ask ID, retained for parity with a live run.
• allow (boolean): Boolean verdict, retained for parity with a live run.

Returns: Promise<never>: A rejected promise.

Throws: UnsupportedFeatureError for every call.

AttachedRun.cancel

Cancels the attached run using its exact run ID.

cancel(): Promise<void>;

Returns: Promise<void>: A promise that resolves after the cancellation request is accepted.

AttachedRun.live

True until this attachment observes its run's terminal result.

readonly live: boolean;

AttachedRun.resolveAsk

Reports that ask resolution is unavailable on durable attachments.

resolveAsk(askId: string, verdict: PermissionVerdict): Promise<never>;

Parameters:

• askId (string): Permission-ask ID, retained for parity with a live run.
• verdict (PermissionVerdict): Permission verdict, retained for parity with a live run.

Returns: Promise<never>: A rejected promise.

Throws: UnsupportedFeatureError for every call.

AttachedRun.runId

readonly runId: string;

AttachedRun.steer

Reports that steering is unavailable on durable attachments.

steer(text: string): Promise<never>;

Parameters:

• text (string): Steering text, retained for parity with a live run.

Returns: Promise<never>: A rejected promise.

Throws: UnsupportedFeatureError for every call.

AttachOptions

Where an attached run begins reading its durable activity.

export interface AttachOptions

AttachOptions.from

Starts with events received after attachment, discarding the existing replay locally.

from?: "now" | "start" | SdkCursor;

AttachOptions.includeLogOnly

Includes durable records omitted by the high-level view by default.

includeLogOnly?: boolean;

AttachOptions.onReconnect

Called before each resumable reconnect attempt (never for the first connection, never after detach) with the 1-based attempt number and the backoff delay about to be waited.

onReconnect?: (info: {
        readonly attempt: number;
        readonly delayMs: number;
    }) => void;

AttachOptions.signal

Detaches this view when aborted; it never cancels a run.

signal?: AbortSignal;

AudioPromptPart

Audio in a structured prompt.

export interface AudioPromptPart

AudioPromptPart.bytes

readonly bytes?: Uint8Array;

AudioPromptPart.kind

readonly kind: "audio";

AudioPromptPart.mimeType

readonly mimeType: string;

AudioPromptPart.url

readonly url?: string;

ClearSessionOptions

Optional overrides accepted when clearing a session.

export interface ClearSessionOptions

ClearSessionOptions.worktreeSelector

Opaque source-scoped selector for an existing worktree.

worktreeSelector?: string;

Client

The high-level Mecatl client.

export interface Client

Callable members: [Symbol.asyncDispose](), close()

Client[Symbol.asyncDispose]

Releases the same resources as close() when used with await using.

[Symbol.asyncDispose](): Promise<void>;

Returns: Promise<void>

Client.agents

readonly agents: Agents;

Client.close

Releases activity, transports, and resources owned by this client.

close(): Promise<void>;

Returns: Promise<void>

Client.commands

readonly commands: Commands;

Client.dreamPlans

readonly dreamPlans: DreamPlans;

Client.learnedSkills

readonly learnedSkills: LearnedSkills;

Client.learningAttempts

readonly learningAttempts: LearningAttempts;

Client.learningProposals

readonly learningProposals: LearningProposals;

Client.mcp

readonly mcp: McpInventory;

Client.models

readonly models: Models;

Client.reflection

readonly reflection: Reflection;

Client.schedules

readonly schedules: Schedules;

Client.server

readonly server: Server;

Client.sessions

readonly sessions: Sessions;

Client.skills

readonly skills: Skills;

Client.soul

readonly soul: Soul;

Client.status

readonly status: ConnectionStatusStore;

Client.storage

readonly storage: Storage;

Client.teams

readonly teams: Teams;

Client.userModel

readonly userModel: UserModel;

Client.worktrees

readonly worktrees: Worktrees;

ClientDiagnosticsOptions

Client-construction option shared by SDK entry points that emit local diagnostics.

export interface ClientDiagnosticsOptions

ClientDiagnosticsOptions.diagnostics

Receives SDK-local diagnostics. Nothing is written to console by default.

diagnostics?: DiagnosticsSink;

Commands

Session-scoped slash-command inventory operations.

export interface Commands

Callable members: list()

Commands.list

Lists slash commands available to a session.

list(request: ListCommandsRequest, options?: RequestOptions): Promise<ListCommandsResponse>;

Parameters:

• request (ListCommandsRequest)
• options (RequestOptions, optional)

Returns: Promise<ListCommandsResponse>

CompactionArchiveEventPayload

The payload of a compaction.archive replay event.

export interface CompactionArchiveEventPayload

CompactionArchiveEventPayload.replaced

readonly replaced: readonly ArchivedConversationMessage[];

ConnectionStatusStore

A multicast view of the client's latest connection status.

export interface ConnectionStatusStore

Callable members: getSnapshot(), subscribe()

ConnectionStatusStore.getSnapshot

Returns the client's current connection status.

getSnapshot(): ConnectionStatus;

Returns: ConnectionStatus

ConnectionStatusStore.subscribe

Registers a listener and returns a function that removes it.

subscribe(listener: ConnectionStatusListener): () => void;

Parameters:

• listener (ConnectionStatusListener)

Returns: () => void

CreateSessionOptions

Session-creation fields map directly onto CreateSessionRequest.

export interface CreateSessionOptions

CreateSessionOptions.debugMcpServers

Configured server-global MCP servers selected for a diagnostic session.

debugMcpServers?: string[];

CreateSessionOptions.debugTargetSessionId

Existing session ID used to create a separate diagnostic session.

debugTargetSessionId?: string;

CreateSessionOptions.limits

Stop conditions for the new session.

limits?: SessionLimits;

CreateSessionOptions.mcpServers

Client-provided streaming-HTTP MCP servers mounted for this session.

mcpServers?: SessionMcpServer[];

CreateSessionOptions.mode

Permission posture for the new session.

mode?: SessionMode;

CreateSessionOptions.modelId

Model selector within providerId.

modelId?: string;

CreateSessionOptions.profile

Tool-surface profile, or the deployment default when omitted.

profile?: string;

CreateSessionOptions.providerId

Configured model-provider ID, or the deployment default when omitted.

providerId?: string;

CreateSessionOptions.reasoningEffort

Requested reasoning-effort tier. The server reports the effective value.

reasoningEffort?: string;

CreateTeamOptions

Options used to create a server-owned team.

export interface CreateTeamOptions

CreateTeamOptions.goal

Objective supplied to the coordinating member.

goal?: string;

CreateTeamOptions.maxTeamTokens

Optional team-wide token limit. The daemon applies the lower of this value and its configured cap. Omit it to use the daemon's cap.

maxTeamTokens?: number;

CreateTeamOptions.members

Initial members enrolled atomically.

members?: readonly TeamMemberOptions[];

CreateTeamOptions.name

Optional human-readable team label.

name?: string;

CreateTeamOptions.sessionId

Session that owns the team.

sessionId: string;

CredentialOptions

Static or per-request credentials accepted by SDK transports.

export interface CredentialOptions

CredentialOptions.credentialProvider

Invoked for every request, after static headers have been copied.

credentialProvider?: CredentialProvider;

CredentialOptions.headers

Headers copied once at transport construction.

headers?: HeadersInit;

DiagnosticRecord

A structured SDK-local observation that is separate from the server event stream.

export interface DiagnosticRecord

DiagnosticRecord.cause

The original failure value when the diagnostic observes a thrown cause.

readonly cause?: unknown;

DiagnosticRecord.code

Stable machine-readable identifier for the observation.

readonly code: string;

DiagnosticRecord.fields

Typed context that is safe to expose to the application.

readonly fields: Readonly<Record<string, DiagnosticFieldValue>>;

DiagnosticRecord.level

Diagnostic severity.

readonly level: DiagnosticLevel;

DiagnosticRecord.message

Human-readable summary.

readonly message: string;

DreamPlans

Dream-plan generation and server-owned decision operations.

export interface DreamPlans

Callable members: decide(), generate()

DreamPlans.decide

Applies or dismisses a generated dream plan.

decide(request: DecideDreamPlanRequest, options?: RequestOptions): Promise<DecideDreamPlanResponse>;

Parameters:

• request (DecideDreamPlanRequest)
• options (RequestOptions, optional)

Returns: Promise<DecideDreamPlanResponse>

DreamPlans.generate

Generates a bounded-lifetime dream plan.

generate(request: GenerateDreamPlanRequest, options?: RequestOptions): Promise<GenerateDreamPlanResponse>;

Parameters:

• request (GenerateDreamPlanRequest)
• options (RequestOptions, optional)

Returns: Promise<GenerateDreamPlanResponse>

DreamTargetCapability

Manual dream operations available for one target.

export interface DreamTargetCapability

DreamTargetCapability.decide

readonly decide: boolean;

DreamTargetCapability.generate

readonly generate: boolean;

DreamTargetCapability.unavailableReason

readonly unavailableReason?: string;

EventCommon

Fields decoded for every event, including future event kinds.

export interface EventCommon

EventCommon.runId

readonly runId: string;

EventCommon.seq

readonly seq: bigint;

EventCommon.text

readonly text: string;

EventCommon.turn

readonly turn: number;

EventCommon.usage

readonly usage: EventUsage | undefined;

EventContent

One media part as represented on the protobuf event payloads.

export interface EventContent

EventContent.data

readonly data: Uint8Array;

EventContent.kind

readonly kind: 0 | 1 | 2;

EventContent.mimeType

readonly mimeType: string;

EventContent.url

readonly url: string;

EventContentBlock

One raw protobuf content block carried by a tool result.

export interface EventContentBlock

EventContentBlock.audience

readonly audience: readonly string[];

EventContentBlock.data

readonly data: Uint8Array;

EventContentBlock.description

readonly description: string;

EventContentBlock.kind

readonly kind: 0 | 1 | 2 | 3 | 4 | 5 | 6;

EventContentBlock.lastModified

readonly lastModified: string;

EventContentBlock.mimeType

readonly mimeType: string;

EventContentBlock.name

readonly name: string;

EventContentBlock.priority

readonly priority: number;

EventContentBlock.size

readonly size: bigint;

EventContentBlock.text

readonly text: string;

EventContentBlock.title

readonly title: string;

EventContentBlock.url

readonly url: string;

EventPayloads

Maps every supported event kind to its typed payload.

export interface EventPayloads

EventPayloads["authorization.required"]

readonly "authorization.required": AuthorizationEventPayload;

EventPayloads["authorization.resolved"]

readonly "authorization.resolved": AuthorizationEventPayload;

EventPayloads["compaction.archive"]

readonly "compaction.archive": CompactionArchiveEventPayload;

EventPayloads["message.delta"]

readonly "message.delta": undefined;

EventPayloads["model.retry"]

readonly "model.retry": ModelRetryEventPayload;

EventPayloads["network.attempt"]

readonly "network.attempt": undefined;

EventPayloads["parallel.branch"]

readonly "parallel.branch": ParallelEventPayload;

EventPayloads["parallel.end"]

readonly "parallel.end": ParallelEventPayload;

EventPayloads["parallel.start"]

readonly "parallel.start": ParallelEventPayload;

EventPayloads["permission.ask"]

readonly "permission.ask": PermissionAskEventPayload;

EventPayloads["permission.retract"]

readonly "permission.retract": PermissionAskEventPayload;

EventPayloads["provider.route"]

readonly "provider.route": undefined;

EventPayloads["reasoning.delta"]

readonly "reasoning.delta": undefined;

EventPayloads["request.manifest"]

readonly "request.manifest": undefined;

EventPayloads["schedule.failed"]

readonly "schedule.failed": ScheduleEventPayload;

EventPayloads["schedule.fired"]

readonly "schedule.fired": ScheduleEventPayload;

EventPayloads["schedule.skipped"]

readonly "schedule.skipped": ScheduleEventPayload;

EventPayloads["session.init"]

readonly "session.init": undefined;

EventPayloads["session.title"]

readonly "session.title": SessionTitleEventPayload;

EventPayloads["steer.outcome"]

readonly "steer.outcome": SteerOutcomeEventPayload;

EventPayloads["subagent.end"]

readonly "subagent.end": SubagentEventPayload;

EventPayloads["subagent.start"]

readonly "subagent.start": SubagentEventPayload;

EventPayloads["subagent.tool"]

readonly "subagent.tool": SubagentEventPayload;

EventPayloads["team.end"]

readonly "team.end": TeamEventPayload;

EventPayloads["team.findings"]

readonly "team.findings": TeamEventPayload;

EventPayloads["team.member"]

readonly "team.member": TeamEventPayload;

EventPayloads["team.start"]

readonly "team.start": TeamEventPayload;

EventPayloads["team.tasks"]

readonly "team.tasks": TeamEventPayload;

EventPayloads["tool.call"]

readonly "tool.call": ToolCallEventPayload;

EventPayloads["tool.progress"]

readonly "tool.progress": undefined;

EventPayloads["tool.result"]

readonly "tool.result": ToolResultEventPayload;

EventPayloads["turn.end"]

readonly "turn.end": TurnEndEventPayload;

EventPayloads["turn.start"]

readonly "turn.start": undefined;

EventPayloads.approval

readonly approval: ApprovalEventPayload;

EventPayloads.compaction

readonly compaction: undefined;

EventPayloads.hook

readonly hook: HookEventPayload;

EventPayloads.no_progress

readonly no_progress: undefined;

EventPayloads.recover_notice

readonly recover_notice: undefined;

EventPayloads.result

readonly result: ResultEventPayload;

EventPayloads.steer

readonly steer: SteerEventPayload;

EventPayloads.user_prompt

readonly user_prompt: UserPromptEventPayload;

EventUsage

Token accounting carried by usage-bearing events.

export interface EventUsage

EventUsage.cacheReadTokens

readonly cacheReadTokens: bigint;

EventUsage.cacheWriteTokens

readonly cacheWriteTokens: bigint;

EventUsage.inputTokens

readonly inputTokens: bigint;

EventUsage.outputTokens

readonly outputTokens: bigint;

EventUsage.reasoningTokens

readonly reasoningTokens: bigint;

ForkSessionOptions

Optional overrides accepted when forking a session.

export interface ForkSessionOptions

ForkSessionOptions.modelId

Model selector within providerId.

modelId?: string;

ForkSessionOptions.providerId

Configured model-provider ID.

providerId?: string;

ForkSessionOptions.reasoningEffort

Requested reasoning-effort tier for the forked session.

reasoningEffort?: string;

ForkSessionOptions.title

Human-readable title for the forked session.

title?: string;

ForkSessionOptions.worktreeSelector

Opaque source-scoped selector for an existing worktree.

worktreeSelector?: string;

HookEventPayload

The payload of a hook event.

export interface HookEventPayload

HookEventPayload.callId

readonly callId: string;

HookEventPayload.decision

readonly decision: 0 | 1 | 2 | 3 | 4;

HookEventPayload.phase

readonly phase: string;

HookEventPayload.tool

readonly tool: string;

HttpTransportOptions

Options for the browser-compatible HTTP and SSE transport.

export interface HttpTransportOptions extends CredentialOptions

HttpTransportOptions.baseUrl

HTTP API base URL. Relative values resolve against the browser origin.

baseUrl: string;

HttpTransportOptions.credentials

Passed to every request made by this transport.

credentials?: RequestCredentials;

HttpTransportOptions.fetch

When supplied, global fetch is never consulted.

fetch?: typeof globalThis.fetch;

ImagePromptPart

An image in a structured prompt.

export interface ImagePromptPart

ImagePromptPart.bytes

readonly bytes?: Uint8Array;

ImagePromptPart.kind

readonly kind: "image";

ImagePromptPart.mimeType

readonly mimeType: string;

ImagePromptPart.url

readonly url?: string;

InjectedTransportOptions

Options accepted by the isomorphic entry point when injecting a transport.

export interface InjectedTransportOptions

InjectedTransportOptions.transport

A caller-owned Connect-ES transport.

transport: Transport;

InjectedTransportOptions.transportKind

Required only when an unregistered transport speaks the HTTP/JSON/SSE protocol.

transportKind?: TransportKind;

LearnedSkills

Learned-skill inventory and server-owned lifecycle operations.

export interface LearnedSkills

Callable members: activate(), archive(), diffVersions(), get(), list(), listChanges(), reject(), rollback()

LearnedSkills.activate

Activates a learned skill.

activate(request: MutateLearnedSkillRequest, options?: RequestOptions): Promise<MutateLearnedSkillResponse>;

Parameters:

• request (MutateLearnedSkillRequest)
• options (RequestOptions, optional)

Returns: Promise<MutateLearnedSkillResponse>

LearnedSkills.archive

Archives a learned skill.

archive(request: MutateLearnedSkillRequest, options?: RequestOptions): Promise<MutateLearnedSkillResponse>;

Parameters:

• request (MutateLearnedSkillRequest)
• options (RequestOptions, optional)

Returns: Promise<MutateLearnedSkillResponse>

LearnedSkills.diffVersions

Compares two versions of a learned skill.

diffVersions(request: DiffLearnedSkillVersionsRequest, options?: RequestOptions): Promise<DiffLearnedSkillVersionsResponse>;

Parameters:

• request (DiffLearnedSkillVersionsRequest)
• options (RequestOptions, optional)

Returns: Promise<DiffLearnedSkillVersionsResponse>

LearnedSkills.get

Gets one learned skill.

get(request: GetLearnedSkillRequest, options?: RequestOptions): Promise<GetLearnedSkillResponse>;

Parameters:

• request (GetLearnedSkillRequest)
• options (RequestOptions, optional)

Returns: Promise<GetLearnedSkillResponse>

LearnedSkills.list

Lists learned skills and their lifecycle state.

list(request: ListLearnedSkillsRequest, options?: RequestOptions): Promise<ListLearnedSkillsResponse>;

Parameters:

• request (ListLearnedSkillsRequest)
• options (RequestOptions, optional)

Returns: Promise<ListLearnedSkillsResponse>

LearnedSkills.listChanges

Lists the recorded changes to learned skills.

listChanges(request: ListSkillChangesRequest, options?: RequestOptions): Promise<ListSkillChangesResponse>;

Parameters:

• request (ListSkillChangesRequest)
• options (RequestOptions, optional)

Returns: Promise<ListSkillChangesResponse>

LearnedSkills.reject

Rejects a learned skill.

reject(request: MutateLearnedSkillRequest, options?: RequestOptions): Promise<MutateLearnedSkillResponse>;

Parameters:

• request (MutateLearnedSkillRequest)
• options (RequestOptions, optional)

Returns: Promise<MutateLearnedSkillResponse>

LearnedSkills.rollback

Rolls a learned skill back to an earlier version.

rollback(request: RollbackLearnedSkillRequest, options?: RequestOptions): Promise<MutateLearnedSkillResponse>;

Parameters:

• request (RollbackLearnedSkillRequest)
• options (RequestOptions, optional)

Returns: Promise<MutateLearnedSkillResponse>

LearningAttempts

Learning-attempt inventory and server-owned lifecycle operations.

export interface LearningAttempts

Callable members: abandon(), get(), list(), retry()

LearningAttempts.abandon

Abandons an eligible learning attempt.

abandon(request: MutateLearningAttemptRequest, options?: RequestOptions): Promise<MutateLearningAttemptResponse>;

Parameters:

• request (MutateLearningAttemptRequest)
• options (RequestOptions, optional)

Returns: Promise<MutateLearningAttemptResponse>

LearningAttempts.get

Gets one learning attempt.

get(request: GetLearningAttemptRequest, options?: RequestOptions): Promise<GetLearningAttemptResponse>;

Parameters:

• request (GetLearningAttemptRequest)
• options (RequestOptions, optional)

Returns: Promise<GetLearningAttemptResponse>

LearningAttempts.list

Lists learning attempts visible to the caller.

list(request: ListLearningAttemptsRequest, options?: RequestOptions): Promise<ListLearningAttemptsResponse>;

Parameters:

• request (ListLearningAttemptsRequest)
• options (RequestOptions, optional)

Returns: Promise<ListLearningAttemptsResponse>

LearningAttempts.retry

Retries a failed learning attempt.

retry(request: MutateLearningAttemptRequest, options?: RequestOptions): Promise<MutateLearningAttemptResponse>;

Parameters:

• request (MutateLearningAttemptRequest)
• options (RequestOptions, optional)

Returns: Promise<MutateLearningAttemptResponse>

LearningProposals

Learning-proposal inventory and server-owned decision operations.

export interface LearningProposals

Callable members: decide(), get(), list(), undoPromotion()

LearningProposals.decide

Approves or rejects a staged learning proposal.

decide(request: DecideLearningProposalRequest, options?: RequestOptions): Promise<DecideLearningProposalResponse>;

Parameters:

• request (DecideLearningProposalRequest)
• options (RequestOptions, optional)

Returns: Promise<DecideLearningProposalResponse>

LearningProposals.get

Gets one staged learning proposal.

get(request: GetLearningProposalRequest, options?: RequestOptions): Promise<GetLearningProposalResponse>;

Parameters:

• request (GetLearningProposalRequest)
• options (RequestOptions, optional)

Returns: Promise<GetLearningProposalResponse>

LearningProposals.list

Lists staged learning proposals.

list(request: ListLearningProposalsRequest, options?: RequestOptions): Promise<ListLearningProposalsResponse>;

Parameters:

• request (ListLearningProposalsRequest)
• options (RequestOptions, optional)

Returns: Promise<ListLearningProposalsResponse>

LearningProposals.undoPromotion

Reverts an eligible learning promotion.

undoPromotion(request: UndoLearningPromotionRequest, options?: RequestOptions): Promise<UndoLearningPromotionResponse>;

Parameters:

• request (UndoLearningPromotionRequest)
• options (RequestOptions, optional)

Returns: Promise<UndoLearningPromotionResponse>

ManualDreamCapabilities

Manual dream support for deployment-owned targets.

export interface ManualDreamCapabilities

ManualDreamCapabilities.projectMemory

readonly projectMemory?: DreamTargetCapability;

ManualDreamCapabilities.userModel

readonly userModel?: DreamTargetCapability;

McpAuthorization

Controls for one pending per-tool MCP authorization (authorization.required). presentation() fetches the live browser URL; recheck() asks the daemon to re-inspect the authorization and streams the outcome (and the resumed run when it succeeds); cancel() abandons the authorization with the same stream shape.

export interface McpAuthorization

Callable members: cancel(), presentation(), recheck()

McpAuthorization.authorizationId

readonly authorizationId: string;

McpAuthorization.cancel

Cancels the authorization and streams the cancellation outcome plus any continuation run.

cancel(options?: RequestOptions): McpAuthorizationStream;

Parameters:

• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: McpAuthorizationStream: A single-consumption event stream.

McpAuthorization.presentation

Reads the live browser URL for this pending authorization.

presentation(options?: RequestOptions): Promise<McpAuthorizationPresentation>;

Parameters:

• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<McpAuthorizationPresentation>: The URL the operator opens to authorize the tool.

McpAuthorization.recheck

Re-checks the authorization and streams status plus any continuation run.

recheck(options?: RequestOptions): McpAuthorizationStream;

Parameters:

• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: McpAuthorizationStream: A single-consumption event stream.

McpAuthorization.sessionId

readonly sessionId: string;

McpAuthorizationOutcome

The terminal outcome of an authorization recheck or cancellation stream.

export interface McpAuthorizationOutcome

McpAuthorizationOutcome.result

The terminal result of the continuation run, absent when the stream ended without one.

readonly result?: RunResult;

McpAuthorizationPresentation

The live browser URL for one pending MCP authorization.

export interface McpAuthorizationPresentation

McpAuthorizationPresentation.url

The URL to open in a browser. It is returned only by this live control and never enters an event or snapshot.

readonly url: string;

McpAuthorizationStream

The event stream an authorization control returns: the daemon's status events followed by the continuation run when the tool call resumes. Single-consumption: iterate it, or call result().

export interface McpAuthorizationStream extends AsyncIterable<Event>

Callable members: close(), result()

McpAuthorizationStream.close

Stops consuming the stream without cancelling the authorization.

close(): Promise<void>;

Returns: Promise<void>

McpAuthorizationStream.result

Drains the stream and returns the continuation's terminal, when one arrived.

result(): Promise<McpAuthorizationOutcome>;

Returns: Promise<McpAuthorizationOutcome>

McpConnectorStatus

One broker-local MCP connector as the session sees it.

export interface McpConnectorStatus

McpConnectorStatus.catalogueState

readonly catalogueState: string;

McpConnectorStatus.name

readonly name: string;

McpConnectorStatus.toolCount

readonly toolCount: number;

McpInventory

MCP resource, prompt, source, and ToolHive-group inventory operations.

export interface McpInventory

Callable members: getPrompt(), listPrompts(), listResources(), listSources(), listToolHiveGroups(), readResource()

McpInventory.getPrompt

Expands one MCP prompt into its rendered messages.

getPrompt(request: GetMcpPromptRequest, options?: RequestOptions): Promise<GetMcpPromptResponse>;

Parameters:

• request (GetMcpPromptRequest)
• options (RequestOptions, optional)

Returns: Promise<GetMcpPromptResponse>

McpInventory.listPrompts

Lists the MCP prompts exposed by configured servers.

listPrompts(request: ListMcpPromptsRequest, options?: RequestOptions): Promise<ListMcpPromptsResponse>;

Parameters:

• request (ListMcpPromptsRequest)
• options (RequestOptions, optional)

Returns: Promise<ListMcpPromptsResponse>

McpInventory.listResources

Lists the MCP resources exposed by configured servers.

listResources(request: ListMcpResourcesRequest, options?: RequestOptions): Promise<ListMcpResourcesResponse>;

Parameters:

• request (ListMcpResourcesRequest)
• options (RequestOptions, optional)

Returns: Promise<ListMcpResourcesResponse>

McpInventory.listSources

Lists configured MCP sources and their diagnostics.

listSources(request: ListMcpSourcesRequest, options?: RequestOptions): Promise<ListMcpSourcesResponse>;

Parameters:

• request (ListMcpSourcesRequest)
• options (RequestOptions, optional)

Returns: Promise<ListMcpSourcesResponse>

McpInventory.listToolHiveGroups

Lists ToolHive groups present in the resolved MCP inventory.

listToolHiveGroups(request: ListToolHiveGroupsRequest, options?: RequestOptions): Promise<ListToolHiveGroupsResponse>;

Parameters:

• request (ListToolHiveGroupsRequest)
• options (RequestOptions, optional)

Returns: Promise<ListToolHiveGroupsResponse>

McpInventory.readResource

Reads one MCP resource by URI.

readResource(request: ReadMcpResourceRequest, options?: RequestOptions): Promise<ReadMcpResourceResponse>;

Parameters:

• request (ReadMcpResourceRequest)
• options (RequestOptions, optional)

Returns: Promise<ReadMcpResourceResponse>

MecatlErrorOptions

Metadata attached to one MecatlError.

export interface MecatlErrorOptions

MecatlErrorOptions.cause

Original failure retained on the JavaScript Error instance.

cause?: unknown;

MecatlErrorOptions.code

Stable machine-readable SDK or server error code.

code: MecatlErrorCode;

MecatlErrorOptions.requestId

Server request ID, when the transport supplied one.

requestId?: string | undefined;

MecatlErrorOptions.status

HTTP status, when the failure came from the HTTP transport.

status?: number | undefined;

MecatlErrorOptions.transport

Transport that observed the failure, or local for SDK validation.

transport: ErrorOrigin;

MediaPartOptions

Options accepted by imagePart() and audioPart().

export interface MediaPartOptions extends MediaPartSource

MediaPartOptions.mimeType

Media type beginning with image/ or audio/ for the selected helper.

mimeType: string;

MediaPartSource

The source accepted by imagePart() and audioPart(). Exactly one field is required.

export interface MediaPartSource

MediaPartSource.bytes

Inline media bytes.

bytes?: Uint8Array;

MediaPartSource.url

Absolute HTTPS media URL.

url?: string;

ModelRetryEventPayload

The payload of a model.retry event.

export interface ModelRetryEventPayload

ModelRetryEventPayload.retryDisposition

readonly retryDisposition: RetryDisposition;

ModelRetryEventPayload.streamProgress

readonly streamProgress: StreamProgress;

Models

Selectable model inventory operations.

export interface Models

Callable members: list()

Models.list

Lists selectable providers and models.

list(request: ListModelsRequest, options?: RequestOptions): Promise<ListModelsResponse>;

Parameters:

• request (ListModelsRequest)
• options (RequestOptions, optional)

Returns: Promise<ListModelsResponse>

ParallelEventPayload

The payload shared by parallel.* events.

export interface ParallelEventPayload

ParallelEventPayload.branchCount

readonly branchCount: number;

ParallelEventPayload.branchIndex

readonly branchIndex: number;

ParallelEventPayload.branchLabel

readonly branchLabel: string;

ParallelEventPayload.childId

readonly childId: string;

ParallelEventPayload.detail

readonly detail: string;

ParallelEventPayload.durationMs

readonly durationMs: bigint;

ParallelEventPayload.failed

readonly failed: boolean;

ParallelEventPayload.goal

readonly goal: string;

ParallelEventPayload.innerKind

readonly innerKind: string;

ParallelEventPayload.isError

readonly isError: boolean;

ParallelEventPayload.join

readonly join: string;

ParallelEventPayload.kind

readonly kind: string;

ParallelEventPayload.model

readonly model: string;

ParallelEventPayload.parentCallId

readonly parentCallId: string;

ParallelEventPayload.routedCategory

readonly routedCategory: string;

ParallelEventPayload.routedModel

readonly routedModel: string;

ParallelEventPayload.routingReason

readonly routingReason: string;

ParallelEventPayload.stop

readonly stop: string;

ParallelEventPayload.text

readonly text: string;

ParallelEventPayload.toolCount

readonly toolCount: number;

ParallelEventPayload.toolName

readonly toolName: string;

ParallelEventPayload.usage

readonly usage?: EventUsage | undefined;

ParallelEventPayload.winner

readonly winner: number;

ParallelEventPayload.winnerWorkspace

readonly winnerWorkspace: string;

ParallelEventPayload.workspace

readonly workspace: string;

PermissionAskEventPayload

The payload shared by permission.ask and permission.retract.

export interface PermissionAskEventPayload

PermissionAskEventPayload.args

readonly args: string;

PermissionAskEventPayload.askId

readonly askId: string;

PermissionAskEventPayload.reason

readonly reason: string;

PermissionAskEventPayload.tool

readonly tool: string;

PlanResolution

One atomic, single-consumption resolution of a durably parked plan.

export interface PlanResolution extends AsyncIterable<Event>

Callable members: result()

PlanResolution.result

Drains the merged stream and returns the resumed and optional continuation outcomes.

result(): Promise<PlanResolutionResult>;

Returns: Promise<PlanResolutionResult>: The resumed run and any continuation run started by approval.

Throws: InvalidStateError when the resolution is already being consumed.

Throws: PlanContinuationStartError when an approved continuation cannot start.

PlanResolutionResult

The two ordered outcomes carried by one atomic plan-resolution stream.

export interface PlanResolutionResult

PlanResolutionResult.continuation

readonly continuation?: RunResult;

PlanResolutionResult.resumed

readonly resumed: RunResult;

RawClient

Transport-neutral, descriptor-driven operations beneath Client/Session/Run.

export interface RawClient

Callable members: features(), stream(), unary()

RawClient.features

Returns the build features learned from the shared compatibility probe.

features(options?: CallOptions): Promise<ReadonlySet<string>>;

Parameters:

• options (CallOptions, optional)

Returns: Promise<ReadonlySet<string>>

RawClient.stream

Invokes one streaming RPC after enforcing the SDK compatibility floor.

stream<I extends DescMessage, O extends DescMessage>(method: DescMethodStreaming<I, O>, input: AsyncIterable<MessageInitShape<I>>, options?: CallOptions): AsyncIterable<MessageShape<O>>;

Parameters:

• method (DescMethodStreaming<I, O>)
• input (AsyncIterable<MessageInitShape<I>>)
• options (CallOptions, optional)

Returns: AsyncIterable<MessageShape<O>>

RawClient.unary

Invokes one unary RPC after enforcing the SDK compatibility floor.

unary<I extends DescMessage, O extends DescMessage>(method: DescMethodUnary<I, O>, input: MessageInitShape<I>, options?: CallOptions): Promise<MessageShape<O>>;

Parameters:

• method (DescMethodUnary<I, O>)
• input (MessageInitShape<I>)
• options (CallOptions, optional)

Returns: Promise<MessageShape<O>>

RawClientOptions

Options for constructing the transport-neutral raw client.

export interface RawClientOptions

RawClientOptions.transport

A caller-owned Connect-ES transport.

transport: Transport;

RawClientOptions.transportKind

Required only for an unregistered injected transport. Defaults to gRPC.

transportKind?: TransportKind;

Reflection

Session-reflection operations.

export interface Reflection

Callable members: reflect()

Reflection.reflect

Reflects one completed session into learning evidence.

reflect(request: ReflectSessionRequest, options?: RequestOptions): Promise<ReflectSessionResponse>;

Parameters:

• request (ReflectSessionRequest)
• options (RequestOptions, optional)

Returns: Promise<ReflectSessionResponse>

ResultEventPayload

The payload of a terminal result event.

export interface ResultEventPayload

ResultEventPayload.error

readonly error: string;

ResultEventPayload.permanent

readonly permanent: boolean;

ResultEventPayload.retryDisposition

readonly retryDisposition?: RetryDisposition | undefined;

ResultEventPayload.stop

readonly stop: string;

ResultEventPayload.streamProgress

readonly streamProgress?: StreamProgress | undefined;

ResultEventPayload.text

readonly text: string;

ResultEventPayload.usage

readonly usage?: EventUsage | undefined;

Run

One accepted server run and its single-consumption event stream.

export interface Run extends AsyncIterable<Event>

Callable members: approve(), cancel(), resolveAsk(), result(), steer()

Run.approve

Sends a Boolean permission verdict for a permission.ask event.

approve(askId: string, allow: boolean): Promise<void>;

Parameters:

• askId (string): ID carried by the permission ask.
• allow (boolean): Whether to allow the call once.

Returns: Promise<void>: A promise that resolves after the verdict is sent.

Throws: PermissionAskAlreadyResolvedError when the ask is no longer pending.

Run.cancel

Requests cancellation; consume the run normally to receive the cancelled outcome.

cancel(): Promise<void>;

Returns: Promise<void>: A promise that resolves after the cancellation request is sent.

Run.id

readonly id: string;

Run.resolveAsk

Resolves one pending ask on this run with the server's string verdict vocabulary.

resolveAsk(askId: string, verdict: PermissionVerdict): Promise<void>;

Parameters:

• askId (string): ID carried by the permission ask.
• verdict (PermissionVerdict): Decision to apply to the pending ask.

Returns: Promise<void>: A promise that resolves after the server accepts the verdict.

Throws: PermissionAskAlreadyResolvedError when the ask is no longer pending.

Throws: InvalidStateError when used for a plan-approval ask.

Run.result

Drains all remaining events and returns the typed terminal outcome.

result(): Promise<RunResult>;

Returns: Promise<RunResult>: The terminal result for this run.

Throws: InvalidStateError when the run is already being consumed.

Run.sessionId

readonly sessionId: string;

Run.steer

Strictly steers this run. A late steer is refused and is never promoted.

steer(text: string): Promise<void>;

Parameters:

• text (string): Instruction to apply to the active run.

Returns: Promise<void>: A promise that resolves after the steering request is sent.

RunControls

Prompt-free controls for one run, addressed by run id. Every control is STRICT: it names the run through expected_run_id, so a control that outlives its run is refused by the server as stale_run_control rather than acting on the session's next run. Unlike the controls on a Run, these do not require the run's own event stream, so they also serve a run this client re-attached to or observes through a durable watch. HTTP transport only.

export interface RunControls

Callable members: cancel(), cancelSteer(), resolveAsk(), steer()

RunControls.cancel

Requests cancellation of this run.

cancel(options?: RequestOptions): Promise<void>;

Parameters:

• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<void>

Throws: ServerError with code stale_run_control when the run already ended.

RunControls.cancelSteer

Retracts this run's pending, un-drained steer bundle.

cancelSteer(options?: SteerControlOptions): Promise<SteerCancelAck>;

Parameters:

• options (SteerControlOptions, optional): Correlation id plus request headers, signal, and deadline.

Returns: Promise<SteerCancelAck>: retracted, or none_pending when nothing was waiting.

Throws: UnsupportedFeatureError when the server lacks http_steer.

RunControls.resolveAsk

Resolves one pending permission ask on this run.

resolveAsk(askId: string, verdict: PermissionVerdict, options?: RequestOptions): Promise<void>;

Parameters:

• askId (string): ID carried by the permission ask.
• verdict (PermissionVerdict): Decision to apply to the pending ask.
• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<void>

Throws: ServerError with code stale_run_control when the run already ended.

RunControls.runId

readonly runId: string;

RunControls.sessionId

readonly sessionId: string;

RunControls.steer

Strictly steers this run with text or ordered text and media parts.

steer(prompt: PromptInput, options?: SteerControlOptions): Promise<SteerAck>;

Parameters:

• prompt (PromptInput): Instruction to inject at the run's next turn boundary.
• options (SteerControlOptions, optional): Correlation id plus request headers, signal, and deadline.

Returns: Promise<SteerAck>: The server's outcome; the caller keeps the text on too_late.

Throws: UnsupportedFeatureError when the server lacks http_steer.

Throws: ServerError with code stale_run_control when the run already ended.

RunOptions

Options applied to one run.

export interface RunOptions

RunOptions.onPermissionAsk

Automatically answers ordinary permission asks.

onPermissionAsk?: PermissionAskResponder;

RunOptions.onPlanApproval

Automatically answers only plan-originated PresentPlan asks.

onPlanApproval?: PlanApprovalResponder;

RunResult

The terminal outcome of a consumed run. Server-declared stops are values, not errors.

export interface RunResult

RunResult.content

readonly content: string;

RunResult.rawEvent

The terminal event from the same discriminated union exposed by iteration.

readonly rawEvent: EventOf<"result">;

RunResult.runId

readonly runId: string;

RunResult.sessionId

readonly sessionId: string;

RunResult.stopReason

readonly stopReason: string;

RunResult.text

Final text, mirrored as content for content-oriented consumers.

readonly text: string;

RunResult.usage

readonly usage: EventUsage | undefined;

ScheduleEventPayload

The payload shared by schedule.* events.

export interface ScheduleEventPayload

ScheduleEventPayload.err

readonly err: string;

ScheduleEventPayload.fireId

readonly fireId: string;

ScheduleEventPayload.kind

readonly kind: string;

ScheduleEventPayload.scheduleName

readonly scheduleName: string;

ScheduleEventPayload.sessionId

readonly sessionId: string;

ScheduleEventPayload.stop

readonly stop: string;

Schedules

Schedule and fire inventory plus server-owned lifecycle operations.

export interface Schedules

Callable members: create(), delete(), fireNow(), get(), getFire(), list(), listFires(), pause(), resume(), update()

Schedules.create

Creates a recurring schedule.

create(request: CreateScheduleRequest, options?: RequestOptions): Promise<CreateScheduleResponse>;

Parameters:

• request (CreateScheduleRequest)
• options (RequestOptions, optional)

Returns: Promise<CreateScheduleResponse>

Schedules.delete

Deletes one schedule.

delete(request: DeleteScheduleRequest, options?: RequestOptions): Promise<DeleteScheduleResponse>;

Parameters:

• request (DeleteScheduleRequest)
• options (RequestOptions, optional)

Returns: Promise<DeleteScheduleResponse>

Schedules.fireNow

Requests an immediate schedule fire.

fireNow(request: FireNowRequest, options?: RequestOptions): Promise<FireNowResponse>;

Parameters:

• request (FireNowRequest)
• options (RequestOptions, optional)

Returns: Promise<FireNowResponse>

Schedules.get

Gets one schedule.

get(request: GetScheduleRequest, options?: RequestOptions): Promise<GetScheduleResponse>;

Parameters:

• request (GetScheduleRequest)
• options (RequestOptions, optional)

Returns: Promise<GetScheduleResponse>

Schedules.getFire

Gets one schedule fire.

getFire(request: GetFireRequest, options?: RequestOptions): Promise<GetFireResponse>;

Parameters:

• request (GetFireRequest)
• options (RequestOptions, optional)

Returns: Promise<GetFireResponse>

Schedules.list

Lists schedules visible to the caller.

list(request: ListSchedulesRequest, options?: RequestOptions): Promise<ListSchedulesResponse>;

Parameters:

• request (ListSchedulesRequest)
• options (RequestOptions, optional)

Returns: Promise<ListSchedulesResponse>

Schedules.listFires

Lists fires for a schedule.

listFires(request: ListFiresRequest, options?: RequestOptions): Promise<ListFiresResponse>;

Parameters:

• request (ListFiresRequest)
• options (RequestOptions, optional)

Returns: Promise<ListFiresResponse>

Schedules.pause

Pauses one schedule.

pause(request: PauseScheduleRequest, options?: RequestOptions): Promise<PauseScheduleResponse>;

Parameters:

• request (PauseScheduleRequest)
• options (RequestOptions, optional)

Returns: Promise<PauseScheduleResponse>

Schedules.resume

Resumes one paused schedule.

resume(request: ResumeScheduleRequest, options?: RequestOptions): Promise<ResumeScheduleResponse>;

Parameters:

• request (ResumeScheduleRequest)
• options (RequestOptions, optional)

Returns: Promise<ResumeScheduleResponse>

Schedules.update

Updates one schedule.

update(request: UpdateScheduleRequest, options?: RequestOptions): Promise<UpdateScheduleResponse>;

Parameters:

• request (UpdateScheduleRequest)
• options (RequestOptions, optional)

Returns: Promise<UpdateScheduleResponse>

Server

Pre-session compatibility and safe server-identity operations.

export interface Server

Callable members: compatibility(), info()

Server.compatibility

Starts a fresh compatibility negotiation and makes it the generation shared by subsequent ordinary operations.

compatibility(options?: RequestOptions): Promise<ServerCompatibility>;

Parameters:

• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<ServerCompatibility>: A detached compatibility projection.

Server.info

Reads safe server identity after an ordinary cached compatibility preflight.

info(options?: ServerInfoOptions, requestOptions?: RequestOptions): Promise<ServerInfo>;

Parameters:

• options (ServerInfoOptions, optional): Optional exact provider selector.
• requestOptions (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<ServerInfo>: Detached display-only server identity.

ServerCapabilities

Optional server features captured with a session snapshot.

export interface ServerCapabilities

ServerCapabilities.agents

readonly agents: boolean;

ServerCapabilities.audio

readonly audio: boolean;

ServerCapabilities.bash

readonly bash: boolean;

ServerCapabilities.debugMcp

readonly debugMcp: boolean;

ServerCapabilities.image

readonly image: boolean;

ServerCapabilities.learnedSkills

readonly learnedSkills: boolean;

ServerCapabilities.learningProposals

readonly learningProposals: boolean;

ServerCapabilities.manualCompaction

readonly manualCompaction: boolean;

ServerCapabilities.manualDream

readonly manualDream?: ManualDreamCapabilities;

ServerCapabilities.mcp

readonly mcp: boolean;

ServerCapabilities.mcpConnectorStatus

readonly mcpConnectorStatus: boolean;

ServerCapabilities.memory

readonly memory: boolean;

ServerCapabilities.modelSelection

readonly modelSelection: boolean;

ServerCapabilities.posture

readonly posture: string;

ServerCapabilities.reflection

readonly reflection: boolean;

ServerCapabilities.scheduling

readonly scheduling: boolean;

ServerCapabilities.sessionDebug

readonly sessionDebug: boolean;

ServerCapabilities.skills

readonly skills: boolean;

ServerCapabilities.slashCommands

readonly slashCommands: boolean;

ServerCapabilities.soul

readonly soul: boolean;

ServerCapabilities.steer

readonly steer: boolean;

ServerCapabilities.storageCleanup

readonly storageCleanup: boolean;

ServerCapabilities.storageHealth

readonly storageHealth: boolean;

ServerCapabilities.storageMigration

readonly storageMigration: boolean;

ServerCapabilities.teams

readonly teams: boolean;

ServerCapabilities.userModel

readonly userModel: boolean;

ServerCapabilities.workspaceEnrollment

readonly workspaceEnrollment: boolean;

ServerCapabilities.worktrees

readonly worktrees: boolean;

ServerCompatibility

A detached view of one server compatibility negotiation.

export interface ServerCompatibility

ServerCompatibility.apiMajor

The wire-contract major supported by this SDK.

readonly apiMajor: typeof SUPPORTED_API_MAJOR;

ServerCompatibility.capabilities

Deployment capabilities currently enabled by the operator.

readonly capabilities: ServerCapabilities;

ServerCompatibility.deployment

Optional operator-authored deployment label.

readonly deployment?: string;

ServerCompatibility.features

Open build-feature identifiers advertised on this listener.

readonly features: ReadonlySet<string>;

ServerInfo

Safe, display-only identity information for the connected server.

export interface ServerInfo

ServerInfo.buildId

Linker-stamped server build identity.

readonly buildId: string;

ServerInfo.llmProviderDisplayEndpoint

Sanitized provider endpoint for diagnostics, never connection configuration.

readonly llmProviderDisplayEndpoint?: string;

ServerInfo.serverImplementation

Stable server composition family, or unknown.

readonly serverImplementation: string;

ServerInfoOptions

Selector accepted by Server.info.

export interface ServerInfoOptions

ServerInfoOptions.providerId

Already-known provider ID to select for the diagnostic endpoint projection.

readonly providerId?: string;

Session

A durable Mecatl session handle.

export interface Session

Callable members: activity(), attach(), cancelChild(), clear(), close(), compact(), controls(), delete(), mcpAuthorization(), mcpConnectors(), rename(), resolvePlan(), retry(), run(), setMode(), snapshot(), transcript()

Session.activity

Opens the durable cross-run activity stream for this session.

activity(options?: AttachOptions): Promise<SessionActivity>;

Parameters:

• options (AttachOptions, optional): Replay position, event filtering, and cancellation options.

Returns: Promise<SessionActivity>: A single-consumption stream of session activity.

Throws: CursorScopeError when a cursor would widen its original filter.

Session.attach

Attaches to an explicit run, or selects the newest run in the durable log.

attach(runId?: string, options?: AttachOptions): Promise<AttachedRun>;

Parameters:

• runId (string, optional): Run ID to follow. Omit it to select the newest run.
• options (AttachOptions, optional): Replay position, event filtering, and cancellation options.

Returns: Promise<AttachedRun>: A single-consumption durable stream bound to the selected run.

Throws: NoRunsError when no run can be selected.

Throws: CursorScopeError when a cursor would widen its original filter.

Session.cancelChild

Cancels one running child (subagent, parallel branch, or team member) of this session's live run.

cancelChild(childId: string, options?: RequestOptions): Promise<void>;

Parameters:

• childId (string): The child session id carried by subagent.start, parallel.branch, or team.member.
• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<void>: A promise that resolves after the daemon accepts the cancellation.

Throws: ServerError with code not_found when the child is unknown or already finished.

Session.clear

Creates an empty-history successor without changing this handle.

clear(options?: ClearSessionOptions, requestOptions?: RequestOptions): Promise<Session>;

Parameters:

• options (ClearSessionOptions, optional): Optional opaque worktree selector.
• requestOptions (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<Session>: A distinct session handle for the successor.

Session.close

Releases runtime resources without removing the durable session.

close(options?: RequestOptions): Promise<void>;

Parameters:

• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<void>: A promise that resolves after local session resources are released.

Session.compact

Requests one out-of-band compaction pass.

compact(options?: RequestOptions): Promise<boolean>;

Parameters:

• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<boolean>: Whether the server reduced the model-visible history.

Session.controls

Returns strict, run-id-addressed controls for one run of this session. The handle needs no event stream, so it also serves a run this client did not start (a durable watch, a re-attached page). HTTP transport only.

controls(runId: string): RunControls;

Parameters:

• runId (string): The run every control names through expected_run_id.

Returns: RunControls: Controls that resolve asks, cancel, steer, and retract a steer.

Session.delete

Permanently removes the durable session and its sidecars.

delete(options?: RequestOptions): Promise<void>;

Parameters:

• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<void>: A promise that resolves after the server removes the session.

Session.id

readonly id: string;

Session.mcpAuthorization

Returns the controls for one pending per-tool MCP authorization.

mcpAuthorization(authorizationId: string): McpAuthorization;

Parameters:

• authorizationId (string): The id carried by the authorization.required event.

Returns: McpAuthorization: Presentation, recheck, and cancel controls bound to that authorization.

Session.mcpConnectors

Inspects the session's broker-local MCP connector catalogue (no upstream probe).

mcpConnectors(options?: RequestOptions): Promise<SessionMcpConnectors>;

Parameters:

• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<SessionMcpConnectors>: Availability, enrollment state, and the connector rows.

Session.rename

Replaces the title of an eligible session.

rename(title: string, options?: RequestOptions): Promise<SessionSnapshot>;

Parameters:

• title (string): New human-readable title.
• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<SessionSnapshot>: The resulting authoritative snapshot.

Session.resolvePlan

Atomically resolves a durably parked plan and streams its resumed and continuation runs.

resolvePlan(verdict?: PlanApprovalVerdict): PlanResolution;

Parameters:

• verdict (PlanApprovalVerdict, optional): Plan decision. Defaults to approve.

Returns: PlanResolution: A single-consumption plan-resolution stream.

Throws: ServerError when the session has no parked plan awaiting approval.

Session.retry

Retries the server-selected eligible failed model step.

retry(options?: RunOptions, requestOptions?: RequestOptions): Promise<Run>;

Parameters:

• options (RunOptions, optional): Automatic permission and plan-approval responders.
• requestOptions (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<Run>: The same single-consumption run lifecycle returned by run().

Throws: SessionBusyError when the session already has an active run.

Session.run

Starts a run and resolves once its first run-ID-bearing event arrives.

run(prompt: PromptInput, options?: RunOptions, requestOptions?: RequestOptions): Promise<Run>;

Parameters:

• prompt (PromptInput): Text or ordered text, image, and audio parts for the run.
• options (RunOptions, optional): Automatic permission and plan-approval responders.
• requestOptions (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<Run>: A single-consumption handle for the accepted run.

Throws: PromptValidationError when the prompt is invalid or unsupported.

Throws: SessionBusyError when the session already has an active run.

Session.setMode

Changes the permission posture of an eligible session.

setMode(mode: SessionMode, options?: RequestOptions): Promise<SessionSnapshot>;

Parameters:

• mode (SessionMode): New SDK permission mode.
• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<SessionSnapshot>: The resulting authoritative snapshot.

Session.snapshot

Reads the authoritative current session snapshot.

snapshot(options?: RequestOptions): Promise<SessionSnapshot>;

Parameters:

• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<SessionSnapshot>: A detached SDK-owned projection of the session aggregate.

Throws: ProtocolError when the server response is missing or mismatched.

Session.transcript

Reads the authoritative model-visible conversation.

transcript(options?: RequestOptions): Promise<SessionTranscript>;

Parameters:

• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<SessionTranscript>: The ordered transcript without provider-private replay fields.

Throws: ProtocolError when the server response is missing or mismatched.

Session.workspaceEnrollment

Pre-prompt workspace-services enrollment controls for this session.

readonly workspaceEnrollment: WorkspaceEnrollmentControls;

SessionActivity

A durable, cross-run session activity stream.

export interface SessionActivity extends AsyncIterable<WatchEnvelope>, AsyncDisposable

Callable members: close()

SessionActivity.close

Detaches from the watch without cancelling a run.

close(): Promise<void>;

Returns: Promise<void>

SessionActivity.cursor

readonly cursor: SdkCursor;

SessionActivityReplayStatus

Availability and completeness of the separate activity replay plane.

export interface SessionActivityReplayStatus

SessionActivityReplayStatus.authoritative

readonly authoritative: boolean;

SessionActivityReplayStatus.available

readonly available: boolean;

SessionActivityReplayStatus.complete

readonly complete: boolean;

SessionCapabilities

Media input support for the provider and model bound to a session.

export interface SessionCapabilities

SessionCapabilities.audio

readonly audio: boolean;

SessionCapabilities.image

readonly image: boolean;

SessionLimits

Optional stop conditions for a newly created session.

export interface SessionLimits

SessionLimits.maxConsecutiveFailures

Maximum consecutive tool failures; zero disables this limit.

maxConsecutiveFailures?: number;

SessionLimits.maxToolCalls

Maximum tool calls; zero disables this limit.

maxToolCalls?: number;

SessionLimits.maxTurns

Maximum model turns; zero disables this limit.

maxTurns?: number;

SessionMcpConnectors

The session's broker-local MCP connector catalogue.

export interface SessionMcpConnectors

SessionMcpConnectors.availability

readonly availability: string;

SessionMcpConnectors.connectors

readonly connectors: readonly McpConnectorStatus[];

SessionMcpConnectors.enrollmentState

readonly enrollmentState: string;

SessionMcpConnectors.totalConnectors

readonly totalConnectors: number;

SessionMcpConnectors.truncated

readonly truncated: boolean;

SessionMcpServer

A client-provided streaming-HTTP MCP server.

export interface SessionMcpServer

SessionMcpServer.command

Command-shaped value used only to reject unsupported stdio configurations.

command?: string;

SessionMcpServer.headers

HTTP headers sent to the MCP server. Treat their values as secrets.

headers?: Record<string, string>;

SessionMcpServer.name

Stable server name used in namespaced MCP tool names.

name?: string;

SessionMcpServer.type

Transport type. The server accepts http or an empty value with a URL.

type?: string;

SessionMcpServer.url

Absolute HTTPS endpoint, or an HTTP endpoint on an explicit loopback host.

url?: string;

SessionPlacement

Bounded display metadata for a session placement.

export interface SessionPlacement

SessionPlacement.branch

readonly branch: string;

SessionPlacement.kind

readonly kind: string;

SessionPlacement.label

readonly label: string;

SessionPlacement.revision

readonly revision: string;

SessionRelationship

Durable links between a session and its parent resource.

export interface SessionRelationship

SessionRelationship.branchIndex

readonly branchIndex?: number;

SessionRelationship.callId

readonly callId?: string;

SessionRelationship.debugTargetSessionId

readonly debugTargetSessionId?: string;

SessionRelationship.memberName

readonly memberName?: string;

SessionRelationship.originSessionId

readonly originSessionId?: string;

SessionRelationship.parentSessionId

readonly parentSessionId?: string;

SessionRelationship.scheduleName

readonly scheduleName?: string;

SessionRelationship.teamId

readonly teamId?: string;

SessionResolvedModel

The effective provider and model reported for a session.

export interface SessionResolvedModel

SessionResolvedModel.contextWindow

readonly contextWindow: bigint;

SessionResolvedModel.modelId

readonly modelId: string;

SessionResolvedModel.providerId

readonly providerId: string;

SessionResolvedModel.reasoningEffort

readonly reasoningEffort?: string;

Sessions

Session lifecycle operations exposed by a Client.

export interface Sessions

Callable members: create(), fork(), get(), list()

Sessions.create

Creates a session and returns its handle.

create(options: CreateSessionOptions, requestOptions?: RequestOptions): Promise<Session>;

Parameters:

• options (CreateSessionOptions): Session configuration fields.
• requestOptions (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<Session>: A handle for the newly created session.

Sessions.fork

Forks an existing session into a distinct successor.

fork(sourceSessionId: string, options?: ForkSessionOptions, requestOptions?: RequestOptions): Promise<Session>;

Parameters:

• sourceSessionId (string): Session whose conversation will be copied.
• options (ForkSessionOptions, optional): Optional title, model, reasoning, and worktree overrides.
• requestOptions (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<Session>: A handle for the forked successor session.

Sessions.get

Loads an existing session by ID.

get(sessionId: string, options?: RequestOptions): Promise<Session>;

Parameters:

• sessionId (string): Durable session ID to load.
• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<Session>: A handle bound to the requested session.

Sessions.list

Lists the sessions visible to the authenticated caller.

list(request: ListSessionsRequest, options?: RequestOptions): Promise<ListSessionsResponse>;

Parameters:

• request (ListSessionsRequest)
• options (RequestOptions, optional)

Returns: Promise<ListSessionsResponse>

SessionSnapshot

An authoritative, detached view of one durable session.

export interface SessionSnapshot

SessionSnapshot.capabilities

readonly capabilities?: ServerCapabilities;

SessionSnapshot.createdAtUnix

readonly createdAtUnix: bigint;

SessionSnapshot.debugMcpServers

readonly debugMcpServers: readonly string[];

SessionSnapshot.debugMcpTools

readonly debugMcpTools: readonly string[];

SessionSnapshot.kind

readonly kind: string;

SessionSnapshot.limits

readonly limits?: SessionSnapshotLimits;

SessionSnapshot.mode

readonly mode: SessionMode;

SessionSnapshot.placement

readonly placement?: SessionPlacement;

SessionSnapshot.relationship

readonly relationship?: SessionRelationship;

SessionSnapshot.resolvedModel

readonly resolvedModel?: SessionResolvedModel;

SessionSnapshot.sessionCapabilities

readonly sessionCapabilities?: SessionCapabilities;

SessionSnapshot.sessionId

readonly sessionId: string;

SessionSnapshot.state

readonly state: string;

SessionSnapshot.title

readonly title?: SessionTitle;

SessionSnapshot.tokenUsage

readonly tokenUsage: Readonly<Record<string, SessionTokenUsage>>;

SessionSnapshot.toolCalls

readonly toolCalls: number;

SessionSnapshot.turns

readonly turns: number;

SessionSnapshotLimits

Stop conditions reported by a session snapshot.

export interface SessionSnapshotLimits

SessionSnapshotLimits.maxConsecutiveFailures

readonly maxConsecutiveFailures: number;

SessionSnapshotLimits.maxToolCalls

readonly maxToolCalls: number;

SessionSnapshotLimits.maxTurns

readonly maxTurns: number;

SessionTitle

Normalized session title metadata.

export interface SessionTitle

SessionTitle.generationState

readonly generationState?: string;

SessionTitle.latestAttempt

readonly latestAttempt?: SessionTitleAttempt;

SessionTitle.provenance

readonly provenance: string;

SessionTitle.revision

readonly revision?: bigint;

SessionTitle.value

readonly value: string;

SessionTitleAttempt

The latest bounded title-generation attempt.

export interface SessionTitleAttempt

SessionTitleAttempt.id

readonly id: string;

SessionTitleAttempt.outcome

readonly outcome: string;

SessionTitleEventPayload

The source-free payload of a session.title event.

export interface SessionTitleEventPayload

SessionTitleEventPayload.generationState

readonly generationState: string;

SessionTitleEventPayload.latestAttempt

readonly latestAttempt?: TitleAttemptEventPayload | undefined;

SessionTitleEventPayload.provenance

readonly provenance: string;

SessionTitleEventPayload.revision

readonly revision: bigint;

SessionTitleEventPayload.title

readonly title: string;

SessionTokenUsage

One durable session usage bucket.

export interface SessionTokenUsage

SessionTokenUsage.models

readonly models: Readonly<Record<string, EventUsage>>;

SessionTokenUsage.total

readonly total?: EventUsage;

SessionTranscript

The authoritative, ordered conversation for one session.

export interface SessionTranscript

SessionTranscript.activity

readonly activity?: SessionActivityReplayStatus;

SessionTranscript.complete

readonly complete: boolean;

SessionTranscript.kind

readonly kind: string;

SessionTranscript.messages

readonly messages: readonly SessionTranscriptMessage[];

SessionTranscript.relationship

readonly relationship?: SessionRelationship;

SessionTranscript.sessionId

readonly sessionId: string;

SessionTranscriptMessage

One human-displayable message in the authoritative session transcript.

export interface SessionTranscriptMessage

SessionTranscriptMessage.parts

readonly parts: readonly EventContent[];

SessionTranscriptMessage.role

readonly role: string;

SessionTranscriptMessage.text

readonly text: string;

SessionTranscriptMessage.toolCalls

readonly toolCalls: readonly ToolCallEventPayload[];

SessionTranscriptMessage.toolResult

readonly toolResult?: ToolResultEventPayload;

Skills

Configured skill inventory operations.

export interface Skills

Callable members: list()

Skills.list

Lists the configured skills visible to the server.

list(request: ListSkillsRequest, options?: RequestOptions): Promise<ListSkillsResponse>;

Parameters:

• request (ListSkillsRequest)
• options (RequestOptions, optional)

Returns: Promise<ListSkillsResponse>

Soul

Resolved soul inspection operations.

export interface Soul

Callable members: get()

Soul.get

Gets the server's resolved soul snapshot.

get(request: GetSoulRequest, options?: RequestOptions): Promise<GetSoulResponse>;

Parameters:

• request (GetSoulRequest)
• options (RequestOptions, optional)

Returns: Promise<GetSoulResponse>

SteerAck

The acknowledgement of a steer control.

export interface SteerAck

SteerAck.messageId

The request's own message id, echoed by the server ("" when none).

readonly messageId: string;

SteerAck.outcome

readonly outcome: SteerOutcome;

SteerAck.promoted

True when a too-late unqualified steer was promoted into a follow-up run.

readonly promoted: boolean;

SteerAck.runId

The promoted follow-up run's id, "" when nothing was promoted.

readonly runId: string;

SteerCancelAck

The acknowledgement of a cancel-steer control.

export interface SteerCancelAck

SteerCancelAck.messageId

readonly messageId: string;

SteerCancelAck.outcome

readonly outcome: SteerCancelOutcome;

SteerControlOptions

Options accepted by the steer and cancel-steer run controls.

export interface SteerControlOptions extends RequestOptions

SteerControlOptions.messageId

Client-minted correlation id. The acknowledgement echoes it, and the run's later steer drain echo names the id of the LAST message merged into the drained bundle (the watermark a client splits its queue on).

messageId?: string;

SteerEventPayload

The payload of a committed steer event.

export interface SteerEventPayload

SteerEventPayload.messageId

readonly messageId: string;

SteerEventPayload.parts

readonly parts: readonly EventContent[];

SteerEventPayload.text

readonly text: string;

SteerOutcomeEventPayload

The payload of a gRPC-only steer.outcome event.

export interface SteerOutcomeEventPayload

SteerOutcomeEventPayload.messageId

readonly messageId: string;

SteerOutcomeEventPayload.outcome

readonly outcome: 0 | 1 | 2 | 3 | 4 | 5;

SteerOutcomeEventPayload.promoted

readonly promoted: boolean;

SteerOutcomeEventPayload.text

readonly text: string;

Storage

Storage health, migration, and cleanup operations owned by the server.

export interface Storage

Callable members: applyCleanup(), applyMigration(), cancelCleanup(), cancelMigration(), getCleanupJob(), getHealth(), getMigrationJob(), planCleanup(), planMigration(), resumeMigration()

Storage.applyCleanup

Starts a planned session-storage cleanup.

applyCleanup(request: ApplySessionCleanupRequest, options?: RequestOptions): Promise<CleanupJob>;

Parameters:

• request (ApplySessionCleanupRequest)
• options (RequestOptions, optional)

Returns: Promise<CleanupJob>

Storage.applyMigration

Starts a planned session-storage migration.

applyMigration(request: ApplySessionMigrationRequest, options?: RequestOptions): Promise<SessionMigrationJob>;

Parameters:

• request (ApplySessionMigrationRequest)
• options (RequestOptions, optional)

Returns: Promise<SessionMigrationJob>

Storage.cancelCleanup

Cancels a session-storage cleanup.

cancelCleanup(request: CancelSessionCleanupRequest, options?: RequestOptions): Promise<CleanupJob>;

Parameters:

• request (CancelSessionCleanupRequest)
• options (RequestOptions, optional)

Returns: Promise<CleanupJob>

Storage.cancelMigration

Cancels a session-storage migration.

cancelMigration(request: CancelSessionMigrationRequest, options?: RequestOptions): Promise<SessionMigrationJob>;

Parameters:

• request (CancelSessionMigrationRequest)
• options (RequestOptions, optional)

Returns: Promise<SessionMigrationJob>

Storage.getCleanupJob

Gets one session-storage cleanup job.

getCleanupJob(request: GetSessionCleanupJobRequest, options?: RequestOptions): Promise<CleanupJob>;

Parameters:

• request (GetSessionCleanupJobRequest)
• options (RequestOptions, optional)

Returns: Promise<CleanupJob>

Storage.getHealth

Gets the configured session-storage health.

getHealth(request: GetStorageHealthRequest, options?: RequestOptions): Promise<GetStorageHealthResponse>;

Parameters:

• request (GetStorageHealthRequest)
• options (RequestOptions, optional)

Returns: Promise<GetStorageHealthResponse>

Storage.getMigrationJob

Gets one session-storage migration job.

getMigrationJob(request: GetSessionMigrationJobRequest, options?: RequestOptions): Promise<SessionMigrationJob>;

Parameters:

• request (GetSessionMigrationJobRequest)
• options (RequestOptions, optional)

Returns: Promise<SessionMigrationJob>

Storage.planCleanup

Previews a session-storage cleanup.

planCleanup(request: PlanSessionCleanupRequest, options?: RequestOptions): Promise<PlanSessionCleanupResponse>;

Parameters:

• request (PlanSessionCleanupRequest)
• options (RequestOptions, optional)

Returns: Promise<PlanSessionCleanupResponse>

Storage.planMigration

Previews a session-storage migration.

planMigration(request: PlanSessionMigrationRequest, options?: RequestOptions): Promise<SessionMigrationPlan>;

Parameters:

• request (PlanSessionMigrationRequest)
• options (RequestOptions, optional)

Returns: Promise<SessionMigrationPlan>

Storage.resumeMigration

Resumes an interrupted session-storage migration.

resumeMigration(request: ResumeSessionMigrationRequest, options?: RequestOptions): Promise<SessionMigrationJob>;

Parameters:

• request (ResumeSessionMigrationRequest)
• options (RequestOptions, optional)

Returns: Promise<SessionMigrationJob>

SubagentEventPayload

The payload shared by subagent.* events.

export interface SubagentEventPayload

SubagentEventPayload.background

readonly background: boolean;

SubagentEventPayload.cause

readonly cause: string;

SubagentEventPayload.childId

readonly childId: string;

SubagentEventPayload.detail

readonly detail: string;

SubagentEventPayload.durationMs

readonly durationMs: bigint;

SubagentEventPayload.goal

readonly goal: string;

SubagentEventPayload.innerKind

readonly innerKind: string;

SubagentEventPayload.isError

readonly isError: boolean;

SubagentEventPayload.model

readonly model: string;

SubagentEventPayload.parentCallId

readonly parentCallId: string;

SubagentEventPayload.routedCategory

readonly routedCategory: string;

SubagentEventPayload.routedModel

readonly routedModel: string;

SubagentEventPayload.routingReason

readonly routingReason: string;

SubagentEventPayload.stop

readonly stop: string;

SubagentEventPayload.text

readonly text: string;

SubagentEventPayload.toolCount

readonly toolCount: number;

SubagentEventPayload.toolName

readonly toolName: string;

SubagentEventPayload.usage

readonly usage?: EventUsage | undefined;

Team

A handle for direct team operations.

export interface Team

Callable members: cancel(), cleanup(), list(), message(), run(), spawn()

Team.cancel

Cancels one team member.

cancel(member: string, options?: RequestOptions): Promise<CancelTeammateResponse>;

Parameters:

• member (string)
• options (RequestOptions, optional)

Returns: Promise<CancelTeammateResponse>

Team.cleanup

Permanently removes the server-owned team.

cleanup(options?: RequestOptions): Promise<CleanupTeamResponse>;

Parameters:

• options (RequestOptions, optional)

Returns: Promise<CleanupTeamResponse>

Team.id

readonly id: string;

Team.initialMembers

The typed initial roster returned atomically by CreateTeam. This is not a live view.

readonly initialMembers: readonly TeamMember[];

Team.list

Returns the current team roster and state.

list(options?: RequestOptions): Promise<ListTeamResponse>;

Parameters:

• options (RequestOptions, optional)

Returns: Promise<ListTeamResponse>

Team.message

Sends a message to a team member.

message(message: TeamMessageOptions, options?: RequestOptions): Promise<SendTeammateMessageResponse>;

Parameters:

• message (TeamMessageOptions)
• options (RequestOptions, optional)

Returns: Promise<SendTeammateMessageResponse>

Team.run

Starts a single-consumption team run.

run(options?: RequestOptions): TeamRun;

Parameters:

• options (RequestOptions, optional)

Returns: TeamRun

Team.spawn

Adds one member to the team.

spawn(member: TeamMemberOptions, options?: RequestOptions): Promise<SpawnTeammateResponse>;

Parameters:

• member (TeamMemberOptions)
• options (RequestOptions, optional)

Returns: Promise<SpawnTeammateResponse>

TeamEventPayload

The payload shared by team.* events.

export interface TeamEventPayload

TeamEventPayload.cause

readonly cause: string;

TeamEventPayload.contextUsed

readonly contextUsed: bigint;

TeamEventPayload.contextWindow

readonly contextWindow: bigint;

TeamEventPayload.detail

readonly detail: string;

TeamEventPayload.dispositions

readonly dispositions: readonly TeamMemberDispositionEventPayload[];

TeamEventPayload.findings

readonly findings: readonly TeamFindingEventPayload[];

TeamEventPayload.innerKind

readonly innerKind: string;

TeamEventPayload.isError

readonly isError: boolean;

TeamEventPayload.member

readonly member: string;

TeamEventPayload.memberSessionId

readonly memberSessionId: string;

TeamEventPayload.parentCallId

readonly parentCallId: string;

TeamEventPayload.roster

readonly roster: readonly TeamMemberSpecEventPayload[];

TeamEventPayload.rounds

readonly rounds: number;

TeamEventPayload.stop

readonly stop: string;

TeamEventPayload.tasks

readonly tasks: readonly TeamTaskEventPayload[];

TeamEventPayload.teamId

readonly teamId: string;

TeamEventPayload.text

readonly text: string;

TeamEventPayload.toolName

readonly toolName: string;

TeamEventPayload.usage

readonly usage?: EventUsage | undefined;

TeamFindingEventPayload

One finding in a team event snapshot.

export interface TeamFindingEventPayload

TeamFindingEventPayload.body

readonly body: string;

TeamFindingEventPayload.member

readonly member: string;

TeamMemberDispositionEventPayload

One terminal member disposition in a team.end payload.

export interface TeamMemberDispositionEventPayload

TeamMemberDispositionEventPayload.errorRounds

readonly errorRounds: number;

TeamMemberDispositionEventPayload.name

readonly name: string;

TeamMemberDispositionEventPayload.reason

readonly reason: 0 | 1 | 2 | 3;

TeamMemberDispositionEventPayload.stopped

readonly stopped: boolean;

TeamMemberOptions

One initial or incrementally spawned team member.

export interface TeamMemberOptions

TeamMemberOptions.agentType

Agent-definition name adopted by this member.

agentType?: string;

TeamMemberOptions.initialPrompt

First-turn prompt for this member.

initialPrompt?: string;

TeamMemberOptions.lead

Marks this member as the team coordinator.

lead?: boolean;

TeamMemberOptions.mutating

Requests an isolated workspace with mutating tools.

mutating?: boolean;

TeamMemberOptions.name

Unique handle used to address this member.

name: string;

TeamMemberSpecEventPayload

One member in a team.start roster.

export interface TeamMemberSpecEventPayload

TeamMemberSpecEventPayload.lead

readonly lead: boolean;

TeamMemberSpecEventPayload.model

readonly model: string;

TeamMemberSpecEventPayload.mutating

readonly mutating: boolean;

TeamMemberSpecEventPayload.name

readonly name: string;

TeamMemberSpecEventPayload.role

readonly role: string;

TeamMemberSpecEventPayload.routedCategory

readonly routedCategory: string;

TeamMemberSpecEventPayload.routedModel

readonly routedModel: string;

TeamMemberSpecEventPayload.routingReason

readonly routingReason: string;

TeamMessageOptions

One operator message sent to a team member.

export interface TeamMessageOptions

TeamMessageOptions.body

Message body delivered to the member.

body: string;

TeamMessageOptions.from

Sender label recorded with the message.

from?: string;

TeamMessageOptions.to

Recipient member handle.

to: string;

TeamOutcomeRunEvent

The one terminal outcome from a direct team run.

export interface TeamOutcomeRunEvent

TeamOutcomeRunEvent.kind

readonly kind: "outcome";

TeamOutcomeRunEvent.outcome

readonly outcome: TeamOutcome;

TeamRun

One single-consumption direct team run.

export interface TeamRun extends AsyncIterable<TeamRunEvent>

Callable members: result()

TeamRun.result

Drains the stream and returns its one required terminal outcome.

result(): Promise<TeamOutcome>;

Returns: Promise<TeamOutcome>

TeamRun.teamId

readonly teamId: string;

Teams

Direct team creation operations exposed by a Client.

export interface Teams

Callable members: create()

Teams.create

Creates a server-owned team bound to a session.

create(request: CreateTeamOptions, options?: RequestOptions): Promise<Team>;

Parameters:

• request (CreateTeamOptions)
• options (RequestOptions, optional)

Returns: Promise<Team>

TeamTaskEventPayload

One task in a team event snapshot.

export interface TeamTaskEventPayload

TeamTaskEventPayload.assignee

readonly assignee: string;

TeamTaskEventPayload.deps

readonly deps: readonly string[];

TeamTaskEventPayload.description

readonly description: string;

TeamTaskEventPayload.id

readonly id: string;

TeamTaskEventPayload.state

readonly state: string;

TextPromptPart

A text segment in a structured prompt.

export interface TextPromptPart

TextPromptPart.kind

readonly kind: "text";

TextPromptPart.text

readonly text: string;

TitleAttemptEventPayload

One title-generation attempt projected by a session.title event.

export interface TitleAttemptEventPayload

TitleAttemptEventPayload.id

readonly id: string;

TitleAttemptEventPayload.outcome

readonly outcome: string;

ToolCallEventPayload

The payload of a tool.call event.

export interface ToolCallEventPayload

ToolCallEventPayload.args

readonly args: string;

ToolCallEventPayload.id

readonly id: string;

ToolCallEventPayload.name

readonly name: string;

ToolResultEventPayload

The text, structured data, and content blocks from a tool.result event.

export interface ToolResultEventPayload

ToolResultEventPayload.blocks

readonly blocks: readonly EventContentBlock[];

ToolResultEventPayload.callId

readonly callId: string;

ToolResultEventPayload.content

readonly content: string;

ToolResultEventPayload.isError

readonly isError: boolean;

ToolResultEventPayload.structuredContent

readonly structuredContent: string;

TurnEndEventPayload

The payload of a turn.end event.

export interface TurnEndEventPayload

TurnEndEventPayload.durationMs

readonly durationMs: bigint;

TurnEndEventPayload.usage

readonly usage?: EventUsage | undefined;

UnknownGrpcEvent

An unknown event received over a protobuf transport.

export interface UnknownGrpcEvent extends EventCommon

UnknownGrpcEvent.kind

readonly kind: "unknown";

UnknownGrpcEvent.rawData

The protobuf unknown fields, preserving their wire order and payload bytes.

readonly rawData: Uint8Array;

UnknownGrpcEvent.transport

readonly transport: "grpc";

UnknownGrpcEvent.wireKind

readonly wireKind: string;

UnknownHttpEvent

An unknown event received over the HTTP JSON/SSE transport.

export interface UnknownHttpEvent extends EventCommon

UnknownHttpEvent.kind

readonly kind: "unknown";

UnknownHttpEvent.rawData

The exact parsed JSON object received in the SSE frame.

readonly rawData: JsonValue;

UnknownHttpEvent.transport

readonly transport: "http";

UnknownHttpEvent.wireKind

readonly wireKind: string;

UnknownWatchEnvelope

A future watch phase preserved for forward compatibility.

export interface UnknownWatchEnvelope

UnknownWatchEnvelope.cursor

readonly cursor: SdkCursor;

UnknownWatchEnvelope.event

readonly event?: Event;

UnknownWatchEnvelope.kind

readonly kind: "unknown";

UnknownWatchEnvelope.phase

readonly phase: string;

UserModel

Resolved user-model inspection operations.

export interface UserModel

Callable members: get()

UserModel.get

Gets the caller's bounded user-model index or one detail entry.

get(request: GetUserModelRequest, options?: RequestOptions): Promise<GetUserModelResponse>;

Parameters:

• request (GetUserModelRequest)
• options (RequestOptions, optional)

Returns: Promise<GetUserModelResponse>

UserPromptEventPayload

The payload shared by user_prompt replay events.

export interface UserPromptEventPayload

UserPromptEventPayload.parts

readonly parts: readonly EventContent[];

UserPromptEventPayload.text

readonly text: string;

WatchBoundaryEnvelope

The single replay-to-live transition marker.

export interface WatchBoundaryEnvelope

WatchBoundaryEnvelope.cursor

readonly cursor: SdkCursor;

WatchBoundaryEnvelope.kind

readonly kind: "boundary";

WatchBoundaryEnvelope.phase

readonly phase: "live";

WatchEventEnvelope

A replayed or live durable event.

export interface WatchEventEnvelope

WatchEventEnvelope.cursor

readonly cursor: SdkCursor;

WatchEventEnvelope.event

readonly event: Event;

WatchEventEnvelope.kind

readonly kind: "event";

WatchEventEnvelope.phase

readonly phase: "live" | "replay";

WatchGapEnvelope

A known hole in durable delivery. It deliberately exposes no cursor.

export interface WatchGapEnvelope

WatchGapEnvelope.kind

readonly kind: "gap";

WatchGapEnvelope.phase

readonly phase: "gap";

WorkspaceEnrollmentControls

The pre-prompt workspace-services enrollment controls for one session. connect() begins an eligible enrollment or observes the pending one; retry() and cancel() act on one exact enrollment id and fail stale with a 412 problem.

export interface WorkspaceEnrollmentControls

Callable members: cancel(), connect(), retry()

WorkspaceEnrollmentControls.cancel

Cancels only the exact pending enrollment and clears its prompt gate.

cancel(enrollmentId: string, options?: RequestOptions): Promise<WorkspaceEnrollmentState>;

Parameters:

• enrollmentId (string): The enrollment to cancel.
• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<WorkspaceEnrollmentState>: The cancelled enrollment's projection.

Throws: ServerError with status 412 when the id is stale.

WorkspaceEnrollmentControls.connect

Begins an eligible pre-prompt enrollment, or observes the exact pending one.

connect(options?: RequestOptions): Promise<WorkspaceEnrollmentState>;

Parameters:

• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<WorkspaceEnrollmentState>: The safe enrollment projection, including the browser URL while pending.

WorkspaceEnrollmentControls.retry

Cancels the exact pending enrollment and begins its replacement.

retry(enrollmentId: string, options?: RequestOptions): Promise<WorkspaceEnrollmentState>;

Parameters:

• enrollmentId (string): The enrollment to replace.
• options (RequestOptions, optional): Request headers, cancellation signal, and deadline.

Returns: Promise<WorkspaceEnrollmentState>: The replacement enrollment's projection.

Throws: ServerError with status 412 when the id is stale.

WorkspaceEnrollmentState

The safe projection of one workspace-services enrollment.

export interface WorkspaceEnrollmentState

WorkspaceEnrollmentState.enrollmentId

readonly enrollmentId: string;

WorkspaceEnrollmentState.presentationUrl

The browser URL to complete the enrollment, "" when none is pending.

readonly presentationUrl: string;

WorkspaceEnrollmentState.requiredServices

readonly requiredServices: number;

WorkspaceEnrollmentState.status

readonly status: string;

Worktrees

Session-scoped worktree inventory operations.

export interface Worktrees

Callable members: list()

Worktrees.list

Lists worktrees eligible for a session fork or clear operation.

list(request: ListWorktreesRequest, options?: RequestOptions): Promise<ListWorktreesResponse>;

Parameters:

• request (ListWorktreesRequest)
• options (RequestOptions, optional)

Returns: Promise<ListWorktreesResponse>

Type aliases

AgentEvent

The agent-lifecycle portion of the known event union.

export type AgentEvent = Exclude<KnownEvent, {
    readonly kind: `team.${string}`;
}>;

ConnectionStatus

The complete connection-state vocabulary exposed by the SDK.

export type ConnectionStatus = "connecting" | "online" | "reconnecting" | "offline" | "unauthorized" | "incompatible";

ConnectionStatusListener

A callback notified whenever connection status changes.

export type ConnectionStatusListener = (status: ConnectionStatus) => void;

ConnectOptions

Options accepted by the isomorphic connect() entry point.

export type ConnectOptions = HttpTransportOptions | InjectedTransportOptions;

CredentialProvider

Resolves request headers immediately before each SDK request.

export type CredentialProvider = () => HeadersInit | Promise<HeadersInit>;

DiagnosticFieldValue

Values carried by the structured fields of an SDK-local diagnostic.

export type DiagnosticFieldValue = boolean | number | string | null;

DiagnosticLevel

Severity attached to one SDK-local diagnostic record.

export type DiagnosticLevel = "debug" | "error" | "info" | "warn";

DiagnosticsSink

Optional client-level receiver for SDK-local diagnostics.

export type DiagnosticsSink = (record: DiagnosticRecord) => void;

ErrorOrigin

The request transport, or local when validation failed before transport selection.

export type ErrorOrigin = TransportKind | "local";

Event

A decoded agent or team event.

export type Event = KnownEvent | UnknownEvent;

EventOf

Selects one known event variant by its literal kind.

export type EventOf<Kind extends KnownEventKind> = Extract<KnownEvent, {
    readonly kind: Kind;
}>;

KnownEvent

All currently known agent and team event variants.

export type KnownEvent = {
    [Kind in KnownEventKind]: EventCommon & {
        readonly kind: Kind;
        readonly payload: EventPayloads[Kind];
    };
}[KnownEventKind];

KnownEventKind

A wire event kind currently understood by this SDK.

export type KnownEventKind = (typeof MECATL_EVENT_KINDS)[number];

MecatlErrorCode

Every machine-readable error code exposed by the SDK.

export type MecatlErrorCode = ServerErrorCode | SDKErrorCode;

PermissionAskResponder

An optional automatic responder invoked for each permission ask on a run.

export type PermissionAskResponder = (ask: PermissionAskEventPayload, signal: AbortSignal) => PermissionVerdict | undefined | Promise<PermissionVerdict | undefined>;

PermissionVerdict

A server permission verdict accepted by run.resolveAsk().

export type PermissionVerdict = "allow_once" | "allow_always" | "deny";

PlanApprovalResponder

An automatic responder invoked only for a PresentPlan approval ask.

export type PlanApprovalResponder = (ask: PermissionAskEventPayload, signal: AbortSignal) => PlanApprovalVerdict | undefined | Promise<PlanApprovalVerdict | undefined>;

PlanApprovalVerdict

The plan-specific decisions accepted by session.resolvePlan() and onPlanApproval.

export type PlanApprovalVerdict = "approve" | "accept_edits" | "iterate";

PromptInput

A backwards-compatible string prompt or structured text/media parts.

export type PromptInput = string | readonly PromptPart[];

PromptPart

One segment accepted by Session.run().

export type PromptPart = TextPromptPart | ImagePromptPart | AudioPromptPart;

PromptValidationReason

Stable reasons reported by PromptValidationError.

export type PromptValidationReason = "capability" | "mime_type" | "prompt" | "size" | "source_xor" | "url";

RequestOptions

Request controls shared by all thin typed namespaces.

export type RequestOptions = CallOptions;

RetryDisposition

Retry classification fields carried by model-retry and result payloads.

export type RetryDisposition = 0 | 1 | 2 | 3;

SdkCursor

A serializable cursor issued by a durable SDK attachment.

export type SdkCursor = string;

SDKErrorCode

Error codes produced locally by the SDK.

export type SDKErrorCode = "authentication" | "cursor_scope" | "incompatible_server" | "invalid_prompt" | "invalid_state" | "no_runs" | "plan_continuation_start" | "protocol" | "readiness_timeout" | "spawn_failed" | "tool_registration" | "transport" | "unsupported_platform" | "unsupported_feature";

ServerErrorCode

Error codes returned by the Mecatl server, plus unknown for future codes.

export type ServerErrorCode = (typeof MECATL_ERROR_CODES)[number] | "unknown";

ServerFeature

One known server feature identifier.

export type ServerFeature = (typeof ServerFeature)[keyof typeof ServerFeature];

ServerPosture

One known server posture value.

export type ServerPosture = (typeof ServerPosture)[keyof typeof ServerPosture];

SessionMode

One SDK permission-mode value.

export type SessionMode = (typeof SessionMode)[keyof typeof SessionMode];

SteerCancelOutcome

The server's answer to a cancel-steer control.

export type SteerCancelOutcome = "retracted" | "none_pending";

SteerOutcome

The server's answer to a steer control.

export type SteerOutcome = "accepted" | "appended" | "too_late";

StreamProgress

Stream-progress classification carried by model-retry and result payloads.

export type StreamProgress = 0 | 1 | 2 | 3 | 4;

TeamEvent

Team lifecycle events projected onto an agent run.

export type TeamEvent = Extract<KnownEvent, {
    readonly kind: `team.${string}`;
}>;

TeamMemberRunEvent

A run event tagged with the team member that produced it.

export type TeamMemberRunEvent = Event & {
    readonly member: string;
};

TeamRunEvent

A decoded direct-team stream frame.

export type TeamRunEvent = TeamMemberRunEvent | TeamOutcomeRunEvent;

TransportKind

Transport implementations supported by the SDK.

export type TransportKind = "grpc" | "http";

UnknownEvent

A future wire event that this SDK does not yet type.

export type UnknownEvent = UnknownHttpEvent | UnknownGrpcEvent;

WatchEnvelope

One decoded durable-watch delivery envelope.

export type WatchEnvelope = WatchEventEnvelope | WatchBoundaryEnvelope | WatchGapEnvelope | UnknownWatchEnvelope;

Variables

MAX_MEDIA_PART_BYTES

Maximum inline bytes in one image or audio part.

MAX_MEDIA_PART_BYTES: number

MAX_PROMPT_MEDIA_BYTES

Maximum inline media bytes in one prompt.

MAX_PROMPT_MEDIA_BYTES: number

MAX_PROMPT_MEDIA_PARTS

Maximum image and audio parts in one prompt.

MAX_PROMPT_MEDIA_PARTS = 16

MECATL_ATTACH_FILTERED_KINDS

Event kinds omitted by high-level attachment views unless requested.

MECATL_ATTACH_FILTERED_KINDS: readonly ["approval", "compaction.archive", "network.attempt", "request.manifest", "user_prompt"]

MECATL_ERROR_CODES

Stable server error codes, kept in parity with the Go registry.

MECATL_ERROR_CODES: readonly ["activity_gap", "attempt_live_claim_conflict", "attempt_terminal_conflict", "attempt_version_conflict", "child_not_found", "cleanup_backend", "cleanup_plan_stale", "cleanup_unsupported", "client_mcp_unreachable", "client_mcp_unsupported", "conflict", "context_window_unavailable", "cursor_expired", "cursor_malformed", "draining", "dream_apply_failed", "dream_capacity", "dream_conflict", "dream_deadline", "dream_generate_failed", "dream_in_progress", "dream_not_found", "dream_request_failed", "dream_terminal_conflict", "dream_unavailable", "failed_precondition", "failed_step_retry_ineligible", "fire_now_overlap", "internal", "invalid_argument", "learning_unavailable", "management_unauthorized", "mcp_connector_unavailable", "migration_backend", "migration_conflict", "migration_unsupported", "mcp_authorization_pending", "no_active_run", "no_event_log", "no_mcp_provider", "no_schedule_store", "not_awaiting_plan", "not_found", "placement_binding_invalid", "placement_changed", "placement_selector_invalid", "placement_selector_not_found", "placement_selector_stale", "placement_unavailable", "proposal_conflict", "reflection_cancelled", "reflection_deadline", "reflection_failed", "reflection_queue_full", "request_too_large", "resource_exhausted", "schedule_disabled", "schedule_exhausted", "schedule_not_found", "schedule_not_leader", "schedule_unsupported", "scheduler_not_running", "session_delete_unsupported", "session_leased_elsewhere", "session_metadata_cursor_restart", "session_metadata_paging_unsupported", "session_not_found", "stale_run_control", "storage_health_backend", "team_not_found", "team_not_running", "team_running", "teams_disabled", "too_many_session_engines", "too_many_teams", "unauthenticated", "unimplemented", "watch_capacity", "watch_lagging", "watch_unsupported"]

MECATL_EVENT_KINDS

Stable event kinds, kept in parity with the Go server vocabulary.

MECATL_EVENT_KINDS: readonly ["approval", "authorization.required", "authorization.resolved", "compaction", "compaction.archive", "hook", "message.delta", "model.retry", "network.attempt", "no_progress", "parallel.branch", "parallel.end", "parallel.start", "permission.ask", "permission.retract", "provider.route", "reasoning.delta", "recover_notice", "request.manifest", "result", "schedule.failed", "schedule.fired", "schedule.skipped", "session.init", "session.title", "steer", "steer.outcome", "subagent.end", "subagent.start", "subagent.tool", "team.end", "team.findings", "team.member", "team.start", "team.tasks", "tool.call", "tool.progress", "tool.result", "turn.end", "turn.start", "user_prompt"]

MECATL_WATCH_PHASES

Watch phases this SDK understands.

MECATL_WATCH_PHASES: readonly ["gap", "live", "replay"]

PLAN_APPROVAL_TOOL

The daemon's plan-approval tool name: a permission ask for this tool is a plan presented for operator review rather than an ordinary tool call.

PLAN_APPROVAL_TOOL = "PresentPlan"

PLAN_APPROVED_PROCEED_TEXT

The exact prompt the daemon expects when an approved plan continues into execution; clients that start the continuation themselves must send it verbatim.

PLAN_APPROVED_PROCEED_TEXT = "Plan approved by operator. Proceed with execution."

ServerFeature

Known server feature identifiers. Unknown identifiers remain observable.

ServerFeature: {
    readonly HttpSteer: "http_steer";
    readonly McpServersOnCreate: "mcp_servers_on_create";
    readonly ServerInfo: "server_info";
    readonly SessionActivityInventory: "session_activity_inventory";
    readonly WatchSessionEvents: "watch_session_events";
}

ServerPosture

Known server posture values. Unknown capability values remain observable.

ServerPosture: {
    readonly Strict: "strict";
    readonly Trusted: "trusted";
    readonly Auto: "auto";
    readonly Yolo: "yolo";
}

SESSION_ID_HEADER_NAME

Canonical routing hint for session-bound Mecatl requests. It grants no authority.

SESSION_ID_HEADER_NAME = "X-Mecatl-Session-ID"

SessionMode

SDK permission modes accepted by session creation and mutation operations.

SessionMode: {
    readonly Unspecified: 0;
    readonly Default: 1;
    readonly Plan: 2;
    readonly AcceptEdits: 3;
}

SUPPORTED_API_MAJOR

The API major implemented by this SDK.

SUPPORTED_API_MAJOR = 1

WATCH_SESSION_EVENTS_FEATURE

Known watch-session-events feature identifier.

WATCH_SESSION_EVENTS_FEATURE: "watch_session_events"