session-create（会话创建）

/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

What It Does

This skill:

1. Calls mcp__postgres-knowledgebase__sessionCreate with agentName, storyId, and phase
2. Records the returned session_id and emits the structured SESSION CREATED output block
3. 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:

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:

1. Leader opens — calls session-create → sessionCreate → emits SESSION CREATED
2. Workers inherit — each worker calls session-inherit → sessionQuery(activeOnly: true) → emits SESSION INHERITED
3. Workers update tokens — call sessionUpdate({sessionId, mode: 'incremental', inputTokens, outputTokens})
4. Leader closes — the leader (and ONLY the leader that opened the session) calls sessionComplete
5. 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:

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