wangjunxiao/nanoclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(routing): engage modes + sender scope + accumulate/drop + per-agent fan-out

Browse Source 
Replaces the opaque trigger_rules JSON + response_scope enum on
messaging_group_agents with four explicit orthogonal columns:

    engage_mode            'pattern' | 'mention' | 'mention-sticky'
    engage_pattern         regex source; required when mode='pattern';
                           '.' is the "always" sentinel
    sender_scope           'all' | 'known'
    ignored_message_policy 'drop' | 'accumulate'

Inbound routing becomes a fan-out — every wired agent is evaluated
independently. A match gets its own session + container wake. A miss
with accumulate keeps the message as context-only (trigger=0) in that
agent's session, so when the agent does eventually engage it sees the
prior chatter.

## Schema

- Migration 010 (`engage-modes`): adds the 4 new columns, backfills
  from trigger_rules.pattern + requiresTrigger + response_scope, drops
  the legacy columns.
- messages_in gains `trigger INTEGER NOT NULL DEFAULT 1` (session DB
  schema + `migrateMessagesInTable` forward-compat).
- countDueMessages gates waking on `trigger = 1`.

## Routing

- `pickAgent` (returns one) → loop over all wired agents. Per agent:
  evaluate engage_mode; run access gate + sender-scope gate; on full
  match → resolveSession + writeSessionMessage(trigger=1) + wake. On
  miss with accumulate → writeSessionMessage(trigger=0), no wake. On
  miss with drop → skip.
- New `findSessionForAgent(agentGroupId, mgId, threadId)` scopes
  session lookup by agent so fan-out doesn't cross sessions.
- `messageIdForAgent` namespaces inbound message ids by agent_group_id
  so PRIMARY KEY doesn't collide across per-agent session DBs.

## Adapter layer

- `ConversationConfig` replaces `triggerPattern` + `requiresTrigger`
  with `engageMode` + `engagePattern`.
- Chat SDK bridge stores `Map<platformId, ConversationConfig[]>` (multi-
  agent per conversation) and applies union gating pre-onInbound:
    * onSubscribedMessage: engage if any wiring keeps firing in
      subscribed state (mention-sticky or pattern)
    * onNewMention: engage on mention; only subscribes the thread if
      at least one wiring is `mention-sticky`
    * onDirectMessage: engage per mode; sticky follows same rule
- Bridge no longer unconditionally calls `thread.subscribe()`.

## Sender scope

- Permissions module registers a second hook `setSenderScopeGate` that
  runs per-wiring after the existing access gate. `sender_scope='known'`
  requires canAccessAgentGroup(); `'all'` is a no-op. Not installed →
  no-op everywhere (default allow).

## Container side

- Host passes `NANOCLAW_MAX_MESSAGES_PER_PROMPT` (reuses existing
  MAX_MESSAGES_PER_PROMPT config; was dead code from v1).
- `getPendingMessages` queries `ORDER BY seq DESC LIMIT N`, reverses to
  chronological order for the prompt — accumulated context rides along
  with trigger rows up to the cap.
- `MessageInRow` gains `trigger: number` so the container can tell them
  apart in downstream code (container still processes both; only the
  host uses `trigger=0` for don't-wake).

## Defaults (per ACTION-ITEMS item 1 decision)

- DM (is_group=0): `engage_mode='pattern'`, `engage_pattern='.'` (always)
- Threaded group: `engage_mode='mention-sticky'` (seed-discord)
- Non-threaded group / CLI: pattern '.' in bootstrap scripts

## Tests

- src/host-core.test.ts: 3 new cases — fan-out (2 agents, 2 sessions,
  2 wakes), accumulate (trigger=0 + no wake), drop (no session created).
- Existing 10 host-core tests still pass.
- Migration 010 runs on an empty DB in 0-row path — verified.

Closes: ACTION-ITEMS items 1, 4.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
gavrielc
2026-04-20 01:30:04 +03:00
parent 6a815190c0
commit 16b9499532
22 changed files with 688 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
src/db/db-v2.test.ts
View File

@@ -178,8 +178,10 @@ describe('messaging group agents', () => {
id: 'mga-1',
messaging_group_id: 'mg-1',
agent_group_id: 'ag-1',
trigger_rules: null,
response_scope: 'all' as const,
engage_mode: 'pattern' as const,
engage_pattern: '.',
sender_scope: 'all' as const,
ignored_message_policy: 'drop' as const,
session_mode: 'shared' as const,
priority: 0,
created_at: now(),
@@ -229,7 +231,8 @@ describe('messaging group agents', () => {
});
it('auto-creates an agent_destinations row for the wiring', async () => {
const { getDestinationByTarget, getDestinations } = await import('../modules/agent-to-agent/db/agent-destinations.js');
const { getDestinationByTarget, getDestinations } =
await import('../modules/agent-to-agent/db/agent-destinations.js');
createMessagingGroupAgent(mga());
const dest = getDestinationByTarget('ag-1', 'channel', 'mg-1');

19
src/db/messaging-groups.ts
View File

@@ -87,8 +87,16 @@ export function deleteMessagingGroup(id: string): void {
export function createMessagingGroupAgent(mga: MessagingGroupAgent): void {
getDb()
.prepare(
`INSERT INTO messaging_group_agents (id, messaging_group_id, agent_group_id, trigger_rules, response_scope, session_mode, priority, created_at)
VALUES (@id, @messaging_group_id, @agent_group_id, @trigger_rules, @response_scope, @session_mode, @priority, @created_at)`,
`INSERT INTO messaging_group_agents (
id, messaging_group_id, agent_group_id,
engage_mode, engage_pattern, sender_scope, ignored_message_policy,
session_mode, priority, created_at
)
VALUES (
@id, @messaging_group_id, @agent_group_id,
@engage_mode, @engage_pattern, @sender_scope, @ignored_message_policy,
@session_mode, @priority, @created_at
)`,
)
.run(mga);
@@ -160,7 +168,12 @@ export function getMessagingGroupAgent(id: string): MessagingGroupAgent | undefi
export function updateMessagingGroupAgent(
id: string,
updates: Partial<Pick<MessagingGroupAgent, 'trigger_rules' | 'response_scope' | 'session_mode' | 'priority'>>,
updates: Partial<
Pick<
MessagingGroupAgent,
'engage_mode' | 'engage_pattern' | 'sender_scope' | 'ignored_message_policy' | 'session_mode' | 'priority'
>
>,
): void {
const fields: string[] = [];
const values: Record<string, unknown> = { id };

101
src/db/migrations/010-engage-modes.ts Normal file
View File

@@ -0,0 +1,101 @@
/**
* Replace `trigger_rules` (opaque JSON) + `response_scope` (conflated axis)
* with four explicit orthogonal columns on messaging_group_agents:
*
* engage_mode 'pattern' | 'mention' | 'mention-sticky'
* engage_pattern regex string (required when engage_mode='pattern';
* '.' means "match everything" — the "always" flavor)
* sender_scope 'all' | 'known'
* ignored_message_policy 'drop' | 'accumulate'
*
* Backfill rules (applied per-row, reading the old JSON):
* - If trigger_rules.pattern is a non-empty string → engage_mode='pattern',
* engage_pattern = that value
* - Else if trigger_rules.requiresTrigger === false OR response_scope='all'
* → engage_mode='pattern', engage_pattern='.'
* - Else (requires trigger but no pattern specified) → engage_mode='mention'
* - sender_scope: 'known' when response_scope was 'allowlisted', 'all' otherwise
* - ignored_message_policy: 'drop' (conservative default; no old-schema analog)
*/
import type Database from 'better-sqlite3';
import type { Migration } from './index.js';
import { log } from '../../log.js';
interface LegacyRow {
id: string;
trigger_rules: string | null;
response_scope: string | null;
}
function backfill(row: LegacyRow): {
engage_mode: 'pattern' | 'mention' | 'mention-sticky';
engage_pattern: string | null;
sender_scope: 'all' | 'known';
ignored_message_policy: 'drop' | 'accumulate';
} {
let parsed: Record<string, unknown> = {};
if (row.trigger_rules) {
try {
parsed = JSON.parse(row.trigger_rules) as Record<string, unknown>;
} catch {
// Invalid JSON falls through to conservative defaults.
}
}
const pattern = typeof parsed.pattern === 'string' && parsed.pattern.length > 0 ? (parsed.pattern as string) : null;
const requiresTrigger = parsed.requiresTrigger;
let engage_mode: 'pattern' | 'mention' | 'mention-sticky' = 'mention';
let engage_pattern: string | null = null;
if (pattern) {
engage_mode = 'pattern';
engage_pattern = pattern;
} else if (requiresTrigger === false || row.response_scope === 'all') {
engage_mode = 'pattern';
engage_pattern = '.';
}
const sender_scope: 'all' | 'known' = row.response_scope === 'allowlisted' ? 'known' : 'all';
return { engage_mode, engage_pattern, sender_scope, ignored_message_policy: 'drop' };
}
export const migration010: Migration = {
version: 10,
name: 'engage-modes',
up: (db: Database.Database) => {
// Add the four new columns alongside the existing two. SQLite ALTER ADD
// is cheap and non-rewriting.
db.exec(`
ALTER TABLE messaging_group_agents ADD COLUMN engage_mode TEXT;
ALTER TABLE messaging_group_agents ADD COLUMN engage_pattern TEXT;
ALTER TABLE messaging_group_agents ADD COLUMN sender_scope TEXT;
ALTER TABLE messaging_group_agents ADD COLUMN ignored_message_policy TEXT;
`);
// Backfill existing rows in JS (parsing JSON per-row is painful in pure SQL).
const rows = db.prepare('SELECT id, trigger_rules, response_scope FROM messaging_group_agents').all() as LegacyRow[];
const update = db.prepare(
`UPDATE messaging_group_agents
SET engage_mode = ?,
engage_pattern = ?,
sender_scope = ?,
ignored_message_policy = ?
WHERE id = ?`,
);
for (const row of rows) {
const v = backfill(row);
update.run(v.engage_mode, v.engage_pattern, v.sender_scope, v.ignored_message_policy, row.id);
}
// Drop the legacy columns. DROP COLUMN requires SQLite 3.35+ (2021); our
// better-sqlite3 ships a current build.
db.exec(`
ALTER TABLE messaging_group_agents DROP COLUMN trigger_rules;
ALTER TABLE messaging_group_agents DROP COLUMN response_scope;
`);
log.info('engage-modes migration: backfilled rows', { count: rows.length });
},
};

6
src/db/migrations/index.ts
View File

@@ -6,6 +6,7 @@ import { migration002 } from './002-chat-sdk-state.js';
import { moduleAgentToAgentDestinations } from './module-agent-to-agent-destinations.js';
import { migration008 } from './008-dropped-messages.js';
import { migration009 } from './009-drop-pending-credentials.js';
import { migration010 } from './010-engage-modes.js';
import { moduleApprovalsPendingApprovals } from './module-approvals-pending-approvals.js';
import { moduleApprovalsTitleOptions } from './module-approvals-title-options.js';
@@ -23,6 +24,7 @@ const migrations: Migration[] = [
moduleApprovalsTitleOptions,
migration008,
migration009,
migration010,
];
export function runMigrations(db: Database.Database): void {
@@ -52,8 +54,8 @@ export function runMigrations(db: Database.Database): void {
for (const m of pending) {
db.transaction(() => {
m.up(db);
const next =
(db.prepare('SELECT COALESCE(MAX(version), 0) + 1 AS v FROM schema_version').get() as { v: number }).v;
const next = (db.prepare('SELECT COALESCE(MAX(version), 0) + 1 AS v FROM schema_version').get() as { v: number })
.v;
db.prepare('INSERT INTO schema_version (version, name, applied) VALUES (?, ?, ?)').run(
next,
m.name,

27
src/db/schema.ts
View File

@@ -30,16 +30,23 @@ CREATE TABLE messaging_groups (
UNIQUE(channel_type, platform_id)
);
-- Which agent groups handle which messaging groups
-- Which agent groups handle which messaging groups.
-- engage_mode / engage_pattern / sender_scope / ignored_message_policy are
-- the four orthogonal axes that together replace v1's opaque trigger_rules
-- JSON + response_scope enum. See docs/v1-vs-v2/ACTION-ITEMS.md item 1.
CREATE TABLE messaging_group_agents (
id TEXT PRIMARY KEY,
messaging_group_id TEXT NOT NULL REFERENCES messaging_groups(id),
agent_group_id TEXT NOT NULL REFERENCES agent_groups(id),
trigger_rules TEXT,
response_scope TEXT DEFAULT 'all',
session_mode TEXT DEFAULT 'shared',
priority INTEGER DEFAULT 0,
created_at TEXT NOT NULL,
id TEXT PRIMARY KEY,
messaging_group_id TEXT NOT NULL REFERENCES messaging_groups(id),
agent_group_id TEXT NOT NULL REFERENCES agent_groups(id),
engage_mode TEXT NOT NULL DEFAULT 'mention',
-- 'pattern' | 'mention' | 'mention-sticky'
engage_pattern TEXT, -- regex; required when engage_mode='pattern';
-- '.' means "match every message" (the "always" flavor)
sender_scope TEXT NOT NULL DEFAULT 'all', -- 'all' | 'known'
ignored_message_policy TEXT NOT NULL DEFAULT 'drop', -- 'drop' | 'accumulate'
session_mode TEXT DEFAULT 'shared',
priority INTEGER DEFAULT 0,
created_at TEXT NOT NULL,
UNIQUE(messaging_group_id, agent_group_id)
);
@@ -138,6 +145,8 @@ CREATE TABLE IF NOT EXISTS messages_in (
recurrence TEXT,
series_id TEXT,
tries INTEGER DEFAULT 0,
trigger INTEGER NOT NULL DEFAULT 1,
-- 0 = accumulated context (don't wake), 1 = wake agent
platform_id TEXT,
channel_type TEXT,
thread_id TEXT,

27
src/db/session-db.ts
View File

@@ -95,13 +95,19 @@ export function insertMessage(
content: string;
processAfter: string | null;
recurrence: string | null;
/**
* 1 = wake the agent (default); 0 = accumulate as context only.
* Host countDueMessages gates on this; container reads everything.
*/
trigger?: 0 | 1;
},
): void {
db.prepare(
`INSERT INTO messages_in (id, seq, kind, timestamp, status, platform_id, channel_type, thread_id, content, process_after, recurrence, series_id)
VALUES (@id, @seq, @kind, @timestamp, 'pending', @platformId, @channelType, @threadId, @content, @processAfter, @recurrence, @id)`,
`INSERT INTO messages_in (id, seq, kind, timestamp, status, platform_id, channel_type, thread_id, content, process_after, recurrence, series_id, trigger)
VALUES (@id, @seq, @kind, @timestamp, 'pending', @platformId, @channelType, @threadId, @content, @processAfter, @recurrence, @id, @trigger)`,
).run({
...message,
trigger: message.trigger ?? 1,
seq: nextEvenSeq(db),
});
}
@@ -112,6 +118,7 @@ export function countDueMessages(db: Database.Database): number {
.prepare(
`SELECT COUNT(*) as count FROM messages_in
WHERE status = 'pending'
AND trigger = 1
AND (process_after IS NULL OR datetime(process_after) <= datetime('now'))`,
)
.get() as { count: number }
@@ -169,9 +176,7 @@ export interface ProcessingClaim {
/** Return processing_ack rows still in 'processing' with their claim timestamps. */
export function getProcessingClaims(outDb: Database.Database): ProcessingClaim[] {
return outDb
.prepare(
"SELECT message_id, status_changed FROM processing_ack WHERE status = 'processing'",
)
.prepare("SELECT message_id, status_changed FROM processing_ack WHERE status = 'processing'")
.all() as ProcessingClaim[];
}
@@ -262,10 +267,9 @@ export function migrateDeliveredTable(db: Database.Database): void {
}
}
// Adds series_id (groups all occurrences of a recurring task) to pre-existing
// messages_in tables. No-op on fresh installs where the column is in the schema.
// Backfills existing rows so cancel/pause/resume queries can rely on
// series_id IS NOT NULL.
// Adds columns added to messages_in after the initial v2 schema to
// pre-existing session DBs. No-op on fresh installs where the columns are
// in the baseline schema. Backfills existing rows so invariants hold.
export function migrateMessagesInTable(db: Database.Database): void {
const cols = new Set(
(db.prepare("PRAGMA table_info('messages_in')").all() as Array<{ name: string }>).map((c) => c.name),
@@ -275,4 +279,9 @@ export function migrateMessagesInTable(db: Database.Database): void {
db.prepare('UPDATE messages_in SET series_id = id WHERE series_id IS NULL').run();
db.prepare('CREATE INDEX IF NOT EXISTS idx_messages_in_series ON messages_in(series_id)').run();
}
if (!cols.has('trigger')) {
// All pre-existing rows got written with the old "every inbound wakes
// the agent" semantics, so backfill 1 and default 1 for new inserts.
db.prepare('ALTER TABLE messages_in ADD COLUMN trigger INTEGER NOT NULL DEFAULT 1').run();
}
}

25
src/db/sessions.ts
View File

@@ -27,6 +27,31 @@ export function findSession(messagingGroupId: string, threadId: string | null):
.get(messagingGroupId, 'active') as Session | undefined;
}
/**
* Session lookup scoped to a specific agent group. Needed when multiple
* agents are wired to the same messaging group + thread (fan-out) — the
* plain `findSession` would return whichever agent's session happened to
* be first and route to the wrong container.
*/
export function findSessionForAgent(
agentGroupId: string,
messagingGroupId: string,
threadId: string | null,
): Session | undefined {
if (threadId) {
return getDb()
.prepare(
"SELECT * FROM sessions WHERE agent_group_id = ? AND messaging_group_id = ? AND thread_id = ? AND status = 'active'",
)
.get(agentGroupId, messagingGroupId, threadId) as Session | undefined;
}
return getDb()
.prepare(
"SELECT * FROM sessions WHERE agent_group_id = ? AND messaging_group_id = ? AND thread_id IS NULL AND status = 'active'",
)
.get(agentGroupId, messagingGroupId) as Session | undefined;
}
/** Find an active session scoped to an agent group (ignoring messaging group). */
export function findSessionByAgentGroup(agentGroupId: string): Session | undefined {
return getDb()