feat: add session metadata linking to establish foreign key relationship (#249)

Establish a proper foreign key relationship between OpenCode sessions and workflow state instead of relying on file modification times.

Changes:
- Add SessionMetadata interface to core types with referenceId and createdAt
- Extend ConversationState with optional sessionMetadata field
- Extend ServerContext to include sessionMetadata property
- Add setSessionMetadata/getSessionMetadata methods to ConversationManager
- Update ConversationManager to store sessionMetadata when creating new conversation states
- Pass sessionMetadata from OpenCode plugin to ServerContext at initialization
- Capture OpenCode sessionID in chat.message hook for use in subsequent operations
- Implement sessionId-based lookup in TUI plugin (readStateBySessionId)
- Keep mtime-based fallback in TUI plugin for backward compatibility
- Export SessionMetadata type from mcp-server for external use

This enables the TUI plugin to correctly display the active phase of the current OpenCode session instead of always showing the most recently modified workflow's phase.

Author: mrsimpson

.gitignore

@@ -139,5 +139,8 @@ dist
 # Mac
 .DS_Store
 **/.DS_Store
+
+# Generated resources by build scripts
 packages/mcp-server/resources
 packages/cli/resources
+packages/opencode-plugin/resources

packages/core/src/conversation-manager.ts

@@ -12,7 +12,11 @@ import { existsSync } from 'node:fs';
 import { createLogger } from './logger.js';
 import { getPathBasename } from './path-validation-utils.js';
 import type { IPersistence } from './persistence-interface.js';
-import type { ConversationState, ConversationContext } from './types.js';
+import type {
+  ConversationState,
+  ConversationContext,
+  SessionMetadata,
+} from './types.js';
 import { WorkflowManager } from './workflow-manager.js';
 import { PlanManager } from './plan-manager.js';
 
@@ -22,6 +26,7 @@ export class ConversationManager {
   private database: IPersistence;
   private projectPath: string;
   private workflowManager: WorkflowManager;
+  private currentSessionMetadata: SessionMetadata | null = null;
 
   constructor(
     database: IPersistence,
@@ -33,6 +38,26 @@ export class ConversationManager {
     this.projectPath = projectPath;
   }
 
+  /**
+   * Set session metadata for subsequent conversation state operations.
+   * This links the workflow state to an external session context.
+   *
+   * @param sessionMetadata - Session metadata to store with conversation state
+   */
+  setSessionMetadata(sessionMetadata: SessionMetadata): void {
+    this.currentSessionMetadata = sessionMetadata;
+    logger.debug('Session metadata set', {
+      referenceId: sessionMetadata.referenceId,
+    });
+  }
+
+  /**
+   * Get current session metadata
+   */
+  getSessionMetadata(): SessionMetadata | null {
+    return this.currentSessionMetadata;
+  }
+
   /**
    * Get conversation state by ID
    */
@@ -256,6 +281,9 @@ export class ConversationManager {
       requireReviewsBeforePhaseTransition: false, // Default to false for new conversations
       createdAt: timestamp,
       updatedAt: timestamp,
+      ...(this.currentSessionMetadata && {
+        sessionMetadata: this.currentSessionMetadata,
+      }),
     };
 
     // Save to database

packages/core/src/types.ts

@@ -2,6 +2,14 @@
  * Common types used across the application
  */
 
+/**
+ * Session metadata linking workflow state to an external session/context
+ */
+export interface SessionMetadata {
+  referenceId: string;
+  createdAt: string;
+}
+
 /**
  * Interface for interaction log entries
  */
@@ -42,6 +50,7 @@ export interface ConversationState {
   requireReviewsBeforePhaseTransition: boolean;
   createdAt: string;
   updatedAt: string;
+  sessionMetadata?: SessionMetadata;
 }
 
 /**

packages/mcp-server/src/index.ts

@@ -20,7 +20,7 @@ export {
 export * from './tool-handlers/index.js';
 
 // Re-export types needed by external consumers
-export type { ServerContext, HandlerResult } from './types.js';
+export type { ServerContext, HandlerResult, SessionMetadata } from './types.js';
 
 // Re-export plugin system for external use (e.g., OpenCode plugin)
 export { PluginRegistry } from './plugin-system/index.js';

packages/mcp-server/src/types.ts

@@ -11,6 +11,14 @@ import { InteractionLogger } from '@codemcp/workflows-core';
 import type { TaskBackendConfig, LoggerFactory } from '@codemcp/workflows-core';
 import type { IPluginRegistry } from './plugin-system/plugin-interfaces.js';
 
+/**
+ * Session metadata linking workflow state to an external session/context
+ */
+export interface SessionMetadata {
+  referenceId: string;
+  createdAt: string;
+}
+
 /**
  * Server context shared across all handlers
  * Contains all the core dependencies needed by tool and resource handlers
@@ -26,6 +34,8 @@ export interface ServerContext {
   pluginRegistry?: IPluginRegistry;
   /** Logger factory for creating component loggers - if not provided, handlers use global createLogger */
   loggerFactory?: LoggerFactory;
+  /** Session metadata linking workflow state to external session context */
+  sessionMetadata?: SessionMetadata;
 }
 
 /**

packages/opencode-plugin/src/plugin.ts

@@ -129,6 +129,7 @@ export const WorkflowsPlugin: Plugin = async (
     ReturnType<typeof createServerContext>
   > | null = null;
   let serverContextInitialized = false;
+  let currentSessionId: string | null = null;
 
   // Buffered instructions from tools (proceed_to_phase, start_development).
   // Consumed and cleared by the next chat.message hook call.
@@ -151,12 +152,27 @@ export const WorkflowsPlugin: Plugin = async (
   // Creates once, reuses for all subsequent calls
   async function getServerContext() {
     if (!cachedServerContext) {
+      const sessionMetadata = currentSessionId
+        ? {
+            referenceId: currentSessionId,
+            createdAt: new Date().toISOString(),
+          }
+        : undefined;
+
       cachedServerContext = createServerContext({
         projectDir: input.directory,
         planManager,
         instructionGenerator,
         loggerFactory,
+        sessionMetadata,
       });
+
+      // Set session metadata in the conversation manager for new conversations
+      if (sessionMetadata) {
+        cachedServerContext.conversationManager.setSessionMetadata(
+          sessionMetadata
+        );
+      }
     }
 
     if (!serverContextInitialized) {
@@ -218,6 +234,12 @@ export const WorkflowsPlugin: Plugin = async (
      * We add a synthetic part with phase instructions.
      */
     'chat.message': async (hookInput, output) => {
+      // Capture session ID from the first hook that has it
+      if (hookInput.sessionID && !currentSessionId) {
+        currentSessionId = hookInput.sessionID;
+        logger.debug('Captured session ID', { sessionId: currentSessionId });
+      }
+
       // Skip if workflows are disabled
       if (!workflowsEnabled) {
         logger.debug('chat.message: Workflows disabled, skipping hook');

packages/opencode-plugin/src/server-context.ts

@@ -20,6 +20,7 @@ import {
   type IInstructionGenerator,
   type LoggerFactory,
 } from '@codemcp/workflows-core';
+import type { SessionMetadata } from '@codemcp/workflows-server';
 import * as path from 'node:path';
 
 export interface ServerContextOptions {
@@ -28,6 +29,8 @@ export interface ServerContextOptions {
   instructionGenerator: IInstructionGenerator;
   /** Optional logger factory - if provided, handlers will use this instead of global createLogger */
   loggerFactory?: LoggerFactory;
+  /** Optional session metadata to link workflow state to external context */
+  sessionMetadata?: SessionMetadata;
 }
 
 /**
@@ -39,8 +42,13 @@ export interface ServerContextOptions {
 export function createServerContext(
   options: ServerContextOptions
 ): ServerContext {
-  const { projectDir, planManager, instructionGenerator, loggerFactory } =
-    options;
+  const {
+    projectDir,
+    planManager,
+    instructionGenerator,
+    loggerFactory,
+    sessionMetadata,
+  } = options;
 
   // Create workflow manager and load project workflows
   const workflowManager = new WorkflowManager();
@@ -84,6 +92,7 @@ export function createServerContext(
     projectPath: projectDir,
     pluginRegistry,
     loggerFactory,
+    sessionMetadata,
   };
 }
 

packages/opencode-tui-plugin/workflows-phase.tsx

@@ -29,6 +29,10 @@ const WORKFLOW_TOOLS = new Set([
 interface StateJson {
   currentPhase?: string;
   workflowName?: string;
+  sessionMetadata?: {
+    referenceId: string;
+    createdAt: string;
+  };
 }
 
 interface MessagePartUpdatedEvent {
@@ -41,6 +45,52 @@ interface MessagePartUpdatedEvent {
   };
 }
 
+function readStateBySessionId(
+  sessionDir: string,
+  sessionId: string
+): { phase: string; workflow: string } | null {
+  try {
+    // require() is intentional: top-level ESM imports of Node built-ins are not
+    // supported in the Bun plugin runtime.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const fsSync = require('node:fs') as typeof fs;
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const pathSync = require('node:path') as typeof path;
+    const vibeDir = pathSync.join(sessionDir, '.vibe', 'conversations');
+    const dirs = fsSync.readdirSync(vibeDir);
+
+    // Search for the state file that matches this session ID
+    for (const dir of dirs) {
+      const file = pathSync.join(vibeDir, dir, 'state.json');
+      try {
+        const state = JSON.parse(
+          fsSync.readFileSync(file, 'utf8')
+        ) as StateJson;
+
+        // Check if this state's sessionMetadata matches the current session ID
+        if (state.sessionMetadata?.referenceId === sessionId) {
+          if (!state.currentPhase && !state.workflowName) return null;
+          return {
+            phase: state.currentPhase ?? '—',
+            workflow: state.workflowName ?? '—',
+          };
+        }
+      } catch {
+        // unreadable entry — skip silently
+      }
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fallback: Read the most recently modified state.
+ * Used when no matching session ID is found or for backward compatibility.
+ * This is deprecated in favor of sessionId-based lookup.
+ */
 function readLatestState(
   sessionDir: string
 ): { phase: string; workflow: string } | null {
@@ -95,7 +145,9 @@ const tui: TuiPlugin = async api => {
         // not only after the first tool call.
         const dir = api.state.path.directory;
         if (dir) {
-          setState(readLatestState(dir));
+          // Try session ID-based lookup first, fall back to most recent state
+          const stateBySession = readStateBySessionId(dir, props.session_id);
+          setState(stateBySession || readLatestState(dir));
         }
 
         const offPart = api.event.on('message.part.updated', e => {
@@ -106,7 +158,9 @@ const tui: TuiPlugin = async api => {
           if (part.type !== 'tool') return;
           if (!part.tool || !WORKFLOW_TOOLS.has(part.tool)) return;
           if (!dir) return;
-          setState(readLatestState(dir));
+          // Use session ID-based lookup to get the correct state for this session
+          const stateBySession = readStateBySessionId(dir, props.session_id);
+          setState(stateBySession || readLatestState(dir));
         });
         onCleanup(offPart);