Session Portability

3 min readFor operatorsUpdated 2026-05-23

What you'll do

Export Craik sessions and inspect adjacent transcript imports without turning unsupported tool calls into executable authority.

Imports are inert by default.

Adjacent transcript tool calls are preserved as unsupported-field evidence. They do not become Craik capabilities, grants, receipts, or queued actions.

Export

Use the portable export format for migration reviews or support handoffs:

craik session export-portable agent_session_docs

The output uses schema: craik.session_export, preserves the source session id in provenance, strips process-only state such as pid and endpoint URL, and redacts event metadata before printing.

Import Preview

Preview a Craik session export or adjacent transcript file:

craik session import-portable --path ./transcript.json

Craik accepts transcript files shaped as either messages or transcript arrays. Imported sessions are marked with:

Field

Value

Purpose

recovery_metadata.imported

true

Signals that the session did not originate from a live Craik run.

recovery_metadata.source_session_id

original id

Preserves source identity for review and rollback.

unsupported_fields

evidence only

Lists unsupported tool calls, attachments, and other fields that require adapter work.

Unsupported Tool Calls

Unsupported tool calls are never converted into executable authority. The importer records their source paths and summaries, then creates redacted craik.agent_session_event entries with unsupported_tool_call_count metadata for audit review.

Validation

Run the portability tests when changing session state, event metadata, or transcript migration code:

uv run pytest tests/test_session_portability.py

What's Next

GuidePersistent agent runtimeHow live sessions are created and resumed.ReferenceAgent lifecycleSession state, events, and recovery metadata.GuideAdjacent runtime migrationHow portability fits into broader migration reviews.