crewly 1.11.5 → 1.12.0

package/packages/crewly-agent/src/runtime/audit-trail.service.test.ts

@@ -0,0 +1,178 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fsPromises } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { AuditTrailService } from './audit-trail.service.js';
+import type { AuditEntry } from './types.js';
+
+describe('AuditTrailService', () => {
+  let service: AuditTrailService;
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await fsPromises.mkdtemp(join(tmpdir(), 'crewly-audit-test-'));
+    service = new AuditTrailService(tempDir, 'test-agent-session');
+  });
+
+  afterEach(async () => {
+    await fsPromises.rm(tempDir, { recursive: true, force: true });
+  });
+
+  const makeEntry = (overrides?: Partial<AuditEntry>): AuditEntry => ({
+    timestamp: new Date().toISOString(),
+    sessionName: 'test-agent-session',
+    toolName: 'get_team_status',
+    sensitivity: 'safe',
+    args: {},
+    success: true,
+    durationMs: 15,
+    ...overrides,
+  });
+
+  describe('initialize', () => {
+    it('should create the audit-logs directory', async () => {
+      await service.initialize();
+
+      const stat = await fsPromises.stat(join(tempDir, 'audit-logs'));
+      expect(stat.isDirectory()).toBe(true);
+    });
+
+    it('should set initialized flag', async () => {
+      expect(service.isInitialized()).toBe(false);
+      await service.initialize();
+      expect(service.isInitialized()).toBe(true);
+    });
+
+    it('should be idempotent (safe to call multiple times)', async () => {
+      await service.initialize();
+      await service.initialize();
+      expect(service.isInitialized()).toBe(true);
+    });
+  });
+
+  describe('append', () => {
+    it('should throw if not initialized', async () => {
+      await expect(service.append(makeEntry())).rejects.toThrow('not initialized');
+    });
+
+    it('should write entry as JSONL line', async () => {
+      await service.initialize();
+      const entry = makeEntry();
+      await service.append(entry);
+
+      const content = await fsPromises.readFile(service.getLogFilePath(), 'utf8');
+      const parsed = JSON.parse(content.trim());
+      expect(parsed.toolName).toBe('get_team_status');
+      expect(parsed.sessionName).toBe('test-agent-session');
+    });
+
+    it('should append multiple entries on separate lines', async () => {
+      await service.initialize();
+      await service.append(makeEntry({ toolName: 'tool_a' }));
+      await service.append(makeEntry({ toolName: 'tool_b' }));
+      await service.append(makeEntry({ toolName: 'tool_c' }));
+
+      const content = await fsPromises.readFile(service.getLogFilePath(), 'utf8');
+      const lines = content.trim().split('\n');
+      expect(lines).toHaveLength(3);
+      expect(JSON.parse(lines[0]).toolName).toBe('tool_a');
+      expect(JSON.parse(lines[2]).toolName).toBe('tool_c');
+    });
+  });
+
+  describe('query', () => {
+    it('should throw if not initialized', async () => {
+      await expect(service.query({ limit: 10 })).rejects.toThrow('not initialized');
+    });
+
+    it('should return empty array when log file does not exist', async () => {
+      await service.initialize();
+      const entries = await service.query({ limit: 50 });
+      expect(entries).toEqual([]);
+    });
+
+    it('should return entries in reverse chronological order', async () => {
+      await service.initialize();
+      await service.append(makeEntry({ toolName: 'first', timestamp: '2026-01-01T00:00:00Z' }));
+      await service.append(makeEntry({ toolName: 'second', timestamp: '2026-01-01T00:01:00Z' }));
+      await service.append(makeEntry({ toolName: 'third', timestamp: '2026-01-01T00:02:00Z' }));
+
+      const entries = await service.query({ limit: 50 });
+      expect(entries).toHaveLength(3);
+      expect(entries[0].toolName).toBe('third');
+      expect(entries[2].toolName).toBe('first');
+    });
+
+    it('should respect limit parameter', async () => {
+      await service.initialize();
+      for (let i = 0; i < 10; i++) {
+        await service.append(makeEntry({ toolName: `tool_${i}` }));
+      }
+
+      const entries = await service.query({ limit: 3 });
+      expect(entries).toHaveLength(3);
+      expect(entries[0].toolName).toBe('tool_9');
+    });
+
+    it('should filter by sensitivity', async () => {
+      await service.initialize();
+      await service.append(makeEntry({ toolName: 'safe_tool', sensitivity: 'safe' }));
+      await service.append(makeEntry({ toolName: 'sensitive_tool', sensitivity: 'sensitive' }));
+      await service.append(makeEntry({ toolName: 'destructive_tool', sensitivity: 'destructive' }));
+
+      const entries = await service.query({ limit: 50, sensitivity: 'sensitive' });
+      expect(entries).toHaveLength(1);
+      expect(entries[0].toolName).toBe('sensitive_tool');
+    });
+
+    it('should filter by toolName', async () => {
+      await service.initialize();
+      await service.append(makeEntry({ toolName: 'edit_file' }));
+      await service.append(makeEntry({ toolName: 'read_file' }));
+      await service.append(makeEntry({ toolName: 'edit_file' }));
+
+      const entries = await service.query({ limit: 50, toolName: 'edit_file' });
+      expect(entries).toHaveLength(2);
+    });
+
+    it('should combine sensitivity and toolName filters', async () => {
+      await service.initialize();
+      await service.append(makeEntry({ toolName: 'edit_file', sensitivity: 'destructive' }));
+      await service.append(makeEntry({ toolName: 'read_file', sensitivity: 'safe' }));
+      await service.append(makeEntry({ toolName: 'edit_file', sensitivity: 'safe' }));
+
+      const entries = await service.query({ limit: 50, sensitivity: 'destructive', toolName: 'edit_file' });
+      expect(entries).toHaveLength(1);
+    });
+
+    it('should skip malformed lines gracefully', async () => {
+      await service.initialize();
+      await service.append(makeEntry({ toolName: 'valid' }));
+      // Manually write a malformed line
+      await fsPromises.appendFile(service.getLogFilePath(), 'not-valid-json\n', 'utf8');
+      await service.append(makeEntry({ toolName: 'also_valid' }));
+
+      const entries = await service.query({ limit: 50 });
+      expect(entries).toHaveLength(2);
+      expect(entries[0].toolName).toBe('also_valid');
+      expect(entries[1].toolName).toBe('valid');
+    });
+  });
+
+  describe('getLogFilePath', () => {
+    it('should return path under audit-logs directory', () => {
+      const path = service.getLogFilePath();
+      expect(path).toContain('audit-logs');
+      expect(path).toContain('test-agent-session');
+      expect(path.endsWith('.jsonl')).toBe(true);
+    });
+
+    it('should sanitize special characters in session name', () => {
+      const specialService = new AuditTrailService(tempDir, 'agent/with spaces!');
+      const path = specialService.getLogFilePath();
+      expect(path).not.toContain('/with');
+      expect(path).not.toContain(' ');
+      expect(path).not.toContain('!');
+    });
+  });
+});

package/packages/crewly-agent/src/runtime/audit-trail.service.ts

@@ -0,0 +1,151 @@
+/**
+ * Audit Trail Service
+ *
+ * Provides file-based persistence for the security audit trail.
+ * Writes audit entries as append-only JSONL (one JSON object per line)
+ * for structured, queryable audit logging.
+ *
+ * @module services/agent/crewly-agent/audit-trail.service
+ */
+
+import { promises as fsPromises } from 'fs';
+import { join } from 'path';
+import type { AuditEntry, AuditLogFilters } from './types.js';
+
+/** Default directory name for audit logs under .crewly */
+const AUDIT_DIR = 'audit-logs';
+
+/** Maximum lines to read when querying the log file */
+const MAX_QUERY_LINES = 10000;
+
+/**
+ * File-based audit trail service.
+ *
+ * Persists audit entries as append-only JSONL files organized by session.
+ * Each session gets its own log file for easy per-agent auditing.
+ *
+ * @example
+ * ```typescript
+ * const trail = new AuditTrailService('/path/to/.crewly', 'agent-session-1');
+ * await trail.initialize();
+ * await trail.append(auditEntry);
+ * const entries = await trail.query({ limit: 50 });
+ * ```
+ */
+export class AuditTrailService {
+  private crewlyHome: string;
+  private sessionName: string;
+  private logDir: string;
+  private logFile: string;
+  private initialized = false;
+
+  /**
+   * Create a new AuditTrailService.
+   *
+   * @param crewlyHome - Path to the .crewly directory
+   * @param sessionName - Agent session name for log file naming
+   */
+  constructor(crewlyHome: string, sessionName: string) {
+    this.crewlyHome = crewlyHome;
+    this.sessionName = sessionName;
+    this.logDir = join(crewlyHome, AUDIT_DIR);
+    this.logFile = join(this.logDir, `${sanitizeFilename(sessionName)}.jsonl`);
+  }
+
+  /**
+   * Initialize the audit trail by ensuring the log directory exists.
+   *
+   * @throws Error if directory creation fails
+   */
+  async initialize(): Promise<void> {
+    await fsPromises.mkdir(this.logDir, { recursive: true });
+    this.initialized = true;
+  }
+
+  /**
+   * Append an audit entry to the log file.
+   *
+   * @param entry - Audit entry to persist
+   * @throws Error if not initialized or write fails
+   */
+  async append(entry: AuditEntry): Promise<void> {
+    if (!this.initialized) {
+      throw new Error('AuditTrailService not initialized. Call initialize() first.');
+    }
+    const line = JSON.stringify(entry) + '\n';
+    await fsPromises.appendFile(this.logFile, line, 'utf8');
+  }
+
+  /**
+   * Query persisted audit entries with optional filters.
+   *
+   * Reads the log file and returns matching entries in reverse
+   * chronological order (most recent first).
+   *
+   * @param filters - Query filters for limit, sensitivity, and toolName
+   * @returns Filtered audit entries
+   */
+  async query(filters: AuditLogFilters): Promise<AuditEntry[]> {
+    if (!this.initialized) {
+      throw new Error('AuditTrailService not initialized. Call initialize() first.');
+    }
+
+    let content: string;
+    try {
+      content = await fsPromises.readFile(this.logFile, 'utf8');
+    } catch (err) {
+      // File doesn't exist yet — no entries
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        return [];
+      }
+      throw err;
+    }
+
+    const lines = content.trim().split('\n').filter(Boolean);
+
+    // Parse from end (most recent first), apply filters
+    let entries: AuditEntry[] = [];
+    const startIdx = Math.max(0, lines.length - MAX_QUERY_LINES);
+    for (let i = lines.length - 1; i >= startIdx && entries.length < filters.limit; i--) {
+      try {
+        const entry: AuditEntry = JSON.parse(lines[i]);
+        if (filters.sensitivity && entry.sensitivity !== filters.sensitivity) continue;
+        if (filters.toolName && entry.toolName !== filters.toolName) continue;
+        entries.push(entry);
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    return entries;
+  }
+
+  /**
+   * Get the path to the audit log file.
+   *
+   * @returns Absolute path to the JSONL log file
+   */
+  getLogFilePath(): string {
+    return this.logFile;
+  }
+
+  /**
+   * Check if the service has been initialized.
+   *
+   * @returns True if initialize() has been called successfully
+   */
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+}
+
+/**
+ * Sanitize a session name for use as a filename.
+ * Replaces non-alphanumeric characters (except hyphens and underscores) with hyphens.
+ *
+ * @param name - Raw session name
+ * @returns Sanitized filename-safe string
+ */
+function sanitizeFilename(name: string): string {
+  return name.replace(/[^a-zA-Z0-9_-]/g, '-');
+}

package/packages/crewly-agent/src/runtime/auditor-tools.test.ts

@@ -0,0 +1,274 @@
+import { describe, it, expect, beforeEach, afterEach, vi, type Mocked, type MockInstance } from 'vitest';
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { createAuditorTools, getAuditorToolNames } from './auditor-tools.js';
+import { CrewlyApiClient } from './api-client.js';
+
+describe('Auditor Tools', () => {
+  let mockClient: Mocked<CrewlyApiClient>;
+  let tools: ReturnType<typeof createAuditorTools>;
+  let readFileSpy: MockInstance<typeof fs.readFile>;
+  let writeFileSpy: MockInstance<typeof fs.writeFile>;
+  let mkdirSpy: MockInstance<typeof fs.mkdir>;
+  const projectPath = '/test/project';
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockClient = {
+      get: vi.fn<any>(),
+      post: vi.fn<any>(),
+      put: vi.fn<any>(),
+      delete: vi.fn<any>(),
+    } as any;
+
+    readFileSpy = vi.spyOn(fs, 'readFile') as any;
+    writeFileSpy = vi.spyOn(fs, 'writeFile') as any;
+    mkdirSpy = vi.spyOn(fs, 'mkdir').mockResolvedValue(undefined as any) as any;
+
+    tools = createAuditorTools(mockClient, projectPath);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('getAuditorToolNames', () => {
+    it('should return all 11 tool names', () => {
+      const names = getAuditorToolNames();
+      expect(names).toHaveLength(11);
+      expect(names).toContain('get_team_status');
+      expect(names).toContain('get_agent_logs');
+      expect(names).toContain('get_tasks');
+      expect(names).toContain('recall_goals');
+      expect(names).toContain('heartbeat');
+      expect(names).toContain('get_agent_status');
+      expect(names).toContain('subscribe_event');
+      expect(names).toContain('write_audit_report');
+      expect(names).toContain('reply_slack');
+      expect(names).toContain('read_audit_history');
+    });
+  });
+
+  describe('tool definitions', () => {
+    it('should create all 11 tools', () => {
+      expect(Object.keys(tools)).toHaveLength(11);
+    });
+
+    it('should have description and inputSchema on every tool', () => {
+      for (const [name, tool] of Object.entries(tools)) {
+        expect(tool.description).toBeTruthy();
+        expect(tool.inputSchema).toBeDefined();
+        expect(typeof tool.execute).toBe('function');
+      }
+    });
+  });
+
+  describe('get_team_status', () => {
+    it('should return team data on success', async () => {
+      mockClient.get.mockResolvedValue({ success: true, status: 200, data: [{ id: 'team1' }] });
+      const result = await tools.get_team_status.execute({});
+      expect(mockClient.get).toHaveBeenCalledWith('/teams');
+      expect(result).toEqual([{ id: 'team1' }]);
+    });
+
+    it('should return error on failure', async () => {
+      mockClient.get.mockResolvedValue({ success: false, status: 500, error: 'Network error' });
+      const result = await tools.get_team_status.execute({});
+      expect(result).toEqual({ error: 'Network error' });
+    });
+  });
+
+  describe('get_agent_logs', () => {
+    it('should fetch logs with line count', async () => {
+      mockClient.get.mockResolvedValue({ success: true, status: 200, data: { output: 'log data' } });
+      const result = await tools.get_agent_logs.execute({ sessionName: 'agent-1', lines: 30 });
+      expect(mockClient.get).toHaveBeenCalledWith('/terminal/agent-1/output?lines=30');
+      expect(result).toEqual({ output: 'log data' });
+    });
+  });
+
+  describe('get_tasks', () => {
+    it('should fetch tasks with project path', async () => {
+      mockClient.get.mockResolvedValue({ success: true, status: 200, data: [{ id: 'task1' }] });
+      await tools.get_tasks.execute({ projectPath: '/proj', status: 'in_progress' });
+      // V3-only as of spec 2026-05-06-task-management-v1-deprecation.md.
+      expect(mockClient.get).toHaveBeenCalledWith(expect.stringContaining('/task-pool/items'));
+      expect(mockClient.get).toHaveBeenCalledWith(expect.stringContaining('status=in_progress'));
+    });
+
+    it('should fetch all tasks when no status filter', async () => {
+      mockClient.get.mockResolvedValue({ success: true, status: 200, data: [] });
+      await tools.get_tasks.execute({ projectPath: '/proj' });
+      expect(mockClient.get).toHaveBeenCalledWith(expect.not.stringContaining('status='));
+    });
+  });
+
+  describe('recall_goals', () => {
+    it('should call memory recall with project scope', async () => {
+      mockClient.post.mockResolvedValue({ success: true, status: 200, data: { goals: ['OKR1'] } });
+      const result = await tools.recall_goals.execute({ context: 'current goals' });
+      expect(mockClient.post).toHaveBeenCalledWith('/memory/recall', {
+        context: 'current goals',
+        scope: 'project',
+      });
+      expect(result).toEqual({ goals: ['OKR1'] });
+    });
+  });
+
+  describe('heartbeat', () => {
+    it('should return combined teams and projects status', async () => {
+      mockClient.get.mockResolvedValueOnce({ success: true, status: 200, data: [{ id: 't1' }] });
+      mockClient.get.mockResolvedValueOnce({ success: true, status: 200, data: [{ id: 'p1' }] });
+      const result = await tools.heartbeat.execute({}) as Record<string, unknown>;
+      expect(result.teams).toEqual([{ id: 't1' }]);
+      expect(result.projects).toEqual([{ id: 'p1' }]);
+      expect(result.timestamp).toBeTruthy();
+    });
+  });
+
+  describe('get_agent_status', () => {
+    it('should find agent by session name across teams', async () => {
+      mockClient.get.mockResolvedValue({
+        success: true,
+        status: 200,
+        data: [
+          { members: [{ sessionName: 'other', name: 'Other' }] },
+          { members: [{ sessionName: 'target', name: 'Target', agentStatus: 'active' }] },
+        ],
+      });
+      const result = await tools.get_agent_status.execute({ sessionName: 'target' });
+      expect(result).toEqual({ sessionName: 'target', name: 'Target', agentStatus: 'active' });
+    });
+
+    it('should return error when agent not found', async () => {
+      mockClient.get.mockResolvedValue({ success: true, status: 200, data: [{ members: [] }] });
+      const result = await tools.get_agent_status.execute({ sessionName: 'missing' }) as { error: string };
+      expect(result.error).toContain('not found');
+    });
+  });
+
+  describe('subscribe_event', () => {
+    it('should subscribe with auditor as target', async () => {
+      mockClient.post.mockResolvedValue({ success: true, status: 200, data: { subscriptionId: 's1' } });
+      await tools.subscribe_event.execute({
+        eventType: 'agent:idle',
+        oneShot: false,
+      });
+      expect(mockClient.post).toHaveBeenCalledWith('/events/subscribe', expect.objectContaining({
+        eventType: 'agent:idle',
+        target: 'crewly-auditor',
+      }));
+    });
+  });
+
+  describe('reply_slack', () => {
+    it('should send message via slack API', async () => {
+      mockClient.post.mockResolvedValue({ success: true, status: 200, data: { ok: true } });
+      const result = await tools.reply_slack.execute({
+        text: 'Here are the audit findings...',
+        channelId: 'C12345',
+        threadTs: '1234567890.123456',
+      }) as { sent: boolean };
+      expect(mockClient.post).toHaveBeenCalledWith('/slack/send', {
+        channelId: 'C12345',
+        text: 'Here are the audit findings...',
+        threadTs: '1234567890.123456',
+      });
+      expect(result.sent).toBe(true);
+    });
+
+    it('should return error on failure', async () => {
+      mockClient.post.mockResolvedValue({ success: false, status: 500, error: 'Slack API error' });
+      const result = await tools.reply_slack.execute({
+        text: 'test',
+        channelId: 'C1',
+        threadTs: 't1',
+      }) as { error: string };
+      expect(result.error).toBe('Slack API error');
+    });
+  });
+
+  describe('write_audit_report', () => {
+    it('should create bugs.md with header when file does not exist', async () => {
+      readFileSpy.mockRejectedValue(new Error('ENOENT') as never);
+      writeFileSpy.mockResolvedValue(undefined as never);
+
+      const result = await tools.write_audit_report.execute({
+        severity: 'high',
+        agents: ['agent-sam'],
+        title: 'Agent stuck in loop',
+        description: 'Agent Sam has been retrying the same operation for 30 minutes.',
+        evidence: 'Error: Build failed\nError: Build failed\nError: Build failed',
+        suggestion: 'Investigate build configuration or reset agent.',
+      }) as { success: boolean; severity: string; title: string };
+
+      expect(mkdirSpy).toHaveBeenCalledWith(
+        path.join(projectPath, '.crewly', 'audit'),
+        { recursive: true },
+      );
+      expect(writeFileSpy).toHaveBeenCalled();
+      const written = (writeFileSpy.mock.calls[0] as any[])[1] as string;
+      expect(written).toContain('# Crewly Audit');
+      expect(written).toContain('[HIGH] Agent stuck in loop');
+      expect(written).toContain('agent-sam');
+      expect(written).toContain('Build failed');
+      expect(result.success).toBe(true);
+      expect(result.severity).toBe('high');
+    });
+
+    it('should append to existing bugs.md', async () => {
+      readFileSpy.mockResolvedValue('# Existing content\n\n---\n' as never);
+      writeFileSpy.mockResolvedValue(undefined as never);
+
+      await tools.write_audit_report.execute({
+        severity: 'medium',
+        agents: ['agent-leo'],
+        title: 'Idle agent with pending tasks',
+        description: 'Leo has been idle for 20 minutes with 2 open tasks.',
+        evidence: 'Status: idle. Open tasks: task-123, task-456',
+        suggestion: 'Send a nudge message to Leo.',
+      });
+
+      const written = (writeFileSpy.mock.calls[0] as any[])[1] as string;
+      expect(written).toContain('# Existing content');
+      expect(written).toContain('[MEDIUM] Idle agent');
+    });
+
+    it('should use correct severity icons', async () => {
+      readFileSpy.mockRejectedValue(new Error('ENOENT') as never);
+      writeFileSpy.mockResolvedValue(undefined as never);
+
+      for (const [sev, icon] of [['critical', '🔴'], ['high', '🟠'], ['medium', '🟡'], ['low', '🔵']] as const) {
+        await tools.write_audit_report.execute({
+          severity: sev,
+          agents: ['test'],
+          title: `${sev} issue`,
+          description: 'Test',
+          evidence: 'Test',
+          suggestion: 'Test',
+        });
+      }
+
+      const calls = writeFileSpy.mock.calls;
+      expect((calls[0] as any[])[1]).toContain('🔴');
+      expect((calls[1] as any[])[1]).toContain('🟠');
+      expect((calls[2] as any[])[1]).toContain('🟡');
+      expect((calls[3] as any[])[1]).toContain('🔵');
+    });
+  });
+
+  describe('read_audit_history', () => {
+    it('should return recent findings', async () => {
+      readFileSpy.mockResolvedValue('# Header\n---\nFinding 1\n---\nFinding 2\n---\nFinding 3' as never);
+      const result = await tools.read_audit_history.execute({ lastN: 2 }) as { totalFindings: number };
+      expect(result.totalFindings).toBe(3); // 4 sections - 1 header
+    });
+
+    it('should return empty when no history', async () => {
+      readFileSpy.mockRejectedValue(new Error('ENOENT') as never);
+      const result = await tools.read_audit_history.execute({ lastN: 10 }) as { totalFindings: number; recentFindings: string };
+      expect(result.totalFindings).toBe(0);
+      expect(result.recentFindings).toContain('No audit history');
+    });
+  });
+});