Session Log Management

Session Log Management

Overview

To manage agent session logs, use the workflow.sessionlog.* REPL command namespace via mcpserver-repl --agent-stdio. Direct stdio input must be one single-line JSON request envelope per message, not formatted YAML. Session logging captures agent activity, reasoning dialog, file operations, and design decisions as a structured audit trail.

workflow.sessionlog.* is a plugin workflow/REPL namespace, not a literal native MCP tool namespace. Native McpServer /mcp-transport discovery uses names such as sessionlog_*, todo_*, and requirements_*; hosted-agent adapters may expose mcp_session_* aliases. Do not call this plugin unavailable solely because workflow.* names are absent from generic MCP discovery.

Most session management is automated by the plugin hooks in hooks/. This skill covers manual operations, history queries, and the full lifecycle for agents that need direct control.

Identifier Naming Conventions

Session IDs

Format: <Agent>-<yyyyMMddTHHmmssZ>-<suffix>

Regex: ^[A-Z][A-Za-z0-9]*-\d{8}T\d{6}Z-[a-z0-9]+(?:-[a-z0-9]+)*$

• Agent name must be PascalCase (e.g. ClaudeCode, Copilot, Cursor)
• Timestamp must be ISO 8601 compact UTC: yyyyMMddTHHmmssZ
• Suffix must be lowercase kebab-case: feature-auth, bugfix-timeout

Valid examples: ClaudeCode-20260409T120000Z-implement-auth, Copilot-20260304T113901Z-refactor-session

Invalid: claudecode-20260409T120000Z-task (lowercase agent), Copilot-20260304-feature (missing time component)

Request IDs

Format: req-<yyyyMMddTHHmmssZ>-<slugOrOrdinal>

Regex: ^req-\d{8}T\d{6}Z-[a-z0-9]+(?:-[a-z0-9]+)*$

Valid examples: req-20260409T120001Z-add-jwt-001, req-20260409T120002Z-query-todos

Invalid: request-20260409T120001Z-task (wrong prefix), req-20260409-task (missing time)

Session Lifecycle

Step 1 — Bootstrap (once per process lifetime)

Bootstrap initializes the session log subsystem. This operation is idempotent:

type: request
payload:
  requestId: req-20260409T120000Z-bootstrap-001
  method: workflow.sessionlog.bootstrap
  params: {}

type: result
payload:
  requestId: req-20260409T120000Z-bootstrap-001
  result:
    initialized: true

Step 2 — Open Session

To create a new session record at the start of a work session:

type: request
payload:
  requestId: req-20260409T120001Z-open-001
  method: workflow.sessionlog.openSession
  params:
    agent: ClaudeCode
    sessionId: ClaudeCode-20260409T120001Z-implement-auth
    title: Implement JWT authentication
    model: claude-sonnet-4-6

type: result
payload:
  requestId: req-20260409T120001Z-open-001
  result:
    sessionId: ClaudeCode-20260409T120001Z-implement-auth
    started: 2026-04-09T12:00:01Z

Step 3 — Begin Turn (once per user message)

To start a new turn before working on a user request:

type: request
payload:
  requestId: req-20260409T120002Z-begin-001
  method: workflow.sessionlog.beginTurn
  params:
    requestId: req-20260409T120002Z-add-jwt-001
    queryTitle: Add JWT authentication
    queryText: Implement JWT token generation and validation for the API

type: result
payload:
  requestId: req-20260409T120002Z-begin-001
  result:
    turnRequestId: req-20260409T120002Z-add-jwt-001
    status: in_progress
    timestamp: 2026-04-09T12:00:02Z

Step 4 — Update Turn

To record interpretation, response summary, tags, and referenced files during work:

type: request
payload:
  requestId: req-20260409T120003Z-update-001
  method: workflow.sessionlog.updateTurn
  params:
    response: Created TokenService and JwtValidator classes
    interpretation: User wants JWT authentication with token generation and validation
    tokenCount: 1250
    tags:
      - feature
      - security
      - FR-AUTH-001
    contextList:
      - src/Services/TokenService.cs
      - src/Services/JwtValidator.cs

Step 5 — Append Dialog

To record reasoning steps, tool calls, observations, and decisions as the work progresses:

type: request
payload:
  requestId: req-20260409T120004Z-dialog-001
  method: workflow.sessionlog.appendDialog
  params:
    dialogItems:
      - timestamp: 2026-04-09T12:00:04Z
        role: model
        content: Analyzing authentication requirements and existing patterns...
        category: reasoning
      - timestamp: 2026-04-09T12:00:05Z
        role: model
        content: |
          Decision: Use HS256 for JWT signing.
          Rationale: Symmetric key simplifies key management for this internal service.
          Alternatives: RS256 adds key distribution complexity without benefit here.
        category: decision

Valid category values: reasoning, tool_call, tool_result, observation, decision.

Valid role values: model, tool, system, user.

Step 6 — Append Actions

To record file operations and other work artifacts:

type: request
payload:
  requestId: req-20260409T120005Z-actions-001
  method: workflow.sessionlog.appendActions
  params:
    actions:
      - order: 1
        description: Created TokenService with JWT generation
        type: create
        status: completed
        filePath: src/Services/TokenService.cs
      - order: 2
        description: Created JwtValidator for token validation
        type: create
        status: completed
        filePath: src/Services/JwtValidator.cs
      - order: 3
        description: Chose HS256 for JWT signing (internal service, symmetric key)
        type: design_decision
        status: completed
        filePath: ""

Standard action type values: edit, create, delete, design_decision, commit, pr_comment, issue_comment, web_reference, dependency_add.

Step 7 — Complete Turn

To finalize a turn as successfully completed (immutable after this call):

type: request
payload:
  requestId: req-20260409T120006Z-complete-001
  method: workflow.sessionlog.completeTurn
  params:
    response: |
      JWT authentication implemented:
      - TokenService generates HS256-signed tokens
      - JwtValidator validates and extracts claims
      - Services registered in Startup.cs
      - All unit tests passing

Failing a Turn

To mark a turn as failed with an error description:

type: request
payload:
  requestId: req-20260409T120007Z-fail-001
  method: workflow.sessionlog.failTurn
  params:
    errorMessage: Unable to complete — missing System.IdentityModel.Tokens.Jwt package
    errorCode: dependency_missing

Both completeTurn and failTurn produce an immutable terminal state. No further updateTurn, appendDialog, or appendActions calls are allowed on a completed or failed turn.

Querying Session History

To browse previous sessions for context continuity:

type: request
payload:
  requestId: req-20260409T120008Z-history-001
  method: workflow.sessionlog.queryHistory
  params:
    agent: ClaudeCode
    limit: 10
    offset: 0

type: result
payload:
  requestId: req-20260409T120008Z-history-001
  result:
    sessions:
      - agent: ClaudeCode
        sessionId: ClaudeCode-20260409T120001Z-implement-auth
        title: Implement JWT authentication
        model: claude-sonnet-4-6
        started: 2026-04-09T12:00:01Z
        lastUpdated: 2026-04-09T12:30:00Z
        status: completed
        turnCount: 3
        filesModifiedCount: 5
        tags: [auth, jwt, security]
    totalCount: 1
    offset: 0
    limit: 10

Omit agent to query across all agents. Use offset and limit for pagination.

Turn Lifecycle State Machine

A turn transitions through these states only in forward order:

1. in_progress — created via beginTurn, open for updates
2. completed — finalized via completeTurn (immutable)
3. failed — finalized via failTurn (immutable)

Any attempt to call updateTurn, appendDialog, or appendActions on a completed or failed turn returns a turn_immutable error.

Error Handling

type: error
payload:
  requestId: req-20260409T120003Z-update-001
  code: turn_immutable
  message: Turn is immutable (status: completed)
  details:
    turnRequestId: req-20260409T120002Z-add-jwt-001
    currentStatus: completed
    hint: Begin a new turn instead

Common error codes:

• session_not_found — no active session; call openSession first
• session_already_exists — session ID already in use
• invalid_session_id — session ID format violation
• invalid_request_id — request ID format violation
• turn_not_found — no active turn; call beginTurn first
• turn_already_exists — turn with same request ID already exists
• turn_immutable — cannot modify completed or failed turn

Session Continuity After Restart

After a server restart or agent reconnect:

1. Call workflow.sessionlog.queryHistory to review past sessions
2. Decide whether to continue in a new session referencing the previous one in the title, or to re-open fresh
3. Re-read AGENTS-README-FIRST.yaml for the rotated API key before making any calls
4. Call bootstrap again (idempotent) then openSession for the new session

Codex CLI JSONL Integration

The plugin automatically captures rich session fields from Codex CLI JSONL transcripts. No manual steps are required for normal Codex sessions.

Automatic Rich Field Capture

When a Codex CLI session ends, final-response.sh reads the session JSONL (from CODEX_SESSION_FILE, CODEX_ROLLOUT_FILE, or the most recent ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl) and calls lib/codex-jsonl-enrich.js to extract:

• interpretation - first agent message from the last turn
• processingDialog - all agent messages, tool calls, and observations
• actions - file edits from patch_apply_end events and write tool calls
• filesModified - all files changed in the turn
• contextList - files read as context
• designDecisions - agent messages containing Decision: or Rationale:
• requirementsDiscovered - FR/TR/TEST IDs mentioned in agent messages
• blockers - turn_aborted events

These fields are passed to completeTurn, which routes through importRecovery to persist them on the server. Secret values (API keys, Bearer tokens) are redacted before logging.

Subagent Transcript Import

When a Codex parent session spawns subagents, the hooks/scripts/subagent-import.sh hook (called on subagentComplete) discovers and imports each subagent JSONL as a first-class MCP session-log turn.

Subagent sessions are identified by source.subagent.thread_spawn.parent_thread_id in the JSONL session_meta line. The plugin scans $CODEX_SESSION_DIR (default: ~/.codex/sessions/) for matching files.

Each imported subagent turn:

• Gets tags ["subagent", "<nickname>"] and optionally ["parent:<parentReqId>"]
• Uses a deterministic request ID: req-<subagentStartTs>-subagent-<nickname>-<turnId>
• Is idempotent: a tracker file prevents re-importing the same session twice

Manual Recovery

To manually import a Codex JSONL transcript:

# Extract tab-delimited import lines (method, base64-params, label)
node lib/codex-jsonl.js import /path/to/rollout.jsonl "SessionId-20260525T100000Z-fix" > import-lines.txt

# Dispatch each line via repl-invoke
while IFS=$'\t' read -r method params_b64 label; do
    params="$(printf '%s' "$params_b64" | base64 --decode)"
    repl_invoke "$method" "$params"
done < import-lines.txt

To discover subagent transcripts for a parent:

CODEX_SESSION_DIR=/path/to/sessions node lib/codex-jsonl.js subagents /path/to/parent-rollout.jsonl

Non-Destructive Merge

Server-side rich fields are never overwritten by sparse incoming values. lib/sessionlog-submit-body.js uses field-level merge: an empty incoming array never replaces a non-empty server-side array. This allows completeTurn and importRecovery to be called safely after rich fields have already been captured.

Secret Redaction

The following patterns are redacted from all JSONL-extracted text before logging:

• X-Api-Key: header values
• apiKey: parameter values (20+ character strings)
• Bearer <token> values
• Authorization: header values

Implementation Notes

• Use repl_invoke from lib/repl-invoke.sh to build and dispatch envelopes.
• Generate request IDs with the current UTC timestamp to guarantee uniqueness: req-$(date -u +%Y%m%dT%H%M%SZ)-<slug>.
• Post beginTurn before starting any work on a user request; post completeTurn or failTurn after work ends. Never defer these calls.
• Log all design decisions in appendDialog with category: decision AND in appendActions with type: design_decision.
• Record all web sources consulted as actions with type: web_reference and include the URL in the description.
• At approximately every 10 interactions, verify all turns are persisted and all design decisions are captured before continuing.