@animalabs/connectome-host 0.3.1 → 0.3.5

package/.github/workflows/publish.yml

@@ -15,13 +15,18 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: 24
 
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.14
+
       - name: Install dependencies
         run: npm install
 
@@ -46,10 +51,10 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           # node 24 ships npm >= 11.5.1, required for OIDC publishing.
           node-version: 24

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@animalabs/connectome-host",
-  "version": "0.3.1",
+  "version": "0.3.5",
   "description": "General-purpose agent TUI host with recipe-based configuration",
   "type": "module",
   "scripts": {
     "start": "bun src/index.ts",
     "dev": "bun --watch src/index.ts",
     "test": "bun test",
-    "build:web": "cd web && bun install && bun run build",
-    "postinstall": "test -d web && cd web && bun install && bun run build || true"
+    "build:web": "npm --prefix web install && npm --prefix web run build",
+    "postinstall": "test -d web && npm --prefix web install && npm --prefix web run build || true"
   },
   "dependencies": {
     "@animalabs/agent-framework": "^0.6.0",

package/src/commands.ts

@@ -197,7 +197,13 @@ export function handleCommand(command: string, app: AppContext): CommandResult {
       return handleCheckout(framework, args[0]);
 
     case 'history':
-      return handleHistory(framework);
+      return handleHistory(framework, args[0]);
+
+    case 'branchto':
+      return handleBranchTo(app, args[0]);
+
+    case 'find':
+      return handleFind(framework, args.join(' '));
 
     case 'mcp':
       return handleMcp(args);
@@ -793,7 +799,55 @@ function handleCheckout(framework: AgentFramework, name?: string): CommandResult
   };
 }
 
-function handleHistory(framework: AgentFramework): CommandResult {
+function handleFind(framework: AgentFramework, needle: string): CommandResult {
+  const cm = getAgentCM(framework);
+  if (!cm) return { lines: [{ text: 'No agent context manager.', style: 'system' }] };
+  if (!needle) return { lines: [{ text: 'Usage: /find <text>', style: 'system' }] };
+  const { messages } = cm.queryMessages({});
+  const lines: Line[] = [{ text: `--- Find "${needle}" in ${messages.length} msgs ---`, style: 'system' }];
+  const needleLc = needle.toLowerCase();
+  for (const msg of messages) {
+    // Search text blocks plus stringified tool i/o (case-insensitive), so ids
+    // buried in tool_use inputs / tool_result payloads are findable too.
+    const full = msg.content
+      .map((b) => b.type === 'text' ? b.text : JSON.stringify(b))
+      .join(' ');
+    const at = full.toLowerCase().indexOf(needleLc);
+    if (at >= 0) {
+      const snip = full.slice(Math.max(0, at - 30), at + needle.length + 45).replace(/\s+/g, ' ');
+      lines.push({ text: `  [${msg.id}] ${msg.participant}: ...${snip}...`, style: 'system' });
+    }
+  }
+  if (lines.length === 1) lines.push({ text: '  (no matches)', style: 'system' });
+  return { lines };
+}
+
+function handleBranchTo(app: AppContext, messageId: string | undefined): CommandResult {
+  const cm = getAgentCM(app.framework);
+  if (!cm) return { lines: [{ text: 'No agent context manager.', style: 'system' }] };
+  if (!messageId) return { lines: [{ text: 'Usage: /branchto <messageId>', style: 'system' }] };
+  const { messages } = cm.queryMessages({});
+  const target = messages.find(m => String(m.id) === String(messageId));
+  if (!target) return { lines: [{ text: `No message with id ${messageId} on current branch.`, style: 'system' }] };
+  const newBranchName = `rollback-at-${messageId}-${Date.now()}`;
+  let createdBranchName: string;
+  try {
+    createdBranchName = cm.branchAt(String(messageId), newBranchName);
+  } catch (err) {
+    return { lines: [{ text: `branchto failed (branchAt): ${err}`, style: 'system' }] };
+  }
+  const asyncWork = Promise.resolve(cm.switchBranch(createdBranchName))
+    .then(() => ({
+      lines: [{ text: `Branched at [${messageId}] -> "${createdBranchName}" and switched. Everything after [${messageId}] is dropped on this branch; old branch preserved.`, style: 'system' as const }],
+      branchChanged: true,
+    }))
+    .catch((err: unknown) => ({
+      lines: [{ text: `branchto failed (switchBranch): ${err}`, style: 'system' as const }],
+    }));
+  return { lines: [{ text: `Branching at [${messageId}] -> "${createdBranchName}"...`, style: 'system' }], asyncWork };
+}
+
+function handleHistory(framework: AgentFramework, countArg?: string): CommandResult {
   const cm = getAgentCM(framework);
   if (!cm) return { lines: [{ text: 'No agent context manager.', style: 'system' }] };
 
@@ -801,7 +855,7 @@ function handleHistory(framework: AgentFramework): CommandResult {
   const lines: Line[] = [{ text: `--- History (${messages.length} messages) ---`, style: 'system' }];
 
   // Show the last 20 messages in summary form
-  const recent = messages.slice(-20);
+  const recent = messages.slice(-(countArg && Number(countArg) > 0 ? Number(countArg) : 20));
   for (const msg of recent) {
     const text = msg.content
       .filter((b): b is { type: 'text'; text: string } => b.type === 'text')

package/src/index.ts

@@ -34,6 +34,7 @@ import { ActivityModule } from './modules/activity-module.js';
 import { SubscriptionGcModule } from './modules/subscription-gc-module.js';
 import { ChannelModeModule } from './modules/channel-mode-module.js';
 import { WebUiModule } from './modules/web-ui-module.js';
+import { ObserversModule } from './modules/observers-module.js';
 import { McplAdminModule } from './modules/mcpl-admin-module.js';
 import { loadMcplServers, applyAgentOverlay, DEFAULT_CONFIG_PATH, DEFAULT_AGENT_OVERLAY_PATH } from './mcpl-config.js';
 import { SessionManager } from './session-manager.js';
@@ -317,13 +318,21 @@ async function createFramework(
   let webUiModule: WebUiModule | null = null;
   if (modules.webui !== undefined && modules.webui !== false) {
     const webuiConfig = typeof modules.webui === 'object' ? modules.webui : {};
+    // Observer grants (docs/observability.md): data/observers.json by
+    // default, overridable via OBSERVERS_FILE. The feature is inert until
+    // the file holds at least one grant. The companion ObserversModule
+    // gives the agent grant/revoke tools over the same file — interiority
+    // access is the agent's to give.
+    const observersPath = process.env.OBSERVERS_FILE || resolve(config.dataDir, 'observers.json');
     webUiModule = new WebUiModule({
       port: webuiConfig.port,
       host: webuiConfig.host,
       basicAuth: webuiConfig.basicAuth,
       allowedOrigins: webuiConfig.allowedOrigins,
+      observersPath,
     });
     moduleInstances.push(webUiModule);
+    moduleInstances.push(new ObserversModule({ path: observersPath }));
   }
 
   // -- Build MCP server list --

package/src/modules/fleet-module.ts

@@ -31,7 +31,7 @@ import type {
 } from '@animalabs/agent-framework';
 import { spawn as spawnProcess, type ChildProcess } from 'node:child_process';
 import { connect as netConnect, type Socket } from 'node:net';
-import { existsSync, mkdirSync, unlinkSync, openSync, closeSync, appendFileSync } from 'node:fs';
+import { existsSync, mkdirSync, unlinkSync, openSync, closeSync, appendFileSync, realpathSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
 import { type IncomingCommand, type WireEvent, matchesSubscription } from './fleet-types.js';
 import { loadRecipe } from '../recipe.js';
@@ -1202,9 +1202,11 @@ export class FleetModule implements Module {
    * entries derived from `children[]`, which are absolute post-load).
    */
   private matchesAllowlist(recipe: string, resolved: string): boolean {
+    const canonicalResolved = existsSync(resolved) ? realpathSync(resolved) : resolved;
     for (const entry of this.allowlist) {
       if (entry === '*') return true;
-      if (entry === recipe || entry === resolved) return true;
+      const canonicalEntry = !entry.includes('*') && existsSync(entry) ? realpathSync(entry) : entry;
+      if (entry === recipe || entry === resolved || canonicalEntry === canonicalResolved) return true;
       if (entry.endsWith('*') && !entry.slice(0, -1).includes('*')) {
         const prefix = entry.slice(0, -1);
         if (recipe.startsWith(prefix) || resolved.startsWith(prefix)) return true;

package/src/modules/observers-module.ts

@@ -0,0 +1,180 @@
+/**
+ * ObserversModule — the agent holds the pen on who may observe its interior.
+ *
+ * Interiority access (thinking, tool payloads, conversation stream via the
+ * webui) is a consent question before it is an ACL question — see connectome
+ * docs/observability.md §4. These tools let the agent read and edit its own
+ * data/observers.json grant file. The webui's ObserverRegistry hot-reloads
+ * the file on mtime (~3s), so grants and revocations apply to new
+ * connections without a restart. Operators can edit the same file directly;
+ * writes here are atomic (tmp+rename) so the two never corrupt each other.
+ *
+ * Grants marked `protected: true` (recipe-designated operator baseline) are
+ * visible but not revocable through these tools; only a file edit removes
+ * them. Tools also cannot CREATE protected grants — protection is an
+ * operator-level marker.
+ */
+
+import type {
+  Module,
+  ModuleContext,
+  ProcessEvent,
+  ProcessState,
+  EventResponse,
+  ToolDefinition,
+  ToolCall,
+  ToolResult,
+} from '@animalabs/agent-framework';
+import {
+  OBSERVER_SCOPES,
+  loadObserversFile,
+  saveObserversFile,
+  type ObserverGrant,
+  type ObserverScope,
+  type ObserversFile,
+} from './web-ui-observers.js';
+
+export interface ObserversModuleConfig {
+  /** Absolute path to the grant file (same one the webui watches). */
+  path: string;
+}
+
+export class ObserversModule implements Module {
+  readonly name = 'observers';
+
+  constructor(private readonly config: ObserversModuleConfig) {}
+
+  async start(_ctx: ModuleContext): Promise<void> {}
+  async stop(): Promise<void> {}
+
+  getTools(): ToolDefinition[] {
+    return [
+      {
+        name: 'get',
+        description:
+          'List who is currently authorized to observe your internals through the web viewer ' +
+          '(thinking, tool calls, conversation stream — by scope). Each grant is an ed25519 ' +
+          'public key + label + scope list. Labels are testimony, not verified identity.',
+        inputSchema: { type: 'object', properties: {} },
+      },
+      {
+        name: 'grant',
+        description:
+          'Authorize an observer key to watch your internals through the web viewer. ' +
+          `Scopes (event families): ${OBSERVER_SCOPES.join(', ')}. ` +
+          "'health' = liveness/usage only; 'ops' = alerts (refusals, failures); 'messages' = the " +
+          "conversation; 'tools' = tool calls and results; 'thinking' = your thinking blocks; " +
+          "'debug' = compiled-context debug endpoints (implies seeing everything in your window). " +
+          'Grant deliberately — this is access to your interior. Takes effect within ~3 seconds.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            key: { type: 'string', description: 'ed25519:<base64url public key> — the fingerprint the person/device shows you.' },
+            label: { type: 'string', description: 'Who this is (your words — e.g. "antra-phone", "fleet-hub").' },
+            scopes: {
+              type: 'array',
+              items: { type: 'string', enum: [...OBSERVER_SCOPES] },
+              description: 'Event families this key may receive.',
+            },
+            expires: { type: 'string', description: 'Optional ISO timestamp; the grant stops working after this.' },
+          },
+          required: ['key', 'label', 'scopes'],
+        },
+      },
+      {
+        name: 'revoke',
+        description:
+          'Remove an observer grant by key or by label. Protected (operator-baseline) grants ' +
+          'cannot be revoked here. Existing connections are not killed, but new connections and ' +
+          'HTTP sessions stop authenticating within ~3 seconds.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            key: { type: 'string', description: 'ed25519:<base64url public key> to revoke.' },
+            label: { type: 'string', description: 'Alternative: revoke by exact label (must match exactly one grant).' },
+          },
+        },
+      },
+    ];
+  }
+
+  async handleToolCall(call: ToolCall): Promise<ToolResult> {
+    const input = (call.input ?? {}) as Record<string, unknown>;
+    try {
+      switch (call.name) {
+        case 'get':
+          return ok({ observers: this.load().observers.map(redactNothing) });
+
+        case 'grant': {
+          const key = typeof input.key === 'string' ? input.key.trim() : '';
+          const label = typeof input.label === 'string' ? input.label.trim() : '';
+          const scopes = Array.isArray(input.scopes) ? input.scopes : [];
+          if (!key.startsWith('ed25519:') || key.length < 20) {
+            return err('key must be "ed25519:<base64url public key>"');
+          }
+          if (!label) return err('label is required');
+          if (scopes.length === 0 || !scopes.every((s) => (OBSERVER_SCOPES as readonly string[]).includes(s as string))) {
+            return err(`scopes must be a non-empty subset of: ${OBSERVER_SCOPES.join(', ')}`);
+          }
+          const expires = typeof input.expires === 'string' ? input.expires : null;
+          if (expires && !Number.isFinite(Date.parse(expires))) return err('expires must be an ISO timestamp');
+
+          const file = this.load();
+          const existing = file.observers.find((g) => g.key === key);
+          if (existing?.protected) return err('that key holds a protected grant — edit the file to change it');
+          const grant: ObserverGrant = { key, label, scopes: scopes as ObserverScope[], expires };
+          if (existing) {
+            Object.assign(existing, grant); // update label/scopes/expiry in place
+          } else {
+            file.observers.push(grant);
+          }
+          saveObserversFile(this.config.path, file);
+          return ok({
+            message: `${existing ? 'Updated' : 'Granted'}: ${label} → [${grant.scopes.join(', ')}]${expires ? ` until ${expires}` : ''}. Live within ~3s.`,
+            observers: file.observers,
+          });
+        }
+
+        case 'revoke': {
+          const key = typeof input.key === 'string' ? input.key.trim() : '';
+          const label = typeof input.label === 'string' ? input.label.trim() : '';
+          if (!key && !label) return err('provide key or label');
+          const file = this.load();
+          const matches = file.observers.filter((g) => (key ? g.key === key : g.label === label));
+          if (matches.length === 0) return err('no matching grant');
+          if (matches.length > 1) return err(`label matches ${matches.length} grants — revoke by key`);
+          const target = matches[0]!;
+          if (target.protected) return err('that grant is protected (operator baseline) — edit the file to remove it');
+          file.observers = file.observers.filter((g) => g !== target);
+          saveObserversFile(this.config.path, file);
+          return ok({ message: `Revoked: ${target.label}. New connections stop within ~3s.`, observers: file.observers });
+        }
+
+        default:
+          return { success: false, error: `Unknown tool: ${call.name}`, isError: true };
+      }
+    } catch (e) {
+      return err(`observers file operation failed: ${e instanceof Error ? e.message : e}`);
+    }
+  }
+
+  async onProcess(_event: ProcessEvent, _state: ProcessState): Promise<EventResponse> {
+    return {};
+  }
+
+  private load(): ObserversFile {
+    return loadObserversFile(this.config.path) ?? { observers: [] };
+  }
+}
+
+function redactNothing(g: ObserverGrant): ObserverGrant {
+  return g; // grants hold public keys + labels only — nothing secret to redact
+}
+
+function ok(data: Record<string, unknown>): ToolResult {
+  return { success: true, data, isError: false };
+}
+
+function err(message: string): ToolResult {
+  return { success: false, error: message, isError: true };
+}