Sessions

A session binds conversation state, a permission profile, and a workspace root. Workspaces are bound at session.create via workspace_root — there is no separate registration method.

Docs2026-07-16

Method catalog pages include Try it builders and Markdown export (index.md) for LLM workflows.

Lifecycle

create → (pause / resume) → close
         ↘ submit tasks / stream events
         ↘ fork / checkpoint / goal

session.create

writelocal socket

Create a session bound to a workspace and permission profile.

Params

workspace_rootstringrequiredbody

Absolute path to the workspace directory. Bound for the life of the session.

profilestringbodydefault safe-edit

Permission profile name (e.g. safe-edit, read-only). Evaluated by the capability kernel.

Result

session_idstringrequired

Opaque session identifier used by subsequent session.* and task.* calls.

workspace_idstringrequired

Bound workspace id for the session.

profilestringrequired

Effective capability profile.

requestjson

Copy

{
"jsonrpc": "2.0",
"id": 1,
"method": "session.create",
"params": {
  "workspace_root": "/repo",
  "profile": "safe-edit"
}
}

resultjson

Copy

{
"jsonrpc": "2.0",
"id": 1,
"result": {
  "session_id": "sess_01J…",
  "workspace_id": "ws_01J…",
  "profile": "safe-edit"
}
}

Core methods

Method	Purpose
session.create	Create session with workspace + profile
session.get / session.list	Metadata and active/archived listing
session.archive / session.unarchive	Reversible archive and restore; active work is rejected
session.pause / session.resume	Suspend / continue
session.close	Compatibility alias for archive
session.replay	Replay raw audit event stream
session.items	Normalized item stream for UI/SDK
session.review	Governance projection over items
session.events.stream	Live notifications (since cursor, event_mode)

JSONL / SQLite export is provided by audit.export (format: jsonl|sqlite), not a session.* method.

Task operations

Method	Purpose
execution.start	Submit a prompt/task into a session
execution.cancel	Cancel a running task
execution.status	Query task state
governance.action.approve / governance.action.deny	Resolve pending approval (optional role)

Task events are consumed through session.events.stream — there is no separate task event stream.

Goals

At most one goal per session:

goal.set / get / clear / pause / resume / complete / continue

• goal.continue is an explicit, operator-triggered task submission
• No unattended continuation loop
• Fails closed while a task is in-flight, after continuation limit, or when token budget is exhausted
• Interrupting an active TUI task pauses the goal

TUI: /goal [--tokens N] OBJECTIVE plus clear|pause|resume|complete|continue.

Checkpoints

session.checkpoint.compact compacts only a paused task’s persisted latest checkpoint. It never aliases context.compress. Compaction is WAL-backed, idempotent on retry, and leaves the source checkpoint available.

TUI: /compact.

SDK sketch

client.ts

import { CarinaClient } from '@nebutra/carina-sdk';

const client = await CarinaClient.connect();
const session = await client.sessions.create({
  workspace_root: process.cwd(),
  profile: 'safe-edit',
});

for await (const event of session.events()) {
  console.log(event.type, event.payload);
}

Tip

Prefer safe-edit for interactive coding. Use read-only for review-only agents and sub-agents.

Source of truth

• Lifecycle notes: docs/tui-session-lifecycle.md
• RPC families: session.* · goal.* · session.checkpoint.*
• CLI: carina sessions · carina resume · carina items · carina session review
• Related: JSON-RPC · Method catalog · Audit

Next

• Quickstart — create a session from the CLI
• Traces — items, events, cost