@animalabs/connectome-host 0.7.2 → 0.7.3

package/src/modules/identity-module.ts

@@ -0,0 +1,274 @@
+/**
+ * Agent identity — the agent's own archipelago-home principal (connectome
+ * docs/home-node.md §4).
+ *
+ * Two audiences, deliberately separated:
+ *
+ * HOST-FACING (this module's public methods): the deployment holds an
+ * ed25519 keypair in the data dir; `accessFor(audience)` exchanges a
+ * key-proof at the home node for a short-lived aid1 token, and
+ * `httpAuthFor(audience)` wraps it for HTTP. This is plumbing other host
+ * pieces call — the MCPL transport's per-dial credential provider, future
+ * HTTP helpers. Credentials live and die HERE.
+ *
+ * AGENT-FACING (utilities, via the `utils` meta-tool): deliberately small
+ * and deliberately boring — `status` ("who am I registered as, where is
+ * that recognized") and `accept_invite` ("register with an invitation code
+ * from your operator"). No tokens, keys, proofs, or signing in any
+ * agent-visible name, description, or result: the agent asks for access by
+ * name (`mcpl_deploy … access: "eidoverse"`); the host does the rest. This
+ * is both hygiene (credentials never enter model context, so they never
+ * enter chronicles, compression, or channels) and framing (an agent
+ * narrating credential mechanics reads as exfiltration to safety
+ * classifiers — so it simply never has them to narrate).
+ *
+ * Utilities-only module: enrollment is one-time; it costs no tool slots.
+ * Wire statements per the home-node spec (archipelago-home
+ * src/statements.ts is the source of truth — re-copy, don't fork).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+import {
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  sign as cryptoSign,
+  type KeyObject,
+} from 'node:crypto';
+import type {
+  Module,
+  ModuleContext,
+  ToolCall,
+  ToolResult,
+  ToolDefinition,
+} from '@animalabs/agent-framework';
+
+export interface IdentityModuleConfig {
+  /** ed25519 PKCS#8 PEM, generated on first use, 0600. dataDir-anchored:
+   *  identity is per-deployment, not per-session. */
+  keyPath: string;
+  /** Home node domain (the trust anchor), e.g. `id.animalabs.ai`. */
+  home: string;
+  /** Audience assumed when none is named. */
+  defaultAudience?: string;
+  /** Injectable for tests. */
+  fetchImpl?: typeof fetch;
+}
+
+/** Persisted beside the key after a successful registration. */
+interface IdentityRecord {
+  sub: string;
+  name: string;
+  home: string;
+  enrolledAt: string;
+}
+
+function ok(data: unknown): ToolResult {
+  return { success: true, data };
+}
+function fail(text: string): ToolResult {
+  return { success: false, error: text, isError: true };
+}
+
+export class IdentityModule implements Module {
+  readonly name = 'identity';
+  private readonly recordPath: string;
+
+  constructor(private readonly config: IdentityModuleConfig) {
+    this.recordPath = config.keyPath.replace(/\.pem$/, '') + '.json';
+  }
+
+  async start(_ctx: ModuleContext): Promise<void> {}
+  async stop(): Promise<void> {}
+
+  getTools(): ToolDefinition[] {
+    return []; // utilities-only, by design — see module header
+  }
+
+  getUtilities(): ToolDefinition[] {
+    return [
+      {
+        name: 'status',
+        description:
+          'Your registered identity: the name and id services know you by, and which ' +
+          'identity service vouches for it. Access to networked places (worlds etc.) is ' +
+          'managed by the host from this — you never handle credentials yourself.',
+        inputSchema: { type: 'object', properties: {} },
+      },
+      {
+        name: 'accept_invite',
+        description:
+          'Register with the identity service using an invitation code from your operator. ' +
+          'One-time: it establishes the name services will know you by. After this, the ' +
+          'host handles access automatically (e.g. mcpl_deploy with an `access` name).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            invite: { type: 'string', description: 'Invitation code from your operator.' },
+            name: { type: 'string', description: 'The display name you want (must be unused).' },
+          },
+          required: ['invite', 'name'],
+        },
+      },
+    ];
+  }
+
+  async handleToolCall(call: ToolCall): Promise<ToolResult> {
+    try {
+      switch (call.name) {
+        case 'status':
+          return this.status();
+        case 'accept_invite':
+          return await this.acceptInvite(call.input as { invite?: unknown; name?: unknown });
+        default:
+          return fail(`Unknown identity utility: ${call.name}`);
+      }
+    } catch (err) {
+      return fail(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  async onProcess(): Promise<Record<string, never>> {
+    return {};
+  }
+
+  // ────────────────────────────────────────────────────────────────────────
+  // Host-facing API — credential plumbing. Nothing below ever reaches model
+  // context; callers (MCPL dial provider, HTTP helpers) consume the values
+  // outside the agent's view.
+  // ────────────────────────────────────────────────────────────────────────
+
+  /** True once this deployment holds a registered principal. */
+  isEnrolled(): boolean {
+    return this.record() !== null;
+  }
+
+  /** The registered principal id (`agent:<name>@<domain>`), if any. */
+  sub(): string | null {
+    return this.record()?.sub ?? null;
+  }
+
+  /**
+   * Exchange a key-proof for a fresh aid1 token for `audience`. Called per
+   * MCPL dial (connect + every reconnect) and by HTTP helpers — which is
+   * what lets audience tokens be short-lived. Throws with an actionable
+   * message when unregistered or refused.
+   */
+  async accessFor(audience?: string): Promise<string> {
+    const aud = audience ?? this.config.defaultAudience;
+    if (!aud) throw new Error('identity: no audience named and none configured');
+    if (!this.record()) {
+      throw new Error(
+        `identity: not registered with ${this.config.home} — the agent needs to accept an operator invite first (utils run identity--accept_invite)`,
+      );
+    }
+    const key = this.loadOrCreateKey();
+    const timestamp = new Date().toISOString();
+    const statement = `archipelago-token|v1|${this.config.home}|${aud}|${timestamp}`;
+    const proof = cryptoSign(null, Buffer.from(statement, 'utf8'), key.privateKey).toString('base64url');
+    const { status, json } = await this.post('/token', { id: key.id, audience: aud, timestamp, proof });
+    if (status !== 200 || typeof json.token !== 'string') {
+      throw new Error(`identity: ${this.config.home} refused access to "${aud}" (${status}): ${String(json.error ?? 'unknown')}`);
+    }
+    return json.token;
+  }
+
+  /** Authorization header for HTTP calls to an audience's API. */
+  async httpAuthFor(audience?: string): Promise<Record<string, string>> {
+    return { authorization: `Bearer ${await this.accessFor(audience)}` };
+  }
+
+  // ── key material ──
+
+  private loadOrCreateKey(): { privateKey: KeyObject; id: string } {
+    let privateKey: KeyObject;
+    if (existsSync(this.config.keyPath)) {
+      privateKey = createPrivateKey(readFileSync(this.config.keyPath, 'utf8'));
+    } else {
+      privateKey = generateKeyPairSync('ed25519').privateKey;
+      mkdirSync(dirname(this.config.keyPath), { recursive: true });
+      writeFileSync(this.config.keyPath, privateKey.export({ format: 'pem', type: 'pkcs8' }), { mode: 0o600 });
+    }
+    const spki = createPublicKey(privateKey).export({ format: 'der', type: 'spki' }) as Buffer;
+    return { privateKey, id: `ed25519:${spki.subarray(spki.length - 32).toString('base64url')}` };
+  }
+
+  private record(): IdentityRecord | null {
+    try {
+      return JSON.parse(readFileSync(this.recordPath, 'utf8')) as IdentityRecord;
+    } catch {
+      return null;
+    }
+  }
+
+  private saveRecord(rec: IdentityRecord): void {
+    writeFileSync(this.recordPath + '.tmp', JSON.stringify(rec, null, 2) + '\n');
+    renameSync(this.recordPath + '.tmp', this.recordPath);
+  }
+
+  private async post(path: string, body: unknown): Promise<{ status: number; json: Record<string, unknown> }> {
+    const f = this.config.fetchImpl ?? fetch;
+    const res = await f(`https://${this.config.home}${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return { status: res.status, json: (await res.json().catch(() => ({}))) as Record<string, unknown> };
+  }
+
+  // ── agent-facing utilities ──
+
+  private status(): ToolResult {
+    // Key material is deliberately created lazily here too, so `status` is
+    // always safe to call — but none of it surfaces in the result.
+    this.loadOrCreateKey();
+    const rec = this.record();
+    return ok(
+      rec
+        ? {
+            registeredAs: rec.name,
+            id: rec.sub,
+            recognizedBy: rec.home,
+            since: rec.enrolledAt,
+            note: 'Access to services is handled by the host automatically (e.g. mcpl_deploy with an `access` name).',
+          }
+        : {
+            registeredAs: null,
+            note: `Not registered with ${this.config.home} yet — ask your operator for an invitation code, then use accept_invite.`,
+          },
+    );
+  }
+
+  private async acceptInvite(input: { invite?: unknown; name?: unknown }): Promise<ToolResult> {
+    if (typeof input.invite !== 'string' || typeof input.name !== 'string') {
+      return fail('accept_invite needs { invite, name }');
+    }
+    const existing = this.record();
+    if (existing) {
+      return fail(`Already registered as "${existing.name}" (${existing.sub}) — registration is one-time.`);
+    }
+    const key = this.loadOrCreateKey();
+    const timestamp = new Date().toISOString();
+    const statement = `archipelago-enroll|v1|${this.config.home}|${input.invite}|${timestamp}`;
+    const proof = cryptoSign(null, Buffer.from(statement, 'utf8'), key.privateKey).toString('base64url');
+    const { status, json } = await this.post('/enroll', {
+      invite: input.invite,
+      id: key.id,
+      name: input.name,
+      timestamp,
+      proof,
+    });
+    if (status !== 200 || typeof json.sub !== 'string') {
+      return fail(`Registration refused (${status}): ${String(json.error ?? 'unknown')}`);
+    }
+    this.saveRecord({ sub: json.sub, name: input.name, home: this.config.home, enrolledAt: timestamp });
+    // Note what is NOT returned: the first token the home node minted. The
+    // host fetches its own, fresh, per use — the agent never holds one.
+    return ok({
+      registeredAs: input.name,
+      id: json.sub,
+      recognizedBy: this.config.home,
+      note: 'Done — the host now handles access for you automatically.',
+    });
+  }
+}

package/src/modules/mcpl-admin-module.ts

@@ -51,6 +51,11 @@ export interface McplAdminModuleConfig {
   overlayPath?: string;
   /** Path to the human-owned server config file (read-only here). */
   configPath?: string;
+  /** Where these operations surface to the model: 'tools' (default — four
+   *  first-class slots, exactly the historical behavior) or 'utilities'
+   *  (behind the framework's single `utils` meta-tool: mcpl management is a
+   *  rare operation and needn't tax every inference with four schemas). */
+  surface?: 'tools' | 'utilities';
 }
 
 function ok(text: string): ToolResult {
@@ -69,10 +74,13 @@ export class McplAdminModule implements Module {
   private configPath: string;
   private timeZone: string;
 
+  private surface: 'tools' | 'utilities';
+
   constructor(config?: McplAdminModuleConfig) {
     this.overlayPath = config?.overlayPath ?? DEFAULT_AGENT_OVERLAY_PATH;
     this.configPath = config?.configPath ?? DEFAULT_CONFIG_PATH;
     this.timeZone = resolveTimeZone(config?.timeZone);
+    this.surface = config?.surface ?? 'tools';
   }
 
   /** Post-creation wiring (called from index.ts, mirrors ActivityModule.setFramework). */
@@ -80,6 +88,15 @@ export class McplAdminModule implements Module {
     this.framework = framework;
   }
 
+  /** Optional identity plumbing (index.ts wires it when the recipe enables
+   *  the identity module): lets deployed servers name an `access` grant that
+   *  the host turns into a per-dial credential provider. The agent names the
+   *  access; credentials never surface. */
+  private identity: { accessFor(audience?: string): Promise<string> } | null = null;
+  setIdentity(identity: { accessFor(audience?: string): Promise<string> } | null): void {
+    this.identity = identity;
+  }
+
   async start(_ctx: ModuleContext): Promise<void> {}
 
   async stop(): Promise<void> {
@@ -87,6 +104,16 @@ export class McplAdminModule implements Module {
   }
 
   getTools(): ToolDefinition[] {
+    return this.surface === 'tools' ? this.definitions() : [];
+  }
+
+  /** Same definitions, same handler — the surface flag only decides whether
+   *  they cost four slots or ride the `utils` meta-tool. */
+  getUtilities(): ToolDefinition[] {
+    return this.surface === 'utilities' ? this.definitions() : [];
+  }
+
+  private definitions(): ToolDefinition[] {
     return [
       {
         name: 'mcpl_list',
@@ -111,7 +138,8 @@ export class McplAdminModule implements Module {
             args: { type: 'array', items: { type: 'string' }, description: 'Arguments for the command.' },
             env: { type: 'object', description: 'Environment variables for the spawned process.' },
             url: { type: 'string', description: 'WebSocket URL (websocket transport). Mutually exclusive with command.' },
-            token: { type: 'string', description: 'Bearer token for WebSocket auth.' },
+            token: { type: 'string', description: 'Bearer token for WebSocket auth (only when the operator hands you one — prefer `access`).' },
+            access: { type: 'string', description: 'Name of a host-managed access grant (e.g. "eidoverse"): the host attaches your standing credentials to the connection automatically. Nothing for you to obtain or handle.' },
             toolPrefix: { type: 'string', description: 'Tool namespace prefix. Default: mcpl--<id>.' },
             reconnect: { type: 'boolean', description: 'Auto-reconnect on transport failure (default false). Note: does NOT respawn a crashed child — use mcpl_restart for that.' },
             enabledFeatureSets: { type: 'array', items: { type: 'string' } },
@@ -251,6 +279,15 @@ export class McplAdminModule implements Module {
     if (Array.isArray(input.args)) entry.args = input.args.map(String);
     if (input.env && typeof input.env === 'object') entry.env = input.env as Record<string, string>;
     if (typeof input.token === 'string') entry.token = input.token;
+    if (typeof input.access === 'string' && input.access.trim()) {
+      if (!this.identity) {
+        return fail(
+          '`access` names a host-managed access grant, but this deployment has no identity ' +
+          'configured — ask your operator to enable it (recipe `identity`), or supply a `token`.',
+        );
+      }
+      entry.access = input.access.trim();
+    }
     if (typeof input.toolPrefix === 'string') entry.toolPrefix = input.toolPrefix;
     if (typeof input.reconnect === 'boolean') entry.reconnect = input.reconnect;
     if (Array.isArray(input.enabledFeatureSets)) entry.enabledFeatureSets = input.enabledFeatureSets.map(String);
@@ -266,6 +303,13 @@ export class McplAdminModule implements Module {
 
     const config = resolveOverlayEntry(id, entry, this.overlayPath) as unknown as McplServerConfig;
     config.env = { ...(config.env ?? {}), AGENT_TIMEZONE: this.timeZone };
+    if (entry.access && this.identity) {
+      const identity = this.identity;
+      const audience = entry.access;
+      // Fresh credential on every dial, resolved host-side; the overlay
+      // stores only the access NAME. See identity-module.ts header.
+      config.accessProvider = () => identity.accessFor(audience);
+    }
 
     const alreadyLoaded = framework.listMcplServers().some(s => s.id === id);
     try {

package/src/modules/observers-module.ts

@@ -37,6 +37,10 @@ import {
 export interface ObserversModuleConfig {
   /** Absolute path to the grant file (same one the webui watches). */
   path: string;
+  /** 'tools' (default) or 'utilities' — grant edits are rare; behind the
+   *  `utils` meta-tool they stop costing three schemas per inference. The
+   *  consent semantics are unchanged either way: the agent holds the pen. */
+  surface?: 'tools' | 'utilities';
 }
 
 export class ObserversModule implements Module {
@@ -48,6 +52,14 @@ export class ObserversModule implements Module {
   async stop(): Promise<void> {}
 
   getTools(): ToolDefinition[] {
+    return (this.config.surface ?? 'tools') === 'tools' ? this.definitions() : [];
+  }
+
+  getUtilities(): ToolDefinition[] {
+    return this.config.surface === 'utilities' ? this.definitions() : [];
+  }
+
+  private definitions(): ToolDefinition[] {
     return [
       {
         name: 'get',

package/src/modules/retrieval-module.ts

@@ -154,7 +154,11 @@ export class RetrievalModule implements Module {
 
       const injections: ContextInjection[] = [{
         namespace: 'retrieval',
-        position: 'system',
+        // 'afterUser', NOT 'system': retrieval content changes with recent
+        // context (contextHash above), so injecting it into the system prompt
+        // churns the very front of the KV cache and invalidates the entire
+        // prefix every turn. Tail injection keeps the stable prefix cached.
+        position: 'afterUser',
         content: [{ type: 'text', text: `## Retrieved Knowledge\n${text}` }],
       }];
 

package/src/modules/settings-module.ts

@@ -33,6 +33,14 @@ import type {
 export interface ReasoningSettings {
   enabled: boolean;
   budgetTokens: number;
+  /**
+   * How thinking content comes back from the API: 'summarized' returns a
+   * readable reasoning summary in the `thinking` field; 'omitted' returns an
+   * empty `thinking` field with only the encrypted signature. Models 4.7+
+   * default to 'omitted' server-side — we default to 'summarized' to restore
+   * the pre-4.7 behavior (visible reasoning in stores, webui, estimators).
+   */
+  display: 'summarized' | 'omitted';
 }
 
 export interface SettingsState {
@@ -40,7 +48,7 @@ export interface SettingsState {
 }
 
 const DEFAULTS: SettingsState = {
-  reasoning: { enabled: false, budgetTokens: 8192 },
+  reasoning: { enabled: false, budgetTokens: 8192, display: 'summarized' },
 };
 
 export class SettingsModule implements Module {
@@ -112,8 +120,16 @@ export class SettingsModule implements Module {
           type: 'number',
           description: 'Token budget for thinking blocks (min 1024).',
         },
+        reasoning_display: {
+          type: 'string',
+          enum: ['summarized', 'omitted'],
+          description:
+            "How your thinking is returned: 'summarized' (a readable summary of your reasoning " +
+            "is recorded alongside the signature) or 'omitted' (signature only, slightly faster " +
+            'first token; your reasoning is not visible to anyone, including you on replay).',
+        },
       },
-      keys: ['reasoning_enabled', 'reasoning_budget_tokens'],
+      keys: ['reasoning_enabled', 'reasoning_budget_tokens', 'reasoning_display'],
       get: () => this.reasoningSettingsView(),
       update: (_agentName, patch) => {
         const next = { ...this.state.reasoning };
@@ -130,6 +146,12 @@ export class SettingsModule implements Module {
           }
           next.budgetTokens = Math.max(1024, Math.round(budget));
         }
+        if (patch.reasoning_display !== undefined) {
+          if (patch.reasoning_display !== 'summarized' && patch.reasoning_display !== 'omitted') {
+            throw new Error("reasoning_display must be 'summarized' or 'omitted'");
+          }
+          next.display = patch.reasoning_display;
+        }
         this.state.reasoning = next;
         this.ctx?.setState(this.state);
         return this.reasoningSettingsView();
@@ -142,6 +164,9 @@ export class SettingsModule implements Module {
         if (all || keys?.includes('reasoning_budget_tokens')) {
           this.state.reasoning.budgetTokens = DEFAULTS.reasoning.budgetTokens;
         }
+        if (all || keys?.includes('reasoning_display')) {
+          this.state.reasoning.display = DEFAULTS.reasoning.display;
+        }
         this.ctx?.setState(this.state);
         return this.reasoningSettingsView();
       },
@@ -153,6 +178,7 @@ export class SettingsModule implements Module {
     return {
       reasoning_enabled: this.state.reasoning.enabled,
       reasoning_budget_tokens: this.state.reasoning.budgetTokens,
+      reasoning_display: this.state.reasoning.display,
     };
   }
 

package/src/modules/subscription-gc-module.ts

@@ -336,11 +336,25 @@ export class SubscriptionGcModule implements Module {
       // Cross the threshold → close and clear the counter.
       delete this.state.counters[channelId];
       this.persistNow();
+      // A CONFIGURED numeric budget for this channel is an explicit idle
+      // lease: someone chose a close-at-N budget for this specific channel,
+      // so the registry may close even an explicitly-opened one. The state
+      // does not record WHO configured it (agent via agent_settings,
+      // operator, or imported before these semantics existed), so nothing
+      // downstream may claim "agent-set" — receipts say 'configured-budget',
+      // actor unknown. The global default is not consent of any kind; the
+      // registry refuses machine closes of explicit opens under it (#5).
+      const hasConfiguredLease = typeof this.state.overrides[channelId] === 'number';
       const result = await this.ctx
         ?.callTool({
           id: `gc-unsub-${this.callSeq++}`,
           name: 'channel_close',
-          input: { channelId, serverId: this.serverId },
+          input: {
+            channelId,
+            serverId: this.serverId,
+            source: 'subscription-gc',
+            overrideExplicitOpen: hasConfiguredLease,
+          },
         })
         .catch((err: unknown) => ({
           success: false,
@@ -349,6 +363,34 @@ export class SubscriptionGcModule implements Module {
         }));
 
       if (result && result.success) {
+        // Operator-side receipt (privacy-minimal: ids and thresholds, no
+        // content) — a GC close changes durable listening state and must
+        // not look spontaneous from outside the transcript. Duck-typed
+        // against a framework that may not have ModuleContext.notifyOps yet
+        // (skipped there), and invoked THROUGH the context object: the real
+        // ModuleContextImpl.notifyOps reads `this`, so a detached
+        // `const f = ctx.notifyOps; f(...)` throws in production while
+        // passing against arrow-function mocks.
+        const opsCtx = this.ctx as unknown as {
+          notifyOps?: (kind: string, agent: string, message: string, data?: Record<string, unknown>) => void;
+        } | null;
+        opsCtx?.notifyOps?.(
+          'subscription-gc-close',
+          this.ctx?.getAgents()[0]?.name ?? 'unknown',
+          `subscription-gc auto-closed channel ${channelId} (over ${limit} ambient chars ` +
+          `since last activation${hasConfiguredLease ? ', configured per-channel budget' : ', default budget'}). ` +
+          `Restore: channel_open ${channelId}, or agent_settings channel_idle_limits.`,
+          {
+            channelId,
+            limitChars: limit,
+            decisionSource: 'subscription-gc',
+            // 'configured-budget' deliberately does NOT claim an actor: the
+            // override state records no provenance (agent, operator, or
+            // imported are all possible).
+            lease: hasConfiguredLease ? 'configured-budget' : 'default',
+            restore: `channel_open ${channelId}`,
+          },
+        );
         return {
           addMessages: [
             {
@@ -367,6 +409,17 @@ export class SubscriptionGcModule implements Module {
           ],
         };
       }
+
+      // The registry refused because the channel was explicitly opened and
+      // we hold no lease: stand down quietly — the janitor doesn't argue
+      // with stated intent. The counter stays cleared, so the next refusal
+      // is at least a full budget away; if the channel's provenance later
+      // changes (reopened by policy), GC self-heals.
+      const refusal = (result as { data?: { refusal?: string } } | undefined)?.data?.refusal;
+      if (refusal === 'explicit-open') {
+        return {};
+      }
+
       // Close failed — keep the channel counted so we retry on the next
       // ambient message rather than silently giving up.
       this.state.counters[channelId] = next;