@hueyexe/opencode-ensemble 0.15.2 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.15.2",
+  "version": "0.16.1",
   "description": "Agent teams for OpenCode — parallel agents with peer-to-peer communication, shared tasks, and coordinated execution",
   "module": "src/index.ts",
   "main": "dist/index.js",
@@ -45,7 +45,7 @@
     "typescript": "^5"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "^1.15.1",
-    "@opencode-ai/sdk": "^1.15.1"
+    "@opencode-ai/plugin": "^1.17.18",
+    "@opencode-ai/sdk": "^1.17.18"
   }
 }

package/src/activity.ts

@@ -0,0 +1,215 @@
+import type { MemberRegistry } from "./state"
+
+/**
+ * A single activity event captured per session for the dashboard verbose view.
+ */
+export interface ActivityEntry {
+  /** The kind of activity being recorded. */
+  type: "tool_call" | "tool_result" | "shell_command" | "step" | "reasoning" | "file" | "text"
+  /** Tool name (for tool_call / tool_result types). */
+  tool?: string
+  /** Human-readable title for the activity. */
+  title?: string
+  /** Structured input for a tool call (JSON-formatted string if object). */
+  input?: string
+  /** Structured output for a tool result (JSON-formatted string if object). */
+  output?: string
+  /** Error message if the activity failed. */
+  error?: string
+  /** Shell command string (for shell_command type). */
+  command?: string
+  /** Exit code for shell commands. */
+  exitCode?: number
+  /** Input token count for the activity. */
+  tokensIn?: number
+  /** Output token count for the activity. */
+  tokensOut?: number
+  /** Cost in dollars for the activity. */
+  cost?: number
+  /** Unix millisecond timestamp of the event. */
+  timestamp: number
+  /** Reasoning text (for reasoning type — model's chain of thought). */
+  reasoning?: string
+  /** File path (for file type). */
+  filePath?: string
+  /** File content (for file type). */
+  fileContent?: string
+  /** File diff (for file type). */
+  fileDiff?: string
+  /** Text content (for text type — prompts and responses). */
+  text?: string
+  /** Role for text entries: "user" or "assistant". */
+  role?: string
+}
+
+/** Options for constructing an {@link ActivityBuffer}. */
+export interface ActivityBufferOptions {
+  /** Maximum number of entries retained per session (default 100). */
+  maxPerSession?: number
+}
+
+/**
+ * In-memory rolling buffer of per-session activity events.
+ *
+ * Captures tool calls, shell commands, and step transitions for the dashboard
+ * verbose view. Entries are capped at `maxPerSession` per session — when the
+ * limit is exceeded the oldest entries are evicted.
+ */
+export class ActivityBuffer {
+  private readonly buffers: Map<string, ActivityEntry[]> = new Map()
+  private readonly maxPerSession: number
+
+  /**
+   * @param options Optional configuration. `maxPerSession` defaults to 100.
+   */
+  constructor(options?: ActivityBufferOptions) {
+    this.maxPerSession = options?.maxPerSession ?? 100
+  }
+
+  /**
+   * Add an activity entry to the session's buffer.
+   * When the buffer exceeds `maxPerSession`, the oldest entries are dropped.
+   * @param sessionID The session to record activity for.
+   * @param entry The activity event to store.
+   */
+  record(sessionID: string, entry: ActivityEntry): void {
+    const entries = this.buffers.get(sessionID) ?? []
+    entries.push(entry)
+    if (entries.length > this.maxPerSession) {
+      entries.splice(0, entries.length - this.maxPerSession)
+    }
+    this.buffers.set(sessionID, entries)
+  }
+
+  /**
+   * Retrieve activity entries for a session in chronological order (oldest first).
+   * @param sessionID The session to query.
+   * @param limit If provided, return only the N most recent entries.
+   * @returns Array of entries (empty if session has no recorded activity).
+   */
+  getActivity(sessionID: string, limit?: number): ActivityEntry[] {
+    const entries = this.buffers.get(sessionID)
+    if (!entries) return []
+    if (limit !== undefined) return entries.slice(-limit)
+    return [...entries]
+  }
+
+  /**
+   * Remove all entries for a session.
+   * @param sessionID The session to clear.
+   */
+  remove(sessionID: string): void {
+    this.buffers.delete(sessionID)
+  }
+
+  /**
+   * Check whether any entries exist for a session.
+   * @param sessionID The session to check.
+   * @returns `true` if at least one entry exists, `false` otherwise.
+   */
+  has(sessionID: string): boolean {
+    const entries = this.buffers.get(sessionID)
+    return entries !== undefined && entries.length > 0
+  }
+}
+
+/** V2 event shape for activity recording (permissive — SDK types not available in plugin). */
+interface V2Event {
+  type: string
+  properties: {
+    sessionID?: string
+    tool?: string
+    input?: string
+    content?: string
+    title?: string
+    error?: string
+    command?: string
+    exitCode?: number
+    cost?: number
+    tokens?: { input?: number; output?: number }
+  }
+}
+
+/**
+ * Record activity from a v2 session event (shell commands and step transitions only).
+ * Tool call/result recording is handled by {@link recordFromToolBefore} and {@link recordFromToolAfter}
+ * to avoid duplicate entries from both the event hook and the tool.execute hook.
+ * Only records for sessions registered as team members.
+ * @param event The v2 event from the plugin event hook.
+ * @param registry The member registry for session lookup.
+ * @param buffer The activity buffer to record into.
+ */
+export function recordFromV2Event(
+  event: V2Event,
+  registry: MemberRegistry,
+  buffer: ActivityBuffer,
+): void {
+  const props = event.properties
+  if (!props?.sessionID || !registry.getBySession(props.sessionID)) return
+
+  if (event.type === "session.next.shell.started") {
+    buffer.record(props.sessionID, { type: "shell_command", command: props.command, timestamp: Date.now() })
+  } else if (event.type === "session.next.shell.ended") {
+    buffer.record(props.sessionID, { type: "shell_command", exitCode: props.exitCode, timestamp: Date.now() })
+  } else if (event.type === "session.next.step.ended") {
+    buffer.record(props.sessionID, {
+      type: "step",
+      cost: props.cost,
+      tokensIn: props.tokens?.input,
+      tokensOut: props.tokens?.output,
+      timestamp: Date.now(),
+    })
+  }
+}
+
+/** Input shape for the tool.execute.before hook. */
+interface ToolBeforeInput {
+  sessionID: string
+  tool: string
+}
+
+/** Output shape for the tool.execute.after hook. */
+interface ToolAfterOutput {
+  title?: string
+  output?: string
+}
+
+/**
+ * Record a tool call from the tool.execute.before hook.
+ * Only records for sessions registered as team members.
+ * @param input The tool.execute.before input.
+ * @param registry The member registry for session lookup.
+ * @param buffer The activity buffer to record into.
+ */
+export function recordFromToolBefore(
+  input: ToolBeforeInput,
+  registry: MemberRegistry,
+  buffer: ActivityBuffer,
+): void {
+  if (!registry.getBySession(input.sessionID)) return
+  buffer.record(input.sessionID, { type: "tool_call", tool: input.tool, timestamp: Date.now() })
+}
+
+/**
+ * Record a tool result from the tool.execute.after hook.
+ * Only records for sessions registered as team members.
+ * @param input The tool.execute.before input (for session ID and tool name).
+ * @param output The tool.execute.after output.
+ * @param registry The member registry for session lookup.
+ * @param buffer The activity buffer to record into.
+ */
+export function recordFromToolAfter(
+  input: ToolBeforeInput,
+  output: ToolAfterOutput,
+  registry: MemberRegistry,
+  buffer: ActivityBuffer,
+): void {
+  if (!registry.getBySession(input.sessionID)) return
+  buffer.record(input.sessionID, {
+    type: "tool_result",
+    tool: input.tool,
+    title: output.title,
+    output: output.output,
+    timestamp: Date.now(),
+  })
+}

package/src/client.ts

@@ -22,7 +22,7 @@ function throwing(fn: SdkMethod): SdkMethod {
 
 /** Shape of the raw v2 SDK client — just the methods we wrap. */
 interface RawClient {
-  session: { create: SdkMethod; promptAsync: SdkMethod; abort: SdkMethod; status: SdkMethod }
+  session: { create: SdkMethod; promptAsync: SdkMethod; abort: SdkMethod; status: SdkMethod; messages: SdkMethod; get: SdkMethod }
   tui: { showToast: SdkMethod; selectSession: SdkMethod }
   worktree: { create: SdkMethod; remove: SdkMethod; list: SdkMethod; reset: SdkMethod }
   experimental: { workspace: { create: SdkMethod; remove: SdkMethod; list: SdkMethod } }
@@ -40,6 +40,8 @@ export function wrapThrowingClient(raw: unknown): PluginClient {
       promptAsync: throwing(r.session.promptAsync.bind(r.session)),
       abort: throwing(r.session.abort.bind(r.session)),
       status: throwing(r.session.status.bind(r.session)),
+      messages: throwing(r.session.messages.bind(r.session)),
+      get: throwing(r.session.get.bind(r.session)),
     },
     tui: {
       showToast: throwing(r.tui.showToast.bind(r.tui)),

package/src/dashboard-html.ts

@@ -95,6 +95,7 @@ select{-webkit-appearance:none;appearance:none;background-image:url("data:image/
 <div><kbd class="px-1.5 py-0.5 bg-base-800 rounded font-mono text-txt-300 text-[11px]">k</kbd> <span class="text-txt-400">Prev agent</span></div>
 <div><kbd class="px-1.5 py-0.5 bg-base-800 rounded font-mono text-txt-300 text-[11px]">Enter</kbd> <span class="text-txt-400">Expand agent</span></div>
 <div><kbd class="px-1.5 py-0.5 bg-base-800 rounded font-mono text-txt-300 text-[11px]">Esc</kbd> <span class="text-txt-400">Collapse all</span></div>
+<div><kbd class="px-1.5 py-0.5 bg-base-800 rounded font-mono text-txt-300 text-[11px]">v</kbd> <span class="text-txt-400">Toggle verbose</span></div>
 <div><kbd class="px-1.5 py-0.5 bg-base-800 rounded font-mono text-txt-300 text-[11px]">1-9</kbd> <span class="text-txt-400">Switch team</span></div>
 <div><kbd class="px-1.5 py-0.5 bg-base-800 rounded font-mono text-txt-300 text-[11px]">?</kbd> <span class="text-txt-400">This help</span></div>
 </div>

package/src/dashboard-js-core.ts

@@ -1,6 +1,6 @@
 /** Dashboard JS — utilities, data helpers, and state management. */
 export const DASHBOARD_JS_CORE = `
-let S=null,selId=null,selProjectId=null,fails=0,pollT=Date.now(),prevMC=0,selCard=-1,navCollapsed=false;
+let S=null,selId=null,selProjectId=null,fails=0,pollT=Date.now(),prevMC=0,selCard=-1,navCollapsed=false,verbose=(function(){try{return localStorage.getItem('ensemble-verbose')==='1'}catch(e){return false}})(),drawerActivity=null,drawerSession=null;
 const expCards=new Set(),expMsgs=new Set();
 const E=s=>s?String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;'):'';
 const D=ms=>{const s=Math.floor(Math.abs(ms)/1000);return s<60?s+'s':s<3600?Math.floor(s/60)+'m':Math.floor(s/3600)+'h'};

package/src/dashboard-js-events.ts

@@ -2,6 +2,31 @@
 export const DASHBOARD_JS_EVENTS = `
 function toggleMsg(id){if(expMsgs.has(id))expMsgs.delete(id);else expMsgs.add(id);render()}
 
+function toggleVerbose(){
+  verbose=!verbose;
+  try{localStorage.setItem('ensemble-verbose',verbose?'1':'0')}catch(e){}
+  var btn=document.getElementById('verbose-toggle');
+  if(btn){
+    btn.textContent='verbose: '+(verbose?'on':'off');
+    btn.setAttribute('aria-pressed',verbose?'true':'false');
+    btn.className='text-[10px] '+(verbose?'text-blue-400 border-blue-500/40 bg-blue-500/10':'text-txt-500 hover:text-txt-200 border-base-800')+' rounded px-1.5 py-[2px] transition-colors';
+  }
+  rDrawerActivityUpdate();
+}
+
+var fetchActivityGen=0;
+async function fetchActivity(sessionId){
+  var gen=++fetchActivityGen;
+  try{
+    var res=await fetch('api/session/'+encodeURIComponent(sessionId)+'/activity');
+    var data=await res.json();
+    if(gen!==fetchActivityGen)return;
+    drawerActivity=data.activity||[];
+    drawerSession=data.session||null;
+    rDrawerActivityUpdate();
+  }catch{if(gen!==fetchActivityGen)return;drawerActivity=[];drawerSession=null;rDrawerActivityUpdate()}
+}
+
 function applyNavCollapse(){
   const content=document.getElementById('content'),projects=document.getElementById('projects'),rail=document.getElementById('project-rail'),toggle=document.getElementById('nav-toggle'),expand=document.getElementById('nav-expand');
   content.classList.toggle('nav-collapsed',navCollapsed);
@@ -96,6 +121,7 @@ document.addEventListener('keydown',function(e){
   if(e.key==='Escape'){closeDrawer();expMsgs.clear();selCard=-1;closeShortcuts();render();return}
   if(e.key==='j'&&mm.length){e.preventDefault();selCard=Math.min(selCard+1,mm.length-1);render();return}
   if(e.key==='k'&&mm.length){e.preventDefault();selCard=Math.max(selCard-1,0);render();return}
+  if(e.key==='v'&&!e.ctrlKey&&!e.metaKey&&!e.altKey){e.preventDefault();toggleVerbose();return}
   if(e.key==='Enter'&&selCard>=0&&selCard<mm.length){e.preventDefault();openDrawer(mm[selCard].name);return}
   if(e.key>='1'&&e.key<='9'){
     var teams=allTeams(),all=[...teams.active,...teams.archived];

package/src/dashboard-js-render.ts

@@ -151,6 +151,14 @@ function openDrawer(name){
       h+='</div></div>';
     });
   }
+  // Activity timeline
+  h+='<div class="mt-4 pt-4 border-t border-base-800/50">';
+  h+='<div class="flex items-center justify-between mb-3">';
+  h+='<span class="text-txt-400 text-[10px] uppercase tracking-wider">Activity</span>';
+  h+='<button type="button" id="verbose-toggle" onclick="toggleVerbose()" aria-pressed="'+(verbose?'true':'false')+'" class="text-[10px] '+(verbose?'text-blue-400 border-blue-500/40 bg-blue-500/10':'text-txt-500 hover:text-txt-200 border-base-800')+' rounded px-1.5 py-[2px] transition-colors">verbose: '+(verbose?'on':'off')+'</button>';
+  h+='</div>';
+  h+='<div id="drawer-activity-list"><div class="text-txt-500 text-[12px]">Loading activity...</div></div>';
+  h+='</div>';
   var drawer=document.getElementById('drawer');
   drawer.innerHTML=h;
   drawer.classList.add('open');
@@ -159,6 +167,92 @@ function openDrawer(name){
   setBackgroundInert(true);
   drawer.focus();
   document.getElementById('drawer-bg').classList.add('open');
+  // Fetch activity for this agent's session
+  drawerActivity=null;drawerSession=null;
+  if(m.sessionId)fetchActivity(m.sessionId);
+  else rDrawerActivityUpdate();
+}
+
+function rDrawerActivityUpdate(){
+  var el=document.getElementById('drawer-activity-list');
+  if(!el)return;
+  if(!drawerActivity||!drawerActivity.length){
+    el.innerHTML='<div class="text-txt-500 text-[12px]">No activity recorded</div>';
+    return;
+  }
+  var html=drawerActivity.map(function(a){
+    var icon='\\u25CF',color='text-txt-500',label=a.type;
+    if(a.type==='tool_call'){icon='\\u25B8';color='text-blue-400';label=a.tool||'tool'}
+    if(a.type==='tool_result'){icon='\\u25B8';color=a.error?'text-red-400':'text-emerald-400';label=a.tool||'tool'}
+    if(a.type==='shell_command'){icon='$';color='text-amber-400';label='shell'}
+    if(a.type==='step'){icon='\\u2261';color='text-violet-400';label='step'}
+    if(a.type==='reasoning'){icon='\\u2726';color='text-violet-400';label='reasoning'}
+    if(a.type==='file'){icon='\\u25A3';color='text-cyan-400';label=a.filePath?a.filePath.split('/').pop():'file'}
+    if(a.type==='text'){icon='\\u00BB';color=a.role==='user'?'text-emerald-400':'text-blue-400';label=a.role==='user'?'prompt':'response'}
+    var ts=relT(a.timestamp);
+    if(!verbose){
+      return '<div class="flex items-center gap-2 py-1 border-b border-base-800/30">'+
+        '<span class="'+color+' text-[11px] shrink-0 font-mono">'+icon+'</span>'+
+        '<span class="text-[12px] text-txt-400 truncate flex-1">'+E(label)+'</span>'+
+        '<span class="text-[10px] text-txt-500 shrink-0">'+ts+'</span>'+
+        '</div>';
+    }
+    if(a.type==='reasoning'){
+      return '<details open class="py-2 border-b border-base-800/30">'+
+        '<summary class="flex items-center gap-2 cursor-pointer select-none hover:text-txt-100 transition-colors">'+
+        '<span class="'+color+' text-[11px] shrink-0 font-mono">'+icon+'</span>'+
+        '<span class="text-[12px] text-violet-300 font-medium">Reasoning</span>'+
+        '<span class="text-[10px] text-txt-500 ml-auto shrink-0">'+ts+'</span>'+
+        '</summary>'+
+        '<div class="mt-1.5 ml-5 text-[11px] text-violet-200/60 bg-violet-950/20 rounded-md p-2 border border-violet-800/30 overflow-x-auto whitespace-pre-wrap font-mono max-h-[200px] overflow-y-auto">'+E(a.reasoning||'')+'</div>'+
+        '</details>';
+    }
+    if(a.type==='file'){
+      var fname=a.filePath?a.filePath.split('/').pop():'file';
+      var fcontent=a.fileDiff||a.fileContent||'';
+      return '<details open class="py-2 border-b border-base-800/30">'+
+        '<summary class="flex items-center gap-2 cursor-pointer select-none hover:text-txt-100 transition-colors">'+
+        '<span class="'+color+' text-[11px] shrink-0 font-mono">'+icon+'</span>'+
+        '<span class="text-[12px] text-cyan-300 font-medium truncate flex-1">'+E(a.filePath||fname)+'</span>'+
+        '<span class="text-[10px] text-txt-500 shrink-0">'+ts+'</span>'+
+        '</summary>'+
+        (fcontent?'<div class="mt-1.5 ml-5 text-[11px] text-cyan-200/70 bg-cyan-950/20 rounded-md p-2 border border-cyan-800/30 overflow-x-auto whitespace-pre font-mono max-h-[300px] overflow-y-auto">'+E(fcontent)+'</div>':'')+
+        '</details>';
+    }
+    if(a.type==='text'){
+      return '<div class="py-2 border-b border-base-800/30">'+
+        '<div class="flex items-start gap-2">'+
+        '<span class="'+color+' text-[11px] mt-[1px] shrink-0 font-mono">'+icon+'</span>'+
+        '<div class="flex-1 min-w-0">'+
+        '<div class="text-[12px] '+(a.role==='user'?'text-emerald-300':'text-blue-300')+' font-medium">'+E(label)+'</div>'+
+        '<div class="text-[11px] text-txt-300 mt-1 md">'+md(a.text||'')+'</div>'+
+        '</div>'+
+        '<span class="text-[10px] text-txt-500 shrink-0">'+ts+'</span>'+
+        '</div></div>';
+    }
+    var title=a.title||a.tool||a.command||label;
+    var row='<div class="py-2 border-b border-base-800/30">';
+    row+='<div class="flex items-start gap-2">';
+    row+='<span class="'+color+' text-[11px] mt-[1px] shrink-0 font-mono">'+icon+'</span>';
+    row+='<div class="flex-1 min-w-0">';
+    row+='<div class="text-[12px] text-txt-200 font-medium">'+E(title)+'</div>';
+    if(a.input){row+='<div class="text-[11px] text-txt-300 mt-1.5 bg-base-900/60 rounded-md p-2 border border-base-700/40 overflow-x-auto font-mono whitespace-pre max-h-[200px] overflow-y-auto">'+E(a.input)+'</div>'}
+    if(a.output){row+='<div class="text-[11px] text-emerald-300/80 mt-1.5 bg-emerald-950/20 rounded-md p-2 border border-emerald-800/30 overflow-x-auto whitespace-pre max-h-[200px] overflow-y-auto">'+E(a.output)+'</div>'}
+    if(a.error){row+='<div class="text-[11px] text-red-400 mt-1.5 bg-red-950/20 rounded-md p-2 border border-red-800/30 overflow-x-auto">'+E(a.error)+'</div>'}
+    if(a.command){row+='<div class="text-[11px] text-amber-300 mt-1.5 bg-amber-950/20 rounded-md p-2 border border-amber-800/30 overflow-x-auto font-mono whitespace-pre">'+E(a.command)+'</div>'}
+    if(a.exitCode!==undefined||a.cost||a.tokensIn||a.tokensOut){
+      row+='<div class="flex flex-wrap gap-1.5 mt-1.5">';
+      if(a.exitCode!==undefined){row+=chip('exit: '+a.exitCode,'muted')}
+      if(a.cost){row+=chip('$'+a.cost.toFixed(4),'gray')}
+      if(a.tokensIn||a.tokensOut){row+=chip((a.tokensIn||0)+' in / '+(a.tokensOut||0)+' out','muted')}
+      row+='</div>';
+    }
+    row+='</div>';
+    row+='<span class="text-[10px] text-txt-500 shrink-0">'+ts+'</span>';
+    row+='</div></div>';
+    return row;
+  }).join('');
+  el.innerHTML=html;
 }
 
 function closeDrawer(){

package/src/dashboard.ts

@@ -6,6 +6,8 @@ import { DASHBOARD_JS_CORE } from "./dashboard-js-core"
 import { DASHBOARD_JS_EVENTS } from "./dashboard-js-events"
 import { DASHBOARD_JS_RENDER } from "./dashboard-js-render"
 import { log } from "./log"
+import type { ActivityBuffer, ActivityEntry } from "./activity"
+import type { PluginClient } from "./types"
 
 /** Assemble the full dashboard HTML from parts. */
 const DASHBOARD_HTML = DASHBOARD_HEAD + "\n<script>" + DASHBOARD_JS_CORE + DASHBOARD_JS_RENDER + DASHBOARD_JS_EVENTS + "<\/script>\n</body></html>"
@@ -34,6 +36,7 @@ interface MemberRow {
   agent: string
   status: string
   execution_status: string
+  session_id: string
   worktree_branch: string | null
   prompt: string | null
   model: string | null
@@ -81,7 +84,7 @@ function parseDependsOn(value: string | null): string[] {
 function buildState(db: Database): { projects: unknown[]; teams: unknown[] } {
   const projects = db.query("SELECT id, name, path, status, time_created, time_updated FROM project ORDER BY time_updated DESC").all() as ProjectRow[]
   const teams = db.query("SELECT id, name, project_id, status, lead_agent, time_created, time_updated FROM team ORDER BY time_created DESC").all() as TeamRow[]
-  const memberStmt = db.query("SELECT name, agent, status, execution_status, worktree_branch, prompt, model, plan_approval, time_created, time_updated FROM team_member WHERE team_id = ?")
+  const memberStmt = db.query("SELECT name, agent, status, execution_status, session_id, worktree_branch, prompt, model, plan_approval, time_created, time_updated FROM team_member WHERE team_id = ?")
   const taskStmt = db.query("SELECT id, content, status, priority, assignee, depends_on, time_created, time_updated FROM team_task WHERE team_id = ?")
   const msgStmt = db.query("SELECT id, from_name, to_name, content, delivered, read, time_created FROM team_message WHERE team_id = ? ORDER BY time_created DESC LIMIT 50")
 
@@ -91,6 +94,7 @@ function buildState(db: Database): { projects: unknown[]; teams: unknown[] } {
       agent: m.agent,
       status: m.status,
       executionStatus: m.execution_status,
+      sessionId: m.session_id,
       worktreeBranch: m.worktree_branch,
       prompt: m.prompt,
       model: m.model,
@@ -163,6 +167,14 @@ export interface DashboardServer {
   stop(force?: boolean): void
 }
 
+/** Optional dependencies for the dashboard server. */
+export interface DashboardOptions {
+  /** In-memory activity buffer for real-time per-session events. */
+  activityBuffer?: ActivityBuffer
+  /** SDK client for on-demand session message retrieval. */
+  client?: PluginClient
+}
+
 function sendJson(res: ServerResponse, data: unknown): void {
   res.writeHead(200, {
     "Content-Type": "application/json",
@@ -171,7 +183,101 @@ function sendJson(res: ServerResponse, data: unknown): void {
   res.end(JSON.stringify(data))
 }
 
-function handleDashboardRequest(db: Database, port: number, req: IncomingMessage, res: ServerResponse): void {
+/** Parse SDK message parts into ActivityEntry format for the fallback path. */
+export function parseMessageParts(parts: unknown[], msgInfo: unknown): ActivityEntry[] {
+  const entries: ActivityEntry[] = []
+  const info = (msgInfo ?? {}) as { time?: string; role?: string; tokens?: { input?: number; output?: number } }
+  const timestamp = info.time ? new Date(info.time).getTime() : Date.now()
+
+  for (const part of parts) {
+    if (typeof part !== "object" || part === null) continue
+    const p = part as {
+      type?: string
+      tool?: string
+      state?: { status?: string; input?: unknown; output?: unknown; error?: string; title?: string }
+      text?: string
+      path?: string
+      content?: string
+      diff?: string
+      label?: string
+      step?: string
+    }
+
+    if (p.type === "tool" && p.tool) {
+      const state = p.state ?? {}
+      const inputStr = typeof state.input === "string" ? state.input : state.input != null ? JSON.stringify(state.input, null, 2) : undefined
+      const outputStr = typeof state.output === "string" ? state.output : state.output != null ? JSON.stringify(state.output, null, 2) : undefined
+      entries.push({
+        type: state.status === "completed" ? "tool_result" : "tool_call",
+        tool: p.tool,
+        title: state.title,
+        input: inputStr,
+        output: outputStr,
+        error: state.error,
+        timestamp,
+      })
+    } else if (p.type === "reasoning" && p.text) {
+      entries.push({ type: "reasoning", reasoning: p.text, timestamp })
+    } else if (p.type === "file" && (p.path || p.content || p.diff)) {
+      entries.push({
+        type: "file",
+        filePath: p.path,
+        fileContent: p.content,
+        fileDiff: p.diff,
+        timestamp,
+      })
+    } else if (p.type === "text" && p.text) {
+      entries.push({ type: "text", text: p.text, role: info.role, timestamp })
+    } else if (p.type === "step-start") {
+      entries.push({ type: "step", title: p.label ?? p.step ?? "step", timestamp })
+    } else if (p.type === "step-finish") {
+      entries.push({ type: "step", title: p.label ?? p.step ?? "step complete", timestamp })
+    }
+  }
+  return entries
+}
+
+/** Handle the /api/session/:sessionId/activity endpoint. */
+async function handleActivityRoute(
+  sessionId: string,
+  options: DashboardOptions | undefined,
+  res: ServerResponse,
+): Promise<void> {
+  const buffer = options?.activityBuffer
+  const client = options?.client
+
+  const buffered = buffer?.getActivity(sessionId) ?? []
+
+  let sessionData: unknown = null
+  let fallbackActivity: ActivityEntry[] = []
+
+  if (client) {
+    try {
+      const [msgResult, getResult] = await Promise.all([
+        client.session.messages({ sessionID: sessionId, limit: 100 }),
+        client.session.get({ sessionID: sessionId }),
+      ])
+      const messages = msgResult.data ?? []
+      for (const msg of messages) {
+        const parts = msg.parts ?? []
+        fallbackActivity.push(...parseMessageParts(parts, msg.info))
+      }
+      sessionData = getResult.data ?? null
+    } catch { /* best effort — return what we have */ }
+  }
+
+  const combined = [...buffered, ...fallbackActivity].sort((a, b) => a.timestamp - b.timestamp)
+
+  sendJson(res, { activity: combined, session: sessionData })
+}
+
+function handleDashboardRequest(
+  db: Database,
+  port: number,
+  req: IncomingMessage,
+  res: ServerResponse,
+  options?: DashboardOptions,
+): void {
   const url = new URL(req.url ?? "/", `http://${req.headers.host ?? `localhost:${port}`}`)
 
   if (url.pathname === "/api/health") {
@@ -184,6 +290,18 @@ function handleDashboardRequest(db: Database, port: number, req: IncomingMessage
     return
   }
 
+  const activityMatch = url.pathname.match(/^\/api\/session\/([^/]+)\/activity$/)
+  if (activityMatch) {
+    const sessionId = decodeURIComponent(activityMatch[1]!)
+    handleActivityRoute(sessionId, options, res).catch(() => {
+      if (!res.headersSent) {
+        res.writeHead(500, { "Content-Type": "application/json" })
+        res.end(JSON.stringify({ error: "Failed to fetch activity" }))
+      }
+    })
+    return
+  }
+
   if (url.pathname === "/") {
     res.writeHead(200, { "Content-Type": "text/html" })
     res.end(DASHBOARD_HTML)
@@ -212,13 +330,13 @@ function toDashboardServer(server: Server): DashboardServer {
 
 /**
  * Start the dashboard HTTP server.
- * Serves a JSON API for team state and the dashboard HTML.
+ * Serves a JSON API for team state, session activity, and the dashboard HTML.
  * Singleton: if the port is already in use by another ensemble instance, skips silently.
  * Returns the server instance, or null if skipped.
  */
-export async function startDashboard(db: Database, port: number): Promise<DashboardServer | null> {
+export async function startDashboard(db: Database, port: number, options?: DashboardOptions): Promise<DashboardServer | null> {
   return new Promise((resolve) => {
-    const server = createServer((req, res) => handleDashboardRequest(db, port, req, res))
+    const server = createServer((req, res) => handleDashboardRequest(db, port, req, res, options))
 
     server.once("error", async (err: NodeJS.ErrnoException) => {
       if (err.code === "EADDRINUSE") {