Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

feat(layer4): live messages-table wiring for proximity triggers

Affaan Mustafa71d22d0a77b7
diff --git a/scripts/lib/control-pane/message-sink.js b/scripts/lib/control-pane/message-sink.js
new file mode 100644
index 000000000..e03c856e1
--- /dev/null
+++ b/scripts/lib/control-pane/message-sink.js
@@ -0,0 +1,70 @@
+'use strict';
+
+/**
+ * Concrete message sink for proximity triggers: delivers a session-to-session
+ * message through the canonical writer, the `ecc-tui messages send` CLI. The CLI
+ * owns the ecc2 session DB (the `messages` table the control pane reads), so we
+ * shell out to it rather than writing the SQLite directly and racing the daemon.
+ *
+ * Best-effort: if the binary is not found / the command fails, the call throws,
+ * and the dispatcher counts it as skipped — proximity never blocks on delivery.
+ * The command runner and binary path are injectable for tests.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// Proximity trigger type → ecc-tui message kind (value_enum on `--kind`).
+// A steer/hold is a collision warning; a transmit is a "what are you doing" query.
+const KIND_BY_TYPE = {
+ proximity_steer: 'conflict',
+ proximity_hold: 'conflict',
+ proximity_transmit: 'query'
+};
+
+/**
+ * Resolve the ecc-tui binary: explicit override, env var, a built target in the
+ * repo, then the bare name (hope it's on PATH).
+ */
+function resolveEccBin(deps = {}) {
+ if (deps.binPath) return deps.binPath;
+ if (process.env.ECC_TUI_BIN && process.env.ECC_TUI_BIN.trim()) return process.env.ECC_TUI_BIN.trim();
+ const repoRoot = deps.repoRoot || path.join(__dirname, '..', '..', '..');
+ for (const rel of ['ecc2/target/release/ecc-tui', 'ecc2/target/debug/ecc-tui']) {
+ const candidate = path.join(repoRoot, rel);
+ try {
+ if (fs.existsSync(candidate)) return candidate;
+ } catch {
+ /* ignore */
+ }
+ }
+ return 'ecc-tui';
+}
+
+/**
+ * Build the `messages send` argv for a proximity message.
+ */
+function buildSendArgs({ fromSession, toSession, content, msgType }) {
+ const kind = KIND_BY_TYPE[msgType] || 'query';
+ return ['messages', 'send', '--from', String(fromSession), '--to', String(toSession), '--kind', kind, '--text', String(content)];
+}
+
+/**
+ * Create a `sendMessage({ fromSession, toSession, content, msgType })` sink that
+ * delivers via `ecc-tui messages send`. Inject `runCommand(bin, args)` for tests.
+ */
+function createEccMessageSink(deps = {}) {
+ const run = deps.runCommand || ((bin, args) => execFileSync(bin, args, { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'] }));
+ const bin = resolveEccBin(deps);
+ return function sendMessage(message) {
+ run(bin, buildSendArgs(message));
+ };
+}
+
+module.exports = {
+ KIND_BY_TYPE,
+ resolveEccBin,
+ buildSendArgs,
+ createEccMessageSink
+};
diff --git a/scripts/lib/control-pane/proximity.js b/scripts/lib/control-pane/proximity.js
index bfe1ecf62..7e451baf0 100644
--- a/scripts/lib/control-pane/proximity.js
+++ b/scripts/lib/control-pane/proximity.js
@@ -179,11 +179,84 @@ function dispatchProximityTriggers(triggers, deps = {}) {
return { dispatched, skipped };
}
+/**
+ * Stateful dispatcher with per-trigger cooldown, so a collision that persists
+ * across many ticks fires once and then stays quiet until it clears or the
+ * cooldown lapses — agents get steered, not spammed. Inject `sendMessage`
+ * (e.g. createEccMessageSink) and optionally `now`/`cooldownMs` for tests.
+ */
+function createProximityDispatcher(deps = {}) {
+ const send = deps.sendMessage;
+ const cooldownMs = Number.isFinite(deps.cooldownMs) ? deps.cooldownMs : 5 * 60 * 1000;
+ const now = typeof deps.now === 'function' ? deps.now : () => Date.now();
+ const lastFired = new Map();
+ const keyOf = t => `${t.to}<-${t.from}:${t.type}`;
+
+ return {
+ dispatch(triggers) {
+ let dispatched = 0;
+ let suppressed = 0;
+ let skipped = 0;
+ for (const t of triggers || []) {
+ const key = keyOf(t);
+ const last = lastFired.get(key);
+ const ts = now();
+ if (last !== undefined && ts - last < cooldownMs) {
+ suppressed += 1;
+ continue;
+ }
+ if (typeof send !== 'function') {
+ skipped += 1;
+ continue;
+ }
+ try {
+ send({ fromSession: t.from, toSession: t.to, content: t.content, msgType: t.type });
+ lastFired.set(key, ts);
+ dispatched += 1;
+ } catch {
+ skipped += 1;
+ }
+ }
+ return { dispatched, suppressed, skipped };
+ },
+ reset() {
+ lastFired.clear();
+ }
+ };
+}
+
+/**
+ * One proximity tick: build the snapshot, then dispatch its triggers (steer the
+ * agents). `buildSnapshot()` returns a control-pane snapshot with a `proximity`
+ * field; `dispatcher` is a createProximityDispatcher. `dryRun` reports what
+ * would fire without sending. Both are injected so the CLI stays a thin wrapper
+ * and the logic is unit-testable.
+ */
+async function runProximityTick(deps = {}) {
+ const snapshot = await deps.buildSnapshot();
+ const prox = (snapshot && snapshot.proximity) || { advisories: [], triggers: [], counts: {} };
+ const triggers = prox.triggers || [];
+ let result;
+ if (deps.dryRun || !deps.dispatcher) {
+ result = { dispatched: 0, suppressed: 0, skipped: triggers.length, dryRun: Boolean(deps.dryRun) };
+ } else {
+ result = deps.dispatcher.dispatch(triggers);
+ }
+ return {
+ counts: prox.counts || {},
+ advisories: prox.advisories || [],
+ triggers,
+ result
+ };
+}
+
module.exports = {
buildProximitySnapshot,
sessionsToAgents,
defaultWorkingSetFor,
defaultChangedFilesFor,
parseDiffRanges,
- dispatchProximityTriggers
+ dispatchProximityTriggers,
+ createProximityDispatcher,
+ runProximityTick
};
diff --git a/scripts/proximity-tick.js b/scripts/proximity-tick.js
new file mode 100644
index 000000000..f50a492b1
--- /dev/null
+++ b/scripts/proximity-tick.js
@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Proximity tick — the live loop that turns the agent-space distance metric into
+ * action: scan the airspace from the control-pane state, then steer/transmit by
+ * sending session-to-session messages via `ecc-tui messages send`.
+ *
+ * node scripts/proximity-tick.js # one shot, deliver triggers
+ * node scripts/proximity-tick.js --dry-run # show what would fire, send nothing
+ * node scripts/proximity-tick.js --watch 30 # re-scan every 30s (dedupes per cooldown)
+ *
+ * Messages are internal ECC agent-to-agent coordination (the ecc2 `messages`
+ * table) — not any external channel.
+ */
+
+const { resolveControlPaneConfig, buildControlPaneSnapshot } = require('./lib/control-pane/state');
+const { createProximityDispatcher, runProximityTick } = require('./lib/control-pane/proximity');
+const { createEccMessageSink } = require('./lib/control-pane/message-sink');
+
+function parseArgs(argv) {
+ const args = argv.slice(2);
+ const parsed = { watchSec: 0, dryRun: false, json: false, help: false, dbPath: null, stateDbPath: null };
+ for (let i = 0; i < args.length; i += 1) {
+ const a = args[i];
+ if (a === '--help' || a === '-h') parsed.help = true;
+ else if (a === '--dry-run') parsed.dryRun = true;
+ else if (a === '--json') parsed.json = true;
+ else if (a === '--watch') {
+ const v = Number.parseInt(args[i + 1], 10);
+ if (!Number.isInteger(v) || v <= 0) throw new Error('--watch needs a positive seconds value');
+ parsed.watchSec = v;
+ i += 1;
+ } else if (a === '--db') {
+ parsed.dbPath = args[i + 1];
+ i += 1;
+ } else if (a === '--state-db') {
+ parsed.stateDbPath = args[i + 1];
+ i += 1;
+ } else {
+ throw new Error(`Unknown argument: ${a}`);
+ }
+ }
+ return parsed;
+}
+
+function showHelp() {
+ console.log(
+ [
+ 'Usage: node scripts/proximity-tick.js [--watch <seconds>] [--dry-run] [--json] [--db <path>] [--state-db <path>]',
+ '',
+ 'Scan agent proximity from the control-pane state and steer/transmit by sending',
+ 'internal session-to-session messages. --dry-run sends nothing; --watch loops.'
+ ].join('\n')
+ );
+}
+
+function report(tick, json) {
+ if (json) {
+ console.log(JSON.stringify(tick, null, 2));
+ return;
+ }
+ const c = tick.counts || {};
+ console.log(
+ `proximity: ${c.agents ?? 0} agents, ${c.advisories ?? 0} advisories (${c.resolutions ?? 0} resolutions) — ` +
+ `dispatched ${tick.result.dispatched}, suppressed ${tick.result.suppressed}, skipped ${tick.result.skipped}` +
+ (tick.result.dryRun ? ' [dry-run]' : '')
+ );
+ for (const adv of tick.advisories.slice(0, 8)) {
+ const who = adv.level === 'resolution' ? `${adv.steer} steers (yields to ${adv.hold})` : 'both transmit intent';
+ console.log(` - ${(adv.risk * 100) | 0}% ${adv.level}: ${adv.aLabel || adv.a} <-> ${adv.bLabel || adv.b} => ${who}`);
+ }
+}
+
+async function main() {
+ const opts = parseArgs(process.argv);
+ if (opts.help) {
+ showHelp();
+ return;
+ }
+ const config = resolveControlPaneConfig(opts);
+ const sink = opts.dryRun ? null : createEccMessageSink({});
+ const dispatcher = createProximityDispatcher({ sendMessage: sink });
+ const buildSnapshot = () =>
+ buildControlPaneSnapshot({
+ config,
+ dbPath: opts.dbPath || config.dbPath,
+ stateDbPath: opts.stateDbPath || config.stateDbPath,
+ includeProximity: true
+ });
+
+ const once = async () => report(await runProximityTick({ buildSnapshot, dispatcher, dryRun: opts.dryRun }), opts.json);
+
+ await once();
+ if (opts.watchSec > 0) {
+ const sleep = ms => new Promise(r => setTimeout(r, ms));
+ for (;;) {
+ await sleep(opts.watchSec * 1000);
+ await once();
+ }
+ }
+}
+
+if (require.main === module) {
+ main().catch(err => {
+ process.stderr.write(`proximity-tick error: ${err.message}\n`);
+ process.exit(1);
+ });
+}
+
+module.exports = { parseArgs };
diff --git a/tests/lib/control-pane-message-sink.test.js b/tests/lib/control-pane-message-sink.test.js
new file mode 100644
index 000000000..719f329b3
--- /dev/null
+++ b/tests/lib/control-pane-message-sink.test.js
@@ -0,0 +1,104 @@
+'use strict';
+/**
+ * Tests for the proximity message sink (ecc-tui messages send) and the
+ * deduping dispatcher.
+ */
+
+const assert = require('assert');
+
+const { KIND_BY_TYPE, buildSendArgs, createEccMessageSink, resolveEccBin } = require('../../scripts/lib/control-pane/message-sink');
+const { createProximityDispatcher } = require('../../scripts/lib/control-pane/proximity');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+ try {
+ fn();
+ console.log(` PASS ${name}`);
+ passed += 1;
+ } catch (e) {
+ console.log(` FAIL ${name}`);
+ console.log(` ${e.message}`);
+ failed += 1;
+ }
+}
+
+console.log('\n=== Testing proximity message sink ===\n');
+
+test('buildSendArgs: maps trigger type to message kind and shapes the CLI argv', () => {
+ const args = buildSendArgs({ fromSession: 'lead', toSession: 'worker', content: 'steer away', msgType: 'proximity_steer' });
+ assert.deepStrictEqual(args, ['messages', 'send', '--from', 'lead', '--to', 'worker', '--kind', 'conflict', '--text', 'steer away']);
+ assert.strictEqual(KIND_BY_TYPE.proximity_transmit, 'query');
+});
+
+test('createEccMessageSink: delivers via the injected runner with the resolved binary', () => {
+ const calls = [];
+ const send = createEccMessageSink({
+ binPath: '/fake/ecc-tui',
+ runCommand: (bin, args) => calls.push({ bin, args })
+ });
+ send({ fromSession: 'a', toSession: 'b', content: 'hello', msgType: 'proximity_transmit' });
+ assert.strictEqual(calls.length, 1);
+ assert.strictEqual(calls[0].bin, '/fake/ecc-tui');
+ assert.deepStrictEqual(calls[0].args.slice(0, 2), ['messages', 'send']);
+ assert.ok(calls[0].args.includes('query'), 'transmit maps to query kind');
+});
+
+test('createEccMessageSink: a failing command propagates (dispatcher will count it skipped)', () => {
+ const send = createEccMessageSink({
+ binPath: 'ecc-tui',
+ runCommand: () => {
+ throw new Error('ENOENT');
+ }
+ });
+ assert.throws(() => send({ fromSession: 'a', toSession: 'b', content: 'x', msgType: 'proximity_steer' }));
+});
+
+test('resolveEccBin: honors explicit override', () => {
+ assert.strictEqual(resolveEccBin({ binPath: '/x/ecc-tui' }), '/x/ecc-tui');
+});
+
+test('dispatcher: fires once then suppresses the same trigger within cooldown', () => {
+ let clock = 1000;
+ const sent = [];
+ const dispatcher = createProximityDispatcher({
+ sendMessage: m => sent.push(m),
+ cooldownMs: 1000,
+ now: () => clock
+ });
+ const triggers = [{ to: 'worker', from: 'lead', type: 'proximity_steer', content: 'steer' }];
+
+ const r1 = dispatcher.dispatch(triggers);
+ assert.strictEqual(r1.dispatched, 1);
+
+ clock = 1500; // within cooldown
+ const r2 = dispatcher.dispatch(triggers);
+ assert.strictEqual(r2.dispatched, 0);
+ assert.strictEqual(r2.suppressed, 1);
+
+ clock = 2600; // past cooldown
+ const r3 = dispatcher.dispatch(triggers);
+ assert.strictEqual(r3.dispatched, 1);
+
+ assert.strictEqual(sent.length, 2, 'sent twice total, the middle one suppressed');
+});
+
+test('dispatcher: distinct triggers are not cross-suppressed', () => {
+ const sent = [];
+ const dispatcher = createProximityDispatcher({ sendMessage: m => sent.push(m), now: () => 0 });
+ const r = dispatcher.dispatch([
+ { to: 'worker', from: 'lead', type: 'proximity_steer', content: 'a' },
+ { to: 'lead', from: 'worker', type: 'proximity_hold', content: 'b' }
+ ]);
+ assert.strictEqual(r.dispatched, 2);
+});
+
+test('dispatcher: no sink ⇒ skipped, never throws', () => {
+ const dispatcher = createProximityDispatcher({});
+ const r = dispatcher.dispatch([{ to: 'a', from: 'b', type: 'x', content: 'c' }]);
+ assert.strictEqual(r.skipped, 1);
+ assert.strictEqual(r.dispatched, 0);
+});
+
+console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+if (failed > 0) process.exit(1);
diff --git a/tests/lib/control-pane-proximity.test.js b/tests/lib/control-pane-proximity.test.js
index 556cb6542..c91603f46 100644
--- a/tests/lib/control-pane-proximity.test.js
+++ b/tests/lib/control-pane-proximity.test.js
@@ -5,7 +5,8 @@
const assert = require('assert');
-const { buildProximitySnapshot, sessionsToAgents, parseDiffRanges, dispatchProximityTriggers } = require('../../scripts/lib/control-pane/proximity');
+const { buildProximitySnapshot, sessionsToAgents, parseDiffRanges, dispatchProximityTriggers, createProximityDispatcher, runProximityTick } = require('../../scripts/lib/control-pane/proximity');
+const { parseArgs: parseTickArgs } = require('../../scripts/proximity-tick');
let passed = 0;
let failed = 0;
@@ -146,5 +147,41 @@ test('dispatchProximityTriggers: no sink ⇒ nothing thrown, all skipped', () =>
assert.strictEqual(r.skipped, 1);
});
+test('runProximityTick: dispatches the snapshot triggers via the dispatcher', async () => {
+ const snapshot = {
+ proximity: {
+ counts: { agents: 2, advisories: 1, resolutions: 1 },
+ advisories: [{ a: 'lead', b: 'worker', level: 'resolution', risk: 0.9, steer: 'worker', hold: 'lead' }],
+ triggers: [
+ { to: 'worker', from: 'lead', type: 'proximity_steer', content: 'steer' },
+ { to: 'lead', from: 'worker', type: 'proximity_hold', content: 'hold' }
+ ]
+ }
+ };
+ const sent = [];
+ const dispatcher = createProximityDispatcher({ sendMessage: m => sent.push(m), now: () => 0 });
+ const tick = await runProximityTick({ buildSnapshot: async () => snapshot, dispatcher });
+ assert.strictEqual(tick.result.dispatched, 2);
+ assert.strictEqual(sent.length, 2);
+});
+
+test('runProximityTick: dry-run sends nothing', async () => {
+ const snapshot = { proximity: { counts: {}, advisories: [], triggers: [{ to: 'a', from: 'b', type: 'x', content: 'c' }] } };
+ const sent = [];
+ const dispatcher = createProximityDispatcher({ sendMessage: m => sent.push(m) });
+ const tick = await runProximityTick({ buildSnapshot: async () => snapshot, dispatcher, dryRun: true });
+ assert.strictEqual(tick.result.dispatched, 0);
+ assert.strictEqual(tick.result.dryRun, true);
+ assert.strictEqual(sent.length, 0);
+});
+
+test('proximity-tick parseArgs: parses flags', () => {
+ const a = parseTickArgs(['node', 'proximity-tick.js', '--watch', '30', '--dry-run', '--db', '/x']);
+ assert.strictEqual(a.watchSec, 30);
+ assert.strictEqual(a.dryRun, true);
+ assert.strictEqual(a.dbPath, '/x');
+ assert.throws(() => parseTickArgs(['node', 'p', '--watch', 'nope']), /positive seconds/);
+});
+
console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
if (failed > 0) process.exit(1);