clawmini 0.0.8 → 0.0.9

package/src/shared/adapters/filtering.test.ts

@@ -1,32 +1,49 @@
 import { describe, it, expect } from 'vitest';
-import { shouldDisplayMessage, formatMessage } from './filtering.js';
+import { shouldDisplayMessage, routeMessage, formatMessage } from './filtering.js';
 import type { ChatMessage } from '../chats.js';
 
-describe('shouldDisplayMessage', () => {
+describe('shouldDisplayMessage / routeMessage', () => {
   const defaultConfig = {};
 
-  it('hides messages with subagentId if subagent is not explicitly true', () => {
+  it('hides subagent messages from top-level output by default (legacy shouldDisplayMessage)', () => {
     const msg: ChatMessage = {
       id: '1',
       role: 'agent',
       content: 'hello',
       subagentId: 'sub1',
       timestamp: '',
+      sessionId: undefined,
     };
     expect(shouldDisplayMessage(msg, defaultConfig)).toBe(false);
+    // routeMessage still surfaces it inside the turn thread — that's where
+    // subagent activity now belongs.
+    expect(routeMessage(msg, defaultConfig)).toEqual({ kind: 'thread-log' });
   });
 
-  it('hides standard user messages without subagentId', () => {
-    const msg: ChatMessage = { id: '1', role: 'user', content: 'hello', timestamp: '' };
+  it('drops standard user messages without subagentId', () => {
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'user',
+      content: 'hello',
+      timestamp: '',
+      sessionId: undefined,
+    };
     expect(shouldDisplayMessage(msg, defaultConfig)).toBe(false);
+    expect(routeMessage(msg, defaultConfig)).toEqual({ kind: 'drop' });
   });
 
-  it('displays standard agent messages without subagentId', () => {
-    const msg: ChatMessage = { id: '1', role: 'agent', content: 'hello', timestamp: '' };
-    expect(shouldDisplayMessage(msg, defaultConfig)).toBe(true);
+  it('routes standard agent messages to top-level', () => {
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'agent',
+      content: 'hello',
+      timestamp: '',
+      sessionId: undefined,
+    };
+    expect(routeMessage(msg, defaultConfig)).toEqual({ kind: 'top-level' });
   });
 
-  it('hides non-standard messages by default', () => {
+  it('drops command messages by default', () => {
     const msg: ChatMessage = {
       id: '1',
       role: 'command',
@@ -38,10 +55,72 @@ describe('shouldDisplayMessage', () => {
       stderr: '',
       exitCode: 0,
       timestamp: '',
+      sessionId: undefined,
     };
+    expect(routeMessage(msg, defaultConfig)).toEqual({ kind: 'drop' });
+    // Legacy boolean retains the same "drop by default" semantics for Discord.
     expect(shouldDisplayMessage(msg, defaultConfig)).toBe(false);
   });
 
+  it('routes tool messages to thread-log by default', () => {
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'tool',
+      content: '',
+      messageId: '123',
+      name: 'Read',
+      payload: {},
+      timestamp: '',
+      sessionId: undefined,
+    };
+    expect(routeMessage(msg, defaultConfig)).toEqual({ kind: 'thread-log' });
+  });
+
+  it('drops cron system messages by default (proactive turns are invisible)', () => {
+    // Cron prompts are agent-facing orchestration, not user-facing content.
+    // Adapters that want scheduled work visible opt into their own synthetic
+    // heartbeat (e.g. gchat `visibility.jobs: 'header'`).
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'system',
+      content: 'run my daily report',
+      event: 'cron',
+      timestamp: '',
+      sessionId: undefined,
+    };
+    expect(routeMessage(msg, defaultConfig)).toEqual({ kind: 'drop' });
+  });
+
+  it('promotes cron system messages back to top-level when filters.system is true', () => {
+    // Escape hatch for debugging: `filters.system: true` forces cron activity
+    // back into the main log.
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'system',
+      content: 'run my daily report',
+      event: 'cron',
+      timestamp: '',
+      sessionId: undefined,
+    };
+    expect(routeMessage(msg, { filters: { system: true } })).toEqual({ kind: 'top-level' });
+  });
+
+  it('routes pending policy messages to top-level', () => {
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'policy',
+      content: '',
+      messageId: '123',
+      requestId: 'req',
+      commandName: 'rm',
+      args: [],
+      status: 'pending',
+      timestamp: '',
+      sessionId: undefined,
+    };
+    expect(routeMessage(msg, defaultConfig)).toEqual({ kind: 'top-level' });
+  });
+
   it('displays subagent messages if subagent: true', () => {
     const msg: ChatMessage = {
       id: '1',
@@ -49,6 +128,7 @@ describe('shouldDisplayMessage', () => {
       content: 'hello',
       subagentId: 'sub1',
       timestamp: '',
+      sessionId: undefined,
     };
     expect(shouldDisplayMessage(msg, { filters: { subagent: true } })).toBe(true);
   });
@@ -60,6 +140,7 @@ describe('shouldDisplayMessage', () => {
       content: 'hello subagent',
       subagentId: 'sub1',
       timestamp: '',
+      sessionId: undefined,
     };
     expect(shouldDisplayMessage(msg, { filters: { subagent: true } })).toBe(true);
   });
@@ -76,14 +157,100 @@ describe('shouldDisplayMessage', () => {
       stderr: '',
       exitCode: 0,
       timestamp: '',
+      sessionId: undefined,
     };
     expect(shouldDisplayMessage(msg, { filters: { command: true } })).toBe(true);
   });
+
+  it('hides a role when filter is explicitly false', () => {
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'command',
+      content: 'ls',
+      messageId: '123',
+      command: 'ls',
+      cwd: '.',
+      stdout: '',
+      stderr: '',
+      exitCode: 0,
+      timestamp: '',
+      sessionId: undefined,
+    };
+    expect(shouldDisplayMessage(msg, { filters: { command: false } })).toBe(false);
+  });
+
+  it('promotes a user-role message to top-level when filter is true', () => {
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'user',
+      content: 'hello',
+      timestamp: '',
+      sessionId: undefined,
+    };
+    expect(routeMessage(msg, { filters: { user: true } })).toEqual({ kind: 'top-level' });
+  });
+
+  it('routes subagent tool messages to thread-log even without the subagent filter', () => {
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'tool',
+      content: 'ls',
+      messageId: 'mid',
+      name: 'Read',
+      payload: {},
+      subagentId: 'sub-1',
+      timestamp: '',
+      sessionId: undefined,
+    };
+    expect(routeMessage(msg, defaultConfig)).toEqual({ kind: 'thread-log' });
+  });
+
+  it('routes subagent final replies into the turn thread, not top-level', () => {
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'agent',
+      content: 'done',
+      subagentId: 'sub-1',
+      timestamp: '',
+      sessionId: undefined,
+    };
+    expect(routeMessage(msg, defaultConfig)).toEqual({ kind: 'thread-log' });
+  });
+
+  it('routes subagent prompts (user role with subagentId) into the turn thread', () => {
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'user',
+      content: 'research auth flow',
+      subagentId: 'sub-1',
+      timestamp: '',
+      sessionId: undefined,
+    };
+    expect(routeMessage(msg, defaultConfig)).toEqual({ kind: 'thread-log' });
+  });
+
+  it('surfaces subagent final replies at top-level when subagent filter is true', () => {
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'agent',
+      content: 'done',
+      subagentId: 'sub-1',
+      timestamp: '',
+      sessionId: undefined,
+    };
+    expect(routeMessage(msg, { filters: { subagent: true } })).toEqual({ kind: 'top-level' });
+  });
 });
 
 describe('formatMessage', () => {
   it('returns content as-is for messages without subagentId', () => {
-    const msg: ChatMessage = { id: '1', role: 'agent', content: 'hello world', timestamp: '' };
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'agent',
+      content: 'hello world',
+      timestamp: '',
+      sessionId: undefined,
+    };
     expect(formatMessage(msg)).toBe('hello world');
   });
 
@@ -94,6 +261,7 @@ describe('formatMessage', () => {
       content: 'do task',
       subagentId: 'sub1',
       timestamp: '',
+      sessionId: undefined,
     };
     expect(formatMessage(msg)).toBe('[To:sub1]\ndo task');
   });
@@ -105,7 +273,53 @@ describe('formatMessage', () => {
       content: 'done',
       subagentId: 'sub1',
       timestamp: '',
+      sessionId: undefined,
     };
     expect(formatMessage(msg)).toBe('[From:sub1]\ndone');
   });
+
+  it('prepends [SYSTEM] for system-role messages with no displayRole', () => {
+    // System messages only reach `formatMessage` when they route to top-level
+    // (either a non-cron event, or cron opted back in via `filters.system`).
+    // Without the tag they look like either the user or the bot talking.
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'system',
+      content: 'This chat session has ended.',
+      event: 'cron',
+      timestamp: '',
+      sessionId: undefined,
+    };
+    expect(formatMessage(msg)).toBe('[SYSTEM] This chat session has ended.');
+  });
+
+  it('does not prefix [SYSTEM] when displayRole is set (e.g. router auto-reply)', () => {
+    // Router auto-replies opt into being rendered as agent output. Tagging
+    // them [SYSTEM] would mislabel them.
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'system',
+      content: 'Starting a fresh session...',
+      event: 'router',
+      displayRole: 'agent',
+      timestamp: '',
+      sessionId: undefined,
+    };
+    expect(formatMessage(msg)).toBe('Starting a fresh session...');
+  });
+
+  it('does not prefix [SYSTEM] for system messages from subagents', () => {
+    // Subagent output already gets [From:<id>]; a [SYSTEM] on top would be
+    // noisy and incorrect (the subagent is the speaker, not the system).
+    const msg: ChatMessage = {
+      id: '1',
+      role: 'system',
+      content: 'internal note',
+      event: 'subagent_update',
+      subagentId: 'sub1',
+      timestamp: '',
+      sessionId: undefined,
+    };
+    expect(formatMessage(msg)).toBe('[From:sub1]\ninternal note');
+  });
 });

package/src/shared/adapters/filtering.ts

@@ -4,26 +4,28 @@ export interface FilteringConfig {
   filters?: Record<string, boolean> | undefined;
 }
 
+export type Destination = { kind: 'drop' } | { kind: 'top-level' } | { kind: 'thread-log' };
+
+/**
+ * Legacy boolean. Returns true if the message role is permitted to be
+ * displayed at all; adapters that haven't migrated to `routeMessage` keep
+ * using this unchanged.
+ */
 export function shouldDisplayMessage(message: ChatMessage, config: FilteringConfig): boolean {
   const overrides = config.filters || {};
 
-  // If the message has a subagentId, return false immediately unless subagent messages are allowed.
   if (message.subagentId && overrides['subagent'] !== true) {
     return false;
   }
 
-  // Then check if it's a standard agent message (via role/displayRole) and always return true if so.
   const isStandardAgent =
     message.displayRole === 'agent' ||
     message.role === 'agent' ||
     message.role === 'legacy_log' ||
     (message.role === 'policy' && message.status === 'pending');
 
-  if (isStandardAgent) {
-    return true;
-  }
+  if (isStandardAgent) return true;
 
-  // Then check if it's a user message directed to a subagent, if subagent messages are allowed
   if (
     message.subagentId &&
     overrides['subagent'] === true &&
@@ -32,7 +34,6 @@ export function shouldDisplayMessage(message: ChatMessage, config: FilteringConf
     return true;
   }
 
-  // Finally, check if the role is allowed and forward it if so.
   if (
     overrides[message.role] === true ||
     (message.displayRole && overrides[message.displayRole] === true)
@@ -43,7 +44,94 @@ export function shouldDisplayMessage(message: ChatMessage, config: FilteringConf
   return false;
 }
 
+function defaultDestinationForRole(message: ChatMessage): Destination {
+  if (message.role === 'user') return { kind: 'drop' };
+  if (message.role === 'agent') return { kind: 'top-level' };
+  if (message.role === 'legacy_log') return { kind: 'top-level' };
+  if (message.role === 'tool') return { kind: 'thread-log' };
+  if (message.role === 'subagent_status') return { kind: 'thread-log' };
+  if (message.role === 'command') return { kind: 'drop' };
+  if (message.role === 'policy') {
+    return message.status === 'pending' ? { kind: 'top-level' } : { kind: 'thread-log' };
+  }
+  if (message.role === 'system') {
+    // Cron turns are invisible by default: the activity log anchors on the
+    // agent's eventual top-level reply (if any). Adapters that want a
+    // visible header post (gchat `visibility.jobs: 'header'`) promote this
+    // back to top-level at the forwarder layer.
+    if (message.event === 'cron') return { kind: 'drop' };
+    if (message.event === 'policy_approved' || message.event === 'policy_rejected') {
+      return { kind: 'thread-log' };
+    }
+    if (message.event === 'subagent_update') return { kind: 'thread-log' };
+    return { kind: 'top-level' };
+  }
+  return { kind: 'drop' };
+}
+
+/**
+ * Return the destination for a chat message given the adapter's filtering
+ * config. Adapters that support threaded activity logs (Google Chat) use this
+ * to decide whether each message becomes a top-level post, a thread-log entry,
+ * or is dropped entirely.
+ *
+ * A filter override of `true` on a role whose default destination is `drop`
+ * promotes it to `top-level` (matching the legacy "opted in → show" behavior).
+ * A filter override of `false` drops the role.
+ *
+ * Subagent messages route to their default destination when that default is a
+ * thread one (tool calls, command logs, status updates all belong in the turn
+ * log). They are dropped when the default is top-level — subagent prompts and
+ * final replies are orchestration, not user-facing content — unless
+ * `filters.subagent` is `true`, which surfaces them at top-level for debugging.
+ */
+export function routeMessage(message: ChatMessage, config: FilteringConfig): Destination {
+  const overrides = config.filters || {};
+  const defaultDest = defaultDestinationForRole(message);
+
+  if (message.subagentId) {
+    if (overrides['subagent'] === true) {
+      return defaultDest.kind === 'drop' ? { kind: 'top-level' } : defaultDest;
+    }
+    // Everything produced inside a subagent — tool calls, command logs,
+    // status updates, the prompt handed to it, and its final reply — folds
+    // into the parent turn's activity log so the reader can see what the
+    // subagent did.
+    return { kind: 'thread-log' };
+  }
+
+  const isStandardAgent =
+    message.displayRole === 'agent' ||
+    message.role === 'agent' ||
+    message.role === 'legacy_log' ||
+    (message.role === 'policy' && message.status === 'pending');
+
+  if (isStandardAgent) return defaultDest;
+
+  const roleFilter = overrides[message.role];
+  const displayRoleFilter = message.displayRole ? overrides[message.displayRole] : undefined;
+
+  if (roleFilter === false || displayRoleFilter === false) {
+    return { kind: 'drop' };
+  }
+
+  if (roleFilter === true || displayRoleFilter === true) {
+    return defaultDest.kind === 'drop' ? { kind: 'top-level' } : defaultDest;
+  }
+
+  return defaultDest;
+}
+
 export function formatMessage(message: ChatMessage): string {
+  // System-role messages that aren't explicitly re-displayed as user/agent
+  // (e.g. cron-triggered prompts, policy system notes) are posted verbatim
+  // today, which makes them look like either the user or the bot talking.
+  // Tag them so readers can distinguish automated system output from real
+  // conversation. Router auto-replies opt out via displayRole: 'agent'.
+  if (message.role === 'system' && !message.displayRole && !message.subagentId) {
+    return `[SYSTEM] ${message.content}`;
+  }
+
   if (!message.subagentId) {
     return message.content;
   }

package/src/shared/adapters/inbound-cache.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { createInboundCache } from './inbound-cache.js';
+
+const TTL_MS = 10 * 60 * 1000;
+
+describe('createInboundCache', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('records and resolves a value by key', () => {
+    const cache = createInboundCache<{ channelId: string }>(TTL_MS);
+    cache.record('msg-1', { channelId: 'chan-1' });
+    expect(cache.resolve('msg-1')).toEqual({ channelId: 'chan-1' });
+  });
+
+  it('returns null for unknown keys', () => {
+    const cache = createInboundCache<{ channelId: string }>(TTL_MS);
+    expect(cache.resolve('unknown')).toBeNull();
+  });
+
+  it('expires entries older than ttlMs on resolve', () => {
+    vi.useFakeTimers();
+    const cache = createInboundCache<{ channelId: string }>(TTL_MS);
+    cache.record('msg-1', { channelId: 'chan-1' });
+    expect(cache.resolve('msg-1')).not.toBeNull();
+
+    vi.advanceTimersByTime(TTL_MS + 1000);
+    expect(cache.resolve('msg-1')).toBeNull();
+  });
+
+  it('sweeps expired entries on every insert', () => {
+    vi.useFakeTimers();
+    const cache = createInboundCache<{ channelId: string }>(TTL_MS);
+    cache.record('msg-1', { channelId: 'chan-1' });
+    vi.advanceTimersByTime(TTL_MS + 1000);
+    cache.record('msg-2', { channelId: 'chan-2' });
+    expect(cache.resolve('msg-1')).toBeNull();
+    expect(cache.resolve('msg-2')).not.toBeNull();
+  });
+
+  it('reset() drops all entries', () => {
+    const cache = createInboundCache<{ channelId: string }>(TTL_MS);
+    cache.record('msg-1', { channelId: 'chan-1' });
+    cache.reset();
+    expect(cache.resolve('msg-1')).toBeNull();
+  });
+});

package/src/shared/adapters/inbound-cache.ts

@@ -0,0 +1,54 @@
+/**
+ * Generic in-memory inbound message cache shared by adapters that need to
+ * correlate a daemon `turnStarted` event with the inbound message that
+ * triggered it.
+ *
+ * Adapters whose ingestion and forwarder run in the same Node process don't
+ * need disk persistence: a `Map` keyed by external ref (the same id sent to
+ * the daemon as `externalRef`) is enough. Entries older than `ttlMs` are
+ * swept on every insert — bounded memory without an LRU. Adapter restart
+ * mid-turn loses the cache; that is an explicit tradeoff.
+ */
+export interface InboundCache<TValue> {
+  record(key: string, value: TValue): void;
+  resolve(key: string): TValue | null;
+  /** Test hook: drop all cached records. */
+  reset(): void;
+}
+
+interface Entry<TValue> {
+  value: TValue;
+  receivedAt: number;
+}
+
+export function createInboundCache<TValue>(ttlMs: number): InboundCache<TValue> {
+  const cache = new Map<string, Entry<TValue>>();
+
+  const sweep = (now: number): void => {
+    for (const [key, entry] of cache) {
+      if (now - entry.receivedAt > ttlMs) cache.delete(key);
+    }
+  };
+
+  return {
+    record(key, value) {
+      const now = Date.now();
+      sweep(now);
+      cache.set(key, { value, receivedAt: now });
+    },
+
+    resolve(key) {
+      const entry = cache.get(key);
+      if (!entry) return null;
+      if (Date.now() - entry.receivedAt > ttlMs) {
+        cache.delete(key);
+        return null;
+      }
+      return entry.value;
+    },
+
+    reset() {
+      cache.clear();
+    },
+  };
+}