feat(hooks): add Graphiti knowledge graph hooks and session summary

Wire session events into Graphiti for persistent knowledge graph updates.
Add session summary generation for hook-based context capture.

Author: StackMemory Bot (CLI)

src/hooks/__tests__/graphiti-hooks.test.ts

@@ -1,7 +1,16 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { GraphitiHooks } from '../graphiti-hooks.js';
 import { HookEventEmitter } from '../events.js';
-import type { HookEvent, FileChangeEvent } from '../events.js';
+import type {
+  HookEvent,
+  FileChangeEvent,
+  InputIdleEvent,
+  ContextSwitchEvent,
+  SuggestionReadyEvent,
+  AgentStartEvent,
+  AgentCompleteEvent,
+  AgentErrorEvent,
+} from '../events.js';
 
 // Mock logger to suppress output
 vi.mock('../../core/monitoring/logger.js', () => ({
@@ -51,14 +60,23 @@ describe('GraphitiHooks', () => {
   // ── register ──
 
   describe('register', () => {
-    it('registers handlers for session_start, file_change, session_end', () => {
+    it('registers handlers for all 11 hook events', () => {
       const hooks = makeHooks();
       hooks.register(emitter);
 
       const events = emitter.getRegisteredEvents();
+      expect(events).toHaveLength(11);
       expect(events).toContain('session_start');
       expect(events).toContain('file_change');
       expect(events).toContain('session_end');
+      expect(events).toContain('input_idle');
+      expect(events).toContain('context_switch');
+      expect(events).toContain('prompt_submit');
+      expect(events).toContain('tool_use');
+      expect(events).toContain('suggestion_ready');
+      expect(events).toContain('agent_start');
+      expect(events).toContain('agent_complete');
+      expect(events).toContain('agent_error');
     });
 
     it('skips registration when enabled=false', () => {
@@ -184,6 +202,253 @@ describe('GraphitiHooks', () => {
     });
   });
 
+  // ── onInputIdle ──
+
+  describe('onInputIdle', () => {
+    it('records idle duration and last input', async () => {
+      const hooks = makeHooks();
+      const client = mockClient(hooks);
+      client.upsertEpisode.mockResolvedValue({ id: 'ep-idle' });
+      hooks.register(emitter);
+
+      const event: InputIdleEvent = {
+        type: 'input_idle',
+        timestamp: Date.now(),
+        data: { idleDuration: 30000, lastInput: 'save file' },
+      };
+      await emitter.emitHook(event);
+
+      expect(client.upsertEpisode).toHaveBeenCalledOnce();
+      const episode = client.upsertEpisode.mock.calls[0][0];
+      expect(episode.type).toBe('input_idle');
+      expect(episode.content).toEqual({
+        idleDuration: 30000,
+        lastInput: 'save file',
+      });
+      expect(episode.source).toBe('stackmemory');
+    });
+
+    it('handles missing lastInput', async () => {
+      const hooks = makeHooks();
+      const client = mockClient(hooks);
+      client.upsertEpisode.mockResolvedValue({ id: 'ep-idle2' });
+      hooks.register(emitter);
+
+      const event: InputIdleEvent = {
+        type: 'input_idle',
+        timestamp: Date.now(),
+        data: { idleDuration: 5000 },
+      };
+      await emitter.emitHook(event);
+
+      const episode = client.upsertEpisode.mock.calls[0][0];
+      expect(episode.content.lastInput).toBeUndefined();
+    });
+  });
+
+  // ── onContextSwitch ──
+
+  describe('onContextSwitch', () => {
+    it('records branch and project changes', async () => {
+      const hooks = makeHooks();
+      const client = mockClient(hooks);
+      client.upsertEpisode.mockResolvedValue({ id: 'ep-ctx' });
+      hooks.register(emitter);
+
+      const event: ContextSwitchEvent = {
+        type: 'context_switch',
+        timestamp: Date.now(),
+        data: {
+          fromBranch: 'main',
+          toBranch: 'feature/foo',
+          fromProject: 'proj-a',
+          toProject: 'proj-b',
+        },
+      };
+      await emitter.emitHook(event);
+
+      expect(client.upsertEpisode).toHaveBeenCalledOnce();
+      const episode = client.upsertEpisode.mock.calls[0][0];
+      expect(episode.type).toBe('context_switch');
+      expect(episode.content).toEqual({
+        fromBranch: 'main',
+        toBranch: 'feature/foo',
+        fromProject: 'proj-a',
+        toProject: 'proj-b',
+      });
+    });
+  });
+
+  // ── onPromptSubmit ──
+
+  describe('onPromptSubmit', () => {
+    it('records prompt data as episode', async () => {
+      const hooks = makeHooks();
+      const client = mockClient(hooks);
+      client.upsertEpisode.mockResolvedValue({ id: 'ep-prompt' });
+      hooks.register(emitter);
+
+      const event: HookEvent = {
+        type: 'prompt_submit',
+        timestamp: Date.now(),
+        data: { prompt: 'fix the bug', tokens: 42 },
+      };
+      await emitter.emitHook(event);
+
+      expect(client.upsertEpisode).toHaveBeenCalledOnce();
+      const episode = client.upsertEpisode.mock.calls[0][0];
+      expect(episode.type).toBe('prompt_submit');
+      expect(episode.content).toEqual({ prompt: 'fix the bug', tokens: 42 });
+      expect(episode.source).toBe('stackmemory');
+    });
+  });
+
+  // ── onToolUse ──
+
+  describe('onToolUse', () => {
+    it('records tool use data as episode', async () => {
+      const hooks = makeHooks();
+      const client = mockClient(hooks);
+      client.upsertEpisode.mockResolvedValue({ id: 'ep-tool' });
+      hooks.register(emitter);
+
+      const event: HookEvent = {
+        type: 'tool_use',
+        timestamp: Date.now(),
+        data: { tool: 'Read', file: '/src/index.ts' },
+      };
+      await emitter.emitHook(event);
+
+      expect(client.upsertEpisode).toHaveBeenCalledOnce();
+      const episode = client.upsertEpisode.mock.calls[0][0];
+      expect(episode.type).toBe('tool_use');
+      expect(episode.content).toEqual({ tool: 'Read', file: '/src/index.ts' });
+    });
+  });
+
+  // ── onSuggestionReady ──
+
+  describe('onSuggestionReady', () => {
+    it('records source, confidence, preview but omits full suggestion', async () => {
+      const hooks = makeHooks();
+      const client = mockClient(hooks);
+      client.upsertEpisode.mockResolvedValue({ id: 'ep-suggest' });
+      hooks.register(emitter);
+
+      const event: SuggestionReadyEvent = {
+        type: 'suggestion_ready',
+        timestamp: Date.now(),
+        data: {
+          suggestion: 'full suggestion text that should be omitted',
+          source: 'context-retriever',
+          confidence: 0.85,
+          preview: 'fix authentication...',
+        },
+      };
+      await emitter.emitHook(event);
+
+      expect(client.upsertEpisode).toHaveBeenCalledOnce();
+      const episode = client.upsertEpisode.mock.calls[0][0];
+      expect(episode.type).toBe('suggestion_ready');
+      expect(episode.content).toEqual({
+        source: 'context-retriever',
+        confidence: 0.85,
+        preview: 'fix authentication...',
+      });
+      // Full suggestion text should NOT be in the episode
+      expect(episode.content.suggestion).toBeUndefined();
+    });
+  });
+
+  // ── onAgentStart ──
+
+  describe('onAgentStart', () => {
+    it('maps agent_start to episode with agentType and task', async () => {
+      const hooks = makeHooks();
+      const client = mockClient(hooks);
+      client.upsertEpisode.mockResolvedValue({ id: 'ep-agent-start' });
+      hooks.register(emitter);
+
+      const event: AgentStartEvent = {
+        type: 'agent_start',
+        timestamp: Date.now(),
+        data: {
+          agentType: 'research',
+          workDir: '/tmp/sm-research-abc',
+          task: 'How does FTS5 work?',
+        },
+      };
+      await emitter.emitHook(event);
+
+      expect(client.upsertEpisode).toHaveBeenCalledOnce();
+      const episode = client.upsertEpisode.mock.calls[0][0];
+      expect(episode.type).toBe('agent_start');
+      expect(episode.content).toEqual({
+        agentType: 'research',
+        task: 'How does FTS5 work?',
+      });
+      expect(episode.source).toBe('stackmemory');
+    });
+  });
+
+  // ── onAgentComplete ──
+
+  describe('onAgentComplete', () => {
+    it('maps agent_complete to episode with all fields', async () => {
+      const hooks = makeHooks();
+      const client = mockClient(hooks);
+      client.upsertEpisode.mockResolvedValue({ id: 'ep-agent-done' });
+      hooks.register(emitter);
+
+      const event: AgentCompleteEvent = {
+        type: 'agent_complete',
+        timestamp: Date.now(),
+        data: {
+          agentType: 'maintain',
+          workDir: '/tmp/sm-maint-abc',
+          exitCode: 0,
+          timedOut: false,
+          patchPath: '/repo/.stackmemory/patches/fix.patch',
+          validated: true,
+        },
+      };
+      await emitter.emitHook(event);
+
+      expect(client.upsertEpisode).toHaveBeenCalledOnce();
+      const episode = client.upsertEpisode.mock.calls[0][0];
+      expect(episode.type).toBe('agent_complete');
+      expect(episode.content.agentType).toBe('maintain');
+      expect(episode.content.validated).toBe(true);
+      expect(episode.content.patchPath).toBeDefined();
+    });
+  });
+
+  // ── onAgentError ──
+
+  describe('onAgentError', () => {
+    it('maps agent_error to episode', async () => {
+      const hooks = makeHooks();
+      const client = mockClient(hooks);
+      client.upsertEpisode.mockResolvedValue({ id: 'ep-agent-err' });
+      hooks.register(emitter);
+
+      const event: AgentErrorEvent = {
+        type: 'agent_error',
+        timestamp: Date.now(),
+        data: { agentType: 'spec-run', error: 'git clone failed' },
+      };
+      await emitter.emitHook(event);
+
+      expect(client.upsertEpisode).toHaveBeenCalledOnce();
+      const episode = client.upsertEpisode.mock.calls[0][0];
+      expect(episode.type).toBe('agent_error');
+      expect(episode.content).toEqual({
+        agentType: 'spec-run',
+        error: 'git clone failed',
+      });
+    });
+  });
+
   // ── Error resilience ──
 
   describe('error resilience', () => {

src/hooks/events.ts

@@ -14,6 +14,9 @@ export type HookEventType =
   | 'prompt_submit'
   | 'tool_use'
   | 'suggestion_ready'
+  | 'agent_start'
+  | 'agent_complete'
+  | 'agent_error'
   | 'error';
 
 export interface HookEvent {
@@ -59,11 +62,41 @@ export interface SuggestionReadyEvent extends HookEvent {
   };
 }
 
+export type AgentType = 'research' | 'maintain' | 'spec-run';
+
+export interface AgentStartEvent extends HookEvent {
+  type: 'agent_start';
+  data: { agentType: AgentType; workDir: string; task: string };
+}
+
+export interface AgentCompleteEvent extends HookEvent {
+  type: 'agent_complete';
+  data: {
+    agentType: AgentType;
+    workDir: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    frameId?: string;
+    patchPath?: string;
+    validated?: boolean;
+    branch?: string;
+    validation?: { lint: boolean; test: boolean; build: boolean };
+  };
+}
+
+export interface AgentErrorEvent extends HookEvent {
+  type: 'agent_error';
+  data: { agentType: AgentType; error: string; workDir?: string };
+}
+
 export type HookEventData =
   | FileChangeEvent
   | InputIdleEvent
   | ContextSwitchEvent
   | SuggestionReadyEvent
+  | AgentStartEvent
+  | AgentCompleteEvent
+  | AgentErrorEvent
   | HookEvent;
 
 export type HookHandler = (event: HookEventData) => Promise<void> | void;