/session-create - Open a Context Session

Description

Opens a new context session at the beginning of a leader agent's workflow. The session record tracks token usage, agent identity, and story context across multi-agent workflows. Workers inherit this session via the companion session-inherit skill.

Session tracking is telemetry — it must never gate or block a workflow. If the session cannot be created (DB unavailable, null return), the leader emits a warning and continues normally.

Usage

/session-create # called at start of leader workflow /session-create storyId=WINT-1234 phase=execute # with story and phase context

Parameters

Parameter Required Default Description

agentName

Yes (current agent name) The name of the leader agent opening the session

storyId

No null Story ID for this workflow (e.g. WINT-1234 )

phase

No null Current workflow phase (e.g. execute , plan , qa )

sessionId

No (auto-generated UUID) Override the session UUID (rarely needed)

What It Does

This skill:

• Calls mcp__postgres-knowledgebase__sessionCreate with agentName , storyId , and phase

• Records the returned session_id and emits the structured SESSION CREATED output block

• Handles null returns (DB error) gracefully — emits SESSION UNAVAILABLE and continues

Execution Steps

Step 1: Invoke sessionCreate

Call the MCP tool with required and optional fields:

const result = await mcp__postgres_knowledgebase__sessionCreate({ agentName: 'dev-execute-leader', // required — name of THIS agent storyId: 'WINT-2090', // optional phase: 'execute', // optional // sessionId: crypto.randomUUID() // omit to auto-generate })

SessionCreateInput fields:

Field Type Required Notes

agentName

string (min 1) Yes Name of the leader agent

sessionId

UUID string No Auto-generated if omitted

storyId

string | null No Story identifier

phase

string | null No Workflow phase label

inputTokens

int >= 0 No Default: 0

outputTokens

int >= 0 No Default: 0

cachedTokens

int >= 0 No Default: 0

startedAt

Date No Defaults to now()

Step 2: Handle the result

Success path — result is not null:

if (result && result.sessionId) { // Emit the structured output block (see Output section below) }

Null-return path — DB error or connection failure:

if (result === null) { // Emit SESSION UNAVAILABLE warning and continue }

Step 3: Emit structured output

On success, always emit the following block so workers can parse the session ID:

SESSION CREATED session_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 agent: dev-execute-leader story_id: WINT-2090 phase: execute

The session_id line must match the regex: /SESSION CREATED\n\s+session_id:\s+([0-9a-f-]{36})/

Output

Success

After a successful sessionCreate call, emit:

SESSION CREATED session_id: {uuid returned by sessionCreate} agent: {agentName} story_id: {storyId or "—"} phase: {phase or "—"}

Null Return (Graceful Degradation)

If sessionCreate returns null (DB unavailable or insertion error):

SESSION UNAVAILABLE — continuing without session tracking

Then continue the workflow normally. Do not block, retry, or raise an error. Session tracking is telemetry, not a gate.

Session Lifecycle

The full session lifecycle across a multi-agent workflow:

• Leader opens — calls session-create → sessionCreate → emits SESSION CREATED

• Workers inherit — each worker calls session-inherit → sessionQuery(activeOnly: true) → emits SESSION INHERITED

• Workers update tokens — call sessionUpdate({ sessionId, mode: 'incremental', inputTokens, outputTokens })

• Leader closes — the leader (and ONLY the leader that opened the session) calls sessionComplete

• Periodic cleanup — sessionCleanup({ retentionDays: 90 }) archives old sessions (future: WINT-2100)

Workers MUST NOT call sessionComplete . See the session-inherit skill for the full restriction.

Graceful Degradation

Session tracking is purely telemetry. The following conditions must NOT block the workflow:

Condition Behavior

DB connection unavailable Emit SESSION UNAVAILABLE — continuing without session tracking and proceed

sessionCreate returns null Same as above

MCP tool unavailable Log warning, proceed without session

Network timeout Log warning, proceed without session

The leader's downstream work (plan execution, file writes, code generation) must continue regardless of session state.

Examples

Minimal invocation

const session = await mcp__postgres_knowledgebase__sessionCreate({ agentName: 'dev-execute-leader', }) // Emits: // SESSION CREATED // session_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 // agent: dev-execute-leader // story_id: — // phase: —

Full invocation with context

const session = await mcp__postgres_knowledgebase__sessionCreate({ agentName: 'dev-execute-leader', storyId: 'WINT-2090', phase: 'execute', }) // Emits: // SESSION CREATED // session_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 // agent: dev-execute-leader // story_id: WINT-2090 // phase: execute

Null-return path

const session = await mcp__postgres_knowledgebase__sessionCreate({ agentName: 'dev-execute-leader', storyId: 'WINT-2090', phase: 'execute', })

if (!session) { // Emit: // SESSION UNAVAILABLE — continuing without session tracking // then continue with the rest of the workflow normally }

Integration Notes

• The session_id from SESSION CREATED should be passed to spawned workers via their prompt context so they can call session-inherit

• Workers use sessionQuery({ activeOnly: true, limit: 50 }) and filter client-side — they do NOT receive a sessionId filter directly

• The leader is solely responsible for calling sessionComplete at the end of its workflow