TypeScript SDK core API
This reference describes the declarations exported by @stacklok-oss/mecatl-sdk.
Symbol index
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. Malformed successful HTTP responses and ordinary SSE data frames omit the underlying JSON or protobuf decoder cause. They retain safe correlation metadata such as HTTP status and a response request ID when available. Server errors, authentication failures, and transport or body-read failures keep their separately defined cause behavior.
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">)
RunAuthorizationRequiredError
Run.result() consumed a valid authorization handoff instead of a completed result. Read outcome to create Session.mcpAuthorization() with the exact authorization ID.
export declare class RunAuthorizationRequiredError extends InvalidStateError
Callable members: constructor
RunAuthorizationRequiredError.constructor
Constructs a new instance of the RunAuthorizationRequiredError class
constructor(outcome: RunAuthorizationRequiredOutcome, options: Omit<MecatlErrorOptions, "code">);
Parameters:
outcome(RunAuthorizationRequiredOutcome)options(Omit<MecatlErrorOptions, "code">)
RunAuthorizationRequiredError.outcome
readonly outcome: RunAuthorizationRequiredOutcome;
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.askId
readonly askId: string;
ApprovalEventPayload.callId
readonly callId: string;
ApprovalEventPayload.tool
readonly tool: string;
ApprovalEventPayload.verdict
readonly verdict: 0 | 1 | 2 | 3;
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: cancel(), resolveAsk(), steer()
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 or valid authorization park.
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.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;
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
A reusable session-bound correlation handle for one server-owned authorization. Construction stores exact correlation only. It performs no I/O and makes no state or authority claim. The handle does not persist credentials or lifecycle truth. Every presentation lookup and control request receives automatic session affinity. It consumes session-scoped ToolHive broker authorization handoffs; it does not administer direct or global MCP profiles or credentials.
export interface McpAuthorization
Callable members: cancel(), presentation(), recheck()
McpAuthorization.authorizationId
readonly authorizationId: string;
McpAuthorization.cancel
Creates one lazy authorization cancellation flow.
cancel(options?: McpAuthorizationFlowOptions, requestOptions?: RequestOptions): McpAuthorizationFlow;
Parameters:
options(McpAuthorizationFlowOptions, optional): Permission handling for a possible continuation.requestOptions(RequestOptions, optional): Options used only when this flow starts.
Returns: McpAuthorizationFlow: A distinct, transport-lazy, single-consumption flow.
McpAuthorization.presentation
Reads the live presentation URL for this authorization. The application owns display and browser policy. The SDK validates and returns the HTTP(S) string without opening, copying, caching, rendering, or persisting it.
presentation(requestOptions?: RequestOptions): Promise<string>;
Parameters:
requestOptions(RequestOptions, optional): Request headers, callbacks, cancellation signal, and deadline.
Returns: Promise<string>: The server's current absolute HTTP(S) presentation URL.
Throws: ProtocolError when the response has no valid absolute HTTP(S) URL.
McpAuthorization.recheck
Creates one lazy authorization recheck flow.
recheck(options?: McpAuthorizationFlowOptions, requestOptions?: RequestOptions): McpAuthorizationFlow;
Parameters:
options(McpAuthorizationFlowOptions, optional): Permission handling for a possible continuation.requestOptions(RequestOptions, optional): Options used only when this flow starts.
Returns: McpAuthorizationFlow: A distinct, transport-lazy, single-consumption flow.
McpAuthorization.sessionId
readonly sessionId: string;
McpAuthorizationFlow
One lazy, single-consumption authorization control and optional continuation. Calling recheck() or cancel() creates this flow without I/O. The first iterator next() or result() performs the one control request with exact session affinity. Iteration and result() are mutually exclusive. Request cancellation releases SDK-owned resources but does not determine whether the server committed the control. The SDK does not poll, retry, reconnect, or scan durable activity automatically.
export interface McpAuthorizationFlow extends AsyncIterable<Event>
Callable members: cancelContinuation(), resolveAsk(), result()
McpAuthorizationFlow.authorizationId
readonly authorizationId: string;
McpAuthorizationFlow.cancelContinuation
Requests cancellation of the exact continuation run already observed by this flow.
cancelContinuation(requestOptions?: RequestOptions): Promise<void>;
Parameters:
requestOptions(RequestOptions, optional): Options used only for this cancellation mutation.
Returns: Promise<void>: A promise that resolves after the server accepts the request.
Throws: InvalidStateError before a continuation run is observed.
Throws: UnsupportedFeatureError when the server lacks prompt_free_controls.
McpAuthorizationFlow.continuationRunId
readonly continuationRunId: string | undefined;
McpAuthorizationFlow.operation
readonly operation: McpAuthorizationOperation;
McpAuthorizationFlow.resolveAsk
Resolves one observed ordinary permission ask on the exact continuation run.
resolveAsk(askId: string, verdict: PermissionVerdict, requestOptions?: RequestOptions): Promise<void>;
Parameters:
askId(string): ID of a pending ask already observed on this flow.verdict(PermissionVerdict): Application-owned permission decision to send unchanged.requestOptions(RequestOptions, optional): Options used only for this permission mutation.
Returns: Promise<void>: A promise that resolves after the server accepts the decision.
Throws: InvalidStateError when the ask is unknown, no longer pending, or plan-originated.
Throws: UnsupportedFeatureError when the server lacks prompt_free_controls.
McpAuthorizationFlow.result
Starts and drains this flow as its single consumption mode.
result(): Promise<McpAuthorizationResult>;
Returns: Promise<McpAuthorizationResult>: A pending, settled, completed, or chained-authorization result.
Throws: InvalidStateError when the flow is already being consumed.
Throws: ProtocolError when the server stream violates lifecycle correlation or grammar.
McpAuthorizationFlow.sessionId
readonly sessionId: string;
McpAuthorizationFlowOptions
Application-owned permission behavior for one authorization continuation. These options never choose an authorization status or browser policy. Automatic permission replies use only permissionRequestOptions, independently of the flow request options.
export interface McpAuthorizationFlowOptions
McpAuthorizationFlowOptions.onPermissionAsk
Automatically answers only ordinary permission asks observed on the continuation.
onPermissionAsk?: PermissionAskResponder;
McpAuthorizationFlowOptions.permissionRequestOptions
Request options used only for automatic permission replies.
permissionRequestOptions?: RequestOptions;
McpConnectorInventory
A current, nonhistorical snapshot of broker connector publication.
export interface McpConnectorInventory
McpConnectorInventory.availability
Whether the process-local broker snapshot is available.
readonly availability: McpConnectorAvailability;
McpConnectorInventory.connectors
Ordered bounded connector display rows.
readonly connectors: readonly McpConnectorStatus[];
McpConnectorInventory.enrollmentState
Aggregate whole-bundle enrollment state.
readonly enrollmentState: McpConnectorEnrollmentState;
McpConnectorInventory.totalConnectors
Total connector count before server-side truncation.
readonly totalConnectors: number;
McpConnectorInventory.truncated
Whether the connector rows omit entries because of the server bound.
readonly truncated: boolean;
McpConnectorStatus
A bounded connector display row. It is not a routing handle.
export interface McpConnectorStatus
McpConnectorStatus.catalogueState
Broker-local catalogue publication state.
readonly catalogueState: McpConnectorCatalogueState;
McpConnectorStatus.name
Display name supplied by the server.
readonly name: string;
McpConnectorStatus.toolCount
Number of published tools when the catalogue state makes that count meaningful.
readonly toolCount: number;
McpInventory
MCP resource, prompt, source, and ToolHive-group inventory operations.
export interface McpInventory
Callable members: getPrompt(), listPrompts(), listResources(), listSources(), listToolHiveGroups(), readResource(), refresh()
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>
McpInventory.refresh
Refreshes direct MCP sources for one eligible owned session.
refresh(request: RefreshMcpSourcesRequest, options?: RequestOptions): Promise<RefreshMcpSourcesResponse>;
Parameters:
request(RefreshMcpSourcesRequest)options(RequestOptions, optional)
Returns: Promise<RefreshMcpSourcesResponse>
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.routingDecision
readonly routingDecision?: RoutingDecisionEventPayload | undefined;
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.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;
RoutingDecisionEventPayload
Bounded configured-router evidence on delegation start events.
export interface RoutingDecisionEventPayload
RoutingDecisionEventPayload.backend
readonly backend: string;
RoutingDecisionEventPayload.breakerOpen
readonly breakerOpen: boolean;
RoutingDecisionEventPayload.candidateCategory
readonly candidateCategory: string;
RoutingDecisionEventPayload.candidateModel
readonly candidateModel: string;
RoutingDecisionEventPayload.classifierModel
readonly classifierModel: string;
RoutingDecisionEventPayload.confidence
readonly confidence?: number | undefined;
RoutingDecisionEventPayload.consecutiveMisses
readonly consecutiveMisses: number;
RoutingDecisionEventPayload.minimumConfidence
readonly minimumConfidence?: number | undefined;
RoutingDecisionEventPayload.missLimit
readonly missLimit: number;
RoutingDecisionEventPayload.outcome
readonly outcome: string;
Run
One accepted server run and its single-consumption event stream.
export interface Run extends AsyncIterable<Event>
Callable members: cancel(), outcome(), resolveAsk(), result(), steer()
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.outcome
Drains all remaining events and returns either completion or an authorization handoff.
outcome(): Promise<RunOutcome>;
Returns: Promise<RunOutcome>: The normal terminal outcome for this run.
Throws: InvalidStateError when the run is already being consumed.
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 verdict frame is handed to the active stream transport. This send-only API does not acknowledge server acceptance; use Session.controls(runId).resolveAsk() when an acknowledged control operation is required.
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 completed terminal result.
result(): Promise<RunResult>;
Returns: Promise<RunResult>: The terminal result for this run.
Throws: InvalidStateError when the run is already being consumed.
Throws: RunAuthorizationRequiredError when the run parks on external authorization.
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.
RunAuthorizationRequiredOutcome
A run that handed off one pending external authorization. This detached value carries correlation only. The server retains lifecycle ownership.
export interface RunAuthorizationRequiredOutcome
RunAuthorizationRequiredOutcome.authorization
readonly authorization: EventOf<"authorization.required">;
RunAuthorizationRequiredOutcome.outcome
readonly outcome: "authorization_required";
RunAuthorizationRequiredOutcome.runId
readonly runId: string;
RunAuthorizationRequiredOutcome.sessionId
readonly sessionId: string;
RunCompletedOutcome
A normally completed run outcome returned by Run.outcome().
export interface RunCompletedOutcome
RunCompletedOutcome.outcome
readonly outcome: "completed";
RunCompletedOutcome.result
readonly result: RunResult;
RunControls
Prompt-free controls bound to one exact session run. Construct this resource with Session.controls. It does not attach, subscribe, or keep a run alive. Every method requires the server's prompt_free_controls feature, addresses runId exactly, performs one unary request without automatic retry, and accepts ordinary RequestOptions. A server that lacks the feature raises UnsupportedFeatureError before a control RPC is sent. Ended, cancelling, replaced, or otherwise stale runs fail with the server's typed stale_run_control error. A transport failure, caller cancellation, or deadline after dispatch can reject the promise after the server accepted the operation. Reconcile that ambiguous case from the authoritative session or activity state before deciding whether to retry.
export interface RunControls
Callable members: cancel(), cancelSteer(), resolveAsk(), steer()
RunControls.cancel
Requests cancellation of this exact live run.
cancel(requestOptions?: RequestOptions): Promise<void>;
Parameters:
requestOptions(RequestOptions, optional): Request headers, cancellation signal, and deadline.
Returns: Promise<void>
RunControls.cancelSteer
Retracts this exact live run's pending steer bundle.
cancelSteer(options?: RunSteerOptions, requestOptions?: RequestOptions): Promise<RunSteerCancellationAcknowledgement>;
Parameters:
options(RunSteerOptions, optional): Optional message correlation for this retraction request.requestOptions(RequestOptions, optional): Request headers, cancellation signal, and deadline.
Returns: Promise<RunSteerCancellationAcknowledgement>: Whether the server retracted a bundle or found none pending.
RunControls.resolveAsk
Resolves one ordinary permission ask on this exact run. Root and surfaced-child permission asks are supported, including an ordinary ask restored from a persisted awaiting run. Plan-originated asks require Session.resolvePlan() and fail with plan_resolution_required. Unknown or already resolved asks fail with ask_not_pending. Unlike the stream-local Run.resolveAsk() send-only operation, this control returns only after the server acknowledges acceptance.
resolveAsk(askId: string, verdict: PermissionVerdict, requestOptions?: RequestOptions): Promise<void>;
Parameters:
askId(string): Exact permission ask ID.verdict(PermissionVerdict): Ordinary permission verdict to apply.requestOptions(RequestOptions, optional): Request headers, cancellation signal, and deadline.
Returns: Promise<void>
RunControls.runId
Exact durable run addressed by every operation.
readonly runId: string;
RunControls.sessionId
Session that owns the addressed run.
readonly sessionId: string;
RunControls.steer
Injects text or ordered media into this exact live run. Structured prompt text fragments are joined with a newline, and media parts retain their order relative to other media. An empty prompt is rejected locally. A late steer fails as stale and never creates a successor run.
steer(prompt: PromptInput, options?: RunSteerOptions, requestOptions?: RequestOptions): Promise<RunSteerAcknowledgement>;
Parameters:
prompt(PromptInput): Text, image, audio, or a structured prompt to inject.options(RunSteerOptions, optional): Optional message correlation.requestOptions(RequestOptions, optional): Request headers, cancellation signal, and deadline.
Returns: Promise<RunSteerAcknowledgement>: The server's accepted-or-appended acknowledgement.
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;
RunSteerAcknowledgement
The authoritative acknowledgement for a strict steer request. accepted means the steer created a pending bundle. appended means the steer was merged into the bundle that was already pending. The run and message IDs echo the addressed run and the request correlation.
export interface RunSteerAcknowledgement
RunSteerAcknowledgement.messageId
Request correlation ID, or an empty string when none was supplied.
readonly messageId: string;
RunSteerAcknowledgement.outcome
Whether the steer created or joined the pending bundle.
readonly outcome: "accepted" | "appended";
RunSteerAcknowledgement.runId
Exact run ID addressed by the request.
readonly runId: string;
RunSteerCancellationAcknowledgement
The authoritative acknowledgement for strict steer retraction. retracted means the pending bundle was removed. none_pending means the exact live run had no pending bundle at the transition point. The run and message IDs echo the addressed run and the request correlation.
export interface RunSteerCancellationAcknowledgement
RunSteerCancellationAcknowledgement.messageId
Request correlation ID, or an empty string when none was supplied.
readonly messageId: string;
RunSteerCancellationAcknowledgement.outcome
Whether a pending steer bundle was removed.
readonly outcome: "retracted" | "none_pending";
RunSteerCancellationAcknowledgement.runId
Exact run ID addressed by the request.
readonly runId: string;
RunSteerOptions
Optional application correlation for a strict steer or retraction request. The server accepts at most 64 Unicode code points and echoes the supplied ID in the operation's acknowledgement. Omission sends an empty correlation ID.
export interface RunSteerOptions
RunSteerOptions.messageId
Client-authored correlation ID echoed by the server.
messageId?: string;
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.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.shell
readonly shell: 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.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(), cancelWorkspaceEnrollment(), clear(), close(), compact(), connectWorkspaceServices(), controls(), delete(), listMcpConnectors(), mcpAuthorization(), rename(), resolvePlan(), retry(), retryWorkspaceEnrollment(), 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.cancelWorkspaceEnrollment
Cancels one exact workspace-enrollment correlation. The SDK accepts terminal server outcomes and leaves a future unknown value uninterpreted. It sends no follow-up request.
cancelWorkspaceEnrollment(enrollmentId: string, options?: RequestOptions): Promise<WorkspaceEnrollment>;
Parameters:
enrollmentId(string): Exact enrollment correlation to cancel.options(RequestOptions, optional): Request headers, cancellation signal, and deadline.
Returns: Promise<WorkspaceEnrollment>: The terminal server result, or unknown for a future result state.
Throws: ProtocolError when the returned correlation differs or a known result is pending.
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.connectWorkspaceServices
Starts or observes this session's whole-bundle workspace enrollment. Each invocation performs one target request. The SDK does not poll, retry, open a browser, or retain the returned presentation URL.
connectWorkspaceServices(options?: RequestOptions): Promise<WorkspaceEnrollment>;
Parameters:
options(RequestOptions, optional): Request headers, cancellation signal, and deadline.
Returns: Promise<WorkspaceEnrollment>: The immediate enrollment state and an ephemeral URL while pending.
Throws: ProtocolError when the successful response is structurally malformed.
Session.controls
Creates prompt-free controls bound to one exact run without opening a watch.
controls(runId: string): RunControls;
Parameters:
runId(string): Exact durable run ID to address.
Returns: RunControls: A synchronous lightweight control resource.
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.listMcpConnectors
Reads the current broker connector inventory for this session. The inventory describes broker-local publication rather than connector health or enrollment-attempt history. This method performs one target request and never starts enrollment or a direct MCP operation.
listMcpConnectors(options?: RequestOptions): Promise<McpConnectorInventory>;
Parameters:
options(RequestOptions, optional): Request headers, cancellation signal, and deadline.
Returns: Promise<McpConnectorInventory>: A detached SDK-owned connector inventory projection.
Session.mcpAuthorization
Binds one external authorization ID to this session without performing I/O. This handle consumes session-scoped ToolHive broker authorization handoffs. It does not administer direct or global MCP profiles or their credentials.
mcpAuthorization(authorizationId: string): McpAuthorization;
Parameters:
authorizationId(string): Exact non-empty ID from an authorization event.
Returns: McpAuthorization: A reusable correlation handle that makes no authorization-state assertion.
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 toapprove.
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.retryWorkspaceEnrollment
Replaces one exact pending workspace-enrollment correlation. Use this explicit operation when the application retained a pending correlation but lost its presentation URL. The SDK performs no automatic recovery after an ambiguous unary result.
retryWorkspaceEnrollment(enrollmentId: string, options?: RequestOptions): Promise<WorkspaceEnrollment>;
Parameters:
enrollmentId(string): Exact prior enrollment correlation to replace.options(RequestOptions, optional): Request headers, cancellation signal, and deadline.
Returns: Promise<WorkspaceEnrollment>: A replacement enrollment with a distinct correlation.
Throws: ProtocolError when the replacement correlation is missing or unchanged.
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.
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;
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.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>
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 and cleanup operations owned by the server.
export interface Storage
Callable members: applyCleanup(), cancelCleanup(), getCleanupJob(), getHealth(), planCleanup()
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.cancelCleanup
Cancels a session-storage cleanup.
cancelCleanup(request: CancelSessionCleanupRequest, options?: RequestOptions): Promise<CleanupJob>;
Parameters:
request(CancelSessionCleanupRequest)options(RequestOptions, optional)
Returns: Promise<CleanupJob>
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.planCleanup
Previews a session-storage cleanup.
planCleanup(request: PlanSessionCleanupRequest, options?: RequestOptions): Promise<PlanSessionCleanupResponse>;
Parameters:
request(PlanSessionCleanupRequest)options(RequestOptions, optional)
Returns: Promise<PlanSessionCleanupResponse>
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.routingDecision
readonly routingDecision?: RoutingDecisionEventPayload | undefined;
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.routingDecision
readonly routingDecision?: RoutingDecisionEventPayload | undefined;
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";
WorkspaceEnrollment
The immediate result of one whole-bundle workspace-enrollment operation.
export interface WorkspaceEnrollment
WorkspaceEnrollment.enrollmentId
Opaque correlation for this enrollment attempt.
readonly enrollmentId: string;
WorkspaceEnrollment.presentationUrl
Ephemeral application-facing HTTP(S) launch URL, present only while pending.
readonly presentationUrl?: string;
WorkspaceEnrollment.requiredServices
Number of services that the whole bundle requires.
readonly requiredServices: number;
WorkspaceEnrollment.status
Current operation state, or unknown for a future wire value.
readonly status: WorkspaceEnrollmentStatus;
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];
McpAuthorizationOperation
The one-shot server transition requested by an authorization flow.
export type McpAuthorizationOperation = "recheck" | "cancel";
McpAuthorizationResult
The authoritative result of one authorization recheck or cancellation. pending and settled have no continuation. completed carries one ordinary run result. authorization_required hands off a different authorization parked by the continuation.
export type McpAuthorizationResult = {
readonly outcome: "pending";
readonly status: "pending";
readonly authorization: EventOf<"authorization.required">;
} | {
readonly outcome: "settled";
readonly status: Exclude<McpAuthorizationStatus, "pending">;
readonly authorization: EventOf<"authorization.resolved">;
} | {
readonly outcome: "completed";
readonly status: Exclude<McpAuthorizationStatus, "pending">;
readonly authorization: EventOf<"authorization.resolved">;
readonly continuationRunId: string;
readonly continuation: RunResult;
} | {
readonly outcome: "authorization_required";
readonly status: Exclude<McpAuthorizationStatus, "pending">;
readonly authorization: EventOf<"authorization.resolved">;
readonly continuationRunId: string;
readonly nextAuthorization: EventOf<"authorization.required">;
};
McpAuthorizationStatus
The closed authorization status vocabulary interpreted by the lifecycle helper. The server remains authoritative for every status. An unknown value is a protocol error in this lifecycle even though the general event union keeps raw status strings open.
export type McpAuthorizationStatus = "pending" | "granted" | "denied" | "cancelled" | "expired" | "interrupted" | "failed" | "closed";
McpConnectorAvailability
One broker-snapshot availability value.
export type McpConnectorAvailability = (typeof McpConnectorAvailability)[keyof typeof McpConnectorAvailability];
McpConnectorCatalogueState
One connector catalogue-publication value.
export type McpConnectorCatalogueState = (typeof McpConnectorCatalogueState)[keyof typeof McpConnectorCatalogueState];
McpConnectorEnrollmentState
One aggregate connector-enrollment value.
export type McpConnectorEnrollmentState = (typeof McpConnectorEnrollmentState)[keyof typeof McpConnectorEnrollmentState];
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
One server permission verdict accepted by run.resolveAsk().
export type PermissionVerdict = (typeof PermissionVerdict)[keyof typeof PermissionVerdict];
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
One canonical retry-classification value.
export type RetryDisposition = (typeof RetryDisposition)[keyof typeof RetryDisposition];
RunOutcome
The closed set of completion and authorization-park outcomes from Run.outcome().
export type RunOutcome = RunCompletedOutcome | RunAuthorizationRequiredOutcome;
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];
StreamProgress
One canonical stream-progress value.
export type StreamProgress = (typeof StreamProgress)[keyof typeof StreamProgress];
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;
WorkspaceEnrollmentStatus
One workspace-enrollment operation state.
export type WorkspaceEnrollmentStatus = (typeof WorkspaceEnrollmentStatus)[keyof typeof WorkspaceEnrollmentStatus];
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
McpConnectorAvailability
Availability of the process-local broker snapshot for one session.
McpConnectorAvailability: {
readonly Available: "available";
readonly Unavailable: "unavailable";
readonly Unknown: "unknown";
}
McpConnectorCatalogueState
Broker-local catalogue publication state for one connector.
McpConnectorCatalogueState: {
readonly Hidden: "hidden";
readonly Declared: "declared";
readonly Discovered: "discovered";
readonly Unknown: "unknown";
}
McpConnectorEnrollmentState
Aggregate workspace-enrollment state reported by connector inventory.
McpConnectorEnrollmentState: {
readonly NotRequired: "not_required";
readonly NotStarted: "not_started";
readonly Pending: "pending";
readonly Completed: "completed";
readonly Unknown: "unknown";
}
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", "ask_not_pending", "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", "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", "plan_resolution_required", "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"]
PermissionVerdict
Canonical server permission verdicts.
PermissionVerdict: {
readonly AllowOnce: "allow_once";
readonly AllowAlways: "allow_always";
readonly Deny: "deny";
}
RetryDisposition
Canonical retry classifications carried by model-retry and result payloads.
RetryDisposition: {
readonly Unspecified: 0;
readonly Unknown: 1;
readonly Retryable: 2;
readonly Permanent: 3;
}
ServerFeature
Known server feature identifiers. Unknown identifiers remain observable.
ServerFeature: {
readonly HttpSteer: "http_steer";
readonly McpServersOnCreate: "mcp_servers_on_create";
readonly PromptFreeControls: "prompt_free_controls";
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;
}
StreamProgress
Canonical stream-progress classifications carried by model-retry and result payloads.
StreamProgress: {
readonly Unspecified: 0;
readonly Unknown: 1;
readonly Precommit: 2;
readonly Visible: 3;
readonly Complete: 4;
}
SUPPORTED_API_MAJOR
The API major implemented by this SDK.
SUPPORTED_API_MAJOR = 1
WorkspaceEnrollmentStatus
State returned by a whole-bundle workspace-enrollment operation.
WorkspaceEnrollmentStatus: {
readonly Pending: "pending";
readonly Connected: "connected";
readonly Denied: "denied";
readonly Cancelled: "cancelled";
readonly Expired: "expired";
readonly Failed: "failed";
readonly Unknown: "unknown";
}