macro-agent 0.1.0 → 0.1.2

package/src/store/__tests__/event-store.test.ts

@@ -170,7 +170,7 @@ describe('EventStore', () => {
       });
 
       store.emit({
-        type: 'terminate',
+        type: 'stop',
         source: { agent_id: 'agent_1' },
         payload: { reason: 'completed' },
       });
@@ -1096,6 +1096,201 @@ describe('Event Archival', () => {
 
       await planStore.close();
     });
+
+    it('should update agent name via updateAgentMetadata', async () => {
+      const metaStore = await createEventStore({ inMemory: true });
+
+      metaStore.emit({
+        type: 'spawn',
+        source: { agent_id: 'agent_meta' },
+        payload: {
+          agent_id: 'agent_meta',
+          session_id: 'sess_meta',
+          task: 'test metadata',
+        },
+      });
+
+      // Name starts undefined
+      expect(metaStore.getAgent('agent_meta')?.name).toBeUndefined();
+
+      // Set name via updateAgentMetadata
+      metaStore.updateAgentMetadata('agent_meta', { name: 'MyAgent' });
+      expect(metaStore.getAgent('agent_meta')?.name).toBe('MyAgent');
+
+      await metaStore.close();
+    });
+
+    it('should update agent metadata via updateAgentMetadata', async () => {
+      const metaStore = await createEventStore({ inMemory: true });
+
+      metaStore.emit({
+        type: 'spawn',
+        source: { agent_id: 'agent_meta2' },
+        payload: {
+          agent_id: 'agent_meta2',
+          session_id: 'sess_meta2',
+          task: 'test metadata field',
+        },
+      });
+
+      // Metadata starts undefined
+      expect(metaStore.getAgent('agent_meta2')?.metadata).toBeUndefined();
+
+      // Set metadata
+      metaStore.updateAgentMetadata('agent_meta2', {
+        metadata: { color: 'blue', priority: 1 },
+      });
+      const after = metaStore.getAgent('agent_meta2');
+      expect(after?.metadata).toEqual({ color: 'blue', priority: 1 });
+
+      await metaStore.close();
+    });
+
+    it('should shallow-merge metadata with existing values', async () => {
+      const metaStore = await createEventStore({ inMemory: true });
+
+      metaStore.emit({
+        type: 'spawn',
+        source: { agent_id: 'agent_merge' },
+        payload: {
+          agent_id: 'agent_merge',
+          session_id: 'sess_merge',
+          task: 'test metadata merge',
+        },
+      });
+
+      // Set initial metadata
+      metaStore.updateAgentMetadata('agent_merge', {
+        metadata: { color: 'blue', size: 'large' },
+      });
+      expect(metaStore.getAgent('agent_merge')?.metadata).toEqual({
+        color: 'blue',
+        size: 'large',
+      });
+
+      // Merge with new metadata — existing keys preserved, new keys added
+      metaStore.updateAgentMetadata('agent_merge', {
+        metadata: { color: 'red', shape: 'circle' },
+      });
+      expect(metaStore.getAgent('agent_merge')?.metadata).toEqual({
+        color: 'red',
+        size: 'large',
+        shape: 'circle',
+      });
+
+      await metaStore.close();
+    });
+
+    it('should update multiple fields in a single updateAgentMetadata call', async () => {
+      const metaStore = await createEventStore({ inMemory: true });
+
+      metaStore.emit({
+        type: 'spawn',
+        source: { agent_id: 'agent_multi' },
+        payload: {
+          agent_id: 'agent_multi',
+          session_id: 'sess_multi',
+          task: 'test multi-field update',
+        },
+      });
+
+      const plan = [
+        { content: 'Step 1', priority: 'high', status: 'pending' },
+      ];
+
+      metaStore.updateAgentMetadata('agent_multi', {
+        name: 'MultiAgent',
+        plan,
+        metadata: { tag: 'test' },
+      });
+
+      const agent = metaStore.getAgent('agent_multi');
+      expect(agent?.name).toBe('MultiAgent');
+      expect(agent?.plan).toEqual(plan);
+      expect(agent?.metadata).toEqual({ tag: 'test' });
+
+      await metaStore.close();
+    });
+
+    it('should notify agent change listeners on metadata update', async () => {
+      const metaStore = await createEventStore({ inMemory: true });
+
+      metaStore.emit({
+        type: 'spawn',
+        source: { agent_id: 'agent_notify' },
+        payload: {
+          agent_id: 'agent_notify',
+          session_id: 'sess_notify',
+          task: 'test notify',
+        },
+      });
+
+      const changes: string[] = [];
+      metaStore.onAgentChange((agentId) => {
+        changes.push(agentId);
+      });
+
+      metaStore.updateAgentMetadata('agent_notify', { name: 'Notified' });
+      expect(changes).toContain('agent_notify');
+
+      await metaStore.close();
+    });
+
+    it('should preserve all out-of-band fields across reload', async () => {
+      const metaStore = await createEventStore({
+        baseDir: testDir,
+        instanceId: 'metadata-reload-test',
+      });
+
+      metaStore.emit({
+        type: 'spawn',
+        source: { agent_id: 'agent_reload' },
+        payload: {
+          agent_id: 'agent_reload',
+          session_id: 'sess_reload',
+          task: 'test reload persistence',
+        },
+      });
+
+      // Set all out-of-band fields
+      const plan = [
+        { content: 'Research', priority: 'high', status: 'completed' },
+      ];
+      metaStore.updateAgentMetadata('agent_reload', {
+        name: 'ReloadAgent',
+        plan,
+        metadata: { version: 2, env: 'test' },
+      });
+
+      // Verify before reload
+      const before = metaStore.getAgent('agent_reload');
+      expect(before?.name).toBe('ReloadAgent');
+      expect(before?.plan).toEqual(plan);
+      expect(before?.metadata).toEqual({ version: 2, env: 'test' });
+
+      // Persist and reload (rebuildViews)
+      await metaStore.persist();
+      await metaStore.reload();
+
+      // All fields should survive
+      const after = metaStore.getAgent('agent_reload');
+      expect(after).toBeDefined();
+      expect(after?.name).toBe('ReloadAgent');
+      expect(after?.plan).toEqual(plan);
+      expect(after?.metadata).toEqual({ version: 2, env: 'test' });
+
+      await metaStore.close();
+    });
+
+    it('should no-op when agent does not exist', async () => {
+      const metaStore = await createEventStore({ inMemory: true });
+
+      // Should not throw
+      metaStore.updateAgentMetadata('nonexistent', { name: 'Ghost' });
+      expect(metaStore.getAgent('nonexistent')).toBeNull();
+
+      await metaStore.close();
+    });
   });
 });
 

package/src/store/__tests__/instance.test.ts

@@ -467,10 +467,10 @@ describe('Peer Visibility', () => {
     it('should filter by whitelist when visibleEventTypes is specified', () => {
       const visibility: PeerVisibilityConfig = {
         exportEvents: true,
-        visibleEventTypes: ['spawn', 'terminate'],
+        visibleEventTypes: ['spawn', 'stop'],
       };
       expect(isEventTypeVisibleToPeers('spawn', visibility)).toBe(true);
-      expect(isEventTypeVisibleToPeers('terminate', visibility)).toBe(true);
+      expect(isEventTypeVisibleToPeers('stop', visibility)).toBe(true);
       expect(isEventTypeVisibleToPeers('message', visibility)).toBe(false);
     });
   });
@@ -503,7 +503,7 @@ describe('Peer Visibility', () => {
       { type: 'spawn', source: { agent_id: 'agent-1' }, payload: {} },
       { type: 'message', source: { agent_id: 'agent-1' }, payload: {} },
       { type: 'spawn', source: { agent_id: 'agent-2' }, payload: {} },
-      { type: 'terminate', source: { agent_id: 'agent-2' }, payload: {} },
+      { type: 'stop', source: { agent_id: 'agent-2' }, payload: {} },
     ];
 
     it('should return empty array when export is disabled', () => {

package/src/store/event-store.ts

@@ -23,6 +23,7 @@ import type {
   EventFilter,
   Agent,
   AgentState,
+  AgentMetadataUpdate,
   Task,
   TaskStatus,
   QueuedMessage,
@@ -57,6 +58,7 @@ import {
   readInstanceMeta,
   touchInstance,
   registerInstance,
+  DEFAULT_BASE_DIR,
   DEFAULT_NAMESPACE,
   DEFAULT_PEER_VISIBILITY,
   filterEventsForPeer,
@@ -131,8 +133,8 @@ function createTabularBetterSqlite3Persister(
     undefined,
     // onIgnoredError
     (error: any) => console.warn('[EventStore] Persister error:', error),
-    // destroy
-    () => db.close(),
+    // destroy — do NOT close DB here; close() handles it after the persister drains
+    () => {},
     // persist mode (1 = StoreOnly)
     1 as any,
     // thing (the db instance)
@@ -204,6 +206,7 @@ export interface EventStore {
   getAgent(agentId: AgentId): Agent | null;
   listAgents(filter?: { state?: AgentState; parent?: AgentId | null }): Agent[];
   updateAgentPlan(agentId: AgentId, plan: Array<{ content: string; priority: string; status: string }>): void;
+  updateAgentMetadata(agentId: AgentId, updates: AgentMetadataUpdate): void;
 
   // Task view
   getTask(taskId: TaskId): Task | null;
@@ -306,7 +309,7 @@ export async function createEventStore(config: StoreConfig = {}): Promise<EventS
   }
 
   // Track baseDir for MCP subprocess communication
-  const baseDir = config.baseDir ?? path.join(os.homedir(), '.multiagent');
+  const baseDir = config.baseDir ?? DEFAULT_BASE_DIR;
 
   // Get peer visibility config (default is restrictive)
   const peerVisibility: PeerVisibilityConfig =
@@ -380,7 +383,7 @@ export async function createEventStore(config: StoreConfig = {}): Promise<EventS
 
     // Register in namespace for discovery
     registerInstance(
-      config.baseDir ?? path.join(os.homedir(), '.multiagent'),
+      config.baseDir ?? DEFAULT_BASE_DIR,
       namespace,
       instanceId,
       { label: config.label }
@@ -521,24 +524,56 @@ export async function createEventStore(config: StoreConfig = {}): Promise<EventS
   }
 
   /**
-   * Update an agent's plan entries (persisted to SQLite via TinyBase)
+   * Update agent metadata fields (name, plan, metadata).
+   * Only provided fields are updated. Metadata is shallow-merged with existing.
    */
-  function updateAgentPlan(
+  function updateAgentMetadata(
     agentId: AgentId,
-    plan: Array<{ content: string; priority: string; status: string }>,
+    updates: AgentMetadataUpdate,
   ): void {
     const row = store.getRow('agents', agentId);
     if (!row.id) return;
 
-    store.setPartialRow('agents', agentId, {
-      plan: JSON.stringify(plan),
+    const partial: Record<string, string | number | boolean> = {
       last_activity_at: Date.now(),
-    });
+    };
+
+    if (updates.name !== undefined) {
+      partial.name = updates.name;
+    }
+    if (updates.plan !== undefined) {
+      partial.plan = JSON.stringify(updates.plan);
+    }
+    if (updates.metadata !== undefined) {
+      // Shallow merge with existing metadata
+      const existing = row.metadata ? JSON.parse(row.metadata as string) : {};
+      partial.metadata = JSON.stringify({ ...existing, ...updates.metadata });
+    }
+    if (updates.team_instance !== undefined) {
+      partial.team_instance = updates.team_instance;
+    }
+    if (updates.cwd !== undefined) {
+      partial.cwd = updates.cwd;
+    }
+
+    store.setPartialRow('agents', agentId, partial);
 
     const agent = rowToAgent(store.getRow('agents', agentId));
     notifyAgentChange(agentId, agent);
   }
 
+  /**
+   * Update an agent's plan entries (persisted to SQLite via TinyBase).
+   * Convenience wrapper around updateAgentMetadata.
+   */
+  function updateAgentPlan(
+    agentId: AgentId,
+    plan: Array<{ content: string; priority: string; status: string }>,
+  ): void {
+    updateAgentMetadata(agentId, { plan });
+  }
+
+
   /**
    * Get task by ID
    */
@@ -947,8 +982,18 @@ export async function createEventStore(config: StoreConfig = {}): Promise<EventS
    */
   async function close(): Promise<void> {
     if (persister) {
+      // Stop auto-save first to prevent race conditions between
+      // auto-save callbacks and the explicit save/destroy sequence.
+      await persister.stopAutoSave();
       await persister.save();
+      // Destroy the persister (removes store listeners) BEFORE closing the DB.
+      // The destroy callback is a no-op — we close the DB ourselves below
+      // after giving TinyBase's internal async queues time to drain.
       persister.destroy();
+      // Allow any in-flight TinyBase microtasks to settle before closing
+      // the database connection. Without this, pending writes from store
+      // change listeners can race against db.close().
+      await new Promise(resolve => setTimeout(resolve, 50));
     }
     if (db) {
       db.close();
@@ -1224,6 +1269,7 @@ export async function createEventStore(config: StoreConfig = {}): Promise<EventS
     getAgent,
     listAgents,
     updateAgentPlan,
+    updateAgentMetadata,
     getTask,
     listTasks,
     getMessages,
@@ -1291,13 +1337,21 @@ function initializeTables(store: Store): void {
  */
 function rebuildViews(store: Store): void {
   // Preserve out-of-band agent fields that aren't derived from events.
-  // `plan` is written directly via updateAgentPlan(), not through events,
-  // so it would be lost when we clear and replay.
-  const savedAgentPlan = new Map<string, string>();
+  // These fields are written directly (not through events),
+  // so they would be lost when we clear and replay.
+  const OUT_OF_BAND_FIELDS = ['plan', 'name', 'metadata', 'cwd', 'team_instance'] as const;
+  const savedOutOfBand = new Map<string, Record<string, string>>();
   for (const rowId of store.getRowIds('agents')) {
     const row = store.getRow('agents', rowId);
-    if (row.plan && row.plan !== '[]') {
-      savedAgentPlan.set(rowId, row.plan as string);
+    const saved: Record<string, string> = {};
+    for (const field of OUT_OF_BAND_FIELDS) {
+      const val = row[field] as string | undefined;
+      if (val && val !== '' && val !== '[]') {
+        saved[field] = val;
+      }
+    }
+    if (Object.keys(saved).length > 0) {
+      savedOutOfBand.set(rowId, saved);
     }
   }
 
@@ -1358,10 +1412,10 @@ function rebuildViews(store: Store): void {
   }
 
   // Restore out-of-band agent fields preserved before the wipe
-  for (const [agentId, plan] of savedAgentPlan) {
+  for (const [agentId, fields] of savedOutOfBand) {
     const row = store.getRow('agents', agentId);
     if (row.id) {
-      store.setPartialRow('agents', agentId, { plan });
+      store.setPartialRow('agents', agentId, fields);
     }
   }
 }
@@ -1383,8 +1437,8 @@ function applyEventToViews(
     case 'spawn':
       applySpawnEvent(store, event, notifyAgentChange);
       break;
-    case 'terminate':
-      applyTerminateEvent(store, event, notifyAgentChange);
+    case 'stop':
+      applyStopEvent(store, event, notifyAgentChange);
       break;
     case 'status':
       applyStatusEvent(store, event, notifyAgentChange);
@@ -1431,6 +1485,7 @@ function applySpawnEvent(
     task_id?: TaskId;
     parent?: AgentId | null;
     role?: string;
+    team_instance?: string;
     config?: Record<string, unknown>;
     cwd?: string;
   };
@@ -1451,6 +1506,7 @@ function applySpawnEvent(
 
   store.setRow('agents', agentId, {
     id: agentId,
+    name: '',
     session_id: payload.session_id,
     provider_session_id: '',
     parent: parent ?? '',
@@ -1460,9 +1516,11 @@ function applySpawnEvent(
     task: payload.task,
     task_id: payload.task_id ?? '',
     role: payload.role ?? '',
+    team_instance: payload.team_instance ?? '',
     config: JSON.stringify(payload.config ?? {}),
     cwd: payload.cwd ?? process.cwd(),
     plan: '[]',
+    metadata: '',
     created_at: event.timestamp,
     started_at: 0,
     stopped_at: 0,
@@ -1474,9 +1532,9 @@ function applySpawnEvent(
 }
 
 /**
- * Apply terminate event to agents view
+ * Apply stop event to agents view
  */
-function applyTerminateEvent(
+function applyStopEvent(
   store: Store,
   event: Event,
   notify: (agentId: AgentId, agent: Agent | null) => void,
@@ -1618,6 +1676,7 @@ function applyTaskEvent(
         description: string;
         parent_task?: TaskId;
         inputs?: Record<string, unknown>;
+        tags?: string[];
         retryPolicy?: unknown;
       };
       store.setRow('tasks', taskId, {
@@ -1628,6 +1687,7 @@ function applyTaskEvent(
         parent_task: details.parent_task ?? '',
         subtasks: JSON.stringify([]),
         blockers: JSON.stringify([]),
+        tags: details.tags ? JSON.stringify(details.tags) : '',
         created_at: event.timestamp,
         started_at: 0,
         completed_at: 0,
@@ -1674,10 +1734,15 @@ function applyTaskEvent(
           break;
         }
       }
-      store.setPartialRow('tasks', taskId, {
+      const updates: Record<string, string | number | boolean> = {
         assigned_agent: '',
         agent_history: JSON.stringify(history),
-      });
+      };
+      // Reset to pending if task was only assigned (not yet started)
+      if (existing.status === 'assigned') {
+        updates.status = 'pending';
+      }
+      store.setPartialRow('tasks', taskId, updates);
       break;
     }
     case 'status_change': {
@@ -1800,6 +1865,7 @@ function rowToAgent(row: Record<string, unknown>): Agent {
   const stopReason = row.stop_reason as string;
   return {
     id: row.id as AgentId,
+    name: (row.name as string) || undefined,
     session_id: row.session_id as string,
     provider_session_id: (row.provider_session_id as string) || undefined,
     parent: (row.parent as string) || null,
@@ -1809,9 +1875,11 @@ function rowToAgent(row: Record<string, unknown>): Agent {
     task: row.task as string,
     task_id: (row.task_id as string) || undefined,
     role: (row.role as string) || undefined,
+    team_instance: (row.team_instance as string) || undefined,
     config: row.config ? JSON.parse(row.config as string) : {},
     cwd: (row.cwd as string) || process.cwd(),
     plan: row.plan ? JSON.parse(row.plan as string) : [],
+    metadata: row.metadata ? JSON.parse(row.metadata as string) : undefined,
     created_at: row.created_at as Timestamp,
     started_at: (row.started_at as number) || undefined,
     stopped_at: (row.stopped_at as number) || undefined,
@@ -1839,6 +1907,7 @@ function rowToTask(row: Record<string, unknown>): Task {
     outputs: row.outputs ? JSON.parse(row.outputs as string) : undefined,
     artifacts: row.artifacts ? JSON.parse(row.artifacts as string) : undefined,
     agent_history: row.agent_history ? JSON.parse(row.agent_history as string) : undefined,
+    tags: row.tags ? JSON.parse(row.tags as string) : undefined,
     retryPolicy: row.retry_policy ? JSON.parse(row.retry_policy as string) : undefined,
     retryState: row.retry_state ? JSON.parse(row.retry_state as string) : undefined,
   };

package/src/store/instance.ts

@@ -221,8 +221,8 @@ export interface ResolvedInstance {
 // Constants
 // ─────────────────────────────────────────────────────────────────────────────
 
-/** Default base directory */
-export const DEFAULT_BASE_DIR = path.join(os.homedir(), '.multiagent');
+/** Default base directory (override with MACRO_AGENT_HOME env var) */
+export const DEFAULT_BASE_DIR = process.env.MACRO_AGENT_HOME || path.join(os.homedir(), '.multiagent');
 
 /** Default namespace */
 export const DEFAULT_NAMESPACE = 'default';

package/src/store/types/agents.ts

@@ -28,6 +28,8 @@ export interface AgentConfig {
 // Agent record in materialized view
 export interface Agent {
   id: AgentId;
+  /** Optional display name (set via rename, not derived from events) */
+  name?: string;
   session_id: SessionId;
   /** Session ID from the underlying agent provider (e.g., Claude Code UUID for --resume) */
   provider_session_id?: string;
@@ -38,12 +40,30 @@ export interface Agent {
   task: string;
   task_id?: TaskId;
   role?: string;
+  /** Team instance ID this agent belongs to (set by TeamManager) */
+  team_instance?: string;
   config: AgentConfig;
   cwd: string;
   plan: Array<{ content: string; priority: string; status: string }>;
+  /** Arbitrary metadata (persisted out-of-band, not derived from events) */
+  metadata?: Record<string, unknown>;
   created_at: Timestamp;
   started_at?: Timestamp;
   stopped_at?: Timestamp;
   /** Last time this agent emitted an event (for health monitoring) */
   last_activity_at?: Timestamp;
 }
+
+/**
+ * Partial update for agent metadata fields.
+ * All fields are optional — only provided fields are updated.
+ * `metadata` is merged (shallow) with existing metadata.
+ */
+export interface AgentMetadataUpdate {
+  name?: string;
+  plan?: Array<{ content: string; priority: string; status: string }>;
+  metadata?: Record<string, unknown>;
+  team_instance?: string;
+  /** Override the agent's working directory (e.g., to workspace worktree path) */
+  cwd?: string;
+}

package/src/store/types/events.ts

@@ -11,7 +11,7 @@ export const CURRENT_EVENT_VERSION = 1;
 // Event types
 export type EventType =
   | "spawn"
-  | "terminate"
+  | "stop"
   | "status"
   | "message"
   | "task"