@agentmeshhq/agent 0.1.6 → 0.1.8

package/src/context/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Context Module
+ * Agent context persistence for cross-session state management
+ */
+
+export * from "./handoff.js";
+export * from "./schema.js";
+export * from "./storage.js";

package/src/context/schema.ts

@@ -0,0 +1,111 @@
+/**
+ * Agent Context Schema
+ * Defines the structure for persisting agent context across sessions
+ */
+
+export const CONTEXT_VERSION = 1;
+export const CONTEXT_DIR = `${process.env.HOME}/.agentmesh/context`;
+
+/**
+ * Summary of conversation history for context restoration
+ */
+export interface ConversationSummary {
+  /** Total messages in the conversation */
+  messageCount: number;
+  /** Key topics discussed */
+  topics: string[];
+  /** Summary of what was accomplished */
+  accomplishments: string[];
+  /** Last 5 user messages (truncated) */
+  recentMessages: Array<{
+    role: "user" | "assistant";
+    content: string;
+    timestamp: string;
+  }>;
+}
+
+/**
+ * Current working state of the agent
+ */
+export interface WorkingState {
+  /** Current working directory */
+  workdir: string;
+  /** Recently accessed files */
+  recentFiles: string[];
+  /** Open file paths being edited */
+  openFiles: string[];
+  /** Git branch if in a repo */
+  gitBranch?: string;
+  /** Git status summary */
+  gitStatus?: string;
+}
+
+/**
+ * In-progress task state from TodoWrite
+ */
+export interface TaskState {
+  /** Active tasks */
+  tasks: Array<{
+    content: string;
+    status: "pending" | "in_progress" | "completed" | "cancelled";
+    priority: "high" | "medium" | "low";
+  }>;
+  /** Overall goal being worked on */
+  currentGoal?: string;
+}
+
+/**
+ * Custom key-value store for agent-specific context
+ */
+export interface CustomContext {
+  [key: string]: unknown;
+}
+
+/**
+ * Full agent context structure
+ */
+export interface AgentContext {
+  /** Schema version for migration support */
+  version: number;
+  /** Agent ID this context belongs to */
+  agentId: string;
+  /** Agent name */
+  agentName: string;
+  /** When this context was last saved */
+  savedAt: string;
+  /** Conversation summary */
+  conversation: ConversationSummary;
+  /** Current working state */
+  workingState: WorkingState;
+  /** Task state */
+  tasks: TaskState;
+  /** Custom context data */
+  custom: CustomContext;
+}
+
+/**
+ * Creates an empty context for a new agent
+ */
+export function createEmptyContext(agentId: string, agentName: string): AgentContext {
+  return {
+    version: CONTEXT_VERSION,
+    agentId,
+    agentName,
+    savedAt: new Date().toISOString(),
+    conversation: {
+      messageCount: 0,
+      topics: [],
+      accomplishments: [],
+      recentMessages: [],
+    },
+    workingState: {
+      workdir: process.cwd(),
+      recentFiles: [],
+      openFiles: [],
+    },
+    tasks: {
+      tasks: [],
+    },
+    custom: {},
+  };
+}

package/src/context/storage.ts

@@ -0,0 +1,197 @@
+/**
+ * Context Storage Module
+ * Handles saving and loading agent context to/from disk
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { type AgentContext, CONTEXT_DIR, CONTEXT_VERSION, createEmptyContext } from "./schema.js";
+
+/**
+ * Ensures the context directory exists
+ */
+export function ensureContextDir(): void {
+  if (!fs.existsSync(CONTEXT_DIR)) {
+    fs.mkdirSync(CONTEXT_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Gets the context file path for an agent
+ */
+export function getContextPath(agentId: string): string {
+  return path.join(CONTEXT_DIR, `${agentId}.json`);
+}
+
+/**
+ * Saves agent context to disk
+ */
+export function saveContext(context: AgentContext): void {
+  ensureContextDir();
+  const contextPath = getContextPath(context.agentId);
+
+  // Update savedAt timestamp
+  context.savedAt = new Date().toISOString();
+
+  fs.writeFileSync(contextPath, JSON.stringify(context, null, 2));
+}
+
+/**
+ * Loads agent context from disk
+ * Returns null if context doesn't exist or is invalid
+ */
+export function loadContext(agentId: string): AgentContext | null {
+  const contextPath = getContextPath(agentId);
+
+  try {
+    if (!fs.existsSync(contextPath)) {
+      return null;
+    }
+
+    const content = fs.readFileSync(contextPath, "utf-8");
+    const context = JSON.parse(content) as AgentContext;
+
+    // Validate version
+    if (context.version !== CONTEXT_VERSION) {
+      // In the future, we can migrate old versions here
+      console.warn(`Context version mismatch: expected ${CONTEXT_VERSION}, got ${context.version}`);
+      return null;
+    }
+
+    return context;
+  } catch (error) {
+    console.error(`Failed to load context for agent ${agentId}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Loads context or creates a new empty one
+ */
+export function loadOrCreateContext(agentId: string, agentName: string): AgentContext {
+  const existing = loadContext(agentId);
+  if (existing) {
+    return existing;
+  }
+  return createEmptyContext(agentId, agentName);
+}
+
+/**
+ * Deletes agent context from disk
+ */
+export function deleteContext(agentId: string): boolean {
+  const contextPath = getContextPath(agentId);
+
+  try {
+    if (fs.existsSync(contextPath)) {
+      fs.unlinkSync(contextPath);
+      return true;
+    }
+    return false;
+  } catch (error) {
+    console.error(`Failed to delete context for agent ${agentId}:`, error);
+    return false;
+  }
+}
+
+/**
+ * Lists all saved context files
+ */
+export function listContexts(): Array<{ agentId: string; savedAt: string }> {
+  ensureContextDir();
+
+  try {
+    const files = fs.readdirSync(CONTEXT_DIR);
+    const contexts: Array<{ agentId: string; savedAt: string }> = [];
+
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+
+      const agentId = file.replace(".json", "");
+      const context = loadContext(agentId);
+      if (context) {
+        contexts.push({
+          agentId,
+          savedAt: context.savedAt,
+        });
+      }
+    }
+
+    return contexts.sort((a, b) => new Date(b.savedAt).getTime() - new Date(a.savedAt).getTime());
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Updates specific fields in the context
+ */
+export function updateContext(
+  agentId: string,
+  updates: Partial<Omit<AgentContext, "version" | "agentId" | "savedAt">>,
+): AgentContext | null {
+  const context = loadContext(agentId);
+  if (!context) {
+    return null;
+  }
+
+  const updated: AgentContext = {
+    ...context,
+    ...updates,
+    // Preserve these fields
+    version: CONTEXT_VERSION,
+    agentId: context.agentId,
+    savedAt: new Date().toISOString(),
+  };
+
+  saveContext(updated);
+  return updated;
+}
+
+/**
+ * Exports context to a specified file path
+ */
+export function exportContext(agentId: string, outputPath: string): boolean {
+  const context = loadContext(agentId);
+  if (!context) {
+    return false;
+  }
+
+  try {
+    fs.writeFileSync(outputPath, JSON.stringify(context, null, 2));
+    return true;
+  } catch (error) {
+    console.error(`Failed to export context:`, error);
+    return false;
+  }
+}
+
+/**
+ * Imports context from a file path
+ */
+export function importContext(inputPath: string): AgentContext | null {
+  try {
+    if (!fs.existsSync(inputPath)) {
+      console.error(`File not found: ${inputPath}`);
+      return null;
+    }
+
+    const content = fs.readFileSync(inputPath, "utf-8");
+    const context = JSON.parse(content) as AgentContext;
+
+    // Validate required fields
+    if (!context.agentId || !context.agentName) {
+      console.error("Invalid context file: missing agentId or agentName");
+      return null;
+    }
+
+    // Update version and save
+    context.version = CONTEXT_VERSION;
+    saveContext(context);
+
+    return context;
+  } catch (error) {
+    console.error(`Failed to import context:`, error);
+    return null;
+  }
+}

package/src/core/daemon.ts

@@ -6,10 +6,12 @@ import {
   updateAgentInState,
 } from "../config/loader.js";
 import type { AgentConfig, Config } from "../config/schema.js";
+import { loadContext, loadOrCreateContext, saveContext } from "../context/index.js";
 import { Heartbeat } from "./heartbeat.js";
-import { handleWebSocketEvent, injectStartupMessage } from "./injector.js";
+import { handleWebSocketEvent, injectRestoredContext, injectStartupMessage } from "./injector.js";
 import { checkInbox, registerAgent } from "./registry.js";
 import {
+  captureSessionContext,
   createSession,
   destroySession,
   getSessionName,
@@ -24,6 +26,8 @@ export interface DaemonOptions {
   workdir?: string;
   model?: string;
   daemonize?: boolean;
+  /** Whether to restore context from previous session (default: true) */
+  restoreContext?: boolean;
 }
 
 export class AgentDaemon {
@@ -35,6 +39,7 @@ export class AgentDaemon {
   private token: string | null = null;
   private agentId: string | null = null;
   private isRunning = false;
+  private shouldRestoreContext: boolean;
 
   constructor(options: DaemonOptions) {
     const config = loadConfig();
@@ -44,6 +49,7 @@ export class AgentDaemon {
 
     this.config = config;
     this.agentName = options.name;
+    this.shouldRestoreContext = options.restoreContext !== false;
 
     // Find or create agent config
     let agentConfig = config.agents.find((a) => a.name === options.name);
@@ -141,6 +147,11 @@ export class AgentDaemon {
       onError: (error) => {
         console.error("Heartbeat error:", error.message);
       },
+      onContextSave: () => {
+        // Periodically save context (every 5 heartbeats = ~2.5 minutes)
+        this.saveAgentContext();
+      },
+      contextSaveFrequency: 5,
       onTokenRefresh: (newToken) => {
         this.token = newToken;
         // Update state file
@@ -210,6 +221,18 @@ export class AgentDaemon {
       injectStartupMessage(this.agentName, 0);
     }
 
+    // Restore context from previous session
+    if (this.shouldRestoreContext && this.agentId) {
+      console.log("Checking for previous context...");
+      const savedContext = loadContext(this.agentId);
+      if (savedContext) {
+        console.log(`Restoring context from ${savedContext.savedAt}`);
+        // Wait a moment for the session to be ready
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        injectRestoredContext(this.agentName, savedContext);
+      }
+    }
+
     this.isRunning = true;
 
     console.log(`
@@ -235,6 +258,12 @@ Nudge agent:
 
     this.isRunning = false;
 
+    // Save context before stopping
+    if (this.agentId) {
+      console.log("Saving agent context...");
+      this.saveAgentContext();
+    }
+
     // Stop heartbeat
     if (this.heartbeat) {
       this.heartbeat.stop();
@@ -256,4 +285,33 @@ Nudge agent:
     console.log("Agent stopped.");
     process.exit(0);
   }
+
+  /**
+   * Saves the current agent context to disk
+   */
+  private saveAgentContext(): void {
+    if (!this.agentId) return;
+
+    try {
+      // Load existing context or create new
+      const context = loadOrCreateContext(this.agentId, this.agentName);
+
+      // Capture current session state
+      const sessionContext = captureSessionContext(this.agentName);
+      if (sessionContext) {
+        context.workingState = {
+          ...context.workingState,
+          workdir: sessionContext.workdir,
+          gitBranch: sessionContext.gitBranch,
+          gitStatus: sessionContext.gitStatus,
+        };
+      }
+
+      // Save updated context
+      saveContext(context);
+      console.log(`Context saved for agent ${this.agentName}`);
+    } catch (error) {
+      console.error("Failed to save agent context:", error);
+    }
+  }
 }

package/src/core/heartbeat.ts

@@ -13,16 +13,23 @@ export interface HeartbeatConfig {
   workspace: string;
   onError?: (error: Error) => void;
   onTokenRefresh?: (newToken: string) => void;
+  /** Called periodically to save agent context (every N heartbeats) */
+  onContextSave?: () => void;
+  /** How many heartbeats between context saves (default: 5) */
+  contextSaveFrequency?: number;
 }
 
 export class Heartbeat {
   private config: HeartbeatConfig;
   private currentToken: string;
   private intervalId: NodeJS.Timeout | null = null;
+  private heartbeatCount = 0;
+  private contextSaveFrequency: number;
 
   constructor(config: HeartbeatConfig) {
     this.config = config;
     this.currentToken = config.token;
+    this.contextSaveFrequency = config.contextSaveFrequency ?? 5;
   }
 
   start(): void {
@@ -78,6 +85,12 @@ export class Heartbeat {
         }
         throw new Error(`Heartbeat failed: ${response.status}`);
       }
+
+      // Periodically save context
+      this.heartbeatCount++;
+      if (this.config.onContextSave && this.heartbeatCount % this.contextSaveFrequency === 0) {
+        this.config.onContextSave();
+      }
     } catch (error) {
       this.config.onError?.(error as Error);
     }

package/src/core/injector.ts

@@ -1,11 +1,10 @@
-import { sendKeys } from "./tmux.js";
+import { formatHandoffContextSummary, parseHandoffContext } from "../context/handoff.js";
+import type { AgentContext } from "../context/schema.js";
 import type { InboxItem } from "./registry.js";
+import { sendKeys } from "./tmux.js";
 import type { WebSocketEvent } from "./websocket.js";
 
-export function injectStartupMessage(
-  agentName: string,
-  pendingCount: number
-): void {
+export function injectStartupMessage(agentName: string, pendingCount: number): void {
   if (pendingCount === 0) {
     const message = `[AgentMesh] Connected and ready. No pending items in inbox.`;
     sendKeys(agentName, message);
@@ -18,10 +17,7 @@ Use agentmesh_check_inbox to see them, or agentmesh_accept_handoff to start work
   sendKeys(agentName, message);
 }
 
-export function injectHandoffReceived(
-  agentName: string,
-  event: WebSocketEvent
-): void {
+export function injectHandoffReceived(agentName: string, event: WebSocketEvent): void {
   const fromName =
     (event.from_agent as { display_name?: string })?.display_name ||
     (event.from_agent_id as string) ||
@@ -41,14 +37,9 @@ Accept this handoff and begin work.`;
   sendKeys(agentName, message);
 }
 
-export function injectNudge(
-  agentName: string,
-  event: WebSocketEvent
-): void {
+export function injectNudge(agentName: string, event: WebSocketEvent): void {
   const fromName =
-    (event.from as { name?: string })?.name ||
-    (event.from_name as string) ||
-    "Someone";
+    (event.from as { name?: string })?.name || (event.from_name as string) || "Someone";
   const message = (event.message as string) || "Check your inbox";
 
   const formatted = `[AgentMesh] Nudge from ${fromName}:
@@ -57,12 +48,8 @@ ${message}`;
   sendKeys(agentName, formatted);
 }
 
-export function injectBlockerResolved(
-  agentName: string,
-  event: WebSocketEvent
-): void {
-  const description =
-    (event.description as string) || "A blocker has been resolved";
+export function injectBlockerResolved(agentName: string, event: WebSocketEvent): void {
+  const description = (event.description as string) || "A blocker has been resolved";
   const resolvedBy =
     (event.resolved_by as { display_name?: string })?.display_name ||
     (event.resolved_by_name as string) ||
@@ -78,10 +65,7 @@ You can now proceed with your work.`;
   sendKeys(agentName, message);
 }
 
-export function injectInboxItems(
-  agentName: string,
-  items: InboxItem[]
-): void {
+export function injectInboxItems(agentName: string, items: InboxItem[]): void {
   if (items.length === 0) {
     sendKeys(agentName, "[AgentMesh] Your inbox is empty.");
     return;
@@ -101,10 +85,7 @@ export function injectInboxItems(
   sendKeys(agentName, message);
 }
 
-export function handleWebSocketEvent(
-  agentName: string,
-  event: WebSocketEvent
-): void {
+export function handleWebSocketEvent(agentName: string, event: WebSocketEvent): void {
   switch (event.type) {
     case "handoff_received":
     case "handoff.received":
@@ -126,3 +107,66 @@ export function handleWebSocketEvent(
       break;
   }
 }
+
+/**
+ * Injects restored context from a previous session
+ */
+export function injectRestoredContext(agentName: string, context: AgentContext): void {
+  const parts: string[] = ["[AgentMesh] Restored context from previous session:"];
+
+  // Working state
+  if (context.workingState.workdir) {
+    parts.push(`Working directory: ${context.workingState.workdir}`);
+  }
+  if (context.workingState.gitBranch) {
+    parts.push(`Git branch: ${context.workingState.gitBranch}`);
+  }
+
+  // Tasks
+  const activeTasks = context.tasks.tasks.filter(
+    (t) => t.status === "in_progress" || t.status === "pending",
+  );
+  if (activeTasks.length > 0) {
+    parts.push("");
+    parts.push("Active tasks:");
+    for (const task of activeTasks.slice(0, 5)) {
+      const statusIcon = task.status === "in_progress" ? ">" : "-";
+      parts.push(`  ${statusIcon} ${task.content}`);
+    }
+    if (activeTasks.length > 5) {
+      parts.push(`  ... and ${activeTasks.length - 5} more`);
+    }
+  }
+
+  // Current goal
+  if (context.tasks.currentGoal) {
+    parts.push("");
+    parts.push(`Goal: ${context.tasks.currentGoal}`);
+  }
+
+  // Accomplishments
+  if (context.conversation.accomplishments.length > 0) {
+    parts.push("");
+    parts.push("Recent accomplishments:");
+    for (const acc of context.conversation.accomplishments.slice(0, 3)) {
+      parts.push(`  - ${acc}`);
+    }
+  }
+
+  const message = parts.join("\n");
+  sendKeys(agentName, message);
+}
+
+/**
+ * Injects context received from a handoff
+ */
+export function injectHandoffContext(agentName: string, contextString: string): void {
+  const context = parseHandoffContext(contextString);
+  if (!context) {
+    return;
+  }
+
+  const summary = formatHandoffContextSummary(context);
+  const message = `[AgentMesh] Context from previous agent:\n\n${summary}`;
+  sendKeys(agentName, message);
+}

package/src/core/tmux.ts

@@ -176,3 +176,78 @@ export function getSessionInfo(agentName: string): { exists: boolean; command?:
     return { exists: true };
   }
 }
+
+export interface SessionContext {
+  workdir: string;
+  gitBranch?: string;
+  gitStatus?: string;
+}
+
+/**
+ * Captures current working state from the tmux session
+ */
+export function captureSessionContext(agentName: string): SessionContext | null {
+  const sessionName = getSessionName(agentName);
+
+  if (!sessionExists(sessionName)) {
+    return null;
+  }
+
+  try {
+    // Get current working directory from the pane
+    const workdir = execSync(`tmux display-message -t "${sessionName}" -p "#{pane_current_path}"`, {
+      encoding: "utf-8",
+    }).trim();
+
+    const context: SessionContext = { workdir };
+
+    // Try to get git info if in a git repo
+    try {
+      const gitBranch = execSync("git rev-parse --abbrev-ref HEAD 2>/dev/null", {
+        encoding: "utf-8",
+        cwd: workdir,
+      }).trim();
+      if (gitBranch) {
+        context.gitBranch = gitBranch;
+      }
+
+      const gitStatus = execSync("git status --short 2>/dev/null", {
+        encoding: "utf-8",
+        cwd: workdir,
+      }).trim();
+      if (gitStatus) {
+        // Truncate if too long
+        context.gitStatus =
+          gitStatus.length > 500 ? `${gitStatus.substring(0, 500)}...` : gitStatus;
+      }
+    } catch {
+      // Not a git repo or git not available
+    }
+
+    return context;
+  } catch (error) {
+    console.error(`Failed to capture session context: ${error}`);
+    return null;
+  }
+}
+
+/**
+ * Captures recent output from the tmux pane (last N lines)
+ */
+export function captureSessionOutput(agentName: string, lines = 100): string | null {
+  const sessionName = getSessionName(agentName);
+
+  if (!sessionExists(sessionName)) {
+    return null;
+  }
+
+  try {
+    const output = execSync(`tmux capture-pane -t "${sessionName}" -p -S -${lines}`, {
+      encoding: "utf-8",
+    });
+    return output;
+  } catch (error) {
+    console.error(`Failed to capture session output: ${error}`);
+    return null;
+  }
+}