session

The session contracts of the Robota SDK: what an interactive session is and what it exposes, the events it emits, the handle a caller gets for one submitted turn, the record that persists a session and the store port that loads it, and the in-process interaction channel a surface can talk to a session through.

This subpath is mostly type declarations. Its few runtime exports are pure helpers over those types (listed below); it contains no classes and no I/O. It builds on the other contract subpaths: @robota-sdk/agent-interface/execution (background work), @robota-sdk/agent-interface/command (commands) and @robota-sdk/agent-interface/analytics (usage).

Usage

Code that drives a session depends on IInteractiveSession, not on the class that implements it:

import type { IInteractiveSession } from '@robota-sdk/agent-interface/session';
import { isTurnNotRunError } from '@robota-sdk/agent-interface/session';
 
async function ask(session: IInteractiveSession, prompt: string): Promise<string | undefined> {
  const turn = await session.submit(prompt);
  try {
    const result = await turn.completed;
    return result.response;
  } catch (error) {
    // The turn never ran: it was coalesced, dropped at queue capacity, or cancelled.
    if (isTurnNotRunError(error)) return undefined;
    throw error; // a real failure inside the turn
  }
}

A session runs one turn at a time and queues the rest. submit() returns an ITurnHandle whose completed promise always settles: with this turn's result, or with a "turn did not run" error that isTurnNotRunError recognizes.

What it defines

Area	Main types
The session	`IInteractiveSession`, and the capability slices it is made of (`ISessionTurnSubmission`, `ISessionConversationRead`, `ISessionCommands`, `ISessionBackgroundTasks`, …) collected in `ISessionCapabilityMap`
Turns	`ITurnHandle`, `IExecutionResult`, `ITurnNotRunError`, `TTurnNotRunReason`, `TTurnSource`, `ISubmitOptions`
Events	`IInteractiveSessionEvents`, `TInteractiveEventName`, `IPermissionRequestEvent`, `IAskRequestEvent`, `IPromptResolvedEvent`, `IBranchEvent`, `ISkillActivationEvent`, `IMemoryEvent`
Persistence	`IInteractiveSessionRecord`, `IInteractiveSessionStore`, `TSessionLoadOutcome` (valid, missing, corrupt, unsupported or locked)
Interaction channel	`IInteractionChannel`, `InteractionEvent`, `IAgentDriver`, `ICommandInfo`
Drivers and co-driving	`TDriverId`, `IPeerTurnContext`, `IUiIntentEvent`
Session listing, binding, loops, prompt history, compaction	`ISessionListing`, `ISessionBinder`, `ISessionLoopState`, `IPromptHistorySource`, `ICompactEvent`

Runtime exports:

Export	What it is
`readAssistantReplies`, `readLastAssistantText`, `readToolCalls`, `readErrors`	Pure readers over an `InteractionEvent[]` stream
`isTurnNotRunError`	Tells a "turn did not run" rejection from a real failure
`isSessionChangeRefusal`, `SESSION_CHANGE_REFUSAL_CODES`	Recognize a refused session switch and list its reason codes
`SESSION_CAPABILITY_MEMBER_KEYS`	The members each capability slice contributes to a session
`OWNER_DRIVER_ID`, `AGENT_DRIVER_ID`	Driver ids for the local operator and for autonomous turns

A driver id is for display and attribution only; it is never an authorization input.

Test doubles: `@robota-sdk/agent-interface/session/testing`

The ./testing subpath ships conformant doubles for code that consumes these contracts. It is separate from the main entry so the doubles never land in a production bundle.

Export	What it does
`createTestInteractiveSession(overrides?)`	Returns a complete `IInteractiveSession` with inert defaults; each double has its own session id and every `submit()` handle settles
`createSessionCapabilityHost(capabilities)` (alias `createTestSessionCapabilityHost`)	Builds a host object from a partial set of capability slices, rejecting unknown slice names
`readSessionCapability(host, key)`	Reads one slice as `{ provided: true, value }` or `{ provided: false }`

import { createTestInteractiveSession } from '@robota-sdk/agent-interface/session/testing';
 
const session = createTestInteractiveSession({ getCwd: () => '/tmp/project' });

Because the double is typed as IInteractiveSession without a cast, a test that uses it stops compiling when the contract gains a member, instead of silently testing against an old shape.

Where it sits

Depends on @robota-sdk/agent-core, @robota-sdk/agent-interface/analytics, @robota-sdk/agent-interface/command and @robota-sdk/agent-interface/execution.
@robota-sdk/agent-framework implements the session (InteractiveSession) and an in-process interaction channel (ProgrammaticInteractionChannel).
@robota-sdk/agent-session persists session records (NodeSessionStore implements IInteractiveSessionStore).
Transports (@robota-sdk/agent-transport and its -http, -mcp, -ws carriers), the UIs (@robota-sdk/agent-ui-terminal, @robota-sdk/agent-ui-web), @robota-sdk/agent-product/command, @robota-sdk/agent-session-analytics and @robota-sdk/agent-interface/session-mobility consume these types.

Documentation

SPEC.md — the contract: interaction channel, persistence, capability presence, turn identity, and the runtime-tool capability.