/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