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.
export declare class ProtocolError extends MecatlError
Callable members: constructor
ProtocolError.constructor
Constructs a new instance of the ProtocolError class
constructor(message: string, options: Omit<MecatlErrorOptions, "code">);
Parameters:
message(string)options(Omit<MecatlErrorOptions, "code">)
ServerError
A typed domain failure returned by the Mecatl server.
export declare class ServerError extends MecatlError
Callable members: constructor
ServerError.code
readonly code: ServerErrorCode;
ServerError.constructor
Constructs a new instance of the ServerError class
constructor(message: string, options: Omit<MecatlErrorOptions, "code"> & {
code: ServerErrorCode;
});
Parameters:
message(string)options(Omit<MecatlErrorOptions, "code"> & { code: ServerErrorCode; })
SessionBusyError
A local run is already active on this Session handle.
export declare class SessionBusyError extends InvalidStateError
TransportError
A request failed before the server returned a domain response.
export declare class TransportError extends MecatlError
Callable members: constructor
TransportError.constructor
Constructs a new instance of the TransportError class
constructor(message: string, options: Omit<MecatlErrorOptions, "code">);
Parameters:
message(string)options(Omit<MecatlErrorOptions, "code">)
UnsupportedFeatureError
The connected server does not advertise a required feature.
export declare class UnsupportedFeatureError extends MecatlError
Callable members: constructor
UnsupportedFeatureError.constructor
Constructs a new instance of the UnsupportedFeatureError class
constructor(feature: string, options: Omit<MecatlErrorOptions, "code">);
Parameters:
feature(string)options(Omit<MecatlErrorOptions, "code">)
UnsupportedFeatureError.feature
readonly feature: string;
Functions
audioPart
Constructs an audio part from inline bytes or an HTTPS URL.
export declare function audioPart(options: MediaPartOptions): AudioPromptPart;
Parameters:
options(MediaPartOptions): Audio source and MIME type.
Returns: AudioPromptPart: A validated audio prompt part.
Throws: PromptValidationError when the source, MIME type, or size is invalid.
audioPartFromBlob
Constructs an audio part from a browser Blob or File.
export declare function audioPartFromBlob(blob: Blob, mimeType?: string): Promise<AudioPromptPart>;
Parameters:
blob(Blob): Browser media value to read.mimeType(string, optional): Audio MIME type. Defaults to the Blob's type.
Returns: Promise<AudioPromptPart>: A validated audio prompt part containing the Blob's bytes.
Throws: PromptValidationError when the MIME type or size is invalid.
connect
Creates an isomorphic Client over HTTP or a caller-injected transport.
export declare function connect(options: ConnectOptions): Client;
Parameters:
options(ConnectOptions): HTTP transport settings or a caller-owned transport.
Returns: Client: A high-level Mecatl client.
createHttpTransport
Creates a browser-compatible Connect-ES transport over Mecatl's HTTP and SSE API.
export declare function createHttpTransport(options: HttpTransportOptions): Transport;
Parameters:
options(HttpTransportOptions): HTTP endpoint, credentials, and fetch implementation.
Returns: Transport: A Connect-ES transport for Mecatl's HTTP and SSE routes.
createRawClient
Creates a transport-neutral client for low-level RPC operations. Before the first requested operation, the client performs a stateless compatibility check.
export declare function createRawClient(options: RawClientOptions): RawClient;
Parameters:
options(RawClientOptions): Caller-owned transport and its protocol kind.
Returns: RawClient: A low-level client that enforces SDK compatibility before operations.
getRawJson
Returns the exact JSON value received by the HTTP transport, including unknown fields.
export declare function getRawJson(message: object): JsonValue | undefined;
Parameters:
message(object): Decoded protobuf message returned by the SDK.
Returns: JsonValue | undefined: The original JSON value, or undefined when none was recorded.
imagePart
Constructs an image part from inline bytes or an HTTPS URL.
export declare function imagePart(options: MediaPartOptions): ImagePromptPart;
Parameters:
options(MediaPartOptions): Image source and MIME type.
Returns: ImagePromptPart: A validated image prompt part.
Throws: PromptValidationError when the source, MIME type, or size is invalid.
imagePartFromBlob
Constructs an image part from a browser Blob or File.
export declare function imagePartFromBlob(blob: Blob, mimeType?: string): Promise<ImagePromptPart>;
Parameters:
blob(Blob): Browser media value to read.mimeType(string, optional): Image MIME type. Defaults to the Blob's type.
Returns: Promise<ImagePromptPart>: A validated image prompt part containing the Blob's bytes.
Throws: PromptValidationError when the MIME type or size is invalid.
textPart
Constructs a text segment for a structured prompt.
export declare function textPart(text: string): TextPromptPart;
Parameters:
text(string): Text to send in this prompt segment.
Returns: TextPromptPart: A text prompt part.
withSessionAffinity
Returns call options bound to one explicit session without replacing caller headers. Throws synchronously when sessionId cannot be represented byte-exactly as the affinity header. The binding is a routing hint only; authentication and authorization remain independent.
export declare function withSessionAffinity(sessionId: string, options?: CallOptions): CallOptions;
Parameters:
sessionId(string): Session ID to carry as the affinity header.options(CallOptions, optional): Existing call options whose headers must be preserved.
Returns: CallOptions: Call options containing exactly one session-affinity header.
Throws: RangeError when the session ID is not printable ASCII or is otherwise invalid.
Interfaces
Agents
Resolved agent-definition inventory operations.
export interface Agents
Callable members: list()
Agents.list
Lists the resolved agent definitions.
list(request: ListAgentsRequest, options?: RequestOptions): Promise<ListAgentsResponse>;
Parameters:
request(ListAgentsRequest)options(RequestOptions, optional)
Returns: Promise<ListAgentsResponse>
ApprovalEventPayload
The payload of an approval replay event.
export interface ApprovalEventPayload
ApprovalEventPayload.allowAlways
readonly allowAlways: boolean;
ApprovalEventPayload.askId
readonly askId: string;
ApprovalEventPayload.callId
readonly callId: string;
ApprovalEventPayload.tool
readonly tool: string;
ApprovalEventPayload.verdict
readonly verdict: string;
ArchivedConversationMessage
One conversation entry in a compaction archive.
export interface ArchivedConversationMessage
ArchivedConversationMessage.parts
readonly parts: readonly EventContent[];
ArchivedConversationMessage.providerPhase
readonly providerPhase: string;
ArchivedConversationMessage.reasoning
readonly reasoning: string;
ArchivedConversationMessage.reasoningItemId
readonly reasoningItemId: string;
ArchivedConversationMessage.role
readonly role: string;
ArchivedConversationMessage.text
readonly text: string;
ArchivedConversationMessage.toolCalls
readonly toolCalls: readonly ToolCallEventPayload[];
ArchivedConversationMessage.toolResult
readonly toolResult?: ToolResultEventPayload | undefined;
AttachedRun
A durable activity stream bound to one run.
export interface AttachedRun extends SessionActivity
Callable members: approve(), cancel(), resolveAsk(), steer()
AttachedRun.approve
Reports that approval controls are unavailable on durable attachments.
approve(askId: string, allow: boolean): Promise<never>;
Parameters:
askId(string): Permission-ask ID, retained for parity with a live run.allow(boolean): Boolean verdict, retained for parity with a live run.
Returns: Promise<never>: A rejected promise.
Throws: UnsupportedFeatureError for every call.
AttachedRun.cancel
Cancels the attached run using its exact run ID.
cancel(): Promise<void>;
Returns: Promise<void>: A promise that resolves after the cancellation request is accepted.
AttachedRun.live
True until this attachment observes its run's terminal result.
readonly live: boolean;
AttachedRun.resolveAsk
Reports that ask resolution is unavailable on durable attachments.
resolveAsk(askId: string, verdict: PermissionVerdict): Promise<never>;
Parameters:
askId(string): Permission-ask ID, retained for parity with a live run.verdict(PermissionVerdict): Permission verdict, retained for parity with a live run.
Returns: Promise<never>: A rejected promise.
Throws: UnsupportedFeatureError for every call.
AttachedRun.runId
readonly runId: string;
AttachedRun.steer
Reports that steering is unavailable on durable attachments.
steer(text: string): Promise<never>;
Parameters:
text(string): Steering text, retained for parity with a live run.
Returns: Promise<never>: A rejected promise.
Throws: UnsupportedFeatureError for every call.
AttachOptions
Where an attached run begins reading its durable activity.
export interface AttachOptions
AttachOptions.from
Starts with events received after attachment, discarding the existing replay locally.
from?: "now" | "start" | SdkCursor;
AttachOptions.includeLogOnly
Includes durable records omitted by the high-level view by default.
includeLogOnly?: boolean;
AttachOptions.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;
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.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
PermissionMode enum value from the generated ./gen entry point.
mode?: 0 | 1 | 2 | 3;
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>
EventCommon
Fields decoded for every event, including future event kinds.
export interface EventCommon
EventCommon.runId
readonly runId: string;
EventCommon.seq
readonly seq: bigint;
EventCommon.text
readonly text: string;
EventCommon.turn
readonly turn: number;
EventCommon.usage
readonly usage: EventUsage | undefined;
EventContent
One media part as represented on the protobuf event payloads.
export interface EventContent
EventContent.data
readonly data: Uint8Array;
EventContent.kind
readonly kind: 0 | 1 | 2;
EventContent.mimeType
readonly mimeType: string;
EventContent.url
readonly url: string;
EventContentBlock
One raw protobuf content block carried by a tool result.
export interface EventContentBlock
EventContentBlock.audience
readonly audience: readonly string[];
EventContentBlock.data
readonly data: Uint8Array;
EventContentBlock.description
readonly description: string;
EventContentBlock.kind
readonly kind: 0 | 1 | 2 | 3 | 4 | 5 | 6;
EventContentBlock.lastModified
readonly lastModified: string;
EventContentBlock.mimeType
readonly mimeType: string;
EventContentBlock.name
readonly name: string;
EventContentBlock.priority
readonly priority: number;
EventContentBlock.size
readonly size: bigint;
EventContentBlock.text
readonly text: string;
EventContentBlock.title
readonly title: string;
EventContentBlock.url
readonly url: string;
EventPayloads
Maps every supported event kind to its typed payload.
export interface EventPayloads
EventPayloads["authorization.required"]
readonly "authorization.required": AuthorizationEventPayload;
EventPayloads["authorization.resolved"]
readonly "authorization.resolved": AuthorizationEventPayload;
EventPayloads["compaction.archive"]
readonly "compaction.archive": CompactionArchiveEventPayload;
EventPayloads["message.delta"]
readonly "message.delta": undefined;
EventPayloads["model.retry"]
readonly "model.retry": ModelRetryEventPayload;
EventPayloads["network.attempt"]
readonly "network.attempt": undefined;
EventPayloads["parallel.branch"]
readonly "parallel.branch": ParallelEventPayload;
EventPayloads["parallel.end"]
readonly "parallel.end": ParallelEventPayload;
EventPayloads["parallel.start"]
readonly "parallel.start": ParallelEventPayload;
EventPayloads["permission.ask"]
readonly "permission.ask": PermissionAskEventPayload;
EventPayloads["permission.retract"]
readonly "permission.retract": PermissionAskEventPayload;
EventPayloads["provider.route"]
readonly "provider.route": undefined;
EventPayloads["reasoning.delta"]
readonly "reasoning.delta": undefined;
EventPayloads["request.manifest"]
readonly "request.manifest": undefined;
EventPayloads["schedule.failed"]
readonly "schedule.failed": ScheduleEventPayload;
EventPayloads["schedule.fired"]
readonly "schedule.fired": ScheduleEventPayload;
EventPayloads["schedule.skipped"]
readonly "schedule.skipped": ScheduleEventPayload;
EventPayloads["session.init"]
readonly "session.init": undefined;
EventPayloads["session.title"]
readonly "session.title": SessionTitleEventPayload;
EventPayloads["steer.outcome"]
readonly "steer.outcome": SteerOutcomeEventPayload;
EventPayloads["subagent.end"]
readonly "subagent.end": SubagentEventPayload;
EventPayloads["subagent.start"]
readonly "subagent.start": SubagentEventPayload;
EventPayloads["subagent.tool"]
readonly "subagent.tool": SubagentEventPayload;
EventPayloads["team.end"]
readonly "team.end": TeamEventPayload;
EventPayloads["team.findings"]
readonly "team.findings": TeamEventPayload;
EventPayloads["team.member"]
readonly "team.member": TeamEventPayload;
EventPayloads["team.start"]
readonly "team.start": TeamEventPayload;
EventPayloads["team.tasks"]
readonly "team.tasks": TeamEventPayload;
EventPayloads["tool.call"]
readonly "tool.call": ToolCallEventPayload;
EventPayloads["tool.progress"]
readonly "tool.progress": undefined;
EventPayloads["tool.result"]
readonly "tool.result": ToolResultEventPayload;
EventPayloads["turn.end"]
readonly "turn.end": TurnEndEventPayload;
EventPayloads["turn.start"]
readonly "turn.start": undefined;
EventPayloads.approval
readonly approval: ApprovalEventPayload;
EventPayloads.compaction
readonly compaction: undefined;
EventPayloads.hook
readonly hook: HookEventPayload;
EventPayloads.no_progress
readonly no_progress: undefined;
EventPayloads.recover_notice
readonly recover_notice: undefined;
EventPayloads.result
readonly result: ResultEventPayload;
EventPayloads.steer
readonly steer: SteerEventPayload;
EventPayloads.user_prompt
readonly user_prompt: UserPromptEventPayload;
EventUsage
Token accounting carried by usage-bearing events.
export interface EventUsage
EventUsage.cacheReadTokens
readonly cacheReadTokens: bigint;
EventUsage.cacheWriteTokens
readonly cacheWriteTokens: bigint;
EventUsage.inputTokens
readonly inputTokens: bigint;
EventUsage.outputTokens
readonly outputTokens: bigint;
EventUsage.reasoningTokens
readonly reasoningTokens: bigint;
ForkSessionOptions
Optional overrides accepted when forking a session.
export interface ForkSessionOptions
ForkSessionOptions.reasoningEffort
Requested reasoning-effort tier for the forked session.
reasoningEffort?: string;
ForkSessionOptions.title
Human-readable title for the forked session.
title?: 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>
McpInventory
MCP resource, prompt, source, and ToolHive-group inventory operations.
export interface McpInventory
Callable members: getPrompt(), listPrompts(), listResources(), listSources(), listToolHiveGroups(), readResource()
McpInventory.getPrompt
Expands one MCP prompt into its rendered messages.
getPrompt(request: GetMcpPromptRequest, options?: RequestOptions): Promise<GetMcpPromptResponse>;
Parameters:
request(GetMcpPromptRequest)options(RequestOptions, optional)
Returns: Promise<GetMcpPromptResponse>
McpInventory.listPrompts
Lists the MCP prompts exposed by configured servers.
listPrompts(request: ListMcpPromptsRequest, options?: RequestOptions): Promise<ListMcpPromptsResponse>;
Parameters:
request(ListMcpPromptsRequest)options(RequestOptions, optional)
Returns: Promise<ListMcpPromptsResponse>
McpInventory.listResources
Lists the MCP resources exposed by configured servers.
listResources(request: ListMcpResourcesRequest, options?: RequestOptions): Promise<ListMcpResourcesResponse>;
Parameters:
request(ListMcpResourcesRequest)options(RequestOptions, optional)
Returns: Promise<ListMcpResourcesResponse>
McpInventory.listSources
Lists configured MCP sources and their diagnostics.
listSources(request: ListMcpSourcesRequest, options?: RequestOptions): Promise<ListMcpSourcesResponse>;
Parameters:
request(ListMcpSourcesRequest)options(RequestOptions, optional)
Returns: Promise<ListMcpSourcesResponse>
McpInventory.listToolHiveGroups
Lists ToolHive groups present in the resolved MCP inventory.
listToolHiveGroups(request: ListToolHiveGroupsRequest, options?: RequestOptions): Promise<ListToolHiveGroupsResponse>;
Parameters:
request(ListToolHiveGroupsRequest)options(RequestOptions, optional)
Returns: Promise<ListToolHiveGroupsResponse>
McpInventory.readResource
Reads one MCP resource by URI.
readResource(request: ReadMcpResourceRequest, options?: RequestOptions): Promise<ReadMcpResourceResponse>;
Parameters:
request(ReadMcpResourceRequest)options(RequestOptions, optional)
Returns: Promise<ReadMcpResourceResponse>
MecatlErrorOptions
Metadata attached to one MecatlError.
export interface MecatlErrorOptions
MecatlErrorOptions.cause
Original failure retained on the JavaScript Error instance.
cause?: unknown;
MecatlErrorOptions.code
Stable machine-readable SDK or server error code.
code: MecatlErrorCode;
MecatlErrorOptions.requestId
Server request ID, when the transport supplied one.
requestId?: string | undefined;
MecatlErrorOptions.status
HTTP status, when the failure came from the HTTP transport.
status?: number | undefined;
MecatlErrorOptions.transport
Transport that observed the failure, or local for SDK validation.
transport: ErrorOrigin;
MediaPartOptions
Options accepted by imagePart() and audioPart().
export interface MediaPartOptions extends MediaPartSource
MediaPartOptions.mimeType
Media type beginning with image/ or audio/ for the selected helper.
mimeType: string;
MediaPartSource
The source accepted by imagePart() and audioPart(). Exactly one field is required.
export interface MediaPartSource
MediaPartSource.bytes
Inline media bytes.
bytes?: Uint8Array;
MediaPartSource.url
Absolute HTTPS media URL.
url?: string;
ModelRetryEventPayload
The payload of a model.retry event.
export interface ModelRetryEventPayload
ModelRetryEventPayload.retryDisposition
readonly retryDisposition: RetryDisposition;
ModelRetryEventPayload.streamProgress
readonly streamProgress: StreamProgress;
Models
Selectable model inventory operations.
export interface Models
Callable members: list()
Models.list
Lists selectable providers and models.
list(request: ListModelsRequest, options?: RequestOptions): Promise<ListModelsResponse>;
Parameters:
request(ListModelsRequest)options(RequestOptions, optional)
Returns: Promise<ListModelsResponse>
ParallelEventPayload
The payload shared by parallel.* events.
export interface ParallelEventPayload
ParallelEventPayload.branchCount
readonly branchCount: number;
ParallelEventPayload.branchIndex
readonly branchIndex: number;
ParallelEventPayload.branchLabel
readonly branchLabel: string;
ParallelEventPayload.childId
readonly childId: string;
ParallelEventPayload.detail
readonly detail: string;
ParallelEventPayload.durationMs
readonly durationMs: bigint;
ParallelEventPayload.failed
readonly failed: boolean;
ParallelEventPayload.goal
readonly goal: string;
ParallelEventPayload.innerKind
readonly innerKind: string;
ParallelEventPayload.isError
readonly isError: boolean;
ParallelEventPayload.join
readonly join: string;
ParallelEventPayload.kind
readonly kind: string;
ParallelEventPayload.model
readonly model: string;
ParallelEventPayload.parentCallId
readonly parentCallId: string;
ParallelEventPayload.routedCategory
readonly routedCategory: string;
ParallelEventPayload.routedModel
readonly routedModel: string;
ParallelEventPayload.routingReason
readonly routingReason: string;
ParallelEventPayload.stop
readonly stop: string;
ParallelEventPayload.text
readonly text: string;
ParallelEventPayload.toolCount
readonly toolCount: number;
ParallelEventPayload.toolName
readonly toolName: string;
ParallelEventPayload.usage
readonly usage?: EventUsage | undefined;
ParallelEventPayload.winner
readonly winner: number;
ParallelEventPayload.winnerWorkspace
readonly winnerWorkspace: string;
ParallelEventPayload.workspace
readonly workspace: string;
PermissionAskEventPayload
The payload shared by permission.ask and permission.retract.
export interface PermissionAskEventPayload
PermissionAskEventPayload.args
readonly args: string;
PermissionAskEventPayload.askId
readonly askId: string;
PermissionAskEventPayload.reason
readonly reason: string;
PermissionAskEventPayload.tool
readonly tool: string;
PlanResolution
One atomic, single-consumption resolution of a durably parked plan.
export interface PlanResolution extends AsyncIterable<Event>
Callable members: result()
PlanResolution.result
Drains the merged stream and returns the resumed and optional continuation outcomes.
result(): Promise<PlanResolutionResult>;
Returns: Promise<PlanResolutionResult>: The resumed run and any continuation run started by approval.
Throws: InvalidStateError when the resolution is already being consumed.
Throws: PlanContinuationStartError when an approved continuation cannot start.
PlanResolutionResult
The two ordered outcomes carried by one atomic plan-resolution stream.
export interface PlanResolutionResult
PlanResolutionResult.continuation
readonly continuation?: RunResult;
PlanResolutionResult.resumed
readonly resumed: RunResult;
RawClient
Transport-neutral, descriptor-driven operations beneath Client/Session/Run.
export interface RawClient
Callable members: features(), stream(), unary()
RawClient.features
Returns the build features learned from the shared compatibility probe.
features(options?: CallOptions): Promise<ReadonlySet<string>>;
Parameters:
options(CallOptions, optional)
Returns: Promise<ReadonlySet<string>>
RawClient.stream
Invokes one streaming RPC after enforcing the SDK compatibility floor.
stream<I extends DescMessage, O extends DescMessage>(method: DescMethodStreaming<I, O>, input: AsyncIterable<MessageInitShape<I>>, options?: CallOptions): AsyncIterable<MessageShape<O>>;
Parameters:
method(DescMethodStreaming<I, O>)input(AsyncIterable<MessageInitShape<I>>)options(CallOptions, optional)
Returns: AsyncIterable<MessageShape<O>>
RawClient.unary
Invokes one unary RPC after enforcing the SDK compatibility floor.
unary<I extends DescMessage, O extends DescMessage>(method: DescMethodUnary<I, O>, input: MessageInitShape<I>, options?: CallOptions): Promise<MessageShape<O>>;
Parameters:
method(DescMethodUnary<I, O>)input(MessageInitShape<I>)options(CallOptions, optional)
Returns: Promise<MessageShape<O>>
RawClientOptions
Options for constructing the transport-neutral raw client.
export interface RawClientOptions
RawClientOptions.transport
A caller-owned Connect-ES transport.
transport: Transport;
RawClientOptions.transportKind
Required only for an unregistered injected transport. Defaults to gRPC.
transportKind?: TransportKind;
Reflection
Session-reflection operations.
export interface Reflection
Callable members: reflect()
Reflection.reflect
Reflects one completed session into learning evidence.
reflect(request: ReflectSessionRequest, options?: RequestOptions): Promise<ReflectSessionResponse>;
Parameters:
request(ReflectSessionRequest)options(RequestOptions, optional)
Returns: Promise<ReflectSessionResponse>
ResultEventPayload
The payload of a terminal result event.
export interface ResultEventPayload
ResultEventPayload.error
readonly error: string;
ResultEventPayload.permanent
readonly permanent: boolean;
ResultEventPayload.retryDisposition
readonly retryDisposition?: RetryDisposition | undefined;
ResultEventPayload.stop
readonly stop: string;
ResultEventPayload.streamProgress
readonly streamProgress?: StreamProgress | undefined;
ResultEventPayload.text
readonly text: string;
ResultEventPayload.usage
readonly usage?: EventUsage | undefined;
Run
One accepted server run and its single-consumption event stream.
export interface Run extends AsyncIterable<Event>
Callable members: approve(), cancel(), resolveAsk(), result(), steer()
Run.approve
Sends a Boolean permission verdict for a permission.ask event.
approve(askId: string, allow: boolean): Promise<void>;
Parameters:
askId(string): ID carried by the permission ask.allow(boolean): Whether to allow the call once.
Returns: Promise<void>: A promise that resolves after the verdict is sent.
Throws: PermissionAskAlreadyResolvedError when the ask is no longer pending.
Run.cancel
Requests cancellation; consume the run normally to receive the cancelled outcome.
cancel(): Promise<void>;
Returns: Promise<void>: A promise that resolves after the cancellation request is sent.
Run.id
readonly id: string;
Run.resolveAsk
Resolves one pending ask on this run with the server's string verdict vocabulary.
resolveAsk(askId: string, verdict: PermissionVerdict): Promise<void>;
Parameters:
askId(string): ID carried by the permission ask.verdict(PermissionVerdict): Decision to apply to the pending ask.
Returns: Promise<void>: A promise that resolves after the server accepts the verdict.
Throws: PermissionAskAlreadyResolvedError when the ask is no longer pending.
Throws: InvalidStateError when used for a plan-approval ask.
Run.result
Drains all remaining events and returns the typed terminal outcome.
result(): Promise<RunResult>;
Returns: Promise<RunResult>: The terminal result for this run.
Throws: InvalidStateError when the run is already being consumed.
Run.sessionId
readonly sessionId: string;
Run.steer
Strictly steers this run. A late steer is refused and is never promoted.
steer(text: string): Promise<void>;
Parameters:
text(string): Instruction to apply to the active run.
Returns: Promise<void>: A promise that resolves after the steering request is sent.
RunOptions
Options applied to one run.
export interface RunOptions
RunOptions.onPermissionAsk
Automatically answers ordinary permission asks.
onPermissionAsk?: PermissionAskResponder;
RunOptions.onPlanApproval
Automatically answers only plan-originated PresentPlan asks.
onPlanApproval?: PlanApprovalResponder;
RunResult
The terminal outcome of a consumed run. Server-declared stops are values, not errors.
export interface RunResult
RunResult.content
readonly content: string;
RunResult.rawEvent
The terminal event from the same discriminated union exposed by iteration.
readonly rawEvent: EventOf<"result">;
RunResult.runId
readonly runId: string;
RunResult.sessionId
readonly sessionId: string;
RunResult.stopReason
readonly stopReason: string;
RunResult.text
Final text, mirrored as content for content-oriented consumers.
readonly text: string;
RunResult.usage
readonly usage: EventUsage | undefined;
ScheduleEventPayload
The payload shared by schedule.* events.
export interface ScheduleEventPayload
ScheduleEventPayload.err
readonly err: string;
ScheduleEventPayload.fireId
readonly fireId: string;
ScheduleEventPayload.kind
readonly kind: string;
ScheduleEventPayload.scheduleName
readonly scheduleName: string;
ScheduleEventPayload.sessionId
readonly sessionId: string;
ScheduleEventPayload.stop
readonly stop: string;
Schedules
Schedule and fire inventory plus server-owned lifecycle operations.
export interface Schedules
Callable members: create(), delete(), fireNow(), get(), getFire(), list(), listFires(), pause(), resume(), update()
Schedules.create
Creates a recurring schedule.
create(request: CreateScheduleRequest, options?: RequestOptions): Promise<CreateScheduleResponse>;
Parameters:
request(CreateScheduleRequest)options(RequestOptions, optional)
Returns: Promise<CreateScheduleResponse>
Schedules.delete
Deletes one schedule.
delete(request: DeleteScheduleRequest, options?: RequestOptions): Promise<DeleteScheduleResponse>;
Parameters:
request(DeleteScheduleRequest)options(RequestOptions, optional)
Returns: Promise<DeleteScheduleResponse>
Schedules.fireNow
Requests an immediate schedule fire.
fireNow(request: FireNowRequest, options?: RequestOptions): Promise<FireNowResponse>;
Parameters:
request(FireNowRequest)options(RequestOptions, optional)
Returns: Promise<FireNowResponse>
Schedules.get
Gets one schedule.
get(request: GetScheduleRequest, options?: RequestOptions): Promise<GetScheduleResponse>;
Parameters:
request(GetScheduleRequest)options(RequestOptions, optional)
Returns: Promise<GetScheduleResponse>
Schedules.getFire
Gets one schedule fire.
getFire(request: GetFireRequest, options?: RequestOptions): Promise<GetFireResponse>;
Parameters:
request(GetFireRequest)options(RequestOptions, optional)
Returns: Promise<GetFireResponse>
Schedules.list
Lists schedules visible to the caller.
list(request: ListSchedulesRequest, options?: RequestOptions): Promise<ListSchedulesResponse>;
Parameters:
request(ListSchedulesRequest)options(RequestOptions, optional)
Returns: Promise<ListSchedulesResponse>
Schedules.listFires
Lists fires for a schedule.
listFires(request: ListFiresRequest, options?: RequestOptions): Promise<ListFiresResponse>;
Parameters:
request(ListFiresRequest)options(RequestOptions, optional)
Returns: Promise<ListFiresResponse>
Schedules.pause
Pauses one schedule.
pause(request: PauseScheduleRequest, options?: RequestOptions): Promise<PauseScheduleResponse>;
Parameters:
request(PauseScheduleRequest)options(RequestOptions, optional)
Returns: Promise<PauseScheduleResponse>
Schedules.resume
Resumes one paused schedule.
resume(request: ResumeScheduleRequest, options?: RequestOptions): Promise<ResumeScheduleResponse>;
Parameters:
request(ResumeScheduleRequest)options(RequestOptions, optional)
Returns: Promise<ResumeScheduleResponse>
Schedules.update
Updates one schedule.
update(request: UpdateScheduleRequest, options?: RequestOptions): Promise<UpdateScheduleResponse>;
Parameters:
request(UpdateScheduleRequest)options(RequestOptions, optional)
Returns: Promise<UpdateScheduleResponse>
Session
A durable Mecatl session handle.
export interface Session
Callable members: activity(), attach(), close(), delete(), resolvePlan(), run()
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.close
Releases runtime resources without removing the durable session.
close(): Promise<void>;
Returns: Promise<void>: A promise that resolves after local session resources are released.
Session.delete
Permanently removes the durable session and its sidecars.
delete(): Promise<void>;
Returns: Promise<void>: A promise that resolves after the server removes the session.
Session.id
readonly id: string;
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.run
Starts a run and resolves once its first run-ID-bearing event arrives.
run(prompt: PromptInput, options?: RunOptions): 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.
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.
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;
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;
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): Promise<Session>;
Parameters:
options(CreateSessionOptions)
Returns: Promise<Session>
Sessions.fork
Forks an existing session into a new session.
fork(sourceSessionId: string, options?: ForkSessionOptions): Promise<Session>;
Parameters:
sourceSessionId(string)options(ForkSessionOptions, optional)
Returns: Promise<Session>
Sessions.get
Loads an existing session by ID.
get(sessionId: string): Promise<Session>;
Parameters:
sessionId(string)
Returns: Promise<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>
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;
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, migration, and cleanup operations owned by the server.
export interface Storage
Callable members: applyCleanup(), applyMigration(), cancelCleanup(), cancelMigration(), getCleanupJob(), getHealth(), getMigrationJob(), planCleanup(), planMigration(), resumeMigration()
Storage.applyCleanup
Starts a planned session-storage cleanup.
applyCleanup(request: ApplySessionCleanupRequest, options?: RequestOptions): Promise<CleanupJob>;
Parameters:
request(ApplySessionCleanupRequest)options(RequestOptions, optional)
Returns: Promise<CleanupJob>
Storage.applyMigration
Starts a planned session-storage migration.
applyMigration(request: ApplySessionMigrationRequest, options?: RequestOptions): Promise<SessionMigrationJob>;
Parameters:
request(ApplySessionMigrationRequest)options(RequestOptions, optional)
Returns: Promise<SessionMigrationJob>
Storage.cancelCleanup
Cancels a session-storage cleanup.
cancelCleanup(request: CancelSessionCleanupRequest, options?: RequestOptions): Promise<CleanupJob>;
Parameters:
request(CancelSessionCleanupRequest)options(RequestOptions, optional)
Returns: Promise<CleanupJob>
Storage.cancelMigration
Cancels a session-storage migration.
cancelMigration(request: CancelSessionMigrationRequest, options?: RequestOptions): Promise<SessionMigrationJob>;
Parameters:
request(CancelSessionMigrationRequest)options(RequestOptions, optional)
Returns: Promise<SessionMigrationJob>
Storage.getCleanupJob
Gets one session-storage cleanup job.
getCleanupJob(request: GetSessionCleanupJobRequest, options?: RequestOptions): Promise<CleanupJob>;
Parameters:
request(GetSessionCleanupJobRequest)options(RequestOptions, optional)
Returns: Promise<CleanupJob>
Storage.getHealth
Gets the configured session-storage health.
getHealth(request: GetStorageHealthRequest, options?: RequestOptions): Promise<GetStorageHealthResponse>;
Parameters:
request(GetStorageHealthRequest)options(RequestOptions, optional)
Returns: Promise<GetStorageHealthResponse>
Storage.getMigrationJob
Gets one session-storage migration job.
getMigrationJob(request: GetSessionMigrationJobRequest, options?: RequestOptions): Promise<SessionMigrationJob>;
Parameters:
request(GetSessionMigrationJobRequest)options(RequestOptions, optional)
Returns: Promise<SessionMigrationJob>
Storage.planCleanup
Previews a session-storage cleanup.
planCleanup(request: PlanSessionCleanupRequest, options?: RequestOptions): Promise<PlanSessionCleanupResponse>;
Parameters:
request(PlanSessionCleanupRequest)options(RequestOptions, optional)
Returns: Promise<PlanSessionCleanupResponse>
Storage.planMigration
Previews a session-storage migration.
planMigration(request: PlanSessionMigrationRequest, options?: RequestOptions): Promise<SessionMigrationPlan>;
Parameters:
request(PlanSessionMigrationRequest)options(RequestOptions, optional)
Returns: Promise<SessionMigrationPlan>
Storage.resumeMigration
Resumes an interrupted session-storage migration.
resumeMigration(request: ResumeSessionMigrationRequest, options?: RequestOptions): Promise<SessionMigrationJob>;
Parameters:
request(ResumeSessionMigrationRequest)options(RequestOptions, optional)
Returns: Promise<SessionMigrationJob>
SubagentEventPayload
The payload shared by subagent.* events.
export interface SubagentEventPayload
SubagentEventPayload.background
readonly background: boolean;
SubagentEventPayload.cause
readonly cause: string;
SubagentEventPayload.childId
readonly childId: string;
SubagentEventPayload.detail
readonly detail: string;
SubagentEventPayload.durationMs
readonly durationMs: bigint;
SubagentEventPayload.goal
readonly goal: string;
SubagentEventPayload.innerKind
readonly innerKind: string;
SubagentEventPayload.isError
readonly isError: boolean;
SubagentEventPayload.model
readonly model: string;
SubagentEventPayload.parentCallId
readonly parentCallId: string;
SubagentEventPayload.routedCategory
readonly routedCategory: string;
SubagentEventPayload.routedModel
readonly routedModel: string;
SubagentEventPayload.routingReason
readonly routingReason: string;
SubagentEventPayload.stop
readonly stop: string;
SubagentEventPayload.text
readonly text: string;
SubagentEventPayload.toolCount
readonly toolCount: number;
SubagentEventPayload.toolName
readonly toolName: string;
SubagentEventPayload.usage
readonly usage?: EventUsage | undefined;
Team
A handle for direct team operations.
export interface Team
Callable members: cancel(), cleanup(), list(), message(), run(), spawn()
Team.cancel
Cancels one team member.
cancel(member: string, options?: RequestOptions): Promise<CancelTeammateResponse>;
Parameters:
member(string)options(RequestOptions, optional)
Returns: Promise<CancelTeammateResponse>
Team.cleanup
Permanently removes the server-owned team.
cleanup(options?: RequestOptions): Promise<CleanupTeamResponse>;
Parameters:
options(RequestOptions, optional)
Returns: Promise<CleanupTeamResponse>
Team.id
readonly id: string;
Team.initialMembers
The typed initial roster returned atomically by CreateTeam. This is not a live view.
readonly initialMembers: readonly TeamMember[];
Team.list
Returns the current team roster and state.
list(options?: RequestOptions): Promise<ListTeamResponse>;
Parameters:
options(RequestOptions, optional)
Returns: Promise<ListTeamResponse>
Team.message
Sends a message to a team member.
message(message: TeamMessageOptions, options?: RequestOptions): Promise<SendTeammateMessageResponse>;
Parameters:
message(TeamMessageOptions)options(RequestOptions, optional)
Returns: Promise<SendTeammateMessageResponse>
Team.run
Starts a single-consumption team run.
run(options?: RequestOptions): TeamRun;
Parameters:
options(RequestOptions, optional)
Returns: TeamRun
Team.spawn
Adds one member to the team.
spawn(member: TeamMemberOptions, options?: RequestOptions): Promise<SpawnTeammateResponse>;
Parameters:
member(TeamMemberOptions)options(RequestOptions, optional)
Returns: Promise<SpawnTeammateResponse>
TeamEventPayload
The payload shared by team.* events.
export interface TeamEventPayload
TeamEventPayload.cause
readonly cause: string;
TeamEventPayload.contextUsed
readonly contextUsed: bigint;
TeamEventPayload.contextWindow
readonly contextWindow: bigint;
TeamEventPayload.detail
readonly detail: string;
TeamEventPayload.dispositions
readonly dispositions: readonly TeamMemberDispositionEventPayload[];
TeamEventPayload.findings
readonly findings: readonly TeamFindingEventPayload[];
TeamEventPayload.innerKind
readonly innerKind: string;
TeamEventPayload.isError
readonly isError: boolean;
TeamEventPayload.member
readonly member: string;
TeamEventPayload.memberSessionId
readonly memberSessionId: string;
TeamEventPayload.parentCallId
readonly parentCallId: string;
TeamEventPayload.roster
readonly roster: readonly TeamMemberSpecEventPayload[];
TeamEventPayload.rounds
readonly rounds: number;
TeamEventPayload.stop
readonly stop: string;
TeamEventPayload.tasks
readonly tasks: readonly TeamTaskEventPayload[];
TeamEventPayload.teamId
readonly teamId: string;
TeamEventPayload.text
readonly text: string;
TeamEventPayload.toolName
readonly toolName: string;
TeamEventPayload.usage
readonly usage?: EventUsage | undefined;
TeamFindingEventPayload
One finding in a team event snapshot.
export interface TeamFindingEventPayload
TeamFindingEventPayload.body
readonly body: string;
TeamFindingEventPayload.member
readonly member: string;
TeamMemberDispositionEventPayload
One terminal member disposition in a team.end payload.
export interface TeamMemberDispositionEventPayload
TeamMemberDispositionEventPayload.errorRounds
readonly errorRounds: number;
TeamMemberDispositionEventPayload.name
readonly name: string;
TeamMemberDispositionEventPayload.reason
readonly reason: 0 | 1 | 2 | 3;
TeamMemberDispositionEventPayload.stopped
readonly stopped: boolean;
TeamMemberOptions
One initial or incrementally spawned team member.
export interface TeamMemberOptions
TeamMemberOptions.agentType
Agent-definition name adopted by this member.
agentType?: string;
TeamMemberOptions.initialPrompt
First-turn prompt for this member.
initialPrompt?: string;
TeamMemberOptions.lead
Marks this member as the team coordinator.
lead?: boolean;
TeamMemberOptions.mutating
Requests an isolated workspace with mutating tools.
mutating?: boolean;
TeamMemberOptions.name
Unique handle used to address this member.
name: string;
TeamMemberSpecEventPayload
One member in a team.start roster.
export interface TeamMemberSpecEventPayload
TeamMemberSpecEventPayload.lead
readonly lead: boolean;
TeamMemberSpecEventPayload.model
readonly model: string;
TeamMemberSpecEventPayload.mutating
readonly mutating: boolean;
TeamMemberSpecEventPayload.name
readonly name: string;
TeamMemberSpecEventPayload.role
readonly role: string;
TeamMemberSpecEventPayload.routedCategory
readonly routedCategory: string;
TeamMemberSpecEventPayload.routedModel
readonly routedModel: string;
TeamMemberSpecEventPayload.routingReason
readonly routingReason: string;
TeamMessageOptions
One operator message sent to a team member.
export interface TeamMessageOptions
TeamMessageOptions.body
Message body delivered to the member.
body: string;
TeamMessageOptions.from
Sender label recorded with the message.
from?: string;
TeamMessageOptions.to
Recipient member handle.
to: string;
TeamOutcomeRunEvent
The one terminal outcome from a direct team run.
export interface TeamOutcomeRunEvent
TeamOutcomeRunEvent.kind
readonly kind: "outcome";
TeamOutcomeRunEvent.outcome
readonly outcome: TeamOutcome;
TeamRun
One single-consumption direct team run.
export interface TeamRun extends AsyncIterable<TeamRunEvent>
Callable members: result()
TeamRun.result
Drains the stream and returns its one required terminal outcome.
result(): Promise<TeamOutcome>;
Returns: Promise<TeamOutcome>
TeamRun.teamId
readonly teamId: string;
Teams
Direct team creation operations exposed by a Client.
export interface Teams
Callable members: create()
Teams.create
Creates a server-owned team bound to a session.
create(request: CreateTeamOptions, options?: RequestOptions): Promise<Team>;
Parameters:
request(CreateTeamOptions)options(RequestOptions, optional)
Returns: Promise<Team>
TeamTaskEventPayload
One task in a team event snapshot.
export interface TeamTaskEventPayload
TeamTaskEventPayload.assignee
readonly assignee: string;
TeamTaskEventPayload.deps
readonly deps: readonly string[];
TeamTaskEventPayload.description
readonly description: string;
TeamTaskEventPayload.id
readonly id: string;
TeamTaskEventPayload.state
readonly state: string;
TextPromptPart
A text segment in a structured prompt.
export interface TextPromptPart
TextPromptPart.kind
readonly kind: "text";
TextPromptPart.text
readonly text: string;
TitleAttemptEventPayload
One title-generation attempt projected by a session.title event.
export interface TitleAttemptEventPayload
TitleAttemptEventPayload.id
readonly id: string;
TitleAttemptEventPayload.outcome
readonly outcome: string;
ToolCallEventPayload
The payload of a tool.call event.
export interface ToolCallEventPayload
ToolCallEventPayload.args
readonly args: string;
ToolCallEventPayload.id
readonly id: string;
ToolCallEventPayload.name
readonly name: string;
ToolResultEventPayload
The text, structured data, and content blocks from a tool.result event.
export interface ToolResultEventPayload
ToolResultEventPayload.blocks
readonly blocks: readonly EventContentBlock[];
ToolResultEventPayload.callId
readonly callId: string;
ToolResultEventPayload.content
readonly content: string;
ToolResultEventPayload.isError
readonly isError: boolean;
ToolResultEventPayload.structuredContent
readonly structuredContent: string;
TurnEndEventPayload
The payload of a turn.end event.
export interface TurnEndEventPayload
TurnEndEventPayload.durationMs
readonly durationMs: bigint;
TurnEndEventPayload.usage
readonly usage?: EventUsage | undefined;
UnknownGrpcEvent
An unknown event received over a protobuf transport.
export interface UnknownGrpcEvent extends EventCommon
UnknownGrpcEvent.kind
readonly kind: "unknown";
UnknownGrpcEvent.rawData
The protobuf unknown fields, preserving their wire order and payload bytes.
readonly rawData: Uint8Array;
UnknownGrpcEvent.transport
readonly transport: "grpc";
UnknownGrpcEvent.wireKind
readonly wireKind: string;
UnknownHttpEvent
An unknown event received over the HTTP JSON/SSE transport.
export interface UnknownHttpEvent extends EventCommon
UnknownHttpEvent.kind
readonly kind: "unknown";
UnknownHttpEvent.rawData
The exact parsed JSON object received in the SSE frame.
readonly rawData: JsonValue;
UnknownHttpEvent.transport
readonly transport: "http";
UnknownHttpEvent.wireKind
readonly wireKind: string;
UnknownWatchEnvelope
A future watch phase preserved for forward compatibility.
export interface UnknownWatchEnvelope
UnknownWatchEnvelope.cursor
readonly cursor: SdkCursor;
UnknownWatchEnvelope.event
readonly event?: Event;
UnknownWatchEnvelope.kind
readonly kind: "unknown";
UnknownWatchEnvelope.phase
readonly phase: string;
UserModel
Resolved user-model inspection operations.
export interface UserModel
Callable members: get()
UserModel.get
Gets the caller's bounded user-model index or one detail entry.
get(request: GetUserModelRequest, options?: RequestOptions): Promise<GetUserModelResponse>;
Parameters:
request(GetUserModelRequest)options(RequestOptions, optional)
Returns: Promise<GetUserModelResponse>
UserPromptEventPayload
The payload shared by user_prompt replay events.
export interface UserPromptEventPayload
UserPromptEventPayload.parts
readonly parts: readonly EventContent[];
UserPromptEventPayload.text
readonly text: string;
WatchBoundaryEnvelope
The single replay-to-live transition marker.
export interface WatchBoundaryEnvelope
WatchBoundaryEnvelope.cursor
readonly cursor: SdkCursor;
WatchBoundaryEnvelope.kind
readonly kind: "boundary";
WatchBoundaryEnvelope.phase
readonly phase: "live";
WatchEventEnvelope
A replayed or live durable event.
export interface WatchEventEnvelope
WatchEventEnvelope.cursor
readonly cursor: SdkCursor;
WatchEventEnvelope.event
readonly event: Event;
WatchEventEnvelope.kind
readonly kind: "event";
WatchEventEnvelope.phase
readonly phase: "live" | "replay";
WatchGapEnvelope
A known hole in durable delivery. It deliberately exposes no cursor.
export interface WatchGapEnvelope
WatchGapEnvelope.kind
readonly kind: "gap";
WatchGapEnvelope.phase
readonly phase: "gap";
Worktrees
Session-scoped worktree inventory operations.
export interface Worktrees
Callable members: list()
Worktrees.list
Lists worktrees eligible for a session fork or clear operation.
list(request: ListWorktreesRequest, options?: RequestOptions): Promise<ListWorktreesResponse>;
Parameters:
request(ListWorktreesRequest)options(RequestOptions, optional)
Returns: Promise<ListWorktreesResponse>
Type aliases
AgentEvent
The agent-lifecycle portion of the known event union.
export type AgentEvent = Exclude<KnownEvent, {
readonly kind: `team.${string}`;
}>;
ConnectionStatus
The complete connection-state vocabulary exposed by the SDK.
export type ConnectionStatus = "connecting" | "online" | "reconnecting" | "offline" | "unauthorized" | "incompatible";
ConnectionStatusListener
A callback notified whenever connection status changes.
export type ConnectionStatusListener = (status: ConnectionStatus) => void;
ConnectOptions
Options accepted by the isomorphic connect() entry point.
export type ConnectOptions = HttpTransportOptions | InjectedTransportOptions;
CredentialProvider
Resolves request headers immediately before each SDK request.
export type CredentialProvider = () => HeadersInit | Promise<HeadersInit>;
DiagnosticFieldValue
Values carried by the structured fields of an SDK-local diagnostic.
export type DiagnosticFieldValue = boolean | number | string | null;
DiagnosticLevel
Severity attached to one SDK-local diagnostic record.
export type DiagnosticLevel = "debug" | "error" | "info" | "warn";
DiagnosticsSink
Optional client-level receiver for SDK-local diagnostics.
export type DiagnosticsSink = (record: DiagnosticRecord) => void;
ErrorOrigin
The request transport, or local when validation failed before transport selection.
export type ErrorOrigin = TransportKind | "local";
Event
A decoded agent or team event.
export type Event = KnownEvent | UnknownEvent;
EventOf
Selects one known event variant by its literal kind.
export type EventOf<Kind extends KnownEventKind> = Extract<KnownEvent, {
readonly kind: Kind;
}>;
KnownEvent
All currently known agent and team event variants.
export type KnownEvent = {
[Kind in KnownEventKind]: EventCommon & {
readonly kind: Kind;
readonly payload: EventPayloads[Kind];
};
}[KnownEventKind];
KnownEventKind
A wire event kind currently understood by this SDK.
export type KnownEventKind = (typeof MECATL_EVENT_KINDS)[number];
MecatlErrorCode
Every machine-readable error code exposed by the SDK.
export type MecatlErrorCode = ServerErrorCode | SDKErrorCode;
PermissionAskResponder
An optional automatic responder invoked for each permission ask on a run.
export type PermissionAskResponder = (ask: PermissionAskEventPayload, signal: AbortSignal) => PermissionVerdict | undefined | Promise<PermissionVerdict | undefined>;
PermissionVerdict
A server permission verdict accepted by run.resolveAsk().
export type PermissionVerdict = "allow_once" | "allow_always" | "deny";
PlanApprovalResponder
An automatic responder invoked only for a PresentPlan approval ask.
export type PlanApprovalResponder = (ask: PermissionAskEventPayload, signal: AbortSignal) => PlanApprovalVerdict | undefined | Promise<PlanApprovalVerdict | undefined>;
PlanApprovalVerdict
The plan-specific decisions accepted by session.resolvePlan() and onPlanApproval.
export type PlanApprovalVerdict = "approve" | "accept_edits" | "iterate";
PromptInput
A backwards-compatible string prompt or structured text/media parts.
export type PromptInput = string | readonly PromptPart[];
PromptPart
One segment accepted by Session.run().
export type PromptPart = TextPromptPart | ImagePromptPart | AudioPromptPart;
PromptValidationReason
Stable reasons reported by PromptValidationError.
export type PromptValidationReason = "capability" | "mime_type" | "prompt" | "size" | "source_xor" | "url";
RequestOptions
Request controls shared by all thin typed namespaces.
export type RequestOptions = CallOptions;
RetryDisposition
Retry classification fields carried by model-retry and result payloads.
export type RetryDisposition = 0 | 1 | 2 | 3;
SdkCursor
A serializable cursor issued by a durable SDK attachment.
export type SdkCursor = string;
SDKErrorCode
Error codes produced locally by the SDK.
export type SDKErrorCode = "authentication" | "cursor_scope" | "incompatible_server" | "invalid_prompt" | "invalid_state" | "no_runs" | "plan_continuation_start" | "protocol" | "readiness_timeout" | "spawn_failed" | "tool_registration" | "transport" | "unsupported_platform" | "unsupported_feature";
ServerErrorCode
Error codes returned by the Mecatl server, plus unknown for future codes.
export type ServerErrorCode = (typeof MECATL_ERROR_CODES)[number] | "unknown";
StreamProgress
Stream-progress classification carried by model-retry and result payloads.
export type StreamProgress = 0 | 1 | 2 | 3 | 4;
TeamEvent
Team lifecycle events projected onto an agent run.
export type TeamEvent = Extract<KnownEvent, {
readonly kind: `team.${string}`;
}>;
TeamMemberRunEvent
A run event tagged with the team member that produced it.
export type TeamMemberRunEvent = Event & {
readonly member: string;
};
TeamRunEvent
A decoded direct-team stream frame.
export type TeamRunEvent = TeamMemberRunEvent | TeamOutcomeRunEvent;
TransportKind
Transport implementations supported by the SDK.
export type TransportKind = "grpc" | "http";
UnknownEvent
A future wire event that this SDK does not yet type.
export type UnknownEvent = UnknownHttpEvent | UnknownGrpcEvent;
WatchEnvelope
One decoded durable-watch delivery envelope.
export type WatchEnvelope = WatchEventEnvelope | WatchBoundaryEnvelope | WatchGapEnvelope | UnknownWatchEnvelope;
Variables
MAX_MEDIA_PART_BYTES
Maximum inline bytes in one image or audio part.
MAX_MEDIA_PART_BYTES: number
MAX_PROMPT_MEDIA_BYTES
Maximum inline media bytes in one prompt.
MAX_PROMPT_MEDIA_BYTES: number
MAX_PROMPT_MEDIA_PARTS
Maximum image and audio parts in one prompt.
MAX_PROMPT_MEDIA_PARTS = 16
MECATL_ATTACH_FILTERED_KINDS
Event kinds omitted by high-level attachment views unless requested.
MECATL_ATTACH_FILTERED_KINDS: readonly ["approval", "compaction.archive", "network.attempt", "request.manifest", "user_prompt"]
MECATL_ERROR_CODES
Stable server error codes, kept in parity with the Go registry.
MECATL_ERROR_CODES: readonly ["activity_gap", "attempt_live_claim_conflict", "attempt_terminal_conflict", "attempt_version_conflict", "child_not_found", "cleanup_backend", "cleanup_plan_stale", "cleanup_unsupported", "client_mcp_unreachable", "client_mcp_unsupported", "conflict", "cursor_expired", "cursor_malformed", "draining", "dream_apply_failed", "dream_capacity", "dream_conflict", "dream_deadline", "dream_generate_failed", "dream_in_progress", "dream_not_found", "dream_request_failed", "dream_terminal_conflict", "dream_unavailable", "failed_precondition", "failed_step_retry_ineligible", "fire_now_overlap", "internal", "invalid_argument", "learning_unavailable", "management_unauthorized", "mcp_connector_unavailable", "migration_backend", "migration_conflict", "migration_unsupported", "mcp_authorization_pending", "no_active_run", "no_event_log", "no_mcp_provider", "no_schedule_store", "not_awaiting_plan", "not_found", "placement_binding_invalid", "placement_changed", "placement_selector_invalid", "placement_selector_not_found", "placement_selector_stale", "placement_unavailable", "proposal_conflict", "reflection_cancelled", "reflection_deadline", "reflection_failed", "reflection_queue_full", "request_too_large", "resource_exhausted", "schedule_disabled", "schedule_exhausted", "schedule_not_found", "schedule_not_leader", "schedule_unsupported", "scheduler_not_running", "session_delete_unsupported", "session_leased_elsewhere", "session_metadata_cursor_restart", "session_metadata_paging_unsupported", "session_not_found", "stale_run_control", "storage_health_backend", "team_not_found", "team_not_running", "team_running", "teams_disabled", "too_many_session_engines", "too_many_teams", "unauthenticated", "unimplemented", "watch_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"]
SESSION_ID_HEADER_NAME
Canonical routing hint for session-bound Mecatl requests. It grants no authority.
SESSION_ID_HEADER_NAME = "X-Mecatl-Session-ID"
SUPPORTED_API_MAJOR
The API major implemented by this SDK.
SUPPORTED_API_MAJOR = 1