Skip to content
Makaio Framework

Variable: SessionSchemas

Makaio Framework

Makaio Framework / contracts/session / SessionSchemas

Variable: SessionSchemas

Section titled “Variable: SessionSchemas”

const SessionSchemas: object

Defined in: ../../../packages/contracts/src/session/schemas.ts:158

Session domain schemas.

Subjects for session lifecycle management via bus communication. Each key becomes a subject identifier as: session.{key}

Type Declaration

Section titled “Type Declaration”

abandon

Section titled “abandon”

abandon: object

Abandon a child session without merging. Subject: session.abandon Type: Request (RPC)

abandon.request

Section titled “abandon.request”

request: ZodObject<{ childSessionId: ZodString; extensionId: ZodOptional<ZodString>; parentSessionId: ZodString; source: ZodOptional<ZodEnum<{ extension: "extension"; system: "system"; user: "user"; }>>; }, $strip> = AbandonRequestSchema

abandon.response

Section titled “abandon.response”

response: ZodObject<{ success: ZodBoolean; }, $strip> = AbandonResponseSchema

abandoned

Section titled “abandoned”

abandoned: ZodObject<{ parentSessionId: ZodOptional<ZodString>; sessionId: ZodString; }, $strip> = AbandonedEventSchema

Emitted when session is abandoned. Subject: session.abandoned

agent.added

Section titled “agent.added”

agent.added: ZodObject<{ adapterId: ZodString; adapterName: ZodString; adapterSessionId: ZodString; agentId: ZodString; cwd: ZodOptional<ZodString>; model: ZodOptional<ZodString>; role: ZodOptional<ZodEnum<{ lead: "lead"; member: "member"; }>>; sessionId: ZodString; }, $strip>

Agent added to session event.

Subject: session.agent.added Type: Event (fire-and-forget) Emitted when: An agent is attached to a session

Example
Section titled “Example”
bus.on(SessionSubjects.agent.added, (ctx) => {
  console.debug(`Agent ${ctx.payload.agentId} joined session ${ctx.payload.sessionId}`);
});

agent.attach

Section titled “agent.attach”

agent.attach: object

Explicitly attach an agent to a session.

Subject: session.agent.attach Type: Request (RPC)

Unlike auto-attach via sendMessage, this RPC provides explicit control over:

  • Agent role (lead vs member)
  • Attaching without sending a message

For branching conversations (fork), use session.fork to create a new session with copied history, then attach agents to the new session.

Use this for multi-agent scenarios or when you need to pre-attach agents before sending messages.

Example
Section titled “Example”
// Attach a second agent as a member
const { agentId } = await bus.request(SessionSubjects.agent.attach, {
  sessionId: 'session-123',
  agent: { kind: 'adapter', adapterName: 'openai-node', model: 'gpt-4o' },
  role: 'member',
});


// Attach with initial message using a persona
const { agentId, messageId } = await bus.request(SessionSubjects.agent.attach, {
  sessionId: 'session-123',
  agent: { kind: 'persona', personaId: 'p-456' },
  role: 'lead',
  initialMessage: 'Take over as lead',
});

agent.attach.request

Section titled “agent.attach.request”

request: ZodObject<{ agent: ZodObject<{ allowedDirectories: ZodOptional<ZodArray<ZodString>>; allowedTools: ZodOptional<ZodArray<ZodString>>; cwd: ZodOptional<ZodString>; disallowedTools: ZodOptional<ZodArray<ZodString>>; kind: ZodString; model: ZodOptional<ZodString>; providerConfigId: ZodOptional<ZodString>; reasoningEffort: ZodOptional<ZodEnum<{ extra-high: "extra-high"; high: "high"; low: "low"; medium: "medium"; none: "none"; }>>; systemPrompt: ZodOptional<ZodUnion<readonly [ZodString, ZodObject<{ content: …; mode: …; }, $strip>]>>; }, $loose>; initialMessage: ZodOptional<ZodUnion<readonly [ZodString, ZodObject<{ blocks: ZodUnion<readonly […, …]>; role: ZodOptional<ZodEnum<…>>; }, $strip>]>>; role: ZodOptional<ZodEnum<{ lead: "lead"; member: "member"; }>>; sessionId: ZodString; }, $strip>

agent.attach.response

Section titled “agent.attach.response”

response: ZodObject<{ adapterSessionId: ZodString; agentId: ZodString; messageId: ZodOptional<ZodString>; role: ZodEnum<{ lead: "lead"; member: "member"; }>; turnId: ZodOptional<ZodString>; }, $strip>

agent.removed

Section titled “agent.removed”

agent.removed: ZodObject<{ agentId: ZodString; sessionId: ZodString; }, $strip>

Agent removed from session event.

Subject: session.agent.removed Type: Event (fire-and-forget) Emitted when: An agent is detached/removed from a session

Example
Section titled “Example”
bus.on(SessionSubjects.agent.removed, (ctx) => {
  console.debug(`Agent ${ctx.payload.agentId} left session ${ctx.payload.sessionId}`);
});

archive

Section titled “archive”

archive: object

Archive a closed session.

Subject: session.archive Type: Request (RPC)

archive.request

Section titled “archive.request”

request: ZodObject<{ sessionId: ZodString; }, $strip>

archive.response

Section titled “archive.response”

response: ZodObject<{ success: ZodBoolean; }, $strip>

archived

Section titled “archived”

archived: ZodObject<{ sessionId: ZodString; }, $strip>

Session archived event.

Subject: session.archived Type: Event (fire-and-forget) Emitted when: A closed session is archived

branch.created

Section titled “branch.created”

branch.created: ZodObject<{ childSessionId: ZodString; forkPointMessageId: ZodOptional<ZodString>; kind: ZodEnum<{ aside: "aside"; branch: "branch"; compress: "compress"; coordinator: "coordinator"; fork: "fork"; rewrite: "rewrite"; subagent: "subagent"; }>; parentSessionId: ZodString; sessionId: ZodString; transforms: ZodOptional<ZodObject<{ appliedPipeline: ZodOptional<ZodArray<ZodObject<{ actionId: ZodString; options: ZodOptional<…>; }, $strip>>>; removedMessageIds: ZodOptional<ZodArray<ZodString>>; segments: ZodOptional<ZodArray<ZodObject<{ fromMessageId: ZodString; overrides: ZodOptional<…>; policy: ZodEnum<…>; stripReasoning: ZodOptional<…>; stripToolOutputs: ZodOptional<…>; summaryText: ZodOptional<…>; toMessageId: ZodString; }, $strip>>>; }, $strip>>; }, $strip> = BranchCreatedEventSchema

Branch created event (for storage/persistence via SessionLogger). Subject: session.branch.created Type: Event (fire-and-forget)

Emitted by fork handler. SessionLogger subscribes and persists with transform applied (e.g., PII redaction).

branch.merged

Section titled “branch.merged”

branch.merged: ZodObject<{ childSessionId: ZodString; parentSessionId: ZodString; resultJson: ZodOptional<ZodString>; resultMessageId: ZodOptional<ZodString>; sessionId: ZodString; }, $strip> = BranchMergedEventSchema

Branch merged event (for storage/persistence via SessionLogger). Subject: session.branch.merged Type: Event (fire-and-forget)

Emitted by merge handler. SessionLogger subscribes and persists with transform applied.

childCompleted

Section titled “childCompleted”

childCompleted: ZodObject<{ childSessionId: ZodString; parentSessionId: ZodString; result: ZodUnknown; }, $strip> = ChildCompletedEventSchema

Emitted when a child session completes. Subject: session.childCompleted

clientAccount.changed

Section titled “clientAccount.changed”

clientAccount.changed: ZodObject<{ clientAccountId: ZodString; clientId: ZodString; lastClientIdentityObservation: ZodObject<{ clientId: ZodString; kind: ZodString; observedAt: ZodNumber; payload: ZodType<Record<string, unknown>, unknown, $ZodTypeInternals<Record<string, unknown>, unknown>>; source: ZodString; }, $strip>; observedAt: ZodNumber; previousClientAccountId: ZodNullable<ZodString>; sessionId: ZodString; source: ZodString; }, $strip> = SessionClientAccountChangedSchema

Session client-account linkage changed event.

Subject: session.clientAccount.changed Type: Event (fire-and-forget) Emitted when: A session resolves to a different canonical client account

close

Section titled “close”

close: object

Close an existing session.

Subject: session.close Type: Request (RPC)

Closing a session marks it as inactive but retains session data and events for potential resume. Use purge to permanently delete all data.

Example

Section titled “Example”
const { success } = await bus.request(SessionSubjects.close, { sessionId: 'abc123' });
if (success) {
  console.debug('Session closed successfully');
}

close.request

Section titled “close.request”

request: ZodObject<{ sessionId: ZodString; }, $strip>

close.response

Section titled “close.response”

response: ZodObject<{ success: ZodBoolean; }, $strip>

closed

Section titled “closed”

closed: ZodObject<{ reason: ZodOptional<ZodString>; sessionId: ZodString; }, $strip>

Session closed event.

Subject: session.closed Type: Event (fire-and-forget) Emitted when: A session is closed (via close request)

Example

Section titled “Example”
bus.on(SessionSubjects.closed, (ctx) => {
  console.debug(`Session ${ctx.payload.sessionId} closed`);
  if (ctx.payload.reason) {
    console.debug(`Reason: ${ctx.payload.reason}`);
  }
});

compress

Section titled “compress”

compress: object

Compress session context via pipeline. Subject: session.compress Type: Request (RPC)

compress.request

Section titled “compress.request”

request: ZodObject<{ pipeline: ZodArray<ZodObject<{ actionId: ZodString; options: ZodOptional<ZodRecord<ZodString, ZodUnknown>>; }, $strip>>; sessionId: ZodString; }, $strip> = CompressRequestSchema

compress.response

Section titled “compress.response”

response: ZodObject<{ contextJson: ZodRecord<ZodString, ZodUnknown>; eventId: ZodString; tokensAfter: ZodOptional<ZodNumber>; tokensBefore: ZodNumber; }, $strip> = CompressResponseSchema

compressed

Section titled “compressed”

compressed: ZodObject<{ eventId: ZodString; sessionId: ZodString; }, $strip>

Session compressed event.

Subject: session.compressed Type: Event (fire-and-forget) Emitted when: A session’s context is compressed (via compress request)

Used to notify components (like ContextWindowTracker) that context state should be cleared since compression resets the context window.

Example

Section titled “Example”
bus.on(SessionSubjects.compressed, (ctx) => {
  console.debug(`Session ${ctx.payload.sessionId} compressed`);
  // Clear cached context state
});

compressionRequested

Section titled “compressionRequested”

compressionRequested: ZodObject<{ extensionId: ZodOptional<ZodString>; reason: ZodString; sessionId: ZodString; source: ZodOptional<ZodEnum<{ extension: "extension"; system: "system"; user: "user"; }>>; }, $strip> = CompressionRequestedEventSchema

Compression requested for a session. Subject: session.compressionRequested

connectorSwap.editRequested

Section titled “connectorSwap.editRequested”

connectorSwap.editRequested: ZodObject<{ agentId: ZodString; newCwd: ZodOptional<ZodString>; newModel: ZodOptional<ZodString>; previousCwd: ZodOptional<ZodString>; previousModel: ZodOptional<ZodString>; sessionId: ZodString; }, $strip>

Request UI to open history editing flow after a connector swap decision.

Subject: session.connectorSwap.editRequested Type: Event (fire-and-forget)

create

Section titled “create”

create: object

Create a new makaio session.

Subject: session.create Type: Request (RPC)

Example

Section titled “Example”
const { sessionId } = await bus.request(SessionSubjects.create, {});
console.debug(`Created session: ${sessionId}`);

create.request

Section titled “create.request”

request: ZodObject<{ branchKind: ZodOptional<ZodEnum<{ aside: "aside"; branch: "branch"; compress: "compress"; coordinator: "coordinator"; fork: "fork"; rewrite: "rewrite"; subagent: "subagent"; }>>; executionTargetId: ZodOptional<ZodString>; forkPointMessageId: ZodOptional<ZodString>; forkTransforms: ZodOptional<ZodObject<{ appliedPipeline: ZodOptional<ZodArray<ZodObject<{ actionId: …; options: …; }, $strip>>>; removedMessageIds: ZodOptional<ZodArray<ZodString>>; segments: ZodOptional<ZodArray<ZodObject<{ fromMessageId: …; overrides: …; policy: …; stripReasoning: …; stripToolOutputs: …; summaryText: …; toMessageId: …; }, $strip>>>; }, $strip>>; originWindowId: ZodOptional<ZodString>; parentSessionId: ZodOptional<ZodString>; sessionId: ZodOptional<ZodString>; spawningToolCallId: ZodOptional<ZodString>; targetWorkingDirectory: ZodOptional<ZodString>; title: ZodOptional<ZodString>; }, $strip>

create.response

Section titled “create.response”

response: ZodObject<{ sessionId: ZodString; }, $strip>

created

Section titled “created”

created: ZodObject<{ branchKind: ZodNullable<ZodEnum<{ aside: "aside"; branch: "branch"; compress: "compress"; coordinator: "coordinator"; fork: "fork"; rewrite: "rewrite"; subagent: "subagent"; }>>; createdAt: ZodNumber; originWindowId: ZodOptional<ZodString>; parentSessionId: ZodNullable<ZodString>; sessionId: ZodString; }, $strip> = SessionCreatedEventSchema

Session created event (for storage/persistence via SessionLogger). Subject: session.created Type: Event (fire-and-forget)

Emitted when a new session is created. SessionLogger subscribes and persists with transform applied.

enrichContext

Section titled “enrichContext”

enrichContext: object

Enrich session hook context with optional host-owned fields.

Subject: session.enrichContext Type: Request (RPC, optional)

Framework code calls bus.requestOptional(SessionSubjects.enrichContext, { sessionId }) inside fetchSessionEnrichment. Host registers a handler that returns arbitrary key/value context extensions (e.g., project, worktree). When no handler is registered, requestOptional returns { handled: false } and the hook context carries only framework-owned fields.

Host adds TypeScript visibility via declaration merging on SessionHookContext in @makaio/hooks.

Example

Section titled “Example”
// Host handler (registers the enrichment provider)
bus.on(SessionSubjects.enrichContext, async (ctx) => {
  const scope = await readSessionScope(db, ctx.payload.sessionId);
  const project = scope?.projectId
    ? await bus.request(ProjectSubjects.get, { projectId: scope.projectId }).catch(() => null)
    : null;
  ctx.setResult({
    project: project?.project ?? undefined,
    worktree: undefined,
  });
});

enrichContext.request

Section titled “enrichContext.request”

request: ZodObject<{ sessionId: ZodString; }, $strip>

enrichContext.response

Section titled “enrichContext.response”

response: ZodRecord<ZodString, ZodUnknown>

event

Section titled “event”

event: ZodUnion<readonly [ZodDiscriminatedUnion<[ZodObject<{ eventId: ZodString; payload: ZodObject<{ adapterId: ZodString; adapterName: ZodString; adapterSessionId: ZodString; agentId: ZodString; cwd: ZodOptional<ZodString>; model: ZodOptional<ZodString>; role: ZodOptional<ZodEnum<…>>; sessionId: ZodString; }, $strip>; sessionId: ZodString; timestamp: ZodNumber; type: ZodLiteral<"agent.added">; }, $strip>, ZodObject<{ eventId: ZodString; payload: ZodObject<{ agentIds: ZodArray<ZodString>; content: ZodUnion<readonly […, …]>; messageId: ZodString; origin: ZodOptional<ZodEnum<…>>; sessionId: ZodString; source: ZodOptional<ZodEnum<…>>; turnId: ZodString; turnNumber: ZodNumber; }, $strip>; sessionId: ZodString; timestamp: ZodNumber; type: ZodLiteral<"user_message.sent">; }, $strip>, ZodObject<{ eventId: ZodString; payload: ZodObject<{ agentId: ZodString; messageId: ZodString; sessionId: ZodString; turnId: ZodString; turnNumber: ZodNumber; }, $strip>; sessionId: ZodString; timestamp: ZodNumber; type: ZodLiteral<"user_message.acknowledged">; }, $strip>], "type">, ZodObject<{ eventId: ZodString; payload: ZodRecord<ZodString, ZodUnknown>; sessionId: ZodString; timestamp: ZodNumber; type: ZodString; }, $strip>]> = MakaioSessionEventSchema

Catch-all session event for observability and persistence.

Subject: session.event Type: Event (fire-and-forget) Use for: Single subscription to all session events, event storage

fork

Section titled “fork”

fork: object

Fork a session to create a branch point in conversation history.

Subject: session.fork Type: Request (RPC)

Creates a new session that references the parent via parentSessionId and forkPointMessageId. NO message copying occurs - full conversation is assembled via getFullConversation() which traverses the parent chain.

The forked session starts with no agents - use agent.attach to add agents.

Example

Section titled “Example”
// Fork entire session history
const { sessionId } = await bus.request(SessionSubjects.fork, {
  sourceSessionId: 'session-123',
});


// Fork from a specific message (branch point)
const { sessionId } = await bus.request(SessionSubjects.fork, {
  sourceSessionId: 'session-123',
  fromMessageId: 'msg-abc',
  name: 'Alternative approach',
});

fork.request

Section titled “fork.request”

request: ZodObject<{ branchKind: ZodOptional<ZodEnum<{ aside: "aside"; branch: "branch"; fork: "fork"; }>>; existingSessionId: ZodOptional<ZodString>; fromMessageId: ZodOptional<ZodString>; name: ZodOptional<ZodString>; sourceSessionId: ZodString; targetWorkingDirectory: ZodOptional<ZodString>; transforms: ZodOptional<ZodObject<{ appliedPipeline: ZodOptional<ZodArray<ZodObject<{ actionId: …; options: …; }, $strip>>>; removedMessageIds: ZodOptional<ZodArray<ZodString>>; segments: ZodOptional<ZodArray<ZodObject<{ fromMessageId: …; overrides: …; policy: …; stripReasoning: …; stripToolOutputs: …; summaryText: …; toMessageId: …; }, $strip>>>; }, $strip>>; }, $strip>

fork.response

Section titled “fork.response”

response: ZodObject<{ sessionId: ZodString; }, $strip>

forked

Section titled “forked”

forked: ZodObject<{ childSessionId: ZodString; forkPoint: ZodOptional<ZodString>; parentSessionId: ZodString; }, $strip> = ForkedEventSchema

Emitted after fork completes. Subject: session.forked

forking

Section titled “forking”

forking: ZodObject<{ childSessionId: ZodString; parentSessionId: ZodString; reason: ZodString; }, $strip> = ForkingEventSchema

Emitted when fork is about to happen. Subject: session.forking

get

Section titled “get”

get: object

Get a specific session by ID.

Subject: session.get Type: Request (RPC)

Example

Section titled “Example”
const { session } = await bus.request(SessionSubjects.get, { sessionId: 'abc123' });
if (session) {
  console.debug(`Session status: ${session.status}`);
}

get.request

Section titled “get.request”

request: ZodObject<{ sessionId: ZodString; }, $strip>

get.response

Section titled “get.response”

response: ZodObject<{ session: ZodNullable<ZodObject<{ adapterId: ZodOptional<ZodString>; adapterName: ZodOptional<ZodString>; adapterSessionId: ZodOptional<ZodString>; agents: ZodArray<ZodObject<{ adapterId: ZodString; adapterName: ZodString; adapterSessionId: ZodOptional<…>; agentId: ZodString; clientId: ZodOptional<…>; compressionMode: ZodOptional<…>; createdAt: ZodNumber; cwd: ZodOptional<…>; harnessId: ZodOptional<…>; lastActivityAt: ZodNumber; model: ZodOptional<…>; personaId: ZodOptional<…>; profileId: ZodOptional<…>; providerConfigId: ZodOptional<…>; role: ZodEnum<…>; sessionId: ZodString; status: ZodEnum<…>; }, $strip>>; approvalPolicyOverride: ZodOptional<ZodNullable<ZodEnum<{ always-ask: …; full-access: …; reject: …; }>>>; branchKind: ZodOptional<ZodEnum<{ aside: "aside"; branch: "branch"; compress: "compress"; coordinator: "coordinator"; fork: "fork"; rewrite: "rewrite"; subagent: "subagent"; }>>; clientAccountId: ZodOptional<ZodString>; clientId: ZodOptional<ZodString>; createdAt: ZodNumber; executionTargetId: ZodOptional<ZodString>; forkPointMessageId: ZodOptional<ZodString>; forkTransforms: ZodOptional<ZodObject<{ appliedPipeline: ZodOptional<…>; removedMessageIds: ZodOptional<…>; segments: ZodOptional<…>; }, $strip>>; isImported: ZodOptional<ZodBoolean>; isOrchestrated: ZodOptional<ZodBoolean>; lastActivityAt: ZodNumber; lastClientIdentityObservation: ZodOptional<ZodObject<{ clientId: ZodString; kind: ZodString; observedAt: ZodNumber; payload: ZodType<…, …, …>; source: ZodString; }, $strip>>; leadAgentId: ZodOptional<ZodString>; parentSessionId: ZodOptional<ZodString>; rootSessionId: ZodOptional<ZodString>; sessionId: ZodString; spawningToolCallId: ZodOptional<ZodString>; status: ZodEnum<{ active: "active"; archived: "archived"; closed: "closed"; discovered: "discovered"; }>; summary: ZodOptional<ZodString>; summaryUpdatedAt: ZodOptional<ZodNumber>; targetWorkingDirectory: ZodOptional<ZodString>; title: ZodOptional<ZodString>; }, $strip>>; }, $strip>

getByAdapterSessionId

Section titled “getByAdapterSessionId”

getByAdapterSessionId: object

Get a session by its adapter session ID.

Subject: session.getByAdapterSessionId Type: Request (RPC)

Used by log import to check if a session already exists for a given external session identifier (e.g., Claude Code session ID).

Example

Section titled “Example”
const { session } = await bus.request(SessionSubjects.getByAdapterSessionId, {
  adapterSessionId: 'claude-code-session-abc',
});
if (session && !session.isImported) {
  // Session was created by Makaio runtime, skip import
}

getByAdapterSessionId.request

Section titled “getByAdapterSessionId.request”

request: ZodObject<{ adapterSessionId: ZodString; }, $strip>

getByAdapterSessionId.response

Section titled “getByAdapterSessionId.response”

response: ZodObject<{ session: ZodNullable<ZodObject<{ adapterId: ZodOptional<ZodString>; adapterName: ZodOptional<ZodString>; adapterSessionId: ZodOptional<ZodString>; agents: ZodArray<ZodObject<{ adapterId: ZodString; adapterName: ZodString; adapterSessionId: ZodOptional<…>; agentId: ZodString; clientId: ZodOptional<…>; compressionMode: ZodOptional<…>; createdAt: ZodNumber; cwd: ZodOptional<…>; harnessId: ZodOptional<…>; lastActivityAt: ZodNumber; model: ZodOptional<…>; personaId: ZodOptional<…>; profileId: ZodOptional<…>; providerConfigId: ZodOptional<…>; role: ZodEnum<…>; sessionId: ZodString; status: ZodEnum<…>; }, $strip>>; approvalPolicyOverride: ZodOptional<ZodNullable<ZodEnum<{ always-ask: …; full-access: …; reject: …; }>>>; branchKind: ZodOptional<ZodEnum<{ aside: "aside"; branch: "branch"; compress: "compress"; coordinator: "coordinator"; fork: "fork"; rewrite: "rewrite"; subagent: "subagent"; }>>; clientAccountId: ZodOptional<ZodString>; clientId: ZodOptional<ZodString>; createdAt: ZodNumber; executionTargetId: ZodOptional<ZodString>; forkPointMessageId: ZodOptional<ZodString>; forkTransforms: ZodOptional<ZodObject<{ appliedPipeline: ZodOptional<…>; removedMessageIds: ZodOptional<…>; segments: ZodOptional<…>; }, $strip>>; isImported: ZodOptional<ZodBoolean>; isOrchestrated: ZodOptional<ZodBoolean>; lastActivityAt: ZodNumber; lastClientIdentityObservation: ZodOptional<ZodObject<{ clientId: ZodString; kind: ZodString; observedAt: ZodNumber; payload: ZodType<…, …, …>; source: ZodString; }, $strip>>; leadAgentId: ZodOptional<ZodString>; parentSessionId: ZodOptional<ZodString>; rootSessionId: ZodOptional<ZodString>; sessionId: ZodString; spawningToolCallId: ZodOptional<ZodString>; status: ZodEnum<{ active: "active"; archived: "archived"; closed: "closed"; discovered: "discovered"; }>; summary: ZodOptional<ZodString>; summaryUpdatedAt: ZodOptional<ZodNumber>; targetWorkingDirectory: ZodOptional<ZodString>; title: ZodOptional<ZodString>; }, $strip>>; }, $strip>

getChildren

Section titled “getChildren”

getChildren: object

Get child sessions of a parent. Subject: session.getChildren Type: Request (RPC)

getChildren.request

Section titled “getChildren.request”

request: ZodObject<{ sessionId: ZodString; }, $strip> = GetChildrenRequestSchema

getChildren.response

Section titled “getChildren.response”

response: ZodObject<{ children: ZodArray<ZodObject<{ branchKind: ZodNullable<ZodEnum<{ aside: "aside"; branch: "branch"; compress: "compress"; coordinator: "coordinator"; fork: "fork"; rewrite: "rewrite"; subagent: "subagent"; }>>; forkPointMessageId: ZodNullable<ZodString>; hasChildren: ZodBoolean; messageCount: ZodNumber; sessionId: ZodString; spawningToolCallId: ZodOptional<ZodString>; title: ZodNullable<ZodString>; }, $strip>>; }, $strip> = GetChildrenResponseSchema

getContextWindowState

Section titled “getContextWindowState”

getContextWindowState: object

Get context window state for a session.

Subject: session.getContextWindowState Type: Request (RPC)

Returns the current context window usage for a session, aggregated across all agents (using “worst agent” strategy).

Example

Section titled “Example”
const { state } = await bus.request(SessionSubjects.getContextWindowState, {
  sessionId: 'session-123',
});
if (state.level === 'critical') {
  // Suggest compression
}

getContextWindowState.request

Section titled “getContextWindowState.request”

request: ZodObject<{ sessionId: ZodString; }, $strip>

getContextWindowState.response

Section titled “getContextWindowState.response”

response: ZodObject<{ state: ZodNullable<ZodObject<{ currentTokens: ZodNumber; lastUpdatedAt: ZodNumber; level: ZodEnum<{ critical: "critical"; ok: "ok"; warn: "warn"; }>; maxTokens: ZodNumber; percentage: ZodNumber; }, $strip>>; }, $strip>

getStatusCounts

Section titled “getStatusCounts”

getStatusCounts: object

Get session counts by status for filter UI.

Subject: session.getStatusCounts Type: Request (RPC)

Returns counts for all statuses in a single efficient query. Useful for status filter UI badges that show totals regardless of current filter.

Example

Section titled “Example”
const { all, active, closed, archived, discovered } = await bus.request(
  SessionSubjects.getStatusCounts,
  {},
);
// Display: All (15) | Active (8) | Closed (5) | Archived (2) | Discovered (0)

getStatusCounts.request

Section titled “getStatusCounts.request”

request: ZodObject<{ }, $strip>

getStatusCounts.response

Section titled “getStatusCounts.response”

response: ZodObject<{ active: ZodNumber; all: ZodNumber; archived: ZodNumber; closed: ZodNumber; discovered: ZodNumber; }, $strip>

list

Section titled “list”

list: object

List makaio sessions.

Subject: session.list Type: Request (RPC)

When includePreview: true, each session includes a preview object with messageCount and firstUserMessage for UI display.

Example

Section titled “Example”
// Basic list
const { sessions } = await bus.request(SessionSubjects.list, { status: 'active' });


// With preview data for UI display
const { sessions, total } = await bus.request(SessionSubjects.list, {
  status: 'all',
  includePreview: true,
  limit: 20,
});

list.request

Section titled “list.request”

request: ZodObject<{ executionTargetId: ZodOptional<ZodString>; includePreview: ZodOptional<ZodBoolean>; limit: ZodOptional<ZodNumber>; offset: ZodOptional<ZodNumber>; status: ZodOptional<ZodEnum<{ active: "active"; all: "all"; archived: "archived"; closed: "closed"; discovered: "discovered"; }>>; }, $strip>

list.response

Section titled “list.response”

response: ZodObject<{ sessions: ZodArray<ZodObject<{ adapterId: ZodOptional<ZodString>; adapterName: ZodOptional<ZodString>; adapterSessionId: ZodOptional<ZodString>; agents: ZodArray<ZodObject<{ adapterId: ZodString; adapterName: ZodString; adapterSessionId: ZodOptional<…>; agentId: ZodString; clientId: ZodOptional<…>; compressionMode: ZodOptional<…>; createdAt: ZodNumber; cwd: ZodOptional<…>; harnessId: ZodOptional<…>; lastActivityAt: ZodNumber; model: ZodOptional<…>; personaId: ZodOptional<…>; profileId: ZodOptional<…>; providerConfigId: ZodOptional<…>; role: ZodEnum<…>; sessionId: ZodString; status: ZodEnum<…>; }, $strip>>; approvalPolicyOverride: ZodOptional<ZodNullable<ZodEnum<{ always-ask: …; full-access: …; reject: …; }>>>; branchKind: ZodOptional<ZodEnum<{ aside: "aside"; branch: "branch"; compress: "compress"; coordinator: "coordinator"; fork: "fork"; rewrite: "rewrite"; subagent: "subagent"; }>>; clientAccountId: ZodOptional<ZodString>; clientId: ZodOptional<ZodString>; createdAt: ZodNumber; executionTargetId: ZodOptional<ZodString>; forkPointMessageId: ZodOptional<ZodString>; forkTransforms: ZodOptional<ZodObject<{ appliedPipeline: ZodOptional<…>; removedMessageIds: ZodOptional<…>; segments: ZodOptional<…>; }, $strip>>; isImported: ZodOptional<ZodBoolean>; isOrchestrated: ZodOptional<ZodBoolean>; lastActivityAt: ZodNumber; lastClientIdentityObservation: ZodOptional<ZodObject<{ clientId: ZodString; kind: ZodString; observedAt: ZodNumber; payload: ZodType<…, …, …>; source: ZodString; }, $strip>>; leadAgentId: ZodOptional<ZodString>; parentSessionId: ZodOptional<ZodString>; preview: ZodOptional<ZodObject<{ firstUserMessage: ZodNullable<…>; messageCount: ZodNumber; }, $strip>>; rootSessionId: ZodOptional<ZodString>; sessionId: ZodString; spawningToolCallId: ZodOptional<ZodString>; status: ZodEnum<{ active: "active"; archived: "archived"; closed: "closed"; discovered: "discovered"; }>; summary: ZodOptional<ZodString>; summaryUpdatedAt: ZodOptional<ZodNumber>; targetWorkingDirectory: ZodOptional<ZodString>; title: ZodOptional<ZodString>; }, $strip>>; total: ZodNumber; }, $strip>

merge

Section titled “merge”

merge: object

Merge a child session into parent. Subject: session.merge Type: Request (RPC)

merge.request

Section titled “merge.request”

request: ZodObject<{ childSessionId: ZodString; extensionId: ZodOptional<ZodString>; parentSessionId: ZodString; source: ZodOptional<ZodEnum<{ extension: "extension"; system: "system"; user: "user"; }>>; summary: ZodOptional<ZodString>; }, $strip> = MergeRequestSchema

merge.response

Section titled “merge.response”

response: ZodObject<{ handoff: ZodOptional<ZodString>; success: ZodBoolean; }, $strip> = MergeResponseSchema

merged

Section titled “merged”

merged: ZodObject<{ childSessionId: ZodString; handoff: ZodString; parentSessionId: ZodString; }, $strip> = MergedEventSchema

Emitted after merge completes. Subject: session.merged

merging

Section titled “merging”

merging: ZodObject<{ childSessionId: ZodString; parentSessionId: ZodString; }, $strip> = MergingEventSchema

Emitted when merge is about to happen. Subject: session.merging

purge

Section titled “purge”

purge: object

Permanently delete a session and all its events.

Subject: session.purge Type: Request (RPC)

Unlike close, this permanently removes all session data including event history. Use when session data is no longer needed (e.g., user explicitly deletes conversation, data retention policy).

Requires session to be archived first. This ensures no agents are still emitting events that would race with deletion.

Example

Section titled “Example”
// First close then archive the session
await bus.request(SessionSubjects.close, { sessionId: 'abc123' });
await bus.request(SessionSubjects.archive, { sessionId: 'abc123' });


// Then purge permanently
const { success, eventsDeleted } = await bus.request(SessionSubjects.purge, {
  sessionId: 'abc123',
});
if (success) {
  console.debug(`Purged session with ${eventsDeleted} events`);
}

purge.request

Section titled “purge.request”

request: ZodObject<{ sessionId: ZodString; }, $strip>

purge.response

Section titled “purge.response”

response: ZodObject<{ error: ZodOptional<ZodString>; eventsDeleted: ZodOptional<ZodNumber>; success: ZodBoolean; }, $strip>

purged

Section titled “purged”

purged: ZodObject<{ sessionId: ZodString; }, $strip>

Session purged event.

Subject: session.purged Type: Event (fire-and-forget) Emitted when: A session is permanently deleted (via purge request)

Example

Section titled “Example”
bus.on(SessionSubjects.purged, (ctx) => {
  console.debug(`Session ${ctx.payload.sessionId} purged`);
});

resolveAgentConfig

Section titled “resolveAgentConfig”

resolveAgentConfig: object

Resolve the concrete adapter configuration for a given agent selection.

Subject: session.resolveAgentConfig Type: Request (RPC)

Example

Section titled “Example”
const config = await bus.request(SessionSubjects.resolveAgentConfig, {
  selection: {
    kind: 'adapter',
    adapterName: 'openai-node',
    providerConfigId: 'provider-uuid',
    model: 'gpt-4o',
  },
});
// config.adapterName === 'openai-node'
// config.model       === 'gpt-4o'

resolveAgentConfig.request

Section titled “resolveAgentConfig.request”

request: ZodObject<{ projectId: ZodOptional<ZodString>; selection: ZodObject<{ allowedDirectories: ZodOptional<ZodArray<ZodString>>; allowedTools: ZodOptional<ZodArray<ZodString>>; cwd: ZodOptional<ZodString>; disallowedTools: ZodOptional<ZodArray<ZodString>>; kind: ZodString; model: ZodOptional<ZodString>; providerConfigId: ZodOptional<ZodString>; reasoningEffort: ZodOptional<ZodEnum<{ extra-high: "extra-high"; high: "high"; low: "low"; medium: "medium"; none: "none"; }>>; systemPrompt: ZodOptional<ZodUnion<readonly [ZodString, ZodObject<{ content: …; mode: …; }, $strip>]>>; }, $loose>; }, $strip>

resolveAgentConfig.response

Section titled “resolveAgentConfig.response”

response: ZodObject<{ adapterName: ZodString; allowedDirectories: ZodOptional<ZodArray<ZodString>>; allowedTools: ZodOptional<ZodArray<ZodString>>; disallowedTools: ZodOptional<ZodArray<ZodString>>; model: ZodOptional<ZodString>; providerConfigId: ZodOptional<ZodString>; reasoningEffort: ZodOptional<ZodEnum<{ extra-high: "extra-high"; high: "high"; low: "low"; medium: "medium"; none: "none"; }>>; supportedReasoningLevels: ZodOptional<ZodObject<{ extra-high: ZodOptional<ZodUnion<readonly [ZodNumber, ZodString]>>; high: ZodOptional<ZodUnion<readonly [ZodNumber, ZodString]>>; low: ZodOptional<ZodUnion<readonly [ZodNumber, ZodString]>>; medium: ZodOptional<ZodUnion<readonly [ZodNumber, ZodString]>>; none: ZodOptional<ZodUnion<readonly [ZodNumber, ZodString]>>; }, $strip>>; systemPrompt: ZodOptional<ZodUnion<readonly [ZodString, ZodObject<{ content: ZodString; mode: ZodLiteral<"append">; }, $strip>]>>; }, $strip>

resolveSystemPrompt

Section titled “resolveSystemPrompt”

resolveSystemPrompt: object

Resolve the fully-assembled system prompt for a given session.

Subject: session.resolveSystemPrompt Type: Request (RPC)

Example

Section titled “Example”
const { systemPrompt } = await bus.request(
  SessionSubjects.resolveSystemPrompt,
  { sessionId: 'session-uuid' },
);

resolveSystemPrompt.request

Section titled “resolveSystemPrompt.request”

request: ZodObject<{ personaId: ZodOptional<ZodString>; profileId: ZodOptional<ZodString>; sessionId: ZodString; }, $strip>

resolveSystemPrompt.response

Section titled “resolveSystemPrompt.response”

response: ZodObject<{ personaName: ZodOptional<ZodString>; profileName: ZodOptional<ZodString>; systemPrompt: ZodString; }, $strip>

resume

Section titled “resume”

resume: object

Resume a closed session back to active.

Subject: session.resume Type: Request (RPC)

resume.request

Section titled “resume.request”

request: ZodObject<{ sessionId: ZodString; }, $strip>

resume.response

Section titled “resume.response”

response: ZodObject<{ success: ZodBoolean; }, $strip>

resumed

Section titled “resumed”

resumed: ZodObject<{ sessionId: ZodString; }, $strip>

Session resumed event.

Subject: session.resumed Type: Event (fire-and-forget) Emitted when: A closed session is resumed to active state

Section titled “search”

search: object

Search sessions by content using FTS5 full-text search.

Subject: session.search Type: Request (RPC)

Searches across session message content. Always includes preview data since search is content-focused.

Example

Section titled “Example”
const { sessions, total } = await bus.request(SessionSubjects.search, {
  query: 'authentication bug',
  limit: 20,
});

search.request

Section titled “search.request”

request: ZodObject<{ isImported: ZodOptional<ZodBoolean>; limit: ZodOptional<ZodNumber>; query: ZodString; status: ZodOptional<ZodEnum<{ active: "active"; all: "all"; archived: "archived"; closed: "closed"; discovered: "discovered"; }>>; }, $strip>

search.response

Section titled “search.response”

response: ZodObject<{ sessions: ZodArray<ZodObject<{ adapterId: ZodOptional<ZodString>; adapterName: ZodOptional<ZodString>; adapterSessionId: ZodOptional<ZodString>; agents: ZodArray<ZodObject<{ adapterId: ZodString; adapterName: ZodString; adapterSessionId: ZodOptional<…>; agentId: ZodString; clientId: ZodOptional<…>; compressionMode: ZodOptional<…>; createdAt: ZodNumber; cwd: ZodOptional<…>; harnessId: ZodOptional<…>; lastActivityAt: ZodNumber; model: ZodOptional<…>; personaId: ZodOptional<…>; profileId: ZodOptional<…>; providerConfigId: ZodOptional<…>; role: ZodEnum<…>; sessionId: ZodString; status: ZodEnum<…>; }, $strip>>; approvalPolicyOverride: ZodOptional<ZodNullable<ZodEnum<{ always-ask: …; full-access: …; reject: …; }>>>; branchKind: ZodOptional<ZodEnum<{ aside: "aside"; branch: "branch"; compress: "compress"; coordinator: "coordinator"; fork: "fork"; rewrite: "rewrite"; subagent: "subagent"; }>>; clientAccountId: ZodOptional<ZodString>; clientId: ZodOptional<ZodString>; createdAt: ZodNumber; executionTargetId: ZodOptional<ZodString>; forkPointMessageId: ZodOptional<ZodString>; forkTransforms: ZodOptional<ZodObject<{ appliedPipeline: ZodOptional<…>; removedMessageIds: ZodOptional<…>; segments: ZodOptional<…>; }, $strip>>; isImported: ZodOptional<ZodBoolean>; isOrchestrated: ZodOptional<ZodBoolean>; lastActivityAt: ZodNumber; lastClientIdentityObservation: ZodOptional<ZodObject<{ clientId: ZodString; kind: ZodString; observedAt: ZodNumber; payload: ZodType<…, …, …>; source: ZodString; }, $strip>>; leadAgentId: ZodOptional<ZodString>; parentSessionId: ZodOptional<ZodString>; preview: ZodOptional<ZodObject<{ firstUserMessage: ZodNullable<…>; messageCount: ZodNumber; }, $strip>>; rootSessionId: ZodOptional<ZodString>; sessionId: ZodString; spawningToolCallId: ZodOptional<ZodString>; status: ZodEnum<{ active: "active"; archived: "archived"; closed: "closed"; discovered: "discovered"; }>; summary: ZodOptional<ZodString>; summaryUpdatedAt: ZodOptional<ZodNumber>; targetWorkingDirectory: ZodOptional<ZodString>; title: ZodOptional<ZodString>; }, $strip>>; total: ZodNumber; }, $strip>

sendMessage

Section titled “sendMessage”

sendMessage: object

Send a message to a session’s agents.

Subject: session.sendMessage Type: Request (RPC)

Single entry point for all user messages. Handles:

  • Creating session if sessionId does not exist
  • Auto-attaching agent via adapter.startAgent if session has no agents
  • Turn lifecycle (creates turn if none active)
  • Routing to targeted agents

Default targets lead agent; use agentIds: 'all' for broadcast.

Example

Section titled “Example”
// Start new conversation (client generates sessionId)
const { sessionId, messageId, turnId } = await bus.request(SessionSubjects.sendMessage, {
  sessionId: crypto.randomUUID(),
  agent: { kind: 'adapter', adapterName: 'anthropic-sdk', model: 'sonnet' },
  message: 'Hello!',
});


// Continue conversation (agent already attached)
await bus.request(SessionSubjects.sendMessage, {
  sessionId,
  message: 'Follow-up question',
});


// Broadcast to all agents
await bus.request(SessionSubjects.sendMessage, {
  sessionId,
  message: 'What do you all think?',
  agentIds: 'all',
});

sendMessage.request

Section titled “sendMessage.request”

request: ZodObject<{ agent: ZodOptional<ZodUnion<readonly [ZodObject<{ adapterId: ZodOptional<ZodString>; adapterName: ZodOptional<ZodString>; allowedDirectories: ZodOptional<ZodArray<…>>; allowedTools: ZodOptional<ZodArray<…>>; cwd: ZodOptional<ZodString>; disallowedTools: ZodOptional<ZodArray<…>>; kind: ZodLiteral<"adapter">; model: ZodOptional<ZodString>; providerConfigId: ZodOptional<ZodString>; reasoningEffort: ZodOptional<ZodEnum<…>>; systemPrompt: ZodOptional<ZodUnion<…>>; }, $loose>, ZodObject<{ allowedDirectories: ZodOptional<ZodArray<…>>; allowedTools: ZodOptional<ZodArray<…>>; cwd: ZodOptional<ZodString>; disallowedTools: ZodOptional<ZodArray<…>>; kind: ZodLiteral<"canonical-model">; model: ZodString; providerConfigId: ZodOptional<ZodString>; reasoningEffort: ZodOptional<ZodEnum<…>>; systemPrompt: ZodOptional<ZodUnion<…>>; }, $loose>, ZodObject<{ allowedDirectories: ZodOptional<ZodArray<…>>; allowedTools: ZodOptional<ZodArray<…>>; cwd: ZodOptional<ZodString>; disallowedTools: ZodOptional<ZodArray<…>>; kind: ZodString; model: ZodOptional<ZodString>; providerConfigId: ZodOptional<ZodString>; reasoningEffort: ZodOptional<ZodEnum<…>>; systemPrompt: ZodOptional<ZodUnion<…>>; }, $loose>]>>; agentIds: ZodOptional<ZodUnion<readonly [ZodArray<ZodString>, ZodLiteral<"all">]>>; deliveryMode: ZodOptional<ZodEnum<{ enqueue: "enqueue"; }>>; extensionId: ZodOptional<ZodString>; message: ZodUnion<readonly [ZodString, ZodObject<{ blocks: ZodUnion<readonly [ZodDiscriminatedUnion<…, …>, ZodArray<…>]>; role: ZodOptional<ZodEnum<{ assistant: …; system: …; user: …; }>>; }, $strip>]>; origin: ZodOptional<ZodEnum<{ compact: "compact"; text: "text"; voice: "voice"; }>>; originWindowId: ZodOptional<ZodString>; sessionContext: ZodOptional<ZodObject<{ extractedContext: ZodOptional<ZodUnknown>; hasCompression: ZodOptional<ZodBoolean>; hasConnectorSwap: ZodOptional<ZodBoolean>; hasNewTransforms: ZodOptional<ZodBoolean>; isFirstTurn: ZodOptional<ZodBoolean>; messageHistory: ZodOptional<ZodArray<ZodObject<{ blocks: …; role: …; }, $strip>>>; turnContext: ZodOptional<ZodRecord<ZodString, ZodType<JsonValue, unknown, $ZodTypeInternals<…, …>>>>; }, $strip>>; sessionId: ZodString; skipConnectorSwapWarning: ZodOptional<ZodBoolean>; source: ZodOptional<ZodEnum<{ extension: "extension"; system: "system"; user: "user"; }>>; turnId: ZodOptional<ZodString>; }, $strip>

sendMessage.response

Section titled “sendMessage.response”

response: ZodObject<{ messageId: ZodString; sessionId: ZodString; turnId: ZodString; }, $strip>

snapshot.export

Section titled “snapshot.export”

snapshot.export: object

Export a session to a snapshot file.

Subject: session.snapshot.export Type: Request (RPC)

Creates a snapshot file containing session data for backup or transfer. Supports filtering what data to include via export options.

Example
Section titled “Example”
// Export with default options (ancestors included, no events/outputs)
const { snapshot } = await bus.request(SessionSubjects.snapshot.export, {
  sessionId: 'abc123',
});


// Export with custom options
const { snapshot } = await bus.request(SessionSubjects.snapshot.export, {
  sessionId: 'abc123',
  options: {
    includeEvents: true,
    includeToolOutputs: true,
    includeAncestors: false,
    includeChildren: true,
  },
});

snapshot.export.request

Section titled “snapshot.export.request”

request: ZodObject<{ options: ZodOptional<ZodObject<{ includeAncestors: ZodDefault<ZodBoolean>; includeChildren: ZodDefault<ZodBoolean>; includeEvents: ZodDefault<ZodBoolean>; includeToolOutputs: ZodDefault<ZodBoolean>; }, $strip>>; sessionId: ZodString; }, $strip>

snapshot.export.response

Section titled “snapshot.export.response”

response: ZodObject<{ snapshot: ZodObject<{ agents: ZodArray<ZodObject<{ adapterId: ZodString; adapterName: ZodString; adapterSessionId: ZodOptional<ZodString>; agentId: ZodString; clientId: ZodOptional<ZodString>; compressionMode: ZodOptional<ZodEnum<…>>; createdAt: ZodNumber; cwd: ZodOptional<ZodString>; harnessId: ZodOptional<ZodString>; lastActivityAt: ZodNumber; model: ZodOptional<ZodString>; personaId: ZodOptional<ZodString>; profileId: ZodOptional<ZodString>; providerConfigId: ZodOptional<ZodString>; role: ZodEnum<{ lead: …; member: …; }>; sessionId: ZodString; status: ZodEnum<{ active: …; dead: …; disposed: …; idle: …; }>; }, $strip>>; events: ZodOptional<ZodArray<ZodUnion<readonly [ZodDiscriminatedUnion<…, …>, ZodObject<…, …>]>>>; exportedAt: ZodNumber; messages: ZodArray<ZodObject<{ adapterMessageId: ZodOptional<ZodString>; adapterSessionId: ZodOptional<ZodString>; agentId: ZodOptional<ZodString>; blocks: ZodArray<ZodDiscriminatedUnion<…, …>>; contentText: ZodString; editOf: ZodOptional<ZodString>; messageId: ZodString; origin: ZodOptional<ZodEnum<…>>; role: ZodEnum<{ assistant: …; user: …; }>; sessionId: ZodString; timestamp: ZodNumber; turnId: ZodNullable<ZodString>; }, $strip>>; options: ZodObject<{ includeAncestors: ZodDefault<ZodBoolean>; includeChildren: ZodDefault<ZodBoolean>; includeEvents: ZodDefault<ZodBoolean>; includeToolOutputs: ZodDefault<ZodBoolean>; }, $strip>; sessions: ZodArray<ZodObject<{ adapterId: ZodOptional<ZodString>; adapterName: ZodOptional<ZodString>; adapterSessionId: ZodOptional<ZodString>; agents: ZodArray<ZodObject<…, …>>; approvalPolicyOverride: ZodOptional<ZodNullable<…>>; branchKind: ZodOptional<ZodEnum<…>>; clientAccountId: ZodOptional<ZodString>; clientId: ZodOptional<ZodString>; createdAt: ZodNumber; executionTargetId: ZodOptional<ZodString>; forkPointMessageId: ZodOptional<ZodString>; forkTransforms: ZodOptional<ZodObject<…, …>>; isImported: ZodOptional<ZodBoolean>; isOrchestrated: ZodOptional<ZodBoolean>; lastActivityAt: ZodNumber; lastClientIdentityObservation: ZodOptional<ZodObject<…, …>>; leadAgentId: ZodOptional<ZodString>; parentSessionId: ZodOptional<ZodString>; rootSessionId: ZodOptional<ZodString>; sessionId: ZodString; spawningToolCallId: ZodOptional<ZodString>; status: ZodEnum<{ active: …; archived: …; closed: …; discovered: …; }>; summary: ZodOptional<ZodString>; summaryUpdatedAt: ZodOptional<ZodNumber>; targetWorkingDirectory: ZodOptional<ZodString>; title: ZodOptional<ZodString>; }, $strip>>; turns: ZodArray<ZodObject<{ completedAt: ZodOptional<ZodNumber>; error: ZodOptional<ZodString>; sessionId: ZodString; startedAt: ZodNumber; status: ZodEnum<{ active: …; completed: …; error: …; }>; turnId: ZodString; turnNumber: ZodNumber; usage: ZodOptional<ZodObject<…, …>>; }, $strip>>; version: ZodLiteral<"1.0">; }, $strip>; }, $strip>

snapshot.import

Section titled “snapshot.import”

snapshot.import: object

Import sessions from a snapshot file.

Subject: session.snapshot.import Type: Request (RPC)

Imports session data from a snapshot file, with conflict resolution options for handling existing sessions.

Example
Section titled “Example”
// Import with fail-on-conflict (default)
const { imported, skipped, errors } = await bus.request(
  SessionSubjects.snapshot.import,
  {
    snapshot: mySnapshot,
    onConflict: 'fail',
  },
);


// Import with skip-on-conflict (skip existing sessions)
const { imported, skipped, errors } = await bus.request(
  SessionSubjects.snapshot.import,
  {
    snapshot: mySnapshot,
    onConflict: 'skip',
  },
);


// Import with overwrite (replace existing sessions)
const { imported, skipped, errors } = await bus.request(
  SessionSubjects.snapshot.import,
  {
    snapshot: mySnapshot,
    onConflict: 'overwrite',
  },
);

snapshot.import.request

Section titled “snapshot.import.request”

request: ZodObject<{ onConflict: ZodDefault<ZodEnum<{ fail: "fail"; overwrite: "overwrite"; skip: "skip"; }>>; snapshot: ZodObject<{ agents: ZodArray<ZodObject<{ adapterId: ZodString; adapterName: ZodString; adapterSessionId: ZodOptional<ZodString>; agentId: ZodString; clientId: ZodOptional<ZodString>; compressionMode: ZodOptional<ZodEnum<…>>; createdAt: ZodNumber; cwd: ZodOptional<ZodString>; harnessId: ZodOptional<ZodString>; lastActivityAt: ZodNumber; model: ZodOptional<ZodString>; personaId: ZodOptional<ZodString>; profileId: ZodOptional<ZodString>; providerConfigId: ZodOptional<ZodString>; role: ZodEnum<{ lead: …; member: …; }>; sessionId: ZodString; status: ZodEnum<{ active: …; dead: …; disposed: …; idle: …; }>; }, $strip>>; events: ZodOptional<ZodArray<ZodUnion<readonly [ZodDiscriminatedUnion<…, …>, ZodObject<…, …>]>>>; exportedAt: ZodNumber; messages: ZodArray<ZodObject<{ adapterMessageId: ZodOptional<ZodString>; adapterSessionId: ZodOptional<ZodString>; agentId: ZodOptional<ZodString>; blocks: ZodArray<ZodDiscriminatedUnion<…, …>>; contentText: ZodString; editOf: ZodOptional<ZodString>; messageId: ZodString; origin: ZodOptional<ZodEnum<…>>; role: ZodEnum<{ assistant: …; user: …; }>; sessionId: ZodString; timestamp: ZodNumber; turnId: ZodNullable<ZodString>; }, $strip>>; options: ZodObject<{ includeAncestors: ZodDefault<ZodBoolean>; includeChildren: ZodDefault<ZodBoolean>; includeEvents: ZodDefault<ZodBoolean>; includeToolOutputs: ZodDefault<ZodBoolean>; }, $strip>; sessions: ZodArray<ZodObject<{ adapterId: ZodOptional<ZodString>; adapterName: ZodOptional<ZodString>; adapterSessionId: ZodOptional<ZodString>; agents: ZodArray<ZodObject<…, …>>; approvalPolicyOverride: ZodOptional<ZodNullable<…>>; branchKind: ZodOptional<ZodEnum<…>>; clientAccountId: ZodOptional<ZodString>; clientId: ZodOptional<ZodString>; createdAt: ZodNumber; executionTargetId: ZodOptional<ZodString>; forkPointMessageId: ZodOptional<ZodString>; forkTransforms: ZodOptional<ZodObject<…, …>>; isImported: ZodOptional<ZodBoolean>; isOrchestrated: ZodOptional<ZodBoolean>; lastActivityAt: ZodNumber; lastClientIdentityObservation: ZodOptional<ZodObject<…, …>>; leadAgentId: ZodOptional<ZodString>; parentSessionId: ZodOptional<ZodString>; rootSessionId: ZodOptional<ZodString>; sessionId: ZodString; spawningToolCallId: ZodOptional<ZodString>; status: ZodEnum<{ active: …; archived: …; closed: …; discovered: …; }>; summary: ZodOptional<ZodString>; summaryUpdatedAt: ZodOptional<ZodNumber>; targetWorkingDirectory: ZodOptional<ZodString>; title: ZodOptional<ZodString>; }, $strip>>; turns: ZodArray<ZodObject<{ completedAt: ZodOptional<ZodNumber>; error: ZodOptional<ZodString>; sessionId: ZodString; startedAt: ZodNumber; status: ZodEnum<{ active: …; completed: …; error: …; }>; turnId: ZodString; turnNumber: ZodNumber; usage: ZodOptional<ZodObject<…, …>>; }, $strip>>; version: ZodLiteral<"1.0">; }, $strip>; }, $strip>

snapshot.import.response

Section titled “snapshot.import.response”

response: ZodObject<{ errors: ZodArray<ZodObject<{ error: ZodString; sessionId: ZodString; }, $strip>>; imported: ZodArray<ZodString>; skipped: ZodArray<ZodString>; }, $strip>

snapshot.validate

Section titled “snapshot.validate”

snapshot.validate: object

Validate a snapshot object against the schema.

Subject: session.snapshot.validate Type: Request (RPC)

Validates a snapshot object without importing it. Useful for checking snapshot files before import.

Example
Section titled “Example”
// Validate a snapshot before importing
const { valid, errors } = await bus.request(
  SessionSubjects.snapshot.validate,
  { snapshot: mySnapshot },
);


if (!valid) {
  console.error('Invalid snapshot:', errors);
} else {
  console.log('Snapshot is valid');
}

snapshot.validate.request

Section titled “snapshot.validate.request”

request: ZodObject<{ snapshot: ZodUnknown; }, $strip>

snapshot.validate.response

Section titled “snapshot.validate.response”

response: ZodObject<{ errors: ZodArray<ZodString>; valid: ZodBoolean; }, $strip>

squash

Section titled “squash”

squash: ZodObject<{ compressedMessageIds: ZodOptional<ZodArray<ZodString>>; sessionId: ZodString; summaryJson: ZodString; tokensAfter: ZodOptional<ZodNumber>; tokensBefore: ZodOptional<ZodNumber>; }, $strip> = SquashEventSchema

Context squash event (for storage/persistence via SessionLogger). Subject: session.squash Type: Event (fire-and-forget)

Emitted when context is compressed. SessionLogger subscribes and persists with transform applied.

turn.completed

Section titled “turn.completed”

turn.completed: ZodObject<{ error: ZodOptional<ZodString>; initiator: ZodOptional<ZodObject<{ source: ZodEnum<{ extension: "extension"; system: "system"; user: "user"; }>; sourceId: ZodOptional<ZodString>; }, $strip>>; sessionId: ZodString; success: ZodBoolean; turnId: ZodString; turnNumber: ZodNumber; }, $strip>

Turn completed.

Subject: session.turn.completed Type: Event (fire-and-forget) Emitted when: All targeted agents have completed processing

Semantics:

  • success=true: all agents completed with outcome=‘completed’
  • success=false: any agent had outcome=‘error’
  • cancelled/superseded/merged outcomes are neutral (not errors)

turn.started

Section titled “turn.started”

turn.started: ZodObject<{ agentIds: ZodArray<ZodString>; initiator: ZodOptional<ZodObject<{ source: ZodEnum<{ extension: "extension"; system: "system"; user: "user"; }>; sourceId: ZodOptional<ZodString>; }, $strip>>; messageId: ZodString; sessionId: ZodString; turnId: ZodString; turnNumber: ZodNumber; }, $strip>

Turn started.

Subject: session.turn.started Type: Event (fire-and-forget) Emitted when: First user message of a turn is received

update

Section titled “update”

update: object

Update specific session fields (partial update).

Subject: session.update Type: Request (RPC)

Unlike re-setting the entire session, this performs a targeted update of specific fields.

Example

Section titled “Example”
// Update session approval policy
const { success } = await bus.request(SessionSubjects.update, {
  sessionId: 'abc123',
  approvalPolicyOverride: 'full-access',
});

update.request

Section titled “update.request”

request: ZodObject<{ approvalPolicyOverride: ZodOptional<ZodNullable<ZodEnum<{ always-ask: "always-ask"; full-access: "full-access"; reject: "reject"; }>>>; executionTargetId: ZodOptional<ZodNullable<ZodString>>; sessionId: ZodString; }, $strip>

update.response

Section titled “update.response”

response: ZodObject<{ success: ZodBoolean; }, $strip>

updated

Section titled “updated”

updated: ZodObject<{ changedProperties: ZodArray<ZodString>; sessionId: ZodString; }, $strip> = SessionUpdatedEventSchema

Session property updated event. Subject: session.updated Type: Event (fire-and-forget)

Emitted after a session update (e.g., title, status change). Entity cache subscribes to re-fetch updated session data.

usage

Section titled “usage”

usage: object

Aggregated session-level token usage.

Subject: session.usage Type: Event (fire-and-forget) Emitted when: UsageAggregator receives adapter.session.usage events

Aggregates token usage across all adapters in a session. UsageAggregator listens to adapter.session.usage events, aggregates them per-session (keyed by adapterSessionId to avoid collisions), and emits this canonical session-level usage event.

ContextTracker consumes this to track context window usage against thresholds.

Example

Section titled “Example”
bus.on(SessionSubjects.usage, (ctx) => {
  console.debug(
    `Session ${ctx.payload.sessionId}: ${ctx.payload.totalTokens} tokens ` +
    `(${ctx.payload.adapterCount} adapters)`
  );
});

usage.request

Section titled “usage.request”

request: ZodObject<{ adapterCount: ZodNumber; sessionId: ZodString; totalCalls: ZodNumber; totalInputTokens: ZodNumber; totalOutputTokens: ZodNumber; totalTokens: ZodNumber; }, $strip>

usage.response

Section titled “usage.response”

response: ZodObject<{ acknowledged: ZodLiteral<true>; }, $strip>

user_message.acknowledged

Section titled “user_message.acknowledged”

user_message.acknowledged: ZodObject<{ agentId: ZodString; messageId: ZodString; sessionId: ZodString; turnId: ZodString; turnNumber: ZodNumber; }, $strip>

User message acknowledged by agent.

Subject: session.user_message.acknowledged Type: Event (fire-and-forget) Emitted when: An agent receives and begins processing the message

user_message.completed

Section titled “user_message.completed”

user_message.completed: ZodObject<{ agentId: ZodString; error: ZodOptional<ZodString>; mergedInto: ZodOptional<ZodString>; messageId: ZodString; outcome: ZodEnum<{ cancelled: "cancelled"; completed: "completed"; error: "error"; merged: "merged"; rejected: "rejected"; superseded: "superseded"; }>; sessionId: ZodString; supersededBy: ZodOptional<ZodString>; turnId: ZodString; turnNumber: ZodNumber; }, $strip>

User message processing completed by agent.

Subject: session.user_message.completed Type: Event (fire-and-forget) Emitted when: An agent finishes processing the message

user_message.sent

Section titled “user_message.sent”

user_message.sent: ZodObject<{ agentIds: ZodArray<ZodString>; content: ZodUnion<readonly [ZodString, ZodObject<{ blocks: ZodUnion<readonly [ZodDiscriminatedUnion<[…, …, …, …], "type">, ZodArray<ZodDiscriminatedUnion<…, …>>]>; role: ZodOptional<ZodEnum<{ assistant: "assistant"; system: "system"; user: "user"; }>>; }, $strip>]>; messageId: ZodString; origin: ZodOptional<ZodEnum<{ compact: "compact"; text: "text"; voice: "voice"; }>>; sessionId: ZodString; source: ZodOptional<ZodEnum<{ extension: "extension"; system: "system"; user: "user"; }>>; turnId: ZodString; turnNumber: ZodNumber; }, $strip>

User message sent to session.

Subject: session.user_message.sent Type: Event (fire-and-forget) Emitted when: User sends a message (before routing to agents)

Example

Section titled “Example”
// Create a new session
const { sessionId } = await bus.request(SessionSubjects.create, {});


// List active sessions
const { sessions } = await bus.request(SessionSubjects.list, { status: 'active' });


// Get session details
const session = await bus.request(SessionSubjects.get, { sessionId });


// Close a session
await bus.request(SessionSubjects.close, { sessionId });