@agentmeshhq/agent 0.1.7 → 0.1.8

package/src/cli/index.ts

@@ -5,6 +5,7 @@ import { Command } from "commander";
 import pc from "picocolors";
 import { attach } from "./attach.js";
 import { configCmd } from "./config.js";
+import { contextCmd } from "./context.js";
 import { init } from "./init.js";
 import { list } from "./list.js";
 import { logs } from "./logs.js";
@@ -46,6 +47,7 @@ program
   .option("-w, --workdir <path>", "Working directory")
   .option("-m, --model <model>", "Model identifier")
   .option("-f, --foreground", "Run in foreground (blocking)")
+  .option("--no-context", "Start fresh without restoring previous context")
   .action(async (options) => {
     try {
       await start(options);
@@ -190,4 +192,19 @@ program
     }
   });
 
+program
+  .command("context")
+  .description("Manage agent context persistence")
+  .argument("[action]", "Action: show (default), clear, export, import, list, path")
+  .argument("[name]", "Agent name or file path (for import)")
+  .option("-o, --output <path>", "Output file path (for export)")
+  .action(async (action, name, options) => {
+    try {
+      await contextCmd(action || "show", name, options);
+    } catch (error) {
+      console.error(pc.red((error as Error).message));
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/src/cli/start.ts

@@ -1,10 +1,10 @@
 import { spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
 import path from "node:path";
-import { AgentDaemon } from "../core/daemon.js";
-import { loadConfig, getAgentState } from "../config/loader.js";
-import { sessionExists, getSessionName } from "../core/tmux.js";
+import { fileURLToPath } from "node:url";
 import pc from "picocolors";
+import { getAgentState, loadConfig } from "../config/loader.js";
+import { AgentDaemon } from "../core/daemon.js";
+import { getSessionName, sessionExists } from "../core/tmux.js";
 
 export interface StartOptions {
   name: string;
@@ -12,6 +12,7 @@ export interface StartOptions {
   workdir?: string;
   model?: string;
   foreground?: boolean;
+  noContext?: boolean;
 }
 
 export async function start(options: StartOptions): Promise<void> {
@@ -40,7 +41,10 @@ export async function start(options: StartOptions): Promise<void> {
   // If --foreground flag is set, run in foreground (blocking)
   if (options.foreground) {
     try {
-      const daemon = new AgentDaemon(options);
+      const daemon = new AgentDaemon({
+        ...options,
+        restoreContext: !options.noContext,
+      });
       await daemon.start();
       // Keep process alive
       await new Promise(() => {});
@@ -55,16 +59,14 @@ export async function start(options: StartOptions): Promise<void> {
   console.log(`Starting agent "${options.name}" in background...`);
 
   // Get the path to this CLI
-  const cliPath = path.resolve(
-    path.dirname(fileURLToPath(import.meta.url)),
-    "../cli/index.js"
-  );
+  const cliPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../cli/index.js");
 
   // Build args for the background process
   const args = ["start", "--name", options.name, "--foreground"];
   if (options.command) args.push("--command", options.command);
   if (options.workdir) args.push("--workdir", options.workdir);
   if (options.model) args.push("--model", options.model);
+  if (options.noContext) args.push("--no-context");
 
   // Spawn detached background process
   const child = spawn("node", [cliPath, ...args], {

package/src/context/handoff.ts

@@ -0,0 +1,122 @@
+/**
+ * Context Handoff Module
+ * Functions for sharing context between agents via handoffs
+ */
+
+import type { AgentContext } from "./schema.js";
+import { loadContext } from "./storage.js";
+
+/**
+ * Minimal context for handoff (excludes sensitive/large data)
+ */
+export interface HandoffContext {
+  /** Working directory */
+  workdir: string;
+  /** Git branch if in a repo */
+  gitBranch?: string;
+  /** Current goal being worked on */
+  currentGoal?: string;
+  /** Active tasks (in_progress and pending) */
+  activeTasks: Array<{
+    content: string;
+    status: "in_progress" | "pending";
+    priority: string;
+  }>;
+  /** Recent accomplishments */
+  recentAccomplishments: string[];
+  /** Key topics from conversation */
+  topics: string[];
+  /** Any custom context data */
+  custom?: Record<string, unknown>;
+}
+
+/**
+ * Extracts handoff-relevant context from full agent context
+ */
+export function extractHandoffContext(context: AgentContext): HandoffContext {
+  return {
+    workdir: context.workingState.workdir,
+    gitBranch: context.workingState.gitBranch,
+    currentGoal: context.tasks.currentGoal,
+    activeTasks: context.tasks.tasks
+      .filter((t) => t.status === "in_progress" || t.status === "pending")
+      .map((t) => ({
+        content: t.content,
+        status: t.status as "in_progress" | "pending",
+        priority: t.priority,
+      })),
+    recentAccomplishments: context.conversation.accomplishments.slice(0, 5),
+    topics: context.conversation.topics.slice(0, 10),
+    custom: Object.keys(context.custom).length > 0 ? context.custom : undefined,
+  };
+}
+
+/**
+ * Gets handoff context for an agent by ID
+ */
+export function getHandoffContextForAgent(agentId: string): HandoffContext | null {
+  const context = loadContext(agentId);
+  if (!context) {
+    return null;
+  }
+  return extractHandoffContext(context);
+}
+
+/**
+ * Serializes handoff context to a string for inclusion in API calls
+ */
+export function serializeHandoffContext(context: HandoffContext): string {
+  return JSON.stringify(context);
+}
+
+/**
+ * Parses handoff context from a string (received from API)
+ */
+export function parseHandoffContext(contextString: string): HandoffContext | null {
+  try {
+    return JSON.parse(contextString) as HandoffContext;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generates a human-readable summary of handoff context
+ */
+export function formatHandoffContextSummary(context: HandoffContext): string {
+  const lines: string[] = [];
+
+  if (context.workdir) {
+    lines.push(`Working directory: ${context.workdir}`);
+  }
+  if (context.gitBranch) {
+    lines.push(`Git branch: ${context.gitBranch}`);
+  }
+  if (context.currentGoal) {
+    lines.push(`Current goal: ${context.currentGoal}`);
+  }
+
+  if (context.activeTasks.length > 0) {
+    lines.push("");
+    lines.push("Active tasks:");
+    for (const task of context.activeTasks) {
+      const icon = task.status === "in_progress" ? ">" : "-";
+      lines.push(`  ${icon} ${task.content}`);
+    }
+  }
+
+  if (context.recentAccomplishments.length > 0) {
+    lines.push("");
+    lines.push("Recent accomplishments:");
+    for (const acc of context.recentAccomplishments) {
+      lines.push(`  - ${acc}`);
+    }
+  }
+
+  if (context.topics.length > 0) {
+    lines.push("");
+    lines.push(`Topics: ${context.topics.join(", ")}`);
+  }
+
+  return lines.join("\n");
+}

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);
     }