feat(server): add read-only inspect_session tool for session state introspection (#193)

README.md

@@ -37,12 +37,12 @@ User Goal → Workflow → Activities → Techniques → Tools
 
 ### MCP Tools at a Glance
 
-The server registers 16 MCP tools across five concerns. See [docs/api-reference.md](docs/api-reference.md) for full signatures.
+The server registers 17 MCP tools across five concerns. See [docs/api-reference.md](docs/api-reference.md) for full signatures.
 
 | Concern | Tools |
 |---------|-------|
 | Bootstrap (no session token) | `discover`, `list_workflows`, `health_check` |
-| Session | `start_session`, `get_workflow_status`, `dispatch_child` |
+| Session | `start_session`, `get_workflow_status`, `inspect_session`, `dispatch_child` |
 | Workflow / activity navigation | `get_workflow`, `next_activity`, `get_activity` |
 | Checkpoint flow | `yield_checkpoint`, `resume_checkpoint`, `present_checkpoint`, `respond_checkpoint` |
 | Techniques, resources | `get_technique`, `get_resource` |

docs/api-reference.md

@@ -18,6 +18,7 @@ No `session_index` required.
 |------|------------|---------|-------------|
 | `start_session` | `agent_id`, `workflow_id?`, `planning_slug?`, `parent_planning_slug?`, `context_mode?` | `session_index`, `planning_slug`, workflow info | Starts a new session or resumes an existing one, optionally with a parent for nested-workflow dispatch. **Fresh sessions default to the `meta` workflow** when no `workflow_id` is provided. `agent_id` sets the recorded agent identity in `session.json`, distinguishing orchestrator from worker calls in the trace. `planning_slug` is a single-segment slug for the planning folder under `<workspace>/.engineering/artifacts/planning/<slug>/`; it determines where `session.json` and the sealed `.session-token` live and deterministically derives the 6-character base32 `session_index`. When `planning_slug` is omitted, the server mints a transitional slug. To **resume** a session, pass the same `planning_slug` again — the server loads the existing `session.json`, verifies the seal, and returns the same `session_index`. For **nested dispatch**, also pass `parent_planning_slug`; the server snapshots the parent's `session.json` (seal-verified) under the child's `parentSession` field for trace correlation and recursive parent traversal. `context_mode` declares the session's delivery context model: `"persistent"` opts into [reference delivery](#reference-delivery); omitted (or `"fresh"`) delivers full content on every call — the correct mode when disposable workers each execute in a fresh context. On resume, a supplied `context_mode` overwrites the recorded value. Fresh sessions start with the variable bag seeded from the workflow's declared `defaultValue`s, recorded as a `variables_seeded` history event (resumes never re-seed — the mutated bag is preserved); `dispatch_child` seeds each child's bag from the child workflow's own declarations the same way. Server restarts are transparent because state lives in `session.json` rather than in an agent-held token. |
 | `get_workflow_status` | `session_index` | `status` (active/blocked/completed), `current_activity`, `completed_activities`, `last_checkpoint` info, `workflow`, and `parent` context | Checks the status of the current workflow session. `session_index` identifies the session. The returned `status` is one of `active`, `blocked`, or `completed`. `current_activity` names the activity the agent is executing. `completed_activities` lists all finished activities (from `session.json`). `last_checkpoint` contains the most recent checkpoint details. `workflow` reflects the current workflow metadata. If the session was created with a `parent_planning_slug`, the `parent` field contains the parent's session info derived from the `parentSession` snapshot. |
+| `inspect_session` | `session_index`, `view?`, `child_index?`, `variable?` | A compact structured projection of the addressed session, selected by `view`, serialised as JSON text | Read-only inspection of a session's on-disk state. `view` selects the projection: `summary` (default, the composite of all below), `identity` (workflow/session/agent header + current position), `variables` (the variable bag), `checkpoints` (each checkpoint response as `optionId`, `respondedAt`, `variablesSet`), `activities` (`completed` / `skipped` / `current`), `history` (event `count`, a per-type `byType` tally, and the `milestones` sub-sequence), and `children` (a one-line digest per `triggeredWorkflows` child). `child_index` descends one positional level into the addressed session's `triggeredWorkflows[child_index].state` and projects that child instead (an out-of-range index returns the actionable `NOT_FOUND` message); deeper children are reached by passing that child's own `session_index`. `variable` — meaningful only with `view: variables` — narrows the result to a single key's value. The tool reads through the same sealed load path as every other tool (so it verifies integrity) but never mutates state, and is **not** gated on an active checkpoint — it is usable while the session is blocked, which is exactly when an orchestrator wants to look. It returns a shaped projection, never the raw `session.json`. |
 
 ### Workflow Tools
 

scripts/generate-site-data.ts

@@ -307,7 +307,7 @@ export function captureTools(): CapturedTool[] {
 
 const TOOL_GROUPS: Array<{ title: string; note: string; tools: string[] }> = [
   { title: 'Bootstrap', note: 'Callable without a session_index.', tools: ['discover', 'list_workflows', 'health_check'] },
-  { title: 'Session', note: 'Create, inspect, and extend workflow sessions.', tools: ['start_session', 'get_workflow_status', 'dispatch_child'] },
+  { title: 'Session', note: 'Create, inspect, and extend workflow sessions.', tools: ['start_session', 'get_workflow_status', 'inspect_session', 'dispatch_child'] },
   { title: 'Workflow and activity navigation', note: 'Load workflow structure and advance through activities.', tools: ['get_workflow', 'next_activity', 'get_activity'] },
   { title: 'Checkpoint flow', note: 'Yield to the orchestrator, present decisions to the user, and resume.', tools: ['yield_checkpoint', 'resume_checkpoint', 'present_checkpoint', 'respond_checkpoint'] },
   { title: 'Techniques and resources', note: 'Fetch technique definitions and lazy-loaded reference material.', tools: ['get_technique', 'get_resource'] },
@@ -347,6 +347,12 @@ const SITE_TOOL_GUIDES: Partial<Record<string, string[]>> = {
     'Returns whether the session is active, blocked at a checkpoint, or completed, plus the current activity and completed steps.',
     'If the session is nested under a parent, parent context is included too.',
   ],
+  inspect_session: [
+    'Read-only look at a session\'s stored state. Pick a `view`: `summary` (everything), `identity`, `variables`, `checkpoints`, `activities`, `history`, or `children`.',
+    'Returns a compact, purpose-built projection — never the raw session file.',
+    'Pass `child_index` to look one level into a child session listed under `triggeredWorkflows`; pass `variable` with `view: variables` to read a single value.',
+    'It never changes anything and works even while the session is paused at a checkpoint — which is often exactly when you want to look.',
+  ],
   dispatch_child: [
     'Starts a child workflow inside the parent session you are already in.',
     'Returns the child\'s `session_index` and `planning_folder_path`. The child\'s variables are seeded from the child workflow\'s defaults; the parent is unchanged.',

site/api/tools.html

@@ -71,11 +71,11 @@ <h1>MCP tool reference</h1>
   <p>Conventions: most tools identify their session with a <code>session_index</code> — the 6-character token returned by <code>start_session</code>. Tools in the Bootstrap group work without one. The prose reference with usage guidance lives in <a href="https://github.com/m2ux/workflow-server/blob/main/docs/api-reference.md">docs/api-reference.md</a>.</p>
 
       <!-- BEGIN GENERATED — edit scripts/generate-site-data.ts, then run npm run build:site -->
-      <p>The server registers 16 MCP tools. Each entry shows a short summary; expand for the full description and advanced parameters.</p>
+      <p>The server registers 17 MCP tools. Each entry shows a short summary; expand for the full description and advanced parameters.</p>
       <nav aria-label="Tools on this page">
       <ul>
         <li>Bootstrap: <a href="#discover"><code>discover</code></a>, <a href="#list_workflows"><code>list_workflows</code></a>, <a href="#health_check"><code>health_check</code></a></li>
-        <li>Session: <a href="#start_session"><code>start_session</code></a>, <a href="#get_workflow_status"><code>get_workflow_status</code></a>, <a href="#dispatch_child"><code>dispatch_child</code></a></li>
+        <li>Session: <a href="#start_session"><code>start_session</code></a>, <a href="#get_workflow_status"><code>get_workflow_status</code></a>, <a href="#inspect_session"><code>inspect_session</code></a>, <a href="#dispatch_child"><code>dispatch_child</code></a></li>
         <li>Workflow and activity navigation: <a href="#get_workflow"><code>get_workflow</code></a>, <a href="#next_activity"><code>next_activity</code></a>, <a href="#get_activity"><code>get_activity</code></a></li>
         <li>Checkpoint flow: <a href="#yield_checkpoint"><code>yield_checkpoint</code></a>, <a href="#resume_checkpoint"><code>resume_checkpoint</code></a>, <a href="#present_checkpoint"><code>present_checkpoint</code></a>, <a href="#respond_checkpoint"><code>respond_checkpoint</code></a></li>
         <li>Techniques and resources: <a href="#get_technique"><code>get_technique</code></a>, <a href="#get_resource"><code>get_resource</code></a></li>
@@ -157,6 +157,28 @@ <h3><code>get_workflow_status</code></h3>
         </table>
         </div>
       </section>
+      <section class="tool" id="inspect_session">
+        <h3><code>inspect_session</code></h3>
+        <p class="tool-summary">Read-only inspection of a workflow session's on-disk state.</p>
+        <details class="tool-details">
+          <summary>Full description</summary>
+          <p>Read-only look at a session's stored state. Pick a <code>view</code>: <code>summary</code> (everything), <code>identity</code>, <code>variables</code>, <code>checkpoints</code>, <code>activities</code>, <code>history</code>, or <code>children</code>.</p>
+          <p>Returns a compact, purpose-built projection — never the raw session file.</p>
+          <p>Pass <code>child_index</code> to look one level into a child session listed under <code>triggeredWorkflows</code>; pass <code>variable</code> with <code>view: variables</code> to read a single value.</p>
+          <p>It never changes anything and works even while the session is paused at a checkpoint — which is often exactly when you want to look.</p>
+        </details>
+        <div class="table-wrap">
+        <table class="param-table">
+          <thead><tr><th scope="col">Parameter</th><th scope="col">Type</th><th scope="col">Required</th><th scope="col">Description</th></tr></thead>
+          <tbody>
+          <tr><td><code>session_index</code></td><td><code>string</code></td><td>yes</td><td>Six-character token from <code>start_session</code>. Use the same value for every call in this session.</td></tr>
+          <tr><td><code>view</code></td><td><code>&quot;summary&quot; | &quot;identity&quot; | &quot;variables&quot; | &quot;checkpoints&quot; | &quot;activities&quot; | &quot;history&quot; | &quot;children&quot;</code></td><td>no</td><td>Which projection to return. <code>summary</code> (default) is the composite of all views. <code>identity</code> = workflow/session/agent header + position; <code>variables</code> = the variable bag; <code>checkpoints</code> = checkpoint responses (option, timestamp, variables set); <code>activities</code> = completed/skipped/current; <code>history</code> = event count + per-type tally + milestone sub-sequence; <code>children</code> = one-line digest per triggeredWorkflows child. Default: <code>&quot;summary&quot;</code></td></tr>
+          <tr><td><code>child_index</code></td><td><code>integer</code></td><td>no</td><td>Optional positional index into the addressed session's <code>triggeredWorkflows</code>. When given, the tool descends one level to <code>triggeredWorkflows[child_index].state</code> and projects that child instead of the addressed session. Out of range yields the NOT_FOUND message. Deeper children are reached by passing that child's own session_index instead of stacking indices.</td></tr>
+          <tr><td><code>variable</code></td><td><code>string</code></td><td>no</td><td>Optional single variable name. Only meaningful with <code>view: variables</code> — narrows the result to that one key's value instead of the whole bag.</td></tr>
+          </tbody>
+        </table>
+        </div>
+      </section>
       <section class="tool" id="dispatch_child">
         <h3><code>dispatch_child</code></h3>
         <p class="tool-summary">Start a child workflow inside the current session.</p>