Session Log Management

Files (2)

• .gitkeep
• SKILL.md

SKILL.md (first lines)

# Session Log Management

## Overview

To manage agent session logs, use the `workflow.sessionlog.*` REPL command namespace through the plugin wrapper (`lib/repl-invoke.ps1` / `Invoke-McpPlugin.ps1`). 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, and your agent's tool discovery may show configured MCP tools with native names such as `sessionlog_submit`, `todo_list`, and `requirements_generate`. Do not call this plugin unavailable solely because `workflow.*` names are absent from generic MCP discovery.

`workflow.*` result envelopes may include `deprecated: true`. This is success metadata that tells callers the workflow namespace is legacy-compatible and should migrate toward the canonical `client.*` surface where available; it is not a failure signal and is not a reason to use raw REST. Treat an empty `workflow.sessionlog.queryHistory` result as a valid no-match result, not as an inert wrapper. Re-check the workspace current directory, the explicit `agent` or `sourceType`, and local plugin cache/session state through the wrapper before reporting history as unavailable.

This skill covers manual operations, history queries, and the full lifecycle for agents that need direct control.

## Preferred Workflow

For most work sessions:

1. Bootstrap session logging once.
2. Open or resume the session.
3. On each user request, begin a turn.
4. Consult current session/task state before asking the user for context.
5. Update the turn with relevant files, decisions, and actions.
6. Complete the turn after verification, or record failure if blocked.

## Running the Workflow Methods

When the plugin's hooks (in `hooks/`) are active, most session management is automated and you do not need to drive it by hand. When hooks are not active for your agent, drive the lifecycle yourself through the plugin wrapper, never by hand-piping envelopes to REPL stdio:

```pwsh
pwsh -NoProfile -File "<plugin-root>/lib/repl-invoke.ps1" -Method <method> -ParamsYaml @'
<yaml params>
'@
```

The equivalent function form is `Invoke-McpPlugin.ps1 "<method>" "<yaml params>"`. For a one-shot bootstrap plus session open, prefer `<plugin-root>/lib/session-start.ps1 <workspace-path>`.

The YAML envelope blocks in this skill document the wire contract each method maps to. Pass the `params:` body to the wrapper; it wraps it in the request envelope, validates documented params, and emits single-line JSON to REPL stdio for you. If you bypass the wrapper for diagnostics and write to REPL stdio directly, send one single-line JSON request envelope per message, never formatted YAML.

Why the wrapper and not raw stdio:

- `workflow.sessionlog.beginTurn` and `openSession` are not server routes. Calling them raw returns `method_invocation_error` / `method_not_found`. The wrapper treats them as local no-ops and tracks turn state in `cache/current-turn.yaml`.
- Persisting a turn goes through `client.SessionLog.SubmitAsync`, which is strict: `actions[].order` must be an unquoted integer (`order: 1`, never `order: "1"`) or you get `JSON value could not be converted to System.Int32`. The wrapper builds the envelope with correct types.
- There is no `session.init` method. Bootstrap with `workflow.sessionlog.bootstrap` only.

## 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. `YourAgent`)
- Timestamp must be ISO 8601 compact UTC: `yyyyMMddTHHmmssZ`
- Suffix must be lowercase kebab-case: `feature-auth`, `bugfix-timeout`

Valid examples: `YourAgent-20260409T120000Z-implement-auth`, `YourAgent-20260304T113901Z-refactor-session`

Invalid: `youragent-20260409T120000Z-task` (lowercase agent), `YourAgent-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:

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

```yaml
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:

```yaml
type: request
payload:
  requestId: req-20260409T120001Z-open-001
  method: workflow.sessionlog.openSession
  params:
    agent: YourAgent
    sessionId: YourAgent-20260409T120001Z-implement-auth
    title: Implement JWT authentication
    model: <model-id>
```

```yaml
type: result
payload:
  requestId: req-20260409T120001Z-open-001
  result:
    sessionId: YourAgent-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:

From sharpninja/mcpserver-grok-plugin, MIT.