infinicode 2.3.5 → 2.4.0

package/dist/kernel/federation/federation.js

@@ -1,4 +1,5 @@
 import { MeshServer, MeshClient } from './transport-http.js';
+import { DASHBOARD_HTML } from './dashboard-html.js';
 import { PeerMesh } from './peer-mesh.js';
 import { EventBridge } from './event-bridge.js';
 import { ConfigSync } from './config-sync.js';
@@ -11,6 +12,9 @@ import { loadRole, saveRole, rolePreamble } from './role-context.js';
 import { discoverTailscalePeers } from './discovery.js';
 import { LanBeacon } from './lan-discovery.js';
 import { DEFAULT_MESH_PORT } from './types.js';
+import { createDefaultBackendRegistry } from '../agents/index.js';
+import { RotationState, selectChain } from '../agents/backends/rotation.js';
+import { loadCoderConfig } from '../agents/backends/profiles.js';
 export class Federation {
     deps;
     server;
@@ -30,6 +34,12 @@ export class Federation {
     configSync;
     autoUpdate;
     compute = new ComputeRouter();
+    /** Executors available on this node (native kernel + installed CLIs). */
+    backends;
+    /** Resolved coder profiles + rotation policy for this node. */
+    coderConfig;
+    /** Per-node round-robin cursor for backend rotation. */
+    rotationState = new RotationState();
     /** Local subscribers to the merged mesh frame stream (for MCP stream_activity). */
     frameSubs = new Set();
     /** Recent frames for catch-up. */
@@ -41,6 +51,8 @@ export class Federation {
     constructor(deps) {
         this.deps = deps;
         this.client = new MeshClient({ token: deps.options.token });
+        this.backends = deps.backends ?? createDefaultBackendRegistry();
+        this.coderConfig = loadCoderConfig(deps.options.coder);
         this.configSync = new ConfigSync({ logger: deps.logger, apply: deps.options.applyConfig });
         this.autoUpdate = new AutoUpdate({
             version: deps.options.version,
@@ -59,9 +71,13 @@ export class Federation {
             host: options.host,
             token: options.token,
             logger,
-            getManifest: () => buildManifest(identity, this.deps.describe()),
+            getManifest: () => buildManifest(identity, this.describeWithBackends()),
             getNodes: () => this.nodeStatuses(),
+            getStatus: () => this.statusSnapshot(),
             runCommand: (input) => this.deps.kernel.command(input),
+            commandGate: options.commandGate,
+            onApply: options.onApply,
+            dashboardHtml: options.dashboard ? DASHBOARD_HTML : undefined,
             onRpc: (env, remote) => this.onRpc(env, remote),
         });
         await this.server.start();
@@ -77,9 +93,15 @@ export class Federation {
         });
         this.mesh.start();
         // Bridge local kernel events → mesh stream (coalesced, animation-friendly).
+        // Also record into frameHistory so this node's own activity shows up in the
+        // /fed/status snapshot the dashboard + `robopark fleet` poll — not just in
+        // the live SSE push to connected harnesses.
         this.bridge = new EventBridge({
             nodeId: identity.nodeId,
-            emit: f => this.server?.broadcast(f),
+            emit: f => {
+                this.server?.broadcast(f);
+                this.ingestFrame(identity.nodeId, f);
+            },
         });
         this.unsub = this.deps.kernel.subscribeAll(e => this.bridge?.handle(e));
         // Telemetry heartbeat → stream a HardwareSnapshot on a fixed cadence.
@@ -107,7 +129,7 @@ export class Federation {
                 return reply(env, 'ack', self, { load: loadFromSnapshot(this.lastHw) });
             case 'hello':
                 this.learnInboundPeer(env, remote);
-                return reply(env, 'welcome', self, buildManifest(this.deps.identity, this.deps.describe()));
+                return reply(env, 'welcome', self, buildManifest(this.deps.identity, this.describeWithBackends()));
             case 'task.dispatch': {
                 // Non-blocking handoff: register the run, ack with a runId immediately,
                 // execute in the background, and let the caller follow it.
@@ -144,6 +166,29 @@ export class Federation {
                 const saved = saveRole(r);
                 return reply(env, 'ack', self, saved);
             }
+            case 'agents.list':
+                return reply(env, 'agents.offer', self, this.localAgents());
+            case 'message.send': {
+                // Wake / continue a CLI agent session on this node with a new message.
+                const d = env.data;
+                const runId = newId();
+                this.runs.set(runId, {
+                    runId,
+                    status: 'running',
+                    description: `msg→${(d.sessionId ?? '').slice(0, 8)}`,
+                    agent: d.agent,
+                    sessionId: d.sessionId,
+                    startedAt: Date.now(),
+                });
+                void this.runTaskAsync(runId, {
+                    description: 'message',
+                    capabilities: [],
+                    prompt: d.message,
+                    agent: d.agent,
+                    sessionId: d.sessionId,
+                });
+                return reply(env, 'message.accepted', self, { runId, sessionId: d.sessionId });
+            }
             default:
                 return reply(env, 'ack', self);
         }
@@ -207,12 +252,25 @@ export class Federation {
         if (!rec)
             return;
         const nodeId = this.deps.identity.nodeId;
-        this.server?.broadcast(frame('ev', nodeId, { k: 'RUN_STARTED', run: runId, desc: task.description }));
+        // Rotation is requested when a profile/strategy/route/policy is given, or the
+        // caller asks for 'auto'. Otherwise a concrete agent is a single fixed backend.
+        const wantsRotation = !!(task.profile || task.strategy || task.taskType || task.policy || task.agent === 'auto');
+        const backendId = task.agent && task.agent !== 'kernel' && task.agent !== 'auto' ? task.agent : null;
+        rec.agent = wantsRotation ? 'rotate' : (backendId ?? 'kernel');
+        this.server?.broadcast(frame('ev', nodeId, { k: 'RUN_STARTED', run: runId, desc: task.description, agent: rec.agent }));
         try {
-            const result = await this.runTask(task);
-            rec.status = result.status === 'COMPLETED' ? 'completed' : 'failed';
-            rec.missionId = result.missionId;
-            rec.outputs = result.outputs;
+            if (wantsRotation) {
+                await this.runViaBackendChain(runId, task, rec);
+            }
+            else if (backendId) {
+                await this.runViaBackend(runId, backendId, task, rec);
+            }
+            else {
+                const result = await this.runTask(task);
+                rec.status = result.status === 'COMPLETED' ? 'completed' : 'failed';
+                rec.missionId = result.missionId;
+                rec.outputs = result.outputs;
+            }
             rec.completedAt = Date.now();
         }
         catch (err) {
@@ -222,6 +280,90 @@ export class Federation {
         }
         this.server?.broadcast(frame('ev', nodeId, { k: 'RUN_COMPLETED', run: runId, status: rec.status }));
     }
+    /**
+     * Execute a dispatched task with a third-party CLI backend (Claude Code /
+     * Codex / OpenCode) instead of the native kernel. The backend's activity
+     * streams up the same mesh SSE feed (log/ev frames), and its native session id
+     * is captured on the RunRecord so the run can be followed and later messaged.
+     */
+    async runViaBackend(runId, backendId, task, rec) {
+        const res = await this.runBackendOnce(runId, backendId, task, task.model);
+        this.writeResult(rec, runId, backendId, res);
+    }
+    /** Stream one backend's frames up the mesh, tagged with the backend id. */
+    backendFrameSink(runId, backendId) {
+        const nodeId = this.deps.identity.nodeId;
+        return (f) => {
+            if (f.kind === 'log' && f.text) {
+                this.server?.broadcast(frame('log', nodeId, { run: runId, agent: backendId, line: f.text }));
+            }
+            else {
+                this.server?.broadcast(frame('ev', nodeId, { k: 'AGENT_OUTPUT', run: runId, agent: backendId, kind: f.kind, text: f.text }));
+            }
+        };
+    }
+    /** Run a single backend attempt. Never throws — a missing/unavailable backend
+     *  returns a failed result so a rotation chain can fall through to the next. */
+    async runBackendOnce(runId, backendId, task, model, args) {
+        const backend = this.backends.get(backendId);
+        if (!backend || !backend.available()) {
+            return { status: 'failed', error: `backend not available on this node: ${backendId}` };
+        }
+        const preamble = rolePreamble(loadRole());
+        try {
+            return await backend.run({ prompt: task.prompt, capabilities: task.capabilities, model: model ?? task.model, args, sessionId: task.sessionId }, { runId, rolePreamble: preamble, onFrame: this.backendFrameSink(runId, backendId) });
+        }
+        catch (err) {
+            return { status: 'failed', error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    /** Write a backend result onto the run record. */
+    writeResult(rec, runId, backendId, res) {
+        rec.agent = backendId;
+        rec.status = res.status;
+        rec.sessionId = res.sessionId;
+        rec.missionId = res.sessionId ?? runId;
+        rec.outputs = [{ status: res.status, content: res.content, error: res.error }];
+        rec.error = res.status === 'failed' ? res.error : undefined;
+    }
+    /**
+     * Resolve a rotation chain for the task and run it with fallback: try each
+     * profile's backend in order, streaming its activity; the first `completed`
+     * wins, otherwise fall through to the next. Composes task-type routing, policy
+     * tiers, round-robin and fallback (see agents/backends/rotation.ts).
+     */
+    async runViaBackendChain(runId, task, rec) {
+        const nodeId = this.deps.identity.nodeId;
+        const req = {
+            strategy: task.strategy,
+            profile: task.profile,
+            model: task.model,
+            taskType: task.taskType,
+            policy: task.policy,
+            backend: task.agent && task.agent !== 'auto' && task.agent !== 'kernel' ? task.agent : undefined,
+        };
+        const chain = selectChain(this.coderConfig, req, this.rotationState);
+        let last = { status: 'failed', error: 'no backend available in rotation chain' };
+        for (let i = 0; i < chain.length; i++) {
+            const step = chain[i];
+            this.server?.broadcast(frame('ev', nodeId, {
+                k: 'ROTATION_ATTEMPT', run: runId, agent: step.backend, model: step.model,
+                profile: step.profileName, attempt: i + 1, of: chain.length,
+            }));
+            last = await this.runBackendOnce(runId, step.backend, task, step.model, step.args);
+            if (last.status === 'completed') {
+                this.writeResult(rec, runId, step.backend, last);
+                return;
+            }
+            if (i < chain.length - 1) {
+                this.server?.broadcast(frame('ev', nodeId, {
+                    k: 'ROTATION_FALLBACK', run: runId, from: step.backend,
+                    next: chain[i + 1].backend, reason: (last.error ?? '').slice(0, 200),
+                }));
+            }
+        }
+        this.writeResult(rec, runId, chain[chain.length - 1]?.backend ?? 'kernel', last);
+    }
     // ── Outbound operations ──────────────────────────────────────────────────
     /**
      * Hand a task to the best-fit connected peer (compute-routed) or a named one.
@@ -292,6 +434,96 @@ export class Federation {
         const res = await this.client.rpc(peer.url, envelope('command', this.deps.identity.nodeId, { input }, { to: nodeId }));
         return res.data;
     }
+    // ── Agent mailbox (CLI sessions message each other) ────────────────────────
+    /**
+     * CLI agent sessions on THIS node — any run that used a CLI backend and
+     * captured a session id. Live while running, dormant (still resumable) once
+     * complete. Deduped by session, newest kept, so a session that's been messaged
+     * several times shows once.
+     */
+    localAgents() {
+        const self = this.deps.identity.nodeId;
+        const bySession = new Map();
+        for (const rec of this.runs.values()) {
+            if (!rec.sessionId || !rec.agent || rec.agent === 'kernel')
+                continue;
+            const existing = bySession.get(rec.sessionId);
+            if (existing && existing.lastActiveAt >= (rec.completedAt ?? rec.startedAt))
+                continue;
+            bySession.set(rec.sessionId, {
+                agentId: rec.runId,
+                nodeId: self,
+                backend: rec.agent,
+                sessionId: rec.sessionId,
+                address: `${self}/${rec.sessionId}`,
+                status: rec.status,
+                description: rec.description,
+                lastActiveAt: rec.completedAt ?? rec.startedAt,
+            });
+        }
+        return [...bySession.values()];
+    }
+    /** All messageable CLI agent sessions across the mesh (local + peers). */
+    async agents() {
+        const self = this.deps.identity.nodeId;
+        const out = [...this.localAgents()];
+        for (const peer of this.mesh?.connected() ?? []) {
+            try {
+                const res = await this.client.rpc(peer.url, envelope('agents.list', self, {}, { to: peer.nodeId }));
+                if (Array.isArray(res.data))
+                    out.push(...res.data);
+            }
+            catch {
+                // peer unreachable — skip
+            }
+        }
+        return out;
+    }
+    /** Resolve an address (`nodeId/sessionId`, a sessionId, or a runId) to a handle. */
+    async resolveAgent(address) {
+        const dir = await this.agents();
+        if (address.includes('/')) {
+            const slash = address.indexOf('/');
+            const nodeId = address.slice(0, slash);
+            const sessionId = address.slice(slash + 1);
+            return dir.find(a => a.nodeId === nodeId && a.sessionId === sessionId) ?? null;
+        }
+        return dir.find(a => a.agentId === address) ?? dir.find(a => a.sessionId === address) ?? null;
+    }
+    /**
+     * Message a CLI agent session — wherever it lives on the mesh. Resumes that
+     * exact session with the text (so the agent keeps its context) and returns a
+     * runId to follow the reply. This is how one CLI agent talks to another.
+     */
+    async sendTo(address, text, opts) {
+        const target = await this.resolveAgent(address);
+        if (!target)
+            return null;
+        const self = this.deps.identity.nodeId;
+        if (target.nodeId === self) {
+            const runId = newId();
+            this.runs.set(runId, {
+                runId, status: 'running', description: `msg→${target.sessionId.slice(0, 8)}`,
+                agent: target.backend, sessionId: target.sessionId, startedAt: Date.now(),
+            });
+            void this.runTaskAsync(runId, {
+                description: 'message', capabilities: [], prompt: text,
+                agent: target.backend, sessionId: target.sessionId,
+            });
+            const record = opts?.wait ? await this.awaitRun(runId, opts.timeoutMs ?? 120_000) : undefined;
+            return { runId, nodeId: self, record };
+        }
+        const peer = this.mesh?.get(target.nodeId);
+        if (!peer)
+            return null;
+        const res = await this.client.rpc(peer.url, envelope('message.send', self, {
+            sessionId: target.sessionId, agent: target.backend, message: text, from: self,
+        }, { to: target.nodeId }));
+        const runId = res.data.runId;
+        this.dispatchedRuns.set(runId, target.nodeId);
+        const record = opts?.wait ? await this.awaitRun(runId, opts?.timeoutMs ?? 120_000) : undefined;
+        return { runId, nodeId: target.nodeId, record };
+    }
     /** Hub: publish shared config (providers/API keys/policy) to the fleet. */
     publishConfig(cfg) {
         return this.configSync.publish(cfg);
@@ -406,20 +638,48 @@ export class Federation {
         this.lan.start();
     }
     // ── Views ────────────────────────────────────────────────────────────────
+    /** Backend ids this node can execute tasks with ('kernel' + installed CLIs). */
+    availableBackends() {
+        return this.backends.availableIds();
+    }
+    /**
+     * The manifest inputs augmented with `backend:<id>` capability tags for each
+     * installed executor. This lets the compute-router match a task that asks for
+     * a specific agent (e.g. capabilities:['backend:claude']) to a node that
+     * actually has that CLI — without changing the caller's describe().
+     */
+    describeWithBackends() {
+        const d = this.deps.describe();
+        const tags = this.backends.availableIds().map(id => `backend:${id}`);
+        return { ...d, capabilities: [...d.capabilities, ...tags] };
+    }
     /** Neutral node-status list (self + peers) — feeds the mesh map. */
     nodeStatuses() {
-        const d = this.deps.describe();
+        const d = this.describeWithBackends();
         const self = selfNodeStatus(this.deps.identity, this.lastHw ?? this.telemetry.collect(), {
             version: d.version,
             capabilities: d.capabilities,
             commands: d.commands,
-        });
+        }, loadRole()?.site);
         const peers = (this.mesh?.list() ?? []).map(nodeStatusFromPeer);
         return [self, ...peers];
     }
     peers() {
         return this.mesh?.list() ?? [];
     }
+    /** Consolidated fleet view for the dashboard + `robopark fleet` (GET /fed/status). */
+    statusSnapshot() {
+        return {
+            self: buildManifest(this.deps.identity, this.describeWithBackends()),
+            role: this.getRole(),
+            nodes: this.nodeStatuses(),
+            hardware: this.lastHw,
+            runs: this.localRuns(),
+            agents: this.localAgents(),
+            activity: this.recentFrames(60),
+            ts: Date.now(),
+        };
+    }
     /** Latest local hardware snapshot (for the MOLTFED connector / panels). */
     latestHardware() {
         return this.lastHw;

package/dist/kernel/federation/moltfed-adapter.js

@@ -17,6 +17,7 @@ export function toNodesStatus(statuses) {
             // extra infinicode fields are ignored by InfiniBot but useful to richer UIs
             role: s.role,
             load: s.load,
+            site: s.site,
         })),
     };
 }

package/dist/kernel/federation/telemetry.d.ts

@@ -18,4 +18,4 @@ export declare function selfNodeStatus(identity: NodeIdentity, hw: HardwareSnaps
     version: string;
     capabilities: NodeStatus['capabilities'];
     commands: string[];
-}): NodeStatus;
+}, site?: string): NodeStatus;

package/dist/kernel/federation/telemetry.js

@@ -120,7 +120,7 @@ export function nodeStatusFromPeer(peer) {
     };
 }
 /** Local node's own status entry. */
-export function selfNodeStatus(identity, hw, manifest) {
+export function selfNodeStatus(identity, hw, manifest, site) {
     return {
         nodeId: identity.nodeId,
         displayName: identity.displayName,
@@ -134,5 +134,6 @@ export function selfNodeStatus(identity, hw, manifest) {
         connectedAtMs: Date.now(),
         load: loadFromSnapshot(hw),
         lastSeenAt: Date.now(),
+        site,
     };
 }

package/dist/kernel/federation/transport-http.d.ts

@@ -9,9 +9,22 @@ export interface MeshServerOptions {
     getManifest: () => NodeManifest;
     /** Optional: full mesh view (self + peers) for the GET /fed/nodes probe. */
     getNodes?: () => unknown;
+    /** Optional: consolidated fleet snapshot (self + nodes + hardware + roles +
+     *  runs + recent activity) for the dashboard and `robopark fleet` (GET /fed/status). */
+    getStatus?: () => unknown;
     /** Optional: run a kernel slash-command on this node (POST /fed/command).
-     *  Powers the in-TUI mesh command palette. */
+     *  Powers the in-TUI mesh command palette + the dashboard's action buttons. */
     runCommand?: (input: string) => Promise<unknown>;
+    /** Optional gate on POST /fed/command inputs. Returns {ok:false,reason} to
+     *  reject — used to keep an unauthenticated, network-exposed node read-only. */
+    commandGate?: (input: string) => {
+        ok: boolean;
+        reason?: string;
+    };
+    /** Optional: publish this node's shared config to the fleet (POST /fed/apply). */
+    onApply?: () => Promise<unknown> | unknown;
+    /** Optional: static HTML for the control dashboard, served at GET / and /ui. */
+    dashboardHtml?: string;
     onRpc: RpcHandler;
     logger: Logger;
 }
@@ -25,6 +38,9 @@ export declare class MeshServer {
     start(): Promise<void>;
     /** Push a frame to every connected stream subscriber. */
     broadcast(frame: StreamFrame): void;
+    /** Token presented on a request — Bearer header (peers/CLI) OR ?token= query
+     *  (browsers, which can't set headers on navigation or EventSource). */
+    private presentedToken;
     private authOk;
     private handle;
     private openStream;

package/dist/kernel/federation/transport-http.js

@@ -14,7 +14,16 @@
  * MeshClient/MeshServer shape later for deep InfiniBot-fabric interop.
  */
 import { createServer } from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
 import { frameToSSE, parseSSE } from './protocol.js';
+/** Constant-time string compare — avoids leaking the token via response timing. */
+function safeEqual(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (ab.length !== bb.length)
+        return false;
+    return timingSafeEqual(ab, bb);
+}
 export class MeshServer {
     opts;
     server;
@@ -51,19 +60,67 @@ export class MeshServer {
             }
         }
     }
+    /** Token presented on a request — Bearer header (peers/CLI) OR ?token= query
+     *  (browsers, which can't set headers on navigation or EventSource). */
+    presentedToken(req) {
+        const h = req.headers['authorization'];
+        if (typeof h === 'string' && h.startsWith('Bearer '))
+            return h.slice(7);
+        const url = req.url ?? '';
+        const q = url.indexOf('?');
+        if (q >= 0) {
+            const t = new URLSearchParams(url.slice(q + 1)).get('token');
+            if (t)
+                return t;
+        }
+        return undefined;
+    }
     authOk(req) {
         if (!this.opts.token)
             return true;
-        const h = req.headers['authorization'];
-        return typeof h === 'string' && h === `Bearer ${this.opts.token}`;
+        const presented = this.presentedToken(req);
+        return presented !== undefined && safeEqual(presented, this.opts.token);
     }
     handle(req, res) {
         const url = req.url ?? '/';
+        const path = url.split('?', 1)[0];
         if (!this.authOk(req)) {
             res.writeHead(401).end('unauthorized');
             return;
         }
         const remote = req.socket.remoteAddress ?? 'unknown';
+        // Control dashboard (single self-contained page). Same-origin fetches carry
+        // the ?token= through, so no CORS is opened.
+        if (req.method === 'GET' && (path === '/' || path === '/ui' || path === '/dashboard')) {
+            if (!this.opts.dashboardHtml) {
+                res.writeHead(404).end('dashboard not enabled (start with --dashboard)');
+                return;
+            }
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+            res.end(this.opts.dashboardHtml);
+            return;
+        }
+        if (req.method === 'GET' && path === '/fed/status') {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify(this.opts.getStatus?.() ?? {}));
+            return;
+        }
+        if (req.method === 'POST' && path.startsWith('/fed/apply')) {
+            if (!this.opts.onApply) {
+                res.writeHead(404).end('no apply handler');
+                return;
+            }
+            Promise.resolve(this.opts.onApply())
+                .then(result => {
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify(result ?? { ok: true }));
+            })
+                .catch(err => {
+                this.opts.logger.warn(`[federation] apply error: ${err instanceof Error ? err.message : String(err)}`);
+                res.writeHead(500).end('apply failed');
+            });
+            return;
+        }
         if (req.method === 'GET' && url.startsWith('/fed/manifest')) {
             res.writeHead(200, { 'content-type': 'application/json' });
             res.end(JSON.stringify(this.opts.getManifest()));
@@ -93,6 +150,12 @@ export class MeshServer {
                     res.writeHead(400).end('bad json');
                     return;
                 }
+                const gate = this.opts.commandGate?.(input);
+                if (gate && !gate.ok) {
+                    res.writeHead(403, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, text: gate.reason ?? 'command not permitted on this node' }));
+                    return;
+                }
                 const result = await this.opts.runCommand(input);
                 res.writeHead(200, { 'content-type': 'application/json' });
                 res.end(JSON.stringify(result ?? { ok: false, text: 'no result' }));

package/dist/kernel/federation/types.d.ts

@@ -125,8 +125,12 @@ export interface NodeStatus {
     /** 0–100 rough load, from the latest hardware snapshot. */
     load?: number;
     lastSeenAt: number;
+    /** Physical deployment this node belongs to (e.g. "Tel Aviv"). Sourced from
+     *  this node's own RoleContext.site — lets a fleet UI group by location as
+     *  a customer scales from one site to many, without per-site bespoke code. */
+    site?: string;
 }
-export type MessageKind = 'hello' | 'welcome' | 'heartbeat' | 'manifest' | 'task.dispatch' | 'task.accepted' | 'task.status' | 'task.result' | 'task.cancel' | 'command' | 'command.result' | 'config.request' | 'config.offer' | 'update.announce' | 'update.request' | 'role.get' | 'role.set' | 'event' | 'telemetry' | 'ack' | 'error';
+export type MessageKind = 'hello' | 'welcome' | 'heartbeat' | 'manifest' | 'task.dispatch' | 'task.accepted' | 'task.status' | 'task.result' | 'task.cancel' | 'command' | 'command.result' | 'config.request' | 'config.offer' | 'update.announce' | 'update.request' | 'role.get' | 'role.set' | 'agents.list' | 'agents.offer' | 'message.send' | 'message.accepted' | 'event' | 'telemetry' | 'ack' | 'error';
 /** A dispatched/received task run — tracked for non-blocking handoff + monitoring. */
 export interface RunRecord {
     runId: string;
@@ -141,11 +145,52 @@ export interface RunRecord {
     error?: string;
     startedAt: number;
     completedAt?: number;
+    /** Which executor ran this — 'kernel' (native) or a CLI backend id. */
+    agent?: string;
+    /** The executor's native session id (CLI backends) — enables resume + messaging. */
+    sessionId?: string;
+}
+/**
+ * A messageable CLI agent session on the mesh. Any run that used a CLI backend
+ * and captured a native session id becomes an addressable agent — live while
+ * running, dormant (but still resumable) once complete. Its address is
+ * `nodeId/sessionId`; sending a message resumes that exact CLI session.
+ */
+export interface AgentHandle {
+    /** runId that created/owns the session (the follow handle). */
+    agentId: string;
+    /** node holding the session. */
+    nodeId: string;
+    /** which CLI backend runs it — 'claude' | 'codex' | 'opencode'. */
+    backend: string;
+    /** the CLI's native session id (what resume targets). */
+    sessionId: string;
+    /** routable address: `${nodeId}/${sessionId}`. */
+    address: string;
+    status: 'running' | 'completed' | 'failed';
+    description: string;
+    lastActiveAt: number;
+}
+/** Result of a one-shot `infinicode maintain` run, pushed to an InfiniBot gateway. */
+export interface MaintenanceReport {
+    nodeId: string;
+    role: string;
+    site?: string;
+    taskName: string;
+    startedAt: number;
+    finishedAt: number;
+    durationMs: number;
+    ok: boolean;
+    summary: string;
+    errors?: string[];
 }
 /** Persistent per-device role + server-architecture context. */
 export interface RoleContext {
     /** e.g. "RoboPanda" — the identity a spawned agent adopts. */
     role: string;
+    /** Physical deployment/location this device belongs to (e.g. "Tel Aviv").
+     *  Optional — a single-site deployment can leave it unset. */
+    site?: string;
     /** Free-text description of this device's job + the wider architecture. */
     architecture?: string;
     /** Extra structured context injected into every task run on this node. */